DEV Community: Bala Paranj

We Forgot defer — 6 Resource Leaks We Found During Refactoring

Bala Paranj — Sun, 19 Apr 2026 12:07:11 +0000

We had a progress spinner. It animated on stderr while the evaluation ran. When the evaluation panicked, the spinner kept spinning. The terminal was corrupted. We had to reset the terminal every time.

The fix was one line: defer stop().

We found six patterns like this during a refactoring phase — resource leaks that only appeared under error conditions, panics, or signals. The happy path worked. The unhappy path leaked.

1. The Spinner That Survives a Panic

Before: Cleanup after computation

func (r *runner) Run(ctx context.Context, cfg config) error {
    stop := r.runtime.BeginProgress("Computing observation delta")

    delta, err := r.computeDelta(ctx, cfg.ObservationsDir, cfg.Filter)
    stop()  // <-- Never runs if computeDelta panics

    if err != nil {
        return err
    }
    return writeOutput(r.Stdout, cfg.Format, delta)
}

BeginProgress starts a goroutine that writes ANSI escape codes to stderr every 100ms. stop() sends a signal to the goroutine to stop and write the final "Done" message. If computeDelta panics, stop() is never called. The goroutine keeps running. The terminal keeps receiving escape codes. The panic message is interleaved with spinner frames.

After: defer guarantees cleanup

func (r *runner) Run(ctx context.Context, cfg config) error {
    stop := r.runtime.BeginProgress("Computing observation delta")
    defer stop()

    delta, err := r.computeDelta(ctx, cfg.ObservationsDir, cfg.Filter)
    if err != nil {
        return err
    }
    return writeOutput(r.Stdout, cfg.Format, delta)
}

defer stop() runs after the function returns — whether by normal return, error return, or panic. The spinner is always cleaned up.

But there's a subtlety: the stop function itself runs in a goroutine. If the goroutine panics (say, writing to a closed stderr), the panic propagates to the caller. Fix the goroutine too:

func (r *Runtime) BeginProgress(label string) func() {
    errOut := r.stderr()
    stopCh := make(chan struct{})

    go func() {
        defer func() {
            if r := recover(); r != nil {
                fmt.Fprintf(errOut, "\rprogress render panic: %v\n", r)
            }
        }()
        ticker := time.NewTicker(100 * time.Millisecond)
        defer ticker.Stop()
        for {
            select {
            case <-stopCh:
                return
            case <-ticker.C:
                fmt.Fprintf(errOut, "\r%s Running: %s...", frames[i%len(frames)], label)
                i++
            }
        }
    }()

    var once sync.Once
    return func() {
        once.Do(func() {
            close(stopCh)
            // ... write final "Done" message
        })
    }
}

Three layers of protection:

defer stop() in the caller guarantees the stop signal is sent
defer recover() in the goroutine prevents render panics from crashing the process
sync.Once in the stop function prevents double-close panics if stop is called multiple times

2. The Signal Handler That Skips Cleanup

Before: os.Exit skips all defers

func (a *App) installInterruptHandler() {
    sigCh := make(chan os.Signal, 1)
    signal.Notify(sigCh, os.Interrupt)

    go func() {
        <-sigCh
        fmt.Fprintln(os.Stderr, "Interrupted")
        os.Exit(130)  // <-- All deferred cleanup skipped
    }()
}

When the user hits Ctrl+C, os.Exit(130) terminates the process immediately. No deferred functions run. Open file handles aren't closed. Temp files aren't removed. Log files aren't flushed. CPU profile output is lost.

After: Context cancellation allows defer chain to complete

func (a *App) installInterruptHandler() func() {
    sigCh := make(chan os.Signal, 1)
    done := make(chan struct{})
    signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM)

    go func() {
        defer func() {
            if r := recover(); r != nil {
                fmt.Fprintf(os.Stderr, "signal handler panic: %v\n", r)
            }
        }()
        select {
        case <-sigCh:
            fmt.Fprintln(os.Stderr, "Interrupted")
            if a.cancel != nil {
                a.cancel()  // Cancel context — operations unwind naturally
            }
        case <-done:
            return
        }
    }()

    return func() {
        signal.Stop(sigCh)
        close(done)
    }
}

The main execution path sets up deferred cleanup:

func (a *App) Execute(args []string) {
    cleanup := a.installInterruptHandler()
    defer cleanup()
    defer a.recoverExecutePanic()

    a.executeRootCommand(args)
    // All defers run whether command succeeds, fails, or is interrupted
}

Now Ctrl+C cancels the context. Operations check ctx.Err() and return errors. The normal return path runs all defers. File handles close. Temp files are removed. The exit code is set from the error chain, not hardcoded.

3. The Temp File That Outlives the Process

Before: Error paths skip cleanup

func WriteFileAtomic(path string, data []byte, perm os.FileMode) error {
    dir := filepath.Dir(path)
    tmp, err := os.CreateTemp(dir, ".stave-*.tmp")
    if err != nil {
        return err
    }
    tmpPath := tmp.Name()

    if _, err := tmp.Write(data); err != nil {
        tmp.Close()
        os.Remove(tmpPath)  // Manual cleanup on write error
        return err
    }
    if err := tmp.Sync(); err != nil {
        tmp.Close()
        os.Remove(tmpPath)  // Manual cleanup on sync error
        return err
    }
    if err := tmp.Close(); err != nil {
        os.Remove(tmpPath)  // Manual cleanup on close error
        return err
    }
    return os.Rename(tmpPath, path)
}

Four error paths. Each one manually closes and removes the temp file. If you add a fifth step (like Chmod), you must remember to add cleanup. Miss one path and temp files accumulate.

After: defer handles all cleanup paths

func WriteFileAtomic(path string, data []byte, perm os.FileMode) error {
    dir := filepath.Dir(path)
    tmp, err := os.CreateTemp(dir, ".stave-*.tmp")
    if err != nil {
        return err
    }
    tmpPath := tmp.Name()

    // Cleanup: remove temp file on ANY failure. On success, rename
    // moves it to the final path and remove becomes a no-op.
    closed := false
    defer func() {
        if !closed {
            tmp.Close()
        }
        os.Remove(tmpPath)
    }()

    if _, err := tmp.Write(data); err != nil {
        return fmt.Errorf("write: %w", err)
    }
    if err := tmp.Sync(); err != nil {
        return fmt.Errorf("sync: %w", err)
    }
    if err := tmp.Close(); err != nil {
        return fmt.Errorf("close: %w", err)
    }
    closed = true

    return os.Rename(tmpPath, path)
}

The closed flag prevents double-closing: tmp.Close() is called explicitly for the success path (so we can check its error), and the deferred tmp.Close() only runs if the explicit close wasn't reached.

os.Remove(tmpPath) in the defer always runs. On the success path, Rename already moved the temp file to its final name — Remove tries to delete the old path, which no longer exists, and silently fails. On error paths, the temp file is cleaned up.

Adding a new step (Chmod, Chown, etc.) requires zero cleanup code — the defer handles it.

4. The Mutex That Never Unlocks

Before: Error returns skip unlock

func (cp *CountedProgress) Update(processed, total int) {
    cp.mu.Lock()

    if processed < 0 || total < 0 {
        cp.mu.Unlock()
        return  // Must remember to unlock before every return
    }

    cp.processed = processed
    cp.total = total
    cp.render()

    cp.mu.Unlock()
}

Two unlock calls. If you add a third return path (say, for a cancelled context), you must add a third unlock. Miss one and the mutex deadlocks.

After: defer unlock is unconditional

func (cp *CountedProgress) Update(processed, total int) {
    cp.mu.Lock()
    defer cp.mu.Unlock()

    if processed < 0 || total < 0 {
        return  // Unlock runs automatically via defer
    }

    cp.processed = processed
    cp.total = total
    cp.render()
    // Unlock runs automatically via defer
}

One line. Every return path — including future ones added during refactoring — automatically unlocks.

5. The sync.Once That Replaced a Race

Before: Bool flag with race condition

type Progress struct {
    stopped bool
    ch      chan struct{}
}

func (p *Progress) Stop() {
    if p.stopped {
        return
    }
    p.stopped = true
    close(p.ch)
}

Two goroutines call Stop() concurrently. Both read p.stopped as false. Both set it to true. Both call close(p.ch). Second close panics: "close of closed channel."

After: sync.Once eliminates the race

type Progress struct {
    once sync.Once
    ch   chan struct{}
}

func (p *Progress) Stop() {
    p.once.Do(func() {
        close(p.ch)
    })
}

sync.Once guarantees the closure runs exactly once, regardless of how many goroutines call Stop() concurrently. No race. No double-close. No panic.

Combined with defer:

done := rt.BeginProgress("Evaluating controls")
defer done()  // done() uses sync.Once internally — safe to call twice

If the function calls done() explicitly (e.g., to stop the spinner before printing results) and then returns (triggering the deferred done()), sync.Once ensures the channel is closed only once.

6. The Future-Proof Cleanup Contract

Before: No cleanup mechanism

deps, err := builder.Build(ctx, plan)
if err != nil {
    return err
}
// ... use deps ...
// What if deps acquires resources later? No cleanup contract exists.

Today ApplyDeps holds only values — no file handles, no connections. But tomorrow you might add a database connection, a log file, or a metric exporter. Without a cleanup contract, the caller doesn't know it needs to release resources.

After: Establish the contract now, implement later

type ApplyDeps struct {
    Runner *AuditWorkflow
    Config AssessmentConfig
}

func (d *ApplyDeps) Close() {
    // No-op today. Future resources cleaned up here.
}

The caller:

deps, err := builder.Build(ctx, plan)
if err != nil {
    return err
}
defer deps.Close()
// ... use deps ...

defer deps.Close() runs whether the function succeeds or fails. When you add a file handle to ApplyDeps next month, the cleanup is already wired — you just add d.handle.Close() to the Close() method. No caller changes needed.

The Anti-Pattern: defer in Loops

The deferInLoop gocritic check catches this:

// BAD: defer accumulates — all files stay open until loop ends
for _, path := range files {
    f, err := os.Open(path)
    if err != nil {
        return err
    }
    defer f.Close()  // <-- Runs after the LOOP, not after the iteration

    process(f)
}
// If files has 1000 entries, 1000 file handles are open simultaneously

Fix: extract to a function where defer scopes correctly:

// GOOD: defer scopes to the function, which returns per iteration
for _, path := range files {
    if err := processFile(path); err != nil {
        return err
    }
}

func processFile(path string) error {
    f, err := os.Open(path)
    if err != nil {
        return err
    }
    defer f.Close()  // Runs when processFile returns — per iteration
    return process(f)
}

Or use explicit close when the logic is simple:

for _, path := range files {
    f, err := os.Open(path)
    if err != nil {
        return err
    }
    err = process(f)
    f.Close()
    if err != nil {
        return err
    }
}

When We Added defer vs When We Should Have

Every defer we added during refactoring was a bug we shipped without. The happy path worked. The tests passed. But:

Resource	Happy Path	Panic/Error Path	Signal Path
Spinner stop	Worked	Leaked	Leaked
Signal cleanup	N/A	N/A	Skipped
Temp file remove	Worked	Leaked on some paths	Leaked
Mutex unlock	Worked	Deadlocked on new returns	N/A
Channel close	Worked	Panicked on double-close	Panicked

The pattern is consistent: we tested the success path. The failure path was invisible until a panic happened during development or a user hit Ctrl+C at the wrong moment.

The lesson: write defer on the line after resource acquisition. Not "later." Not "when we add error handling." Immediately. The cost is zero when everything works. The cost of forgetting is a corrupted terminal, a deadlocked process, or a temp directory full of orphaned files.

These 6 defer patterns were added during refactoring of Stave, a Go CLI for offline security evaluation. The deferInLoop gocritic check now prevents the most common defer mistake at CI time.

Value Objects, Entities, and Aggregates in Go — Without a Framework

Bala Paranj — Sat, 18 Apr 2026 12:19:26 +0000

Domain-Driven Design in Go doesn't look like DDD in Java. There are no annotations, no repository interfaces from a framework, no @Entity markers. The building blocks — Value Objects, Entities, and Aggregates — emerge from Go's type system and encapsulation rules.

Here's how each pattern appeared in a security CLI through refactoring, with the actual before/after code.

Value Objects: Equality by Content, Not Identity

A Value Object has no identity. Two instances with the same content are interchangeable. They're immutable, they validate at construction, and they carry domain behavior as methods.

Before: Raw Strings Everywhere

// BEFORE: ControlID is string — no validation, no behavior
type Finding struct {
    ControlID string `json:"control_id"`
    AssetID   string `json:"asset_id"`
}

// Any string is accepted. No validation. No domain methods.
f := Finding{
    ControlID: "not a valid id",
    AssetID:   "also anything",
}

After: kernel.ControlID Value Object

// AFTER: ControlID is a Value Object with validation and behavior
type ControlID string

var controlIDPattern = regexp.MustCompile(`^CTL\.[A-Z][A-Z0-9]*(\.[A-Z][A-Z0-9]*){1,}\.\d{3}$`)

func NewControlID(raw string) (ControlID, error) {
    if err := ValidateControlIDFormat(raw); err != nil {
        return "", err
    }
    return ControlID(raw), nil
}

// Domain behavior lives on the type
func (id ControlID) Provider() string {
    parts := strings.Split(id.String(), ".")
    if len(parts) < 2 { return "" }
    return parts[1]  // "CTL.S3.PUBLIC.001" → "S3"
}

func (id ControlID) Category() string { ... }  // → "PUBLIC"
func (id ControlID) Sequence() string { ... }  // → "001"

// JSON round-trip validates
func (id *ControlID) UnmarshalJSON(b []byte) error {
    var s string
    if err := json.Unmarshal(b, &s); err != nil { return err }
    val, err := NewControlID(s)
    if err != nil { return err }
    *id = val
    return nil
}

Value Object properties:

Equality by content: Two ControlID("CTL.S3.PUBLIC.001") are equal
Validated at construction: NewControlID rejects invalid formats
Immutable: ControlID is a string — no mutation methods
Domain behavior: Provider(), Category(), Sequence() extract meaning
Self-validating at boundaries: UnmarshalJSON validates on deserialization

The codebase has 12 Value Objects in the kernel package:

Value Object	Underlying	Domain Meaning
`ControlID`	`string`	Structured security control identifier
`AssetType`	`string`	Cloud resource category (s3_bucket, iam_role)
`Schema`	`string`	Schema version (obs.v0.1, ctrl.v1)
`Duration`	`time.Duration`	Human-formatted duration (7d, 24h)
`Vendor`	`string`	Cloud provider (aws, azure)
`Digest`	`string`	SHA-256 hex digest
`ObjectPrefix`	`string`	S3 key prefix with matching semantics
`NetworkScope`	`int`	Network boundary classification
`PrincipalScope`	`int`	Identity trust boundary
`TimeWindow`	`struct`	Start/end time pair with containment checks
`Severity`	`int`	Control severity with ordering
`Status`	`int`	Check result (Pass/Warn/Fail/Skipped)

kernel.Duration: A Value Object with Custom Serialization

// kernel.Duration wraps time.Duration with human-friendly formatting
type Duration time.Duration

func (d Duration) String() string { return FormatDuration(time.Duration(d)) }
// 168h → "7d", 36h → "1d12h", 1h → "1h"

func (d Duration) MarshalJSON() ([]byte, error) {
    return json.Marshal(d.String())  // Serializes as "7d", not 604800000000000
}

func (d *Duration) UnmarshalJSON(data []byte) error {
    var s string
    json.Unmarshal(data, &s)
    parsed, err := ParseDuration(s)  // Accepts "7d", "1.5d", "168h"
    *d = Duration(parsed)
    return err
}

Before: time.Duration serialized as "168h0m0s" in JSON. Users had to parse Go's duration format.
After: kernel.Duration serializes as "7d". ParseDuration accepts "7d", "1.5d", "1d12h" — human input formats.

Entities: Identity + Lifecycle

An Entity has a unique identity that persists across state changes. Two entities with the same data but different IDs are different entities. They have lifecycle methods that enforce state machine transitions.

Before: Flat Data Struct

// BEFORE: Flat struct with no lifecycle enforcement
type Timeline struct {
    AssetID       string
    Unsafe        bool
    UnsafeSince   time.Time
    LastChecked   time.Time
    EpisodeCount  int
}

// Caller manages state transitions manually
tl.Unsafe = true
tl.UnsafeSince = time.Now()
// What if caller sets Unsafe=true but forgets UnsafeSince?

After: ExposureLifecycle Entity

// AFTER: Entity with enforced state transitions
type ExposureLifecycle struct {
    ID    ID            // ← unique identity
    asset Asset         // ← private state

    activeWindow   *ExposureWindow   // ← lifecycle state
    lastObservedAt time.Time

    history ExposureHistory   // ← encapsulated history
    stats   ObservationStats  // ← encapsulated metrics
}

// Construction enforces identity invariant
func NewExposureLifecycle(a Asset) *ExposureLifecycle {
    if a.ID.IsEmpty() {
        panic("contract violated: requires non-empty asset ID")
    }
    return &ExposureLifecycle{ID: a.ID, asset: a}
}

// State transitions through methods — caller can't set fields directly
func (l *ExposureLifecycle) RecordCheck(a Asset, ts time.Time) { ... }
func (l *ExposureLifecycle) IsExposed() bool { ... }
func (l *ExposureLifecycle) IsSecure() bool { ... }
func (l *ExposureLifecycle) ExposureDuration() time.Duration { ... }
func (l *ExposureLifecycle) ExceedsSLA(max time.Duration) bool { ... }

// Read-only accessors return values, not pointers
func (l *ExposureLifecycle) Stats() ObservationStats { return l.stats }
func (l *ExposureLifecycle) History() ExposureHistory { return l.history }

Entity properties:

Identity: ID field persists across state changes
Lifecycle: RecordCheck drives the state machine — callers can't set activeWindow directly
Encapsulation: stats and history are private, returned by value (no pointer aliasing)
Contract enforcement: panic on empty ID at construction

The ExposureWindow that the lifecycle manages is itself a Value Object:

// ExposureWindow is a Value Object — no identity, immutable after creation
type ExposureWindow struct {
    openedAt   time.Time
    resolvedAt time.Time
    active     bool
}

func NewActiveWindow(openedAt time.Time) ExposureWindow {
    return ExposureWindow{openedAt: openedAt, active: true}
}

func (w ExposureWindow) Resolve(end time.Time) ExposureWindow {
    // Returns a NEW window — doesn't mutate
    return ExposureWindow{
        openedAt:   w.openedAt,
        resolvedAt: end,
        active:     false,
    }
}

func (w ExposureWindow) IsActive() bool { return w.active }
func (w ExposureWindow) OpenedAt() time.Time { return w.openedAt }
func (w ExposureWindow) DwellTime(now time.Time) time.Duration { ... }

ExposureWindow.Resolve() returns a new window — it doesn't mutate the existing one. This is the Value Object pattern: operations produce new values.

Aggregates: Consistency Boundary

An Aggregate is a cluster of objects treated as a unit. External code accesses the aggregate through its root. Internal state is protected by the root's methods.

ComplianceReport: The Root Aggregate

// ComplianceReport is the root aggregate of an evaluation execution.
type ComplianceReport struct {
    Run              RunInfo               `json:"run"`
    Summary          ComplianceSummary     `json:"summary"`
    SecurityState    SecurityState         `json:"security_state"`
    RiskSignals      risk.ThresholdItems   `json:"risk_signals,omitempty"`
    Findings         []Finding             `json:"findings"`
    ExceptedFindings []ExceptedFinding     `json:"excepted_findings,omitempty"`
    SkippedControls  []SkippedControl      `json:"skipped_controls,omitempty"`
    ExemptedAssets   []asset.ExemptedAsset `json:"exempted_assets,omitempty"`
    Checks           []ResourceCheck       `json:"checks,omitempty"`
}

The ComplianceReport is constructed by the Assessor (the evaluation engine). It contains:

Value Objects: RunInfo, ComplianceSummary, SecurityState
Entity collections: []Finding (each has a ControlID+AssetID identity pair)
Derived state: SecurityState is computed from findings + risk signals

Before: Fat Struct with Mixed Concerns

// BEFORE: Summary mixed counts, gating, and metadata
type Summary struct {
    TotalControls     int           // counting
    PassCount         int           // counting
    FailCount         int           // counting
    FailOn            Severity      // gating logic
    Gated             bool          // gating logic
    StaveVersion      string        // metadata
    EvidenceFreshness time.Duration // metadata
}

RecomputeSummary had to reset counts while preserving metadata — a recipe for bugs.

After: Split into Cohesive Value Objects

// AFTER: Three Value Objects, each with single concern
type ComplianceSummary struct {
    TotalAssets      int `json:"total_assets"`
    ExposedResources int `json:"exposed_resources"`
    Violations       int `json:"violations"`
}

type GatingInfo struct {
    FailOn            Severity
    Gated             bool
    GatedFindingCount int
}

type AuditMeta struct {
    VulnSourceUsed    string
    EvidenceFreshness time.Duration
    StaveVersion      string
}

Each is a Value Object — no identity, no lifecycle, just data. They compose into the aggregate without coupling their concerns.

The Assessor Builds the Aggregate

func (s *assessmentSession) compileReport() ComplianceReport {
    // Sort for deterministic output
    SortFindings(s.collector.findings)

    // Partition findings through exception rules
    activeFindings, exceptedFindings := partitionFindings(
        s.collector.findings, s.assessor.Exceptions, s.auditTime,
    )

    // Derive security state from findings + risk
    riskSignals := risk.ComputeItems(...)
    posture := DeriveSecurityState(len(activeFindings), riskSignals)

    // Construct the aggregate
    return ComplianceReport{
        Run:              RunInfo{...},
        Summary:          ComplianceSummary{...},
        SecurityState:    posture,
        RiskSignals:      riskSignals,
        Findings:         activeFindings,
        ExceptedFindings: exceptedFindings,
        SkippedControls:  s.collector.skippedControls,
        ExemptedAssets:   s.collector.exemptedAssets,
        Checks:           s.collector.checks,
    }
}

The aggregate is assembled inside the assessmentSession — a private type. External code receives the completed ComplianceReport and cannot modify the internal assessment state.

How These Map to Go Constructs

DDD doesn't need a framework in Go. The language provides everything:

DDD Concept	Go Construct	Example
Value Object	Defined type + methods	`kernel.ControlID`, `kernel.Duration`
Value Object equality	`==` on defined types	`id1 == id2`
Value Object immutability	Return new values from methods	`window.Resolve()` returns new `ExposureWindow`
Entity identity	ID field + constructor	`ExposureLifecycle{ID: a.ID}`
Entity lifecycle	Methods with state transitions	`RecordCheck()`, `IsExposed()`
Entity encapsulation	Unexported fields + value receivers	`stats ObservationStats` (private), `Stats()` returns copy
Aggregate root	Struct with composed value objects	`ComplianceReport{Summary, Findings, ...}`
Aggregate construction	Factory method in private session	`compileReport()` on `assessmentSession`
Invariant enforcement	`panic` on contract violation	`NewExposureLifecycle` panics on empty ID
Boundary validation	`UnmarshalJSON` with validation	`ControlID.UnmarshalJSON` rejects invalid formats

The Key Insight

In Go, the DDD building blocks aren't declared — they're enforced by the type system:

Value Objects are defined types with MarshalJSON/UnmarshalJSON and no mutation methods
Entities have private fields, construction invariants, and lifecycle methods
Aggregates are structs assembled by private factory methods that external code receives read-only

No framework needed. No annotations. No base classes. Just types, methods, and encapsulation.

These patterns evolved through 60 refactorings in Stave, an offline configuration safety evaluator. The kernel package contains 12 Value Objects. The asset package contains the ExposureLifecycle Entity. The evaluation package contains the ComplianceReport Aggregate.

Subdomain Takeover is Not Just Phishing: How Acronis Nearly Lost Authenticated API Access

Bala Paranj — Fri, 17 Apr 2026 12:46:34 +0000

Every subdomain takeover writeup ends the same way: "an attacker could host a phishing page under your trusted domain."

That is the low-severity version.

In 2020, a researcher discovered four Acronis subdomains pointing to unclaimed Marketo endpoints and found something more serious buried in the HTTP response headers of a completely different endpoint. The subdomain takeover was not the vulnerability. It was the key that unlocked one.

The Setup: Four Dangling CNAMEs

@ashmek ran subdomain enumeration against acronis.com and found four marketing subdomains all pointing to Marketo landing page infrastructure:

register.acronis.com    → acronis.mktoweb.com
promo.acronis.com       → acronis.mktoweb.com
promosandbox.acronis.com → acronissandbox2.mktoweb.com
info.acronis.com        → mkto-h0084.com

Each target returned 404. Each target was unclaimed. @ashmek confirmed with Marketo support that none of the listed domains were in use or configured anymore.

Standard subdomain takeover. Standard remediation: remove the CNAME records or reclaim the Marketo workspaces. At this point, severity is medium — phishing, content injection, brand impersonation.

Then they looked at the API response headers.

The Escalation: CORS With Credentials

While examining the Acronis account API at account.acronis.com, @ashmek intercepted a request and found this in the response:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://register.acronis.com
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Accept, Authorization, Content-Type, ...
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS

Access-Control-Allow-Origin: https://register.acronis.com with Access-Control-Allow-Credentials: true.

register.acronis.com is one of the four dangling subdomains. The one that is unclaimed on Marketo. The one any attacker can register right now.

The attack chain is now:

1. Attacker registers register.acronis.com on Marketo (free)
2. Attacker hosts malicious JavaScript on register.acronis.com
3. Victim visits register.acronis.com while logged into account.acronis.com
4. JavaScript calls account.acronis.com/v2/account with credentials
5. Browser sends the authenticated request — CORS policy allows it
6. account.acronis.com responds with the victim's account data
7. JavaScript reads the response — CORS + credentials = full access
8. Attacker exfiltrates account data, tokens, or session information

This is not phishing. The user does not need to enter their password on a fake form. They need only visit a subdomain that Acronis's own CORS policy trusts — a subdomain that anyone can claim.

Why this CORS Configuration is Dangerous

The browser's CORS model has one rule that matters here: when Access-Control-Allow-Credentials: true is set, the browser will include cookies and authorization headers in the cross-origin request. The response is readable by the requesting JavaScript.

This is explicitly why the spec prohibits Access-Control-Allow-Origin: * with Access-Control-Allow-Credentials: true — the combination would allow any site to make authenticated API calls on behalf of the visitor. Browsers reject it.

But Access-Control-Allow-Origin: https://register.acronis.com is not a wildcard. It is a specific trusted origin. The browser allows it. The credentials are included. The response is readable.

The security assumption embedded in that CORS policy is: we control register.acronis.com. When that assumption is false — when the subdomain is unclaimed — the CORS policy has granted an arbitrary attacker the same cross-origin access that Acronis's own first-party applications have.

The Compound Vulnerability

Neither issue alone reaches this severity:

Dangling CNAME alone: medium — phishing, content injection
CORS with credentials alone: informative — only exploitable from a trusted origin
Together: high — authenticated cross-origin API access from an attacker-controlled page

This is the compound chain that individual controls miss. CTL.DNS.DANGLING.001 fires on the dangling CNAME. A CORS policy check fires on the Allow-Credentials: true configuration. Neither control alone captures the full attack path — only the combination does.

In Stave's compound chain model:

chain: subdomain_cors_credential_theft
members:
  - CTL.DNS.DANGLING.001       # CNAME points to unclaimed endpoint
  - CTL.CORS.CREDENTIALS.001   # Allow-Credentials: true with dynamic origin

preconditions:  [internet_access]
postconditions: [credential_access]

narrative: >
  A dangling CNAME on a subdomain that is explicitly trusted
  by a CORS policy with Allow-Credentials: true enables an
  attacker who claims the subdomain to make authenticated
  cross-origin API calls on behalf of any victim who visits
  the attacker-controlled page while logged in.

The chain fires when both controls fail simultaneously on related assets. One control finding remediated — either remove the dangling CNAME or remove Allow-Credentials: true — breaks the chain.

The Wildcard CORS Pattern

The Acronis case used an explicit origin (register.acronis.com), but the more common and more dangerous pattern is a wildcard subdomain CORS policy:

# Dangerous: any subdomain is trusted
Access-Control-Allow-Origin: https://anything.acronis.com
Access-Control-Allow-Credentials: true

When an API reflects the Origin header back as Access-Control-Allow-Origin without validation — a common misconfiguration — any subdomain the attacker controls becomes a trusted CORS origin. Combined with Allow-Credentials: true, any subdomain takeover on any *.acronis.com host unlocks authenticated API access.

The correct configuration trusts only the specific origins that legitimately need cross-origin access:

# Safe: explicit allowlist of known first-party origins
Access-Control-Allow-Origin: https://console.acronis.com
Access-Control-Allow-Credentials: true

Or, if credentials are not required:

# Safe: wildcard only when credentials are not needed
Access-Control-Allow-Origin: *
# Access-Control-Allow-Credentials omitted (defaults to false)

What Stave Detects

Running the Acronis scenario through Stave:

CTL.DNS.DANGLING.001    CRITICAL  initial_access
  "DNS CNAME Must Not Point to Unclaimed Third-Party Service"
  fires on: register.acronis.com → acronis.mktoweb.com (404, unclaimed)
  fires on: promo.acronis.com, promosandbox.acronis.com, info.acronis.com

CTL.CORS.CREDENTIALS.001  HIGH  credential_access
  "API Endpoints Must Not Allow Credentials from Untrusted Origins"
  fires on: account.acronis.com returning Allow-Credentials: true
            for an origin not in the explicit safe list

The compound chain subdomain_cors_credential_theft fires because both controls fail on related assets — the dangling subdomains and the CORS policy reference the same domain namespace.

Neither control alone justifies the chain's severity. Together, they describe a path from "attacker registers a free Marketo account" to "attacker reads authenticated account data for any victim who visits the page."

The Infrastructure Invariants

Two System Invariants were false simultaneously:

Invariant 1: Every DNS CNAME record must point to a target owned by the same organization.

register.acronis.com → acronis.mktoweb.com where acronis.mktoweb.com was unclaimed. False.

Invariant 2: API endpoints that set Access-Control-Allow-Credentials: true must only trust origins that are verified to be owned by the same organization.

account.acronis.com trusted register.acronis.com. The trust was not verified against actual ownership. False.

When both are false at the same time, on overlapping domain namespaces, the compound attack path opens.

Remediation

For the dangling CNAMEs — remove them or reclaim the Marketo workspaces. Five minutes per subdomain.

For the CORS policy — audit every endpoint that returns Access-Control-Allow-Credentials: true and verify that every origin in the allowlist is actively owned and monitored.

# Find all responses with Allow-Credentials from your API
# (run against your own API in a security review context)
curl -s -I -H "Origin: https://register.example.com" \
  https://api.example.com/v2/account | \
  grep -i "access-control"

If Access-Control-Allow-Origin reflects back an origin from *.yourcompany.com, check every subdomain in that namespace for dangling CNAMEs. Any unclaimed subdomain that matches the CORS reflection pattern is exploitable.

Checklist

All DNS CNAMEs point to targets owned and actively maintained by the organization
Access-Control-Allow-Credentials: true endpoints have an explicit, audited origin allowlist
No CORS policy reflects Origin header directly without validation
Subdomain enumeration run against all domains in the CORS allowlist
CTL.DNS.DANGLING.001 and CTL.CORS.CREDENTIALS.001 run together in CI
Deprovisioning process removes DNS records before canceling third-party service accounts

The subdomain takeover gave the attacker a trusted origin. The CORS policy gave that origin authenticated API access. Neither was the vulnerability alone. Together they were.

Based on the publicly disclosed Acronis subdomain takeover report on HackerOne. The compound chain analysis — dangling CNAME × CORS credentials — is detected by Stave, an open-source infrastructure invariant engine that evaluates configuration snapshots without cloud credentials.

8 Coupling and Cohesion Fixes That Made a Go CLI Navigable

Bala Paranj — Thu, 16 Apr 2026 10:26:16 +0000

I spent 4 months refactoring a Go CLI and tracked every change in a catalog. When I looked at the 60 entries, the largest cluster wasn't about types or error handling — it was about where code lives.

Coupling and cohesion problems don't cause bugs. They cause something worse: developers who can't find anything. A function in the wrong file. A type in a junk drawer package. A feature spread across 3 files when it should be in 1.

Here are 8 patterns I fixed, each with before/after code from the actual commits.

Pattern 1: The Junk Drawer File

The Problem

Five types.go files contained 125 types with no organizational principle:

setup/types.go          — 40 types (doctor, config, status, init, env, alias, context)
evidence/types.go       — 28 types (enums, params, snapshots, bundles, providers)
dto/types.go            — 23 types (findings, results, remediations)
reporting/types.go      — 22 types (baseline, CI diff, reports, enforce, prompts)
usecase/types.go        — 12 types (gate, fix, trace, apply, verify)

When you grepped for "Gate," you found it in usecase/types.go alongside trace, apply, and verify types. The file was organized by technical role (all types together) instead of business concern (gate types with gate logic).

The Fix

Split each file by business concern:

setup/types.go (40 types) → 8 files:
  doctor_types.go
  config_types.go
  status_types.go
  generate_types.go
  init_types.go
  env_types.go
  alias_types.go
  context_types.go

usecase/types.go (12 types) → 6 files:
  gate.go
  fix.go
  trace.go
  apply.go
  verify.go
  fixloop.go

Now grepping for "Gate" shows only gate-related types. Each file represents one business concern. The file name tells you what's inside without opening it.

Files changed: 5 files split into 30+ focused files.

Pattern 2: The Anemic File

The Problem

The opposite of junk drawers: 25 files with one function each.

baseline/run.go          — empty stub (0 functions)
cidiff/run.go            — empty stub (0 functions)
kernel/normalize.go      — 1 function (EnsureTrailingSlash)
evaluation/scoring.go    — 1 helper
sanitize/common.go       — 1 type

Opening kernel/normalize.go to find a single 4-line function meant more time navigating than reading. These files existed because "one file per function" was applied too aggressively.

The Fix

Merge into the files that own the domain concept:

kernel/normalize.go    → merged into kernel/identity.go
evaluation/scoring.go  → merged into evaluation/confidence.go
sanitize/common.go     → merged into sanitize/sanitize.go
baseline/run.go        → deleted (empty)

Rule: If a file has ≤1 function and ≤30 lines, it should merge into its logical neighbor. Each domain concept lives in one file, not two.

Files changed: 25 anemic files merged, 45 total files touched.

Pattern 3: The Utility Junk Drawer

The Problem

A single logic.go file mixed four unrelated concerns in the S3 policy analyzer:

// logic.go (280 lines)
func classifyAction(action string) ActionCategory { ... }     // Action analysis
func extractPrincipalAccount(arn string) string { ... }       // Principal parsing
func resolveConditionScope(ca ConditionAnalysis) Scope { ... } // Network scoping
func normalizeStringOrArray(v any) []string { ... }           // JSON normalization

A developer adding a new S3 action had to scroll past principal extraction, network scoping, and JSON normalization to find the action classifier.

The Fix

Split by domain concern:

logic.go (280 lines) → 4 files:
  actions.go     — IAM action → security category mapping
  principals.go  — AWS principal ARN/account ID extraction
  scoping.go     — condition analysis → network scope resolution
  normalize.go   — AWS JSON string-or-array helper

A developer adding a new S3 action goes to actions.go. No scrolling past unrelated code. The file name is the search result.

Pattern 4: The Boilerplate Clone

The Problem

14 S3 compliance controls each had identical loop+filter+parse boilerplate:

// BEFORE: Every control had this identical preamble
func (ctl *accessBlockPublic) Evaluate(snap asset.Snapshot) Result {
    for _, a := range snap.Assets {
        if !isS3Bucket(a) {
            continue
        }
        props := ParseS3Properties(a)

        // ... actual control logic here (the only unique part) ...
    }
    return ctl.PassResult()
}

The loop, filter, and parse were copy-pasted across all 14 files. Adding a new control meant copying 8 lines of infrastructure before writing 1 line of business logic.

The Fix

Extract the infrastructure into a callback pattern:

// AFTER: Control implements only the unique logic
func (ctl *accessBlockPublic) Evaluate(snap asset.Snapshot) Result {
    return ctl.evaluateS3Buckets(snap, func(a asset.Asset, props S3Properties) *Result {
        if props.Controls.IsPublicAccessFullyBlocked() {
            return nil // safe — skip
        }
        r := ctl.FailResult("BPA not fully enabled", "Enable all four flags")
        return &r
    })
}

The helper:

func (d *Definition) evaluateS3Buckets(snap asset.Snapshot, check func(asset.Asset, S3Properties) *Result) Result {
    for _, a := range snap.Assets {
        if !isS3Bucket(a) {
            continue
        }
        props := ParseS3Properties(a)
        if result := check(a, props); result != nil {
            return *result
        }
    }
    return d.PassResult()
}

14 copies of the loop → 1 helper. Net -41 lines. New controls implement a single callback function with zero boilerplate.

Pattern 5: The Fat Struct

The Problem

A summary struct mixed three unrelated concerns:

// BEFORE: 10 fields mixing counts, gating, and metadata
type Summary struct {
    TotalControls      int           // ← counting
    PassCount          int           // ← counting
    FailCount          int           // ← counting
    WarnCount          int           // ← counting
    FailOn             Severity      // ← gating
    Gated              bool          // ← gating
    GatedFindingCount  int           // ← gating
    VulnSourceUsed     string        // ← metadata
    EvidenceFreshness  time.Duration // ← metadata
    StaveVersion       string        // ← metadata
}

RecomputeSummary() needed to reset the counts but preserve the metadata. One caller forgot to preserve StaveVersion after a recompute.

The Fix

Split by concern:

// AFTER: Three cohesive structs
type ResultCounts struct {
    Total int
    Pass  int
    Fail  int
    Warn  int
}

type GatingInfo struct {
    FailOn            Severity
    Gated             bool
    GatedFindingCount int
}

type AuditMeta struct {
    VulnSourceUsed    string
    EvidenceFreshness time.Duration
    StaveVersion      string
}

RecomputeSummary() now takes ResultCounts and returns ResultCounts. It physically cannot touch gating or metadata because they're in different structs.

Files changed: 18 — the DTO layer maps from the nested structs to the same flat JSON output.

Pattern 6: The Mutable Global

The Problem

Confidence thresholds were set via a package-level global with a setter:

// BEFORE: Mutable global state
var confidenceThresholds = struct {
    high int
    med  int
}{high: 4, med: 2}

func SetConfidenceThresholds(high, med int) {
    confidenceThresholds.high = high
    confidenceThresholds.med = med
}

This was called once at startup but the global was accessible from any goroutine. Not thread-safe. Not testable (tests leak state between runs). Not traceable (who set it? when?).

The Fix

Replace with a struct threaded through the dependency chain:

// AFTER: Explicit dependency — no global state
type ConfidenceCalculator struct {
    HighMultiplier int
    MedMultiplier  int
}

func DefaultConfidenceCalculator() ConfidenceCalculator {
    return ConfidenceCalculator{HighMultiplier: 4, MedMultiplier: 2}
}

// Threaded through Runner → strategyDeps → strategies
type Runner struct {
    Confidence ConfidenceCalculator
    // ...
}

Configuration flows through the constructor, not through a global setter. Thread-safe by design. Testable without cleanup.

Pattern 7: The Misplaced Function

The Problem

Two functions in core/evaluation were only called by adapters/output/text:

// BEFORE: In core/evaluation (called only by one adapter)
func GroupViolationsByDomain(findings []Finding) map[string][]Finding { ... }
func DomainCount(findings []Finding) int { ... }

These are presentation helpers — they group findings for text output. They don't belong in the core evaluation package.

The Fix

Move to the only consumer:

// AFTER: In adapters/output/text (the sole caller)
func groupViolationsByDomain(findings []evaluation.Finding) map[string][]evaluation.Finding { ... }
func domainCount(findings []evaluation.Finding) int { ... }

The functions became unexported (lowercase) because they're internal to the adapter. Core evaluation no longer carries presentation logic.

Similarly, Sanitized() methods on core domain types were moved to the app layer:

// BEFORE: Sanitization method on core domain type
func (m Misconfiguration) Sanitized(san Sanitizer) Misconfiguration { ... }

// AFTER: Sanitization logic in app layer (enrich.go)
func sanitizeFinding(san Sanitizer, f Finding) Finding { ... }

Core types are now pure data. Sanitization is a presentation concern that lives in the app layer.

Pattern 8: The Duplicate Package

The Problem

Two packages served the same purpose:

internal/sanitize/           — Sanitizer, Policy, constants
internal/sanitize/scrub/     — Engine with Snapshot() and Map() methods

The scrub sub-package was created to avoid a "large file." But its only consumer was sanitize itself. Two packages for one concept.

The Fix

Merge into one:

// BEFORE: Two packages
import "internal/sanitize"
import "internal/sanitize/scrub"

engine := scrub.NewEngine(sanitize.NewSanitizer(policy))
engine.Snapshot(snap)

// AFTER: One package
import "internal/sanitize"

san := sanitize.New(policy)
san.Snapshot(snap)

scrub/ was deleted entirely. One package, one import, one concept.

The Metrics

Metric	Before	After
Junk drawer files	5 (125 types mixed)	0 (each file = 1 concern)
Anemic files	25 (≤1 function each)	0 (merged into neighbors)
Boilerplate copies	14 (S3 control loop)	1 (shared helper)
Mutable globals	1 (confidence thresholds)	0 (threaded dependency)
Misplaced functions	4 (core hosting presentation)	0 (moved to adapters)
Duplicate packages	1 (sanitize + scrub)	0 (merged)
Discoverability score	7/10	9/10

The Principle

Coupling is about how much changes cascade. Cohesion is about how easily you find things.

High cohesion means: when you need to change "gating logic," you open one file in one package. Low coupling means: when you change "gating logic," nothing in "trace" or "apply" needs to change.

Both are served by one question: does this code change for the same reason as its neighbors?

If yes → keep together (merge anemic files, combine duplicate packages)
If no → separate (split junk drawers, extract boilerplate, move misplaced functions)

The metric that matters isn't lines of code or file count. It's: how many files do you open to understand one feature? After these 8 fixes, the answer dropped from 4-5 to 1-2.

*These 8 patterns were identified across 60 refactorings in Stave, an offline configuration safety evaluator.

Compound Risk is a Bigger Problem Than Missing Checks

Bala Paranj — Wed, 15 Apr 2026 18:02:41 +0000

Two different problems

Security tools have blind spots. AWS Trusted Advisor can't detect incomplete observation data, latent exposure behind Public Access Block, or ACL escalation paths. Those are real gaps. If your tool doesn't check for something, you won't find it.

But there's a bigger problem that gets less attention: the tool checks for things individually and misses what happens when they combine.

This is compound risk. It's not a missing check — it's a missing dimension of analysis.

What Trusted Advisor Checks

Trusted Advisor evaluates settings one at a time:

Is this bucket public? Yes/No.
Is encryption enabled? Yes/No.
Is logging turned on? Yes/No.

Each check returns an independent result. The results don't talk to each other. A bucket that passes encryption and fails public access generates two separate findings with no connection between them.

This is useful. It catches the obvious things. But it can't express a statement like: "encryption is enabled AND the bucket is public, which means encryption provides no confidentiality benefit because anyone can read the data through the public endpoint."

That's not a missing check. Both checks exist. What's missing is the relationship between them.

How compound risk caused a $190 million breach

The Capital One breach in 2019 wasn't caused by a single misconfiguration. It was caused by three settings that were individually low-to-medium severity but catastrophic in combination:

An SSRF vulnerability in the WAF configuration — exploitable but contained if nothing else was wrong
An overly permissive IAM role on the compromised instance — broad but not dangerous if the instance wasn't reachable
Unencrypted S3 buckets with sensitive data — risky but not breached if nobody had credentials

Any scanner would have flagged each setting independently. No scanner correlated them into: "an attacker who exploits the SSRF can assume the overly permissive role and read unencrypted customer data from S3."

The breach cost $190 million. Each individual finding would have been prioritized as medium.

The three compound patterns

In the open source security CLI I built, compound risk detection runs after individual control evaluation. It looks for specific combinations that tools checking settings individually will always miss:

Pattern 1: Public access + wildcard IAM policy

[CRITICAL] COMPOUND.001
Triggers: CTL.S3.PUBLIC.001 (FAIL) + CTL.S3.ACCESS.002 (FAIL)

Public access with overly broad IAM permissions — the S3 + IAM
lateral movement pattern present in the majority of documented
AWS breaches.

The bucket is public. The policy allows wildcard actions. Individually they're HIGH severity. Together they're the Capital One pattern: public entry point + broad permissions = full data access.

A checklist that evaluates these independently will list them as two findings on page 4 and page 12 of a 30-page report. An auditor reading sequentially might not connect them. Compound detection puts them at the top as a single critical finding.

Pattern 2: Encryption enabled + public access

[HIGH] COMPOUND.002
Triggers: CTL.S3.PUBLIC.001 (FAIL) + CTL.S3.ENCRYPT.001 (PASS)

Encryption at rest is configured but the bucket is publicly
accessible. Encryption provides no confidentiality benefit
while public access is enabled.

This is the false confidence pattern. The encryption check passes. The team marks "encryption at rest" as compliant. But encryption at rest protects against physical disk theft — it does nothing when the data is served over a public HTTPS endpoint to anyone who asks.

Trusted Advisor would show the encryption check as green. The team would feel secure. The data would be publicly readable.

Pattern 3: VPC endpoint without endpoint policy

[HIGH] COMPOUND.003
Triggers: CTL.S3.NETWORK.VPC.001 (PASS) + CTL.S3.NETWORK.POLICY.001 (FAIL)

VPC endpoint restricts this bucket but the endpoint policy does
not restrict which bucket ARNs are reachable. Any principal on
the VPC can reach any S3 bucket in any account via the endpoint.

The VPC endpoint exists. The network restriction check passes. But the endpoint has no policy limiting which buckets it can access. Any EC2 instance on the VPC can reach any S3 bucket in any AWS account through the endpoint — including buckets in other accounts. The endpoint that was supposed to restrict access became a wormhole.

Why this is harder than adding more checks

Trusted Advisor's blind spots can be fixed by adding checks. Can't detect ACL escalation? Add an ACL check. Can't detect incomplete data? Add a completeness check. Each blind spot has a corresponding check that closes it.

Compound risk can't be fixed by adding more checks. The individual checks already exist. What's missing is the correlation logic that evaluates combinations. This requires a different kind of analysis:

Run all individual checks first — establish the baseline of pass/fail per control per asset
Scan for known dangerous combinations — look for specific multi-control patterns on the same asset
Elevate the combined finding above its individual components — the compound finding is the root cause, the individual findings are symptoms

Trusted Advisor's architecture — independent per-resource checks with no cross-check correlation — structurally cannot do step 2. It's not a feature they haven't built yet. It's a design constraint of evaluating settings in isolation.

The severity math

Individual findings have individual severities. Compound findings have combined severities that don't follow addition.

Finding A	Finding B	Individual Max	Compound Severity
PUBLIC bucket (HIGH)	Wildcard policy (HIGH)	HIGH	CRITICAL
Encryption pass (PASS)	PUBLIC bucket (HIGH)	HIGH	HIGH (false confidence)
VPC endpoint (PASS)	No endpoint policy (MEDIUM)	MEDIUM	HIGH (wormhole)

The compound severity isn't max(A, B). It's a qualitative judgment: "these two findings together create an attack path that neither creates alone." The Capital One breach proved this — three medium findings combined into a $190 million incident.

The $190 million proof of business value

This isn't a theoretical risk model. It's a federal court case.

Capital One had security tools. Those tools found the SSRF vulnerability, the overly permissive IAM role, and the unencrypted S3 buckets. Each was logged. Each was individually categorized as medium severity. Each sat in a findings queue alongside hundreds of other medium findings.

No tool said: "these three medium findings on connected resources form an attack path that leads to 100 million customer records."

The attacker saw the connection. The tools didn't.

The cost of that missing correlation: $190 million in regulatory penalties, legal settlements, customer notification, and remediation. Not from a zero-day. Not from a sophisticated nation-state attack. From three settings that every scanner on the market could detect individually.

Stave's COMPOUND.001 detection pattern — public access + wildcard IAM policy — is the exact pattern that was exploited. It runs against local configuration snapshots in seconds. It's open source. It requires zero live credentials.

The question for any security team is simple: would you rather find this combination before deployment at zero cost, or after a breach at $190 million?

That's not a theoretical ROI. It's a documented federal case with public filings that proves the business value of compound risk detection over individual setting checks. No compliance checklist tool can make this claim, because they structurally cannot detect the relationship between findings.

What this means for tool selection

When evaluating security tools, there are two questions:

What does it check? — This is the coverage question. More checks = fewer blind spots.
Does it correlate findings? — This is the compound risk question. Correlation catches the attack paths that cause breaches.

Most tools compete on question 1. They list how many checks they run, how many services they cover, how many CIS benchmarks they implement. That's important but insufficient.

Question 2 is where breaches live. The settings that caused the Capital One breach were all individually detectable. The attack path they created together was not — because no tool was looking at the combination.

Generate Terminal Recordings for Your CLI Docs Without Touching asciinema

Bala Paranj — Tue, 14 Apr 2026 12:36:28 +0000

CLI documentation has a trust problem. Users read your examples, try to reproduce them, and get different output. Screenshots go stale the moment a flag name changes. And asking developers to manually record terminal sessions with asciinema is a workflow that doesn't scale.

I solved this by generating terminal recordings programmatically in Go. The recordings are asciicast v2 files — the same format asciinema uses — but they're produced by a build target, not a human. When the CLI changes, make docs-recordings regenerates everything.

The Problem

Stave has 18 demo scenarios showing different security evaluation workflows. Each scenario needs a terminal recording that shows the exact command being typed, the exact output produced, and the exact exit behavior.

Maintaining these manually would mean:

Install asciinema on every developer's machine
Record each scenario by hand (type the command, wait for output)
Re-record every time a flag name, output format, or control ID changes
Hope the recording environment matches production (same terminal width, same colors)

This doesn't work when your CLI is under active development with weekly flag renames and output format changes.

The Solution: Generate Recordings in Go

The genrecordings tool is a standalone Go program that:

Imports the demo scenario definitions
Runs the real stave binary against real observation data
Captures stdout/stderr
Produces asciicast v2 files with simulated typing

No asciinema installation required. The output is a .cast file that any asciinema-compatible player can render.

Asciicast v2 Format

The format is simple — newline-delimited JSON (NDJSON):

{"version": 2, "width": 120, "height": 40, "title": "stave: public-read"}
[0.000000, "o", "$ "]
[0.356112, "o", "s"]
[0.390732, "o", "t"]
[0.425352, "o", "a"]
[0.459972, "o", "v"]
[0.494592, "o", "e"]
[0.529212, "o", " "]
[0.563832, "o", "a"]
[0.598452, "o", "p"]
[0.633072, "o", "p"]
[0.667692, "o", "l"]
[0.702312, "o", "y"]
[1.200000, "o", " --controls ..."]
[2.500000, "o", "\r\n"]
[2.600000, "o", "{\n  \"schema_version\": \"out.v0.1\",\n  ..."]

Line 1: header with terminal dimensions and title.
Remaining lines: [timestamp_seconds, "o", "text"] — output events.

The generator simulates realistic typing by emitting one character at a time with randomized delays (30-100ms per keystroke), then dumps the full CLI output after a pause.

Determinism

Typing delays use a fixed random seed (rand.NewSource(42)). Combined with the --now flag on stave (which pins the evaluation timestamp), the same binary + same observations = byte-identical .cast files.

This means CI can verify recordings are fresh:

make docs-recordings
git diff --exit-code docs-content/recordings/
# If diff is non-empty, recordings are stale

Checksum-Based Skip

Before generating, the tool computes a SHA-256 hash over:

The stave binary itself
All observation JSON files for every scenario

If the hash matches the stored checksum in .recordings-checksum, generation is skipped entirely. This avoids pointless 30-second regeneration cycles during development when nothing relevant changed.

Embedding in Docusaurus

The .cast files are served as static assets. A React component wraps the asciinema-player library:

import React, { useEffect, useRef } from 'react';
import 'asciinema-player/dist/bundle/asciinema-player.css';

export default function AsciinemaPlayer({ src, ...opts }) {
  const ref = useRef(null);
  useEffect(() => {
    let player;
    import('asciinema-player').then((mod) => {
      player = mod.create(src, ref.current, {
        cols: 120, rows: 40,
        autoPlay: true, speed: 2,
        theme: 'monokai', ...opts,
      });
    });
    return () => { if (player) player.dispose(); };
  }, [src]);
  return <div ref={ref} />;
}

Usage in MDX:

import AsciinemaPlayer from '@site/src/components/AsciinemaPlayer';

## HIPAA Compliance Check

<AsciinemaPlayer src="/recordings/hipaa-compliance.cast" />

The user sees a terminal replay that shows exactly what happens when they run the command. The recording is always in sync with the current binary because it's generated from the same build.

What This Solves

Manual Recording	Generated Recording
Requires asciinema installed	Requires only Go
Human types the command	Program simulates typing
Output depends on environment	Output is deterministic
Re-record on every change	`make docs-recordings`
May not match production	Uses the real binary + real data
Varies between developers	Byte-identical across machines

When to Use This Pattern

CLI documentation sites — show users exactly what your tool produces
Demo pages — interactive-looking recordings without video hosting
Onboarding guides — step-by-step workflows with real output
Release notes — "here's what changed" with before/after recordings

When NOT to Use This

Interactive sessions — if the demo requires user input (prompts, confirmations), a real recording is better
Long-running processes — asciicast files get large for multi-minute sessions
GUI tools — this is strictly for terminal output

Your CLI's output is the recording data. You don't need a screen recorder — you need a program that runs your CLI and formats the output as asciicast events.

This system is built for Stave. The generator lives at cmd/genrecordings/ and produces 18 recordings covering security evaluation scenarios.

Applying clig.dev to a Go CLI — With an Automated Compliance Test

Bala Paranj — Tue, 14 Apr 2026 00:15:38 +0000

clig.dev is a set of guidelines for building command-line interfaces that are consistent, predictable, and human-friendly. Most teams treat these as aspirational — a checklist someone reviews once during a code review.

We automated it. A test walks our entire command tree and verifies every guideline at CI time. If someone adds a new command without a Long description, without examples, without SilenceUsage, or without exit code documentation, the build fails.

Here's how each guideline maps to concrete Go code, and the test that enforces it.

The Compliance Test

func TestCligCompliance(t *testing.T) {
    root := getRootCmd()

    // Walk the full command tree (including nested subcommands).
    var commands []*cobra.Command
    var walk func(cmd *cobra.Command)
    walk = func(cmd *cobra.Command) {
        commands = append(commands, cmd)
        for _, child := range cmd.Commands() {
            walk(child)
        }
    }
    for _, child := range root.Commands() {
        walk(child)
    }

    for _, cmd := range commands {
        name := cmd.CommandPath()
        if cmd.RunE == nil && cmd.Run == nil {
            continue // Skip group headers
        }

        t.Run(name, func(t *testing.T) {
            t.Run("has_long_description", func(t *testing.T) { ... })
            t.Run("long_starts_with_verb", func(t *testing.T) { ... })
            t.Run("documents_exit_codes", func(t *testing.T) { ... })
            t.Run("has_examples", func(t *testing.T) { ... })
            t.Run("silence_usage_set", func(t *testing.T) { ... })
            t.Run("silence_errors_set", func(t *testing.T) { ... })
            t.Run("format_flag_if_data_command", func(t *testing.T) { ... })
        })
    }
}

Seven checks per command. The test discovers commands dynamically — no manual list to maintain. When someone adds stave inspect newcommand, the test automatically verifies it meets all seven criteria.

Run it:

make clig-check
# or: go test ./cmd/ -run "TestCligCompliance|TestCligGlobalFlags" -count=1

Let's look at each guideline and how it's implemented.

1. Help Text: Long Description Starting With a Verb

clig.dev says: "Provide a detailed help text for every command. Start with a verb phrase that describes what the command does."

The Test

t.Run("long_starts_with_verb", func(t *testing.T) {
    long := strings.TrimSpace(cmd.Long)
    if long == "" {
        t.Skip("no Long description")
    }
    first := strings.SplitN(long, " ", 2)[0]
    if first != "" && first[0] >= 'a' && first[0] <= 'z' {
        t.Errorf("%s: Long description should start with a capitalized verb, got %q", name, first)
    }
})

The Implementation

Every command follows a template:

Long: `Gate applies a CI failure policy and returns exit code 3 when the policy fails.

Supported policies:
  - fail_on_any_violation
  - fail_on_new_violation
  - fail_on_overdue_upcoming

Inputs:
  --policy          CI failure policy mode (default: from project config)
  --in              Path to evaluation JSON
  --format, -f      Output format: text or json (default: text)

Outputs:
  stdout            Gate result summary (text or JSON)
  stderr            Error messages (if any)

Exit Codes:
  0   - Policy passed; no violations detected
  2   - Invalid input or configuration error
  3   - Policy failed; violations detected
  130 - Interrupted (SIGINT)`,

The template has four sections: what it does (verb phrase), inputs (flags), outputs (stdout/stderr), and exit codes. This structure is enforced by the test — the "documents exit codes" check verifies the word "exit" appears in the Long text.

2. Exit Codes: Semantic, Not Binary

clig.dev says: "Use exit codes to indicate what happened. Don't just use 0 and 1."

The Implementation

const (
    ExitSuccess     = 0   // No issues
    ExitSecurity    = 1   // Security-audit gating failure
    ExitInputError  = 2   // Invalid input, flags, or schema validation
    ExitViolations  = 3   // Evaluation completed — findings detected
    ExitInternal    = 4   // Unexpected internal error (bug)
    ExitInterrupted = 130 // Interrupted by SIGINT (Ctrl+C)
)

Exit code 3 is the critical design decision. The tool succeeded — it ran correctly and found violations. That's not an error (exit 1 or 2). It's a policy signal. CI pipelines can branch:

stave apply --controls controls --observations observations
case $? in
    0)   echo "Clean" ;;
    2)   echo "Bad input" ; exit 1 ;;
    3)   echo "Violations found" ; exit 1 ;;
    4)   echo "Bug — report it" ; exit 1 ;;
esac

The Test

t.Run("documents_exit_codes", func(t *testing.T) {
    if cmd.RunE == nil {
        t.Skip("group command")
    }
    if !strings.Contains(strings.ToLower(cmd.Long), "exit") {
        t.Errorf("%s: Long description should document exit codes", name)
    }
})

Every leaf command must mention "exit" in its Long description. The test doesn't check the specific codes — just that exit code documentation exists.

3. --format on Data Commands

clig.dev says: "If your command produces structured data, offer --format for machine-readable output."

The Test

t.Run("format_flag_if_data_command", func(t *testing.T) {
    if !isDataCommand(cmd) {
        t.Skip("not a data command")
    }
    f := cmd.Flags().Lookup("format")
    if f == nil {
        f = cmd.InheritedFlags().Lookup("format")
    }
    if f == nil {
        t.Errorf("%s: data-producing command lacks --format flag", name)
    }
})

isDataCommand maintains an explicit list of commands that produce multi-format output:

func isDataCommand(cmd *cobra.Command) bool {
    multiFormatCommands := map[string]bool{
        "stave apply":             true,
        "stave diagnose":          true,
        "stave validate":          true,
        "stave report":            true,
        "stave security-audit":    true,
        "stave ci gate":           true,
        "stave snapshot diff":     true,
        "stave snapshot quality":  true,
        "stave snapshot upcoming": true,
        "stave controls list":     true,
    }
    return multiFormatCommands[cmd.CommandPath()]
}

Adding a new data command to this map and forgetting the --format flag fails the test.

4. SilenceUsage and SilenceErrors

clig.dev says: "Don't dump usage information on every error. It's noise."

The Problem

By default, Cobra prints the full usage text whenever a command returns an error. A missing file produces 50 lines of flag documentation followed by a one-line error message. The user has to scroll up to find the actual problem.

The Implementation

Every leaf command sets:

cmd := &cobra.Command{
    Use:           "gate",
    SilenceUsage:  true,
    SilenceErrors: true,
    RunE: func(cmd *cobra.Command, _ []string) error {
        // ...
    },
}

SilenceUsage: true — Cobra doesn't print usage on error. The error message alone is shown.
SilenceErrors: true — Cobra doesn't print the error. The executor handles error rendering with structured ErrorInfo (code, title, message, action, URL).

The Test

t.Run("silence_usage_set", func(t *testing.T) {
    if cmd.RunE == nil {
        t.Skip("no RunE")
    }
    if !cmd.SilenceUsage {
        t.Errorf("%s: SilenceUsage should be true", name)
    }
})

t.Run("silence_errors_set", func(t *testing.T) {
    if cmd.RunE == nil {
        t.Skip("no RunE")
    }
    if !cmd.SilenceErrors {
        t.Errorf("%s: SilenceErrors should be true", name)
    }
})

5. --version, --quiet, --no-color, --verbose

clig.dev says: "Provide global flags for version, quiet mode, verbose mode, and color control."

The Test

func TestCligGlobalFlags(t *testing.T) {
    root := getRootCmd()

    if root.Version == "" {
        t.Error("root command has empty Version")
    }

    requiredGlobals := []struct {
        name string
        why  string
    }{
        {"quiet", "CLIG: --quiet suppresses non-essential output"},
        {"verbose", "CLIG: -v enables verbose/debug output"},
        {"no-color", "CLIG: --no-color disables ANSI output"},
    }

    for _, rf := range requiredGlobals {
        t.Run(rf.name, func(t *testing.T) {
            f := root.PersistentFlags().Lookup(rf.name)
            if f == nil {
                t.Errorf("root command missing --%s flag (%s)", rf.name, rf.why)
            }
        })
    }
}

All four are persistent flags on the root command — available to every subcommand.

6. NO_COLOR and TTY Detection

clig.dev says: "Respect the NO_COLOR environment variable. Don't output ANSI codes when stdout is not a terminal."

The Implementation

A five-level cascade determines whether to use color:

func (r *Runtime) CanColor(out io.Writer) bool {
    // 1. Explicit --no-color flag
    if r != nil && r.NoColor {
        return false
    }
    // 2. NO_COLOR environment variable (https://no-color.org)
    if _, noColor := os.LookupEnv("NO_COLOR"); noColor {
        return false
    }
    // 3. TERM=dumb
    if strings.EqualFold(os.Getenv("TERM"), "dumb") {
        return false
    }
    // 4. Test override
    if r != nil && r.IsTTY != nil {
        return *r.IsTTY
    }
    // 5. Actual TTY detection (cached per file descriptor)
    return detectTTY(out)
}

Priority order: explicit flag > environment > terminal type > test override > runtime detection. The result is cached per file descriptor via sync.Map — checking the same os.Stdout twice doesn't make two syscalls.

7. stderr for Diagnostics, stdout for Data

clig.dev says: "Write data to stdout. Write messages, logs, and progress to stderr."

The Implementation

Progress spinners write to stderr:

func (r *Runtime) BeginProgress(label string) func() {
    errOut := r.stderr()  // Always stderr, never stdout
    if !r.isTerminal(errOut) {
        fmt.Fprintf(errOut, "Running: %s...\n", label)
        // ...
    }
    // Spinner frames go to errOut
}

Hints and next-step suggestions write to stderr:

func (r *Runtime) PrintNextSteps(steps ...string) {
    if r.Quiet || len(steps) == 0 {
        return
    }
    fmt.Fprintln(r.stderr(), "\nNext steps:")
    for _, s := range steps {
        fmt.Fprintf(r.stderr(), "  %s\n", s)
    }
}

Data (findings, reports, JSON) writes to stdout:

RunE: func(cmd *cobra.Command, _ []string) error {
    result, err := evaluate(...)
    return jsonutil.WriteIndented(cmd.OutOrStdout(), result)
}

This means stave apply --format json | jq .findings works — progress messages and hints go to stderr and don't contaminate the JSON on stdout.

8. "Did You Mean?" Suggestions

clig.dev says: "If the user makes a typo, suggest the closest valid command or flag value."

The Implementation

For unknown commands:

func SuggestCommandError(err error, commandNames []string) error {
    unknown := extractUnknownCommand(err.Error())
    if unknown == "" {
        return err
    }
    suggestion := ClosestToken(unknown, commandNames)
    if suggestion == "" || suggestion == unknown {
        return err
    }
    return fmt.Errorf("unknown command %q\nDid you mean %q?", unknown, suggestion)
}

For invalid --format values:

func ResolveFormatValue(raw string, valid []string) (OutputFormat, error) {
    normalized := NormalizeToken(raw)
    for _, v := range valid {
        if normalized == v {
            return OutputFormat(v), nil
        }
    }
    if suggestion := ClosestToken(normalized, valid); suggestion != "" {
        return "", fmt.Errorf("invalid --format %q\nDid you mean %q?", raw, suggestion)
    }
    return "", fmt.Errorf("invalid --format %q (use %s)", raw, enumList(valid))
}

The ClosestToken function uses Levenshtein edit distance — if the input is within 2 edits of a valid value, it's suggested. stave apply --format jso → Did you mean "json"?

9. Graceful SIGINT Handling

clig.dev says: "Handle Ctrl+C gracefully. Clean up resources. Use exit code 130."

The Implementation

func (a *App) installInterruptHandler() func() {
    sigCh := make(chan os.Signal, 1)
    signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM)

    go func() {
        select {
        case <-sigCh:
            fmt.Fprintln(os.Stderr, "Interrupted")
            if a.cancel != nil {
                a.cancel()  // Cancel context, operations unwind
            }
        case <-done:
            return
        }
    }()
    // ...
}

Context cancellation, not os.Exit. Deferred cleanup runs. Exit code 130 (128 + SIGINT signal number 2) — the Unix convention that CI tools understand.

10. Examples: Realistic, Copy-Pasteable

clig.dev says: "Show examples that work. Use realistic values, not 'foo' and 'bar'."

The Implementation

Example: `  # Standard evaluation
  stave apply --controls controls --observations observations --max-unsafe 168h

  # JSON output for automation
  stave apply --format json > evaluation.json

  # Quiet mode with exit code only
  stave apply --quiet --max-unsafe 7d

  # Deterministic evaluation for CI
  stave apply --now 2026-01-11T00:00:00Z --format json`,

Real flag values (168h, 7d), real paths (controls, observations), real workflows (pipe to file, CI with --now). A user can copy-paste any example and it works with the test data that ships with the tool.

The Test

t.Run("has_examples", func(t *testing.T) {
    if cmd.RunE == nil {
        t.Skip("group command")
    }
    if strings.TrimSpace(cmd.Example) == "" {
        t.Errorf("%s: missing Example (CLIG: show realistic usage)", name)
    }
})

The Full Checklist

clig.dev Guideline	Implementation	Enforced By
Detailed help text	`Long:` field with verb-phrase + template	`TestCligCompliance/has_long_description`
Help starts with verb	Capitalized verb phrase	`TestCligCompliance/long_starts_with_verb`
Document exit codes	Exit codes section in Long text	`TestCligCompliance/documents_exit_codes`
Realistic examples	`Example:` field with copy-pasteable commands	`TestCligCompliance/has_examples`
Don't dump usage on error	`SilenceUsage: true`	`TestCligCompliance/silence_usage_set`
Custom error rendering	`SilenceErrors: true` + ErrorInfo	`TestCligCompliance/silence_errors_set`
--format on data commands	`-f` flag on multi-format commands	`TestCligCompliance/format_flag_if_data_command`
--version	Root command `Version` field	`TestCligGlobalFlags`
--quiet	Persistent flag, resolves io.Writer	`TestCligGlobalFlags`
--verbose	Persistent flag, controls slog level	`TestCligGlobalFlags`
--no-color	Persistent flag + NO_COLOR env + TTY detection	`TestCligGlobalFlags`
stderr for diagnostics	Progress, hints, errors → stderr	Code review (not automated)
"Did you mean?"	Edit distance suggestions for commands and flags	Code review (not automated)
SIGINT handling	Context cancellation, exit 130	Code review (not automated)

10 guidelines enforced by automated tests. 4 enforced by code review. The test runs in CI on every commit — a new command without proper help text, examples, or exit code documentation breaks the build.

The TestCligCompliance test walks the entire command tree of Stave, a Go CLI with 30+ commands. Adding a new command automatically triggers 7 compliance checks. make clig-check runs in under a second.

5 Builder Patterns in Go — None of Them Are the Textbook Version

Bala Paranj — Sun, 12 Apr 2026 12:41:59 +0000

The textbook builder pattern has a Director, a Builder interface, a ConcreteBuilder, and a Product. In Go, you need none of that. What you need is a way to construct complex objects without 15-parameter constructors, without forgetting required fields, and without making tests unreadable.

Here are five builder patterns from a Go security CLI. Each solves a different construction problem. None of them involve a Director.

1. The Fluent Builder — When Construction Is the API

The Problem

A security finding has 7 fields: rule ID, severity, message, remediation, fix command, resource attributes, and sensitive attributes. Some are required, some are optional, some need special handling (sensitive data must be marked for redaction).

A constructor with 7 parameters:

f := diag.NewFinding("CTL.MISSING.ID", diag.SeverityError,
    "Control ID is missing",
    "Add a unique 'id' to the control definition",
    "",  // no fix command
    map[string]string{"control_id": "CTL.S3.PUBLIC.001"},
    map[string]string{"error": err.Error()},  // sensitive
)

Which string is the message? Which is the remediation? What's that empty string? The reader has to count positions.

The Pattern

type Builder struct {
    finding Finding
}

func NewFinding(rule RuleID) *Builder {
    return &Builder{
        finding: Finding{
            RuleID:   rule,
            Severity: SeverityError,
            Resource: kernel.NewSanitizableMap(nil),
        },
    }
}

func (b *Builder) Error() *Builder {
    b.finding.Severity = SeverityError
    return b
}

func (b *Builder) Warning() *Builder {
    b.finding.Severity = SeverityWarn
    return b
}

func (b *Builder) Message(msg string) *Builder {
    b.finding.Message = msg
    return b
}

func (b *Builder) Remediation(r string) *Builder {
    b.finding.Remediation = r
    return b
}

func (b *Builder) FixCommand(cmd string) *Builder {
    b.finding.FixCommand = cmd
    return b
}

func (b *Builder) Attribute(key, value string) *Builder {
    b.finding.Resource.Set(key, value)
    return b
}

func (b *Builder) SensitiveAttribute(key, value string) *Builder {
    b.finding.Resource.SetSensitive(key, value)
    return b
}

func (b *Builder) Build() Finding {
    f := b.finding
    f.Resource = b.finding.Resource.Clone()  // Defensive copy
    return f
}

Usage reads like a sentence:

issue := diag.NewFinding(diag.RuleControlMissingID).
    Error().
    Message("Control ID is missing").
    Remediation("Add a unique 'id' (e.g., CTL.S3.PUBLIC.001) to the control definition").
    Attribute("control_id", ctl.ID.String()).
    SensitiveAttribute("error", err.Error()).
    Build()

Every call site is self-documenting. No positional ambiguity. Optional fields are simply omitted. The Build() method returns a value (not a pointer) with a defensively cloned resource map — the builder can be reused without aliasing.

Design Details

Why Error() returns *Builder, not *Finding: Severity is set inline in the chain, not at construction time. A finding starts as SeverityError by default. Calling .Warning() changes it. This is a departure from the textbook builder where "set severity" would be just another setter — here the method name IS the severity, making the chain readable.

Why Build() clones the resource map: The SanitizableMap tracks which keys are sensitive (for log redaction vs report display). Without cloning, two findings built from the same builder would share the same map. Mutating one finding's attributes would corrupt the other.

Why no Validate() in Build: The finding is structurally valid by construction — RuleID is required (passed to NewFinding), severity has a default, everything else is optional. There's nothing to validate. If RuleID were optional, Build() should return (Finding, error).

2. The Parameter Object — When a Function Has Too Many Inputs

The Problem

Creating a duration-based violation finding requires 6 pieces of data: the asset's exposure lifecycle, the control definition, the SLA threshold, the current time, cloud identities, and a predicate parser. As individual parameters:

func CreateDurationFinding(
    lifecycle *asset.ExposureLifecycle,
    control *policy.ControlDefinition,
    threshold time.Duration,
    now time.Time,
    identities []asset.CloudIdentity,
    predicateParser policy.PredicateParser,
) *evaluation.Finding {

Six parameters. If you need to add a seventh (say, a trace span), every call site changes.

The Pattern

Group related parameters into a named struct:

type DurationFindingInput struct {
    ExposureLifecycle *asset.ExposureLifecycle
    Control           *policy.ControlDefinition
    Threshold         time.Duration
    Now               time.Time
    Identities        []asset.CloudIdentity
    PredicateParser   policy.PredicateParser
}

func CreateDurationFinding(in DurationFindingInput) *evaluation.Finding {
    a := in.ExposureLifecycle.Asset()
    duration, _ := in.ExposureLifecycle.ExposureDuration(in.Now)
    ctx := policy.NewAssetEvalContext(a, in.Control.Params, in.PredicateParser, in.Identities...)
    misconfigs := policy.ExtractMisconfigurations(&in.Control.UnsafePredicate, ctx)

    f := newBaseFinding(in.Control, in.ExposureLifecycle)
    f.Evidence = evaluation.Evidence{
        FirstUnsafeAt:       in.ExposureLifecycle.FirstExposedAt(),
        LastSeenUnsafeAt:    in.ExposureLifecycle.LastObservedAt(),
        UnsafeDurationHours: duration.Hours(),
        ThresholdHours:      in.Threshold.Hours(),
        Misconfigurations:   misconfigs,
        // ...
    }
    return f
}

Call site is explicit about what each value means:

finding := CreateDurationFinding(DurationFindingInput{
    ExposureLifecycle: lifecycle,
    Control:           ctl,
    Threshold:         maxUnsafe,
    Now:               now,
    Identities:        ids.At(lifecycle.LastObservedAt()),
    PredicateParser:   deps.predicateParser(),
})

Why Not a Builder Here

A builder would add ceremony without value. There are no optional fields — all 6 are required for every finding. There's no conditional logic during construction — every field is set once and used once. The parameter object gives you named fields (readable) without method chains (unnecessary).

The rule: use a builder when construction has conditional steps, defaults, or validation. Use a parameter object when construction is a straight transfer of all inputs.

3. The Dependency Aggregator — When Wiring Is the Complexity

The Problem

The apply command needs to build evaluation dependencies from 12+ sources: a logger, stdout/stderr writers, stdin, sanitizer, output format, hasher, CLI options, resolved parameters, three factory functions, project config, config path, and a progress callback. This isn't object construction — it's dependency wiring.

The Pattern

A builder struct that collects dependencies from multiple sources, then wires them into the target:

type Builder struct {
    Logger    *slog.Logger
    Stdout    io.Writer
    Stderr    io.Writer
    Stdin     io.Reader
    Sanitizer kernel.Sanitizer
    Format    appcontracts.OutputFormat
    Digester  ports.Digester
    Tracer    ports.Tracer

    Opts             *Options
    Params           applyParams
    NewFindingWriter compose.FindingWriterFactory
    NewCtlRepo       compose.CtlRepoFactory
    NewStdinObsRepo  func(io.Reader) (appcontracts.ObservationRepository, error)

    ProjectConfig     *appconfig.WorkspacePolicy
    ProjectConfigPath string
    OnObsProgress     func(processed, total int)
}

The Build method orchestrates the wiring — creating adapters, loading configs, resolving options, and assembling the final ApplyDeps:

func (b *Builder) Build(ctx context.Context, plan *EvaluationPlan) (*ApplyDeps, error) {
    a, err := b.buildAdapters()
    if err != nil {
        return nil, fmt.Errorf("build adapters: %w", err)
    }

    exemptionCfg, err := loadExemptionConfig(b.Opts.ExemptionFile)
    if err != nil {
        return nil, fmt.Errorf("load exemption config: %w", err)
    }

    projCfgInput, err := b.buildProjectConfigFromLoaded(b.ProjectConfig)
    if err != nil {
        return nil, fmt.Errorf("resolve project config: %w", err)
    }

    celEval, err := stavecel.NewPredicateEval()
    if err != nil {
        return nil, fmt.Errorf("initialize CEL evaluator: %w", err)
    }

    built, err := appeval.BuildDependencies(ctx, &appeval.BuildDependenciesInput{
        // ... wire everything together
    })
    if err != nil {
        return nil, err
    }
    return built, nil
}

Why Exported Fields, Not Methods

The dependency aggregator uses exported fields (Logger, Opts, NewCtlRepo) instead of WithLogger(), WithOpts() methods. This is intentional:

Fields are set from different sources at different times. The logger comes from bootstrap, the opts from flag parsing, the factories from provider construction. Method chains assume linear construction.
Fields are read by multiple methods. buildAdapters(), buildProjectConfigFromLoaded(), and Build() all read from the builder's fields. With methods, you'd need private fields plus getters.
No construction validation needed. A nil factory will fail at Build() time with a clear error, not at field-set time.

The difference from a fluent builder: the dependency aggregator collects inputs from 5 different sources across the request lifecycle, then produces the output in one Build() call. A fluent builder constructs linearly.

4. The Test Builder — When Setup Is the Noise

The Problem

Every assessor test requires the same boilerplate:

a := &Assessor{
    Controls: []policy.ControlDefinition{
        {
            ID:       "CTL.A.001",
            Name:     "Test",
            Severity: policy.SeverityHigh,
            Type:     policy.TypeUnsafeState,
        },
    },
    SLAThreshold: 1 * time.Hour,
    Clock:        stubClock{t: base.Add(48 * time.Hour)},
    Exemptions:   policy.NewExemptionConfig("", nil),
    Exceptions:   policy.NewExceptionConfig(nil),
    PredicateEval: func(_ policy.ControlDefinition, _ asset.Asset, _ []asset.CloudIdentity) (bool, error) {
        return true, nil
    },
}

18 lines. The test cares about SLAThreshold and PredicateEval. The other 12 lines are required non-nil values that are identical across 16 tests.

The Pattern

A test-only builder with intent-revealing methods:

type assessorBuilder struct {
    clock         ports.Clock
    sla           time.Duration
    controls      []policy.ControlDefinition
    predicateEval policy.PredicateEval
    exemptions    *policy.ExemptionConfig
    exceptions    *policy.ExceptionConfig
    tracer        ports.Tracer
}

func newTestAssessor() *assessorBuilder {
    return &assessorBuilder{
        clock:      stubClock{t: time.Date(2026, 1, 15, 0, 0, 0, 0, time.UTC)},
        sla:        168 * time.Hour,
        exemptions: policy.NewExemptionConfig("", nil),
        exceptions: policy.NewExceptionConfig(nil),
    }
}

func (b *assessorBuilder) withClock(t time.Time) *assessorBuilder {
    b.clock = stubClock{t: t}
    return b
}

func (b *assessorBuilder) withSLA(d time.Duration) *assessorBuilder {
    b.sla = d
    return b
}

func (b *assessorBuilder) alwaysUnsafe() *assessorBuilder {
    b.predicateEval = func(_ policy.ControlDefinition, _ asset.Asset, _ []asset.CloudIdentity) (bool, error) {
        return true, nil
    }
    return b
}

func (b *assessorBuilder) alwaysSafe() *assessorBuilder {
    b.predicateEval = func(_ policy.ControlDefinition, _ asset.Asset, _ []asset.CloudIdentity) (bool, error) {
        return false, nil
    }
    return b
}

func (b *assessorBuilder) build() *Assessor {
    a := NewAssessor()
    a.Clock = b.clock
    a.SLAThreshold = b.sla
    a.Controls = b.controls
    a.Exemptions = b.exemptions
    a.Exceptions = b.exceptions
    a.PredicateEval = b.predicateEval
    a.Tracer = b.tracer
    return a
}

Now the test reads as intent:

a := newTestAssessor().
    withClock(base.Add(48 * time.Hour)).
    withSLA(1 * time.Hour).
    withControls(newTestControl("CTL.A.001").build()).
    alwaysUnsafe().
    build()

8 lines. Every line conveys what the test cares about. alwaysUnsafe() is more readable than a 3-line anonymous function. withSLA(1 * time.Hour) is more readable than SLAThreshold: 1 * time.Hour buried in a 18-line struct literal.

The Timeline Builder

Snapshot construction has the same problem — each snapshot needs a timestamp and an asset list, but the structure is always the same:

// Before: 12 lines
snapshots := []asset.Snapshot{
    {
        CapturedAt: base,
        Assets:     []asset.Asset{{ID: "bucket-1", Type: "s3_bucket"}},
    },
    {
        CapturedAt: base.Add(48 * time.Hour),
        Assets:     []asset.Asset{{ID: "bucket-1", Type: "s3_bucket"}},
    },
}

// After: 3 lines
snaps := newTimeline(base).
    at(0, "bucket-1").
    at(48*time.Hour, "bucket-1").
    build()

The at method takes an offset from the base time and asset IDs. The struct construction is hidden inside the builder. Adding a third snapshot is one line, not four.

Why Test Builders Are Unexported

The builder types (assessorBuilder, controlBuilder, timelineBuilder) are unexported and live in _test.go files. They're test infrastructure, not production API. Keeping them unexported:

Prevents production code from depending on test helpers
Allows free refactoring without versioning concerns
Keeps the test package's public API clean

5. The Error Chain Builder — When the Product IS the Chain

The Pattern

ErrorInfo uses With* methods that return the same pointer — not a builder that produces a separate product, but the product that builds itself:

func NewErrorInfo(code ErrorCode, message string) *ErrorInfo {
    return &ErrorInfo{Code: code, Message: message}
}

func (e *ErrorInfo) WithTitle(t string) *ErrorInfo {
    if e != nil { e.Title = t }
    return e
}

func (e *ErrorInfo) WithAction(a string) *ErrorInfo {
    if e != nil { e.Action = a }
    return e
}

func (e *ErrorInfo) WithURL(u string) *ErrorInfo {
    if e != nil { e.URL = u }
    return e
}

Usage:

return NewErrorInfo(CodeViolationsFound, message).
    WithTitle("Violations detected").
    WithAction("Review findings and run `stave diagnose` for root-cause guidance.").
    WithURL("https://docs.stave.dev/troubleshooting")

Why Nil-Safe Methods

Every With* method checks if e != nil. This allows chaining from a function that might return nil:

func errorInfoFromError(err error) *ErrorInfo {
    if tmpl, ok := sentinelTemplates[ExitCode(err)]; ok {
        return NewErrorInfo(tmpl.Code, err.Error()).
            WithTitle(tmpl.Title).
            WithAction(tmpl.Action)
    }
    return nil  // No ErrorInfo for this error type
}

// Caller doesn't need to check nil before calling With*:
info := errorInfoFromError(err)
info.WithURL(docsRef)  // Safe even if info is nil

Why No `Build()`

ErrorInfo doesn't have a Build() method because it IS the product. The With* methods mutate the struct directly. This is fine because:

ErrorInfo is always constructed fresh (NewErrorInfo allocates)
It's not shared between goroutines
There's no invariant that could be violated by partial construction

If ErrorInfo were shared or needed validation, a separate builder with Build() would be correct. For a one-shot construction that's immediately rendered, the self-building pattern is simpler.

Choosing the Right Builder

Situation	Pattern	Key Indicator
Complex object with optional fields and validation	Fluent builder with `Build()`	Fields have defaults, some are optional, output needs defensive copying
Function with 6+ required parameters	Parameter object (struct)	All fields are required, no conditional construction
Dependencies from multiple sources	Dependency aggregator	Inputs arrive at different times, `Build()` does orchestration
Test setup is drowning the test intent	Test builder with intent methods	`alwaysUnsafe()` is clearer than a 3-line closure
One-shot object with optional decoration	Self-building with `With*`	No sharing, no validation, immediate consumption

The common thread: Go builders don't need a Director, a Builder interface, or a ConcreteBuilder. They need a struct, some methods that return *self, and optionally a Build() method that finalizes the product. The ceremony comes from the problem, not from the pattern.

These 5 builder patterns are used across Stave, a Go CLI for offline security evaluation. The fluent diagnostic builder constructs SARIF-compatible findings. The test builders reduced 18-line setup blocks to 8-line chains. The dependency aggregator wires 12+ dependencies from 5 different lifecycle stages.

4 Builder Patterns in Go That Aren't the Builder Pattern

Bala Paranj — Sat, 11 Apr 2026 13:46:06 +0000

The classic Builder pattern — New().WithX().WithY().Build() — is rare in Go. But the problem it solves (constructing complex objects with many optional fields) is everywhere.

In a Go CLI with 53 security controls, 20+ commands, and a security-audit pipeline with 14 finding builders, I used 4 different construction patterns. Each solved a specific problem that the others couldn't.

Pattern 1: Functional Options for Open-Ended Extension

The Problem

Security controls needed 7+ optional configuration fields. A constructor with 7 parameters was unreadable:

// BEFORE: Positional constructor — which string is which?
ctrl := NewDefinition(
    "CTL.S3.CONTROLS.001",       // id
    "Block Public Access",        // description
    Critical,                     // severity
    []string{"hipaa", "pci-dss"}, // profiles
    map[string]string{            // refs
        "hipaa": "§164.312(a)(1)",
    },
    "Access control — prevents public exposure", // rationale
    Critical,                     // severity override (or was it the same?)
)

Seven positional parameters. Three are strings. One is a map. The caller has to memorize the order. Adding an 8th parameter means changing every call site.

The Fix: Functional Options

// AFTER: Each option is named and self-documenting
type Option func(*Definition)

func WithID(id kernel.ControlID) Option {
    return func(d *Definition) { d.id = id }
}
func WithSeverity(s policy.Severity) Option {
    return func(d *Definition) { d.severity = s }
}
func WithComplianceRef(profile, citation string) Option {
    return func(d *Definition) {
        if d.complianceRefs == nil {
            d.complianceRefs = make(map[string]string)
        }
        d.complianceRefs[profile] = citation
    }
}
func WithProfileRationale(profile, rationale string) Option {
    return func(d *Definition) {
        if d.profileRationales == nil {
            d.profileRationales = make(map[string]string)
        }
        d.profileRationales[profile] = rationale
    }
}

func NewDefinition(opts ...Option) Definition {
    var d Definition
    for _, opt := range opts {
        opt(&d)
    }
    return d
}

Usage at the registration site:

func init() {
    ControlRegistry.MustRegister(&accessBlockPublic{
        Definition: NewDefinition(
            WithID("CTL.S3.CONTROLS.001"),
            WithDescription("Block Public Access must be fully enabled"),
            WithSeverity(Critical),
            WithComplianceProfiles("hipaa", "pci-dss", "cis-s3"),
            WithComplianceRef("hipaa", "§164.312(a)(1)"),
            WithProfileRationale("hipaa", "Prevents public exposure of ePHI"),
        ),
    })
}

Why functional options here:

New compliance profiles can be added without changing existing options
Optional fields (ProfileRationale, SeverityOverride) are omitted without placeholder nils
Each option initializes its own map — no caller-side make() boilerplate
Adding WithTimeout(d time.Duration) later requires zero changes to existing code

The same pattern was applied to the security-audit request with 14 options:

report, artifacts, err := runner.Run(ctx, NewRequest(
    WithNow(cfg.Now),
    WithStaveVersion(version.String),
    WithSeverityFilter(cfg.SeverityFilter),
    WithSBOMFormat(cfg.SBOMFormat),
    WithComplianceFrameworks(cfg.Frameworks),
    WithVulnSource(cfg.VulnSource),
    WithLiveVulnCheck(cfg.LiveVulnCheck),
    WithFailOn(cfg.FailOn),
    WithRequireOffline(cfg.RequireOffline),
))

14 options, each named, each optional, each independent.

Pattern 2: Spec Struct for Repetitive Construction

The Problem

14 security-audit finding builders each had the same 3-path pattern:

// BEFORE: Each builder repeated the same structure
func findingFromFSDisclosure(in PolicyInspectionSnapshot, err error) Finding {
    if err != nil {
        return Finding{
            ID:             CheckFSAccessDisclosure,
            Pillar:         PillarRuntime,
            Status:         outcome.Warn,
            Severity:       policy.SeverityMedium,
            Title:          "Filesystem disclosure incomplete",
            Details:        err.Error(),
            AuditorHint:    "Read/write footprint declaration could not be generated.",
            Recommendation: "Rerun security-audit with writable bundle directory.",
        }
    }
    return Finding{
        ID:             CheckFSAccessDisclosure,
        Pillar:         PillarRuntime,
        Status:         outcome.Pass,
        Severity:       policy.SeverityMedium,
        Title:          "Filesystem access declared",
        Details:        fmt.Sprintf("Declared %d read paths and %d write paths.", ...),
        AuditorHint:    "Bundle includes explicit read/write footprint for review.",
        Recommendation: "Review filesystem_access_declaration.json.",
    }
}

20 lines. 6 fields repeated (ID, Pillar, Severity). The same if err != nil / pass / fail structure in every builder. 14 copies.

The Fix: Spec Struct + Generic Builder

// Spec declares the three paths as data
type findingSpec struct {
    ID       CheckID
    Pillar   Pillar
    Severity policy.Severity

    // Error path
    ErrStatus outcome.Status
    ErrTitle  string
    ErrHint   string
    ErrReco   string

    // Pass path
    PassTitle string
    PassHint  string
    PassReco  string

    // Fail path
    FailStatus  outcome.Status
    FailTitle   string
    FailHint    string
    FailReco    string
}

// Generic builder handles the 3-path dispatch
func buildFinding(spec findingSpec, err error, pass bool, passDetails, failDetails string) Finding {
    base := Finding{
        ID:       spec.ID,
        Pillar:   spec.Pillar,
        Severity: spec.Severity,
    }
    switch {
    case err != nil:
        base.Status = spec.ErrStatus
        base.Title = spec.ErrTitle
        base.Details = err.Error()
        base.AuditorHint = spec.ErrHint
        base.Recommendation = spec.ErrReco
    case pass:
        base.Status = outcome.Pass
        base.Title = spec.PassTitle
        base.Details = passDetails
        base.AuditorHint = spec.PassHint
        base.Recommendation = spec.PassReco
    default:
        base.Status = spec.FailStatus
        base.Title = spec.FailTitle
        base.Details = failDetails
        base.AuditorHint = spec.FailHint
        base.Recommendation = spec.FailReco
    }
    return base
}

Usage:

// AFTER: Spec is data, builder handles dispatch
var fsDisclosureSpec = findingSpec{
    ID:       CheckFSAccessDisclosure,
    Pillar:   PillarRuntime,
    Severity: policy.SeverityMedium,
    ErrStatus: outcome.Warn,
    ErrTitle:  "Filesystem disclosure incomplete",
    ErrHint:   "Read/write footprint declaration could not be generated.",
    ErrReco:   "Rerun security-audit with writable bundle directory.",
    PassTitle: "Filesystem access declared",
    PassHint:  "Bundle includes explicit read/write footprint for review.",
    PassReco:  "Review filesystem_access_declaration.json.",
}

func findingFromFSDisclosure(in PolicyInspectionSnapshot, err error) Finding {
    details := fmt.Sprintf("Declared %d read and %d write paths.",
        len(in.Filesystem.Reads), len(in.Filesystem.Writes))
    return buildFinding(fsDisclosureSpec, err, true, details, "")
}

20 lines → 4 lines per builder. The spec is data. The builder is logic. Each new finding needs a spec (data) and a one-liner function (glue).

When NOT to use this: 7 complex builders were intentionally kept explicit because they had 4+ paths, extra parameters, or per-finding dynamic logic. The spec pattern would have been more complex than the hand-written version.

Pattern 3: Constructor with Sensible Defaults

The Problem

The evaluation engine had lazy defaults scattered across accessor methods:

// BEFORE: Defaults resolved lazily in accessors
type Runner struct {
    Logger          *slog.Logger
    MaxGapThreshold time.Duration
    Confidence      ConfidenceCalculator
}

func (r *Runner) maxGapThreshold() time.Duration {
    if r.MaxGapThreshold == 0 {
        return DefaultMaxGapThreshold  // ← lazy fallback
    }
    return r.MaxGapThreshold
}

func (r *Runner) confidenceCalculator() ConfidenceCalculator {
    if r.Confidence.HighMultiplier == 0 {
        return DefaultConfidenceCalculator()  // ← lazy fallback
    }
    return r.Confidence
}

Every accessor had a conditional fallback. The object's state was ambiguous — was MaxGapThreshold == 0 intentional or uninitialized?

The Fix: Constructor Sets Defaults

// AFTER: Defaults set at construction — accessors are simple returns
func NewAssessor() *Assessor {
    return &Assessor{
        Logger:          slog.Default(),
        ContinuityLimit: DefaultContinuityLimit,
        Confidence:      DefaultConfidenceCalculator(),
    }
}

func (a *Assessor) continuityLimit() time.Duration { return a.ContinuityLimit }
func (a *Assessor) confidenceCalculator() ConfidenceCalculator { return a.Confidence }

Callers override after construction if needed:

assessor := engine.NewAssessor()
assessor.Controls = catalog.List()
assessor.SLAThreshold = input.MaxUnsafeDuration
assessor.Clock = input.Clock
// ContinuityLimit and Confidence keep their defaults

Why constructor defaults here: The engine has 3 required fields (Controls, Clock, SLAThreshold) and 3 optional fields with sensible defaults (Logger, ContinuityLimit, Confidence). A constructor handles the defaults; callers set the required fields explicitly.

Pattern 4: Config Struct for CLI Command Wiring

The Problem

CLI command runners accepted dependencies as closure variables from RunE:

// BEFORE: Closure variables captured from Cobra
cmd := &cobra.Command{
    RunE: func(cmd *cobra.Command, args []string) error {
        // 8 variables captured from outer scope
        return runEvaluate(cmd, obsRepo, ctlRepo, marshaler, enrichFn,
            format, quiet, sanitizer)
    },
}

The runner function had 8 parameters. Testing required constructing a *cobra.Command to extract flags. The function was coupled to Cobra.

The Fix: Config Struct Decouples from Cobra

// AFTER: Config struct holds all resolved values
type AssessmentConfig struct {
    InventoryConfig
    SLAThreshold    time.Duration
    Clock           ports.Clock
    Hasher          ports.Digester
    Output          io.Writer
    ExemptionRules  *policy.ExemptionConfig
    ExceptionRules  *policy.ExceptionConfig
    BuildVersion    string
    PredicateEval   policy.PredicateEval
}

type AuditWorkflow struct {
    InventoryRepo   appcontracts.ObservationRepository
    PolicyRepo      appcontracts.ControlRepository
    ReportPublisher appcontracts.FindingMarshaler
    ContextEnricher appcontracts.EnrichFunc
}

func NewAuditWorkflow(invRepo, polRepo, publisher, enricher) *AuditWorkflow { ... }
func (w *AuditWorkflow) PerformAssessment(ctx context.Context, cfg AssessmentConfig) (ComplianceReport, SecurityState, error)

Cobra's RunE resolves flags into the config struct, then passes it:

RunE: func(cmd *cobra.Command, _ []string) error {
    cfg := AssessmentConfig{
        SLAThreshold: parsedMaxUnsafe,
        Clock:        resolvedClock,
        // ... all resolved from flags
    }
    workflow := NewAuditWorkflow(obsRepo, ctlRepo, marshaler, enricher)
    report, state, err := workflow.PerformAssessment(ctx, cfg)
}

Testing the workflow requires no Cobra:

// Test: no *cobra.Command needed
cfg := AssessmentConfig{SLAThreshold: 24 * time.Hour, Clock: ports.FixedClock(now)}
workflow := NewAuditWorkflow(mockObs, mockCtl, mockMarshaler, mockEnricher)
report, _, err := workflow.PerformAssessment(ctx, cfg)

When to Use Which

Pattern	Use When	Example
Functional Options	Open-ended optional fields; new options added over time	`NewDefinition(WithID(...), WithSeverity(...))`
Spec Struct	Repetitive construction with common paths; data varies, logic is fixed	`buildFinding(fsDisclosureSpec, err, pass, details)`
Constructor Defaults	Few required + few optional fields with known defaults	`NewAssessor()` then override `.Controls`, `.Clock`
Config Struct	Decoupling framework (Cobra) from business logic; testability	`AssessmentConfig{SLAThreshold: 24h}`

The wrong choice:

Functional options for 3-field structs → overkill
Config struct for domain objects → wrong layer (config is CLI, not domain)
Spec struct for one-off construction → premature abstraction
Constructor defaults for open-ended extension → can't add new fields without changing constructor

The Missing Pattern

Go doesn't need the classic Builder.WithX().WithY().Build() chain. The language provides:

Struct literals with named fields for simple cases
Functional options for open-ended extension
Spec structs for repetitive templates
Constructors for defaults
Config structs for boundary decoupling

The fluent builder chain adds indirection without value in Go. Named struct fields already prevent positional swap bugs. Functional options already handle optional parameters. The builder pattern's job is already done by the language.

These 4 patterns were applied across 60 refactorings in Stave, an offline configuration safety evaluator. The functional options pattern alone eliminated 98 lines of getter boilerplate across 14 security controls.

Boolean Blindness in Go: When true, false, true Tells You Nothing

Bala Paranj — Fri, 10 Apr 2026 12:31:28 +0000

Quick — what does this call do?

v.validateDocument(raw, yaml.Unmarshal, "YAML", "dsl_version",
    accepted, "control", true, "Fix control to match DSL schema", opts...)

What's the true? Is it strict? isYAML? overwrite? allowSymlink? You have to count parameters to find out. And if someone swaps the "YAML" and "dsl_version" strings, the compiler won't catch it — they're both string.

This is boolean blindness: when a function takes bool parameters whose meaning is invisible at the call site. The compiler sees true. The developer sees true. Neither sees "this enables YAML mode."

We found this pattern in five places and fixed each one differently.

1. Adjacent Bool Parameters — The File Safety Trap

Before: Three bools control security behavior

func SafeCreateFile(path string, perm os.FileMode, overwrite bool, allowSymlink bool) (*os.File, error) {
    // ...
}

// At the call site:
f, err := fsutil.SafeCreateFile(outputPath, 0o600, false, false)

What do the two false values mean? The reader must look up the function signature. And if someone writes SafeCreateFile(path, 0o600, true, true), they've just enabled file overwriting AND symlink following — two security-sensitive behaviors activated by an unreadable pair of booleans.

After: Named options struct

type WriteOptions struct {
    Perm         os.FileMode
    Overwrite    bool
    AllowSymlink bool
}

func DefaultWriteOpts() WriteOptions {
    return WriteOptions{
        Perm:         0o600,
        Overwrite:    false,
        AllowSymlink: false,
    }
}

func ConfigWriteOpts() WriteOptions {
    return WriteOptions{
        Perm:         0o644,
        Overwrite:    true,
        AllowSymlink: false,
    }
}

func SafeCreateFile(path string, opts WriteOptions) (*os.File, error) {
    // ...
}

The call site is now self-documenting:

// Sensitive output: conservative defaults
f, err := fsutil.SafeCreateFile(outputPath, fsutil.DefaultWriteOpts())

// Config file: allow overwrite, broader permissions
f, err := fsutil.SafeCreateFile(configPath, fsutil.ConfigWriteOpts())

// Custom: explicit about what's enabled
f, err := fsutil.SafeCreateFile(path, fsutil.WriteOptions{
    Perm:         0o600,
    Overwrite:    true,   // explicitly named
    AllowSymlink: false,  // explicitly named
})

Named factory functions (DefaultWriteOpts, ConfigWriteOpts) capture common combinations. Most callers use a factory instead of constructing the struct — the boolean values are encapsulated behind a meaningful name.

Security benefit: A code reviewer sees ConfigWriteOpts() and knows it allows overwrite. They don't have to count booleans. If a new option is added (say, AppendMode), existing call sites don't change — they get the default value from the factory.

2. The quiet Bool — Wrong Abstraction Level

Before: Every renderer checks a boolean

func writeOutput(w io.Writer, format OutputFormat, quiet bool, delta Delta) error {
    if quiet {
        return nil
    }
    // ... render output
}

func RenderJSON(eval Evaluation, version string, w io.Writer, quiet bool) error {
    if quiet {
        return nil
    }
    // ... render JSON
}

func printScaffoldSummary(w, stderr io.Writer, req SummaryRequest, quiet bool) {
    if quiet {
        return
    }
    // ... print summary
}

Five renderers. Each takes quiet bool. Each has if quiet { return nil } at the top. The quiet behavior is identical in every renderer — but it's implemented five times.

After: Resolve the writer, not the boolean

func ResolveStdout(w io.Writer, quiet bool, format OutputFormat) io.Writer {
    if quiet && !format.IsMachineReadable() {
        return io.Discard
    }
    return w
}

The renderer no longer knows about quiet mode:

// BEFORE: renderer decides whether to write
func writeOutput(w io.Writer, format OutputFormat, quiet bool, delta Delta) error {
    if quiet { return nil }
    // ...
}

// AFTER: renderer writes to whatever it receives
func writeOutput(w io.Writer, format OutputFormat, delta Delta) error {
    // ... always writes — if w is io.Discard, output is silently dropped
}

The caller resolves the writer once:

w := compose.ResolveStdout(cmd.OutOrStdout(), flags.Quiet, format)
writeOutput(w, format, delta)

Why this is better than removing the bool: The quiet decision is made once at the CLI boundary, not repeated in every renderer. The renderers are "dumb pipes" — they write to their writer without knowing or caring whether it's stdout or /dev/null. Adding a sixth renderer requires zero quiet-mode code.

The format-aware twist: ResolveStdout preserves JSON output even in quiet mode (IsMachineReadable()). A CI pipeline running stave apply --quiet --format json | jq .findings gets the JSON it needs. Only text output is silenced. This nuance was previously implemented inconsistently across the five renderers — one discarded JSON in quiet mode, breaking downstream tools.

3. Nine Positional Parameters — The Swap Hazard

Before: Strings and bools that look identical

func (v *Validator) validateDocument(
    raw []byte,
    unmarshal func([]byte, any) error,
    formatName string,      // "YAML" or "JSON"
    versionField string,    // "dsl_version" or "schema_version"
    accepted []string,      // ["ctrl.v1"] or ["obs.v0.1"]
    kind string,            // "control" or "observation"
    isYAML bool,            // true for YAML, false for JSON
    defaultAction string,   // "Fix control to match DSL schema"
    opts ...Option,
) (*diag.Result, error) {

Nine parameters. Four are string. Swapping formatName with versionField compiles fine — both are string. The caller:

v.validateDocument(raw, yaml.Unmarshal, "YAML", "dsl_version",
    accepted, "control", true, "Fix control to match DSL schema", opts...)

Which string is formatName? Which is kind? Which is defaultAction? You have to count. And if you miscount, the validator uses "YAML" as the version field name and "dsl_version" as the human-readable format label.

After: Config struct with named fields

type docConfig struct {
    Unmarshal     func([]byte, any) error
    FormatName    string
    VersionField  string
    Accepted      []string
    Kind          string
    IsYAML        bool
    DefaultAction string
}

func (v *Validator) validateDocument(raw []byte, cfg docConfig, opts ...Option) (*diag.Result, error) {
    // ...
}

The call site:

v.validateDocument(raw, docConfig{
    Unmarshal:     yaml.Unmarshal,
    FormatName:    "YAML",
    VersionField:  "dsl_version",
    Accepted:      []string{string(kernel.SchemaControl)},
    Kind:          string(schemas.KindControl),
    IsYAML:        true,
    DefaultAction: "Fix control to match DSL schema",
}, opts...)

Every value is labeled. FormatName: "YAML" can't be confused with Kind: "control". Adding a new parameter requires no change to existing call sites — it gets the zero value default.

4. Two Adjacent Bools — The Silent Swap

Before: apply and force are next to each other

func resolveMode(apply, force bool, archiveDir string) (Mode, bool) {
    if !apply || !force {
        return ModePreview, false
    }
    if archiveDir != "" {
        return ModeArchive, true
    }
    return ModePrune, true
}

At the call site:

mode, proceed := resolveMode(true, false, archiveDir)

Which true is apply? Which false is force? Swap them and the logic inverts — but it compiles fine.

After: Named parameters via struct

type ModeRequest struct {
    Apply      bool
    Force      bool
    ArchiveDir string
}

func resolveMode(req ModeRequest) (Mode, bool) {
    if !req.Apply || !req.Force {
        return ModePreview, false
    }
    if req.ArchiveDir != "" {
        return ModeArchive, true
    }
    return ModePrune, true
}

Call site:

mode, proceed := resolveMode(ModeRequest{
    Apply:      true,
    Force:      false,
    ArchiveDir: archiveDir,
})

No swap possible. Apply: true is unambiguous. If someone adds a DryRun bool to ModeRequest, existing call sites don't change.

5. The FindingWriterFactory — Hidden Bool in a Function Type

Before: Bool parameter in a type alias

type FindingWriterFactory = func(OutputFormat, bool) (FindingMarshaler, error)

What's the bool? At every call site:

marshaler, err := factory(format, false)

Is false JSON mode? Pretty print? Strict validation? You have to read the factory implementation to find out.

After: Explicit at the call site

The fix here wasn't changing the type — it was eliminating the bool's reason for existing. The bool was isJSONMode, which duplicated information already in OutputFormat:

// BEFORE: redundant bool
marshaler, err := factory(format, cfg.IsJSONMode)

// AFTER: format already carries the information
marshaler, err := factory(format, false)  // isJSONMode removed from config

The false literal is still there, but it's now always false — the JSON mode logic was consolidated into OutputFormat.IsJSON(). The next step is to remove the parameter entirely and update the function type.

The lesson: Before adding a parameter struct, ask whether the bool duplicates information that's already available. Sometimes the fix is removing the bool, not wrapping it.

The Decision Tree

Does the function take 2+ adjacent bools?
├── YES → Replace with an options struct
│
Does the function take 4+ parameters including bools and strings?
├── YES → Replace all params with a config struct
│
Is the bool controlling "output/no output"?
├── YES → Resolve the io.Writer at the boundary, not in the renderer
│
Does the bool duplicate info available elsewhere?
├── YES → Remove the bool, use the existing source
│
Is it a single bool with a clear name in a 2-3 param function?
└── YES → Keep it. Not everything needs a struct.

That last case matters. This is fine:

func (s Severity) Gte(other Severity) bool { return s >= other }
func (a Audience) IsExternal() bool { return a != AudiencePrivate }
func (ctl *ControlDefinition) IsEvaluatable() bool { ... }

Single bool return values and single bool parameters on short functions are readable. The problem is adjacent bools, positional bools, and bools that control behavior the caller should express differently.

These boolean blindness fixes were applied across Stave, a Go CLI for offline security evaluation. The WriteOptions struct replaced 3 security-sensitive bools with named fields and factory defaults. The quiet-to-io.Discard pattern eliminated 5 duplicate if quiet { return } checks. The docConfig struct replaced a 9-parameter function with labeled fields.

One Test File That Prevents All Architecture Regressions

Bala Paranj — Thu, 09 Apr 2026 12:00:37 +0000

Every team talks about hexagonal architecture. Almost no team enforces it.

You draw the dependency diagram: core/ never imports adapters/. adapters/ never imports cmd/. Everyone nods. Then a developer in a hurry adds import "internal/adapters/output" inside a core package because they need a JSON helper. The code review approves it because the reviewer is focused on the feature logic, not the import list.

Six months later, core/ imports from 4 adapter packages and nobody remembers when it started.

I wrote one test file that makes this impossible.

The Test

func TestCoreNeverImportsAdapters(t *testing.T) {
    forbidden := []string{
        "github.com/myapp/internal/adapters/",
        "github.com/myapp/internal/cli/",
        "github.com/myapp/cmd/",
        "os/exec",
    }

    corePackages := discoverPackages(t, "internal/core/")

    for _, pkg := range corePackages {
        for _, imp := range pkg.Imports {
            for _, banned := range forbidden {
                if strings.HasPrefix(imp, banned) {
                    t.Errorf("core package %s imports forbidden %s", 
                        pkg.Name, imp)
                }
            }
        }
    }
}

It walks every Go file in internal/core/, extracts the import list, and fails if any import matches a forbidden prefix. That's it.

What It Catches

Real violation: os/exec in core

When I added an E2E test runner to internal/core/enginetest/, the test immediately caught it:

core test isolation violation: internal/core/enginetest/e2e_test.go: imports os/exec

os/exec is an infrastructure dependency — it invokes external processes. It doesn't belong in core, even in test files. The E2E runner was moved to e2e/ at the repo root.

Without this test, the import would have stayed. It compiled fine. No reviewer would have caught it because os/exec in a test file looks reasonable.

Real violation: adapter type in port interface

A port interface in app/contracts/ accepted an adapter type as a parameter:

// BEFORE: Port contaminated with adapter type
type EvaluationLoader interface {
    Load(ctx context.Context, path string) (*adapters.Evaluation, error)
}

The test caught the import of adapters/ from the app/ layer. The fix: the port returns a domain type, and the adapter converts at the boundary.

// AFTER: Port uses only domain types
type EvaluationLoader interface {
    Load(ctx context.Context, path string) (*report.Assessment, error)
}

Why Code Reviews Aren't Enough

Code reviews catch architecture violations about 80% of the time. The other 20%:

The reviewer is focused on the feature logic, not import lists
The PR has 40 files and the violation is in file 37
The import looks reasonable in context ("I just need this one helper")
The reviewer doesn't know the architecture rules because they're in a wiki nobody reads

A test catches violations 100% of the time. It runs in CI on every push. It doesn't get tired, distracted, or rushed.

How to Build It

Step 1: Define your layers

internal/
  core/       → NEVER imports adapters, app, cmd, os/exec
  app/        → NEVER imports adapters, cmd
  adapters/   → May import core, app
  cli/        → May import anything
cmd/          → May import anything

Step 2: Discover packages programmatically

func discoverPackages(t *testing.T, root string) []PackageInfo {
    var packages []PackageInfo
    filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
        if !d.IsDir() && strings.HasSuffix(path, ".go") {
            imports := extractImports(path)
            packages = append(packages, PackageInfo{
                Path:    path,
                Imports: imports,
            })
        }
        return nil
    })
    return packages
}

Step 3: Check every import against the forbidden list

for _, pkg := range corePackages {
    for _, imp := range pkg.Imports {
        for _, banned := range forbidden {
            if strings.HasPrefix(imp, banned) {
                t.Errorf("%s imports forbidden %s", pkg.Path, imp)
            }
        }
    }
}

Step 4: Run it in CI

- name: Architecture check
  run: go test ./internal/app/ -run TestCoreNeverImportsAdapters

The ROI

This test is the most leveraged single commit in the codebase.

Over 4 months and 60 refactorings, every structural change had to pass this test. When we merged internal/infra/ into internal/adapters/, the test verified no core packages imported the old path. When we moved types between layers, the test verified the dependency direction.

Without it, the hexagonal boundaries would have eroded under the pressure of daily development. With it, the architecture is mechanically guaranteed.

The test took 30 minutes to write. It has prevented more regressions than any refactoring in the catalog.

What It Doesn't Catch

Logic violations: A function in core/ that formats CLI output text. The import is legal (fmt), but the responsibility is wrong. This still needs code review.
Interface design: A port with 10 methods (ISP violation). The import direction is correct but the interface is too fat. This needs design review.
Naming: A core package named utils instead of a domain concept. The architecture is fine but discoverability suffers.

The fitness function enforces the structural rules. Design and naming still need human judgment. But by automating the structural check, you free up code review time to focus on the things that require judgment.

Checkout the code in my open source project Stave. The architecture fitness function has been running in CI since January 2026 and has caught 4 violations that would have been missed in code review.

Accept Interfaces, Return Structs: 5 Patterns From a Go CLI

Bala Paranj — Wed, 08 Apr 2026 14:36:36 +0000

"Accept interfaces, return structs" is the most quoted Go proverb and the least applied. Most Go codebases do the opposite: they define interfaces at the implementation site, accept concrete types, and return interfaces.

Over 60 refactorings, I applied this proverb in 5 distinct ways. Each one solved a different coupling problem, but they all followed the same rule: the consumer defines the interface, the producer returns the concrete type.

Pattern 1: Decouple a Component from Its Container

The Problem

Evaluation strategies had a back-pointer to the concrete Runner:

// BEFORE: Strategy depends on the concrete Runner type
type unsafeStateStrategy struct {
    runner *Runner               // ← concrete dependency
    ctl    *policy.ControlDefinition
}

func (s *unsafeStateStrategy) Evaluate(t *asset.Timeline, now time.Time) (Row, []*Finding) {
    maxUnsafe := s.runner.getMaxUnsafeDurationForControl(s.ctl)
    logger := s.runner.Logger
    parser := s.runner.PredicateParser
    // ...
}

The strategy needed 4 things from the Runner: a max-unsafe duration, a logger, a gap threshold, and a predicate parser. But it depended on the entire Runner type — all 12 fields, all methods, the full dependency graph.

Testing a strategy meant constructing a full Runner with all its dependencies, even though the strategy only used 4 of them.

The Fix

Define a narrow interface at the consumer (the strategy), not at the producer (the Runner):

// AFTER: Strategy depends on a 4-method interface it defines
type strategyDeps interface {
    slaThresholdFor(ctl *policy.ControlDefinition) time.Duration
    continuityLimit() time.Duration
    logger() *slog.Logger
    predicateParser() policy.PredicateParser
}

type unsafeStateStrategy struct {
    deps strategyDeps            // ← interface, not concrete type
    ctl  *policy.ControlDefinition
}

func (s *unsafeStateStrategy) Evaluate(t *asset.ExposureLifecycle, now time.Time) (ResourceCheck, []*Finding) {
    maxUnsafe := s.deps.slaThresholdFor(s.ctl)
    // ...
}

The Runner (now Assessor) satisfies the interface implicitly — no implements keyword:

// Runner/Assessor satisfies strategyDeps without declaring it
func (a *Assessor) slaThresholdFor(ctl *policy.ControlDefinition) time.Duration {
    return ctl.EffectiveMaxUnsafeDuration(a.SLAThreshold)
}
func (a *Assessor) continuityLimit() time.Duration { return a.ContinuityLimit }
func (a *Assessor) logger() *slog.Logger           { return a.Logger }
func (a *Assessor) predicateParser() policy.PredicateParser { return a.PredicateParser }

Testing a strategy now requires a 4-method mock, not a 12-field constructor:

// Test: mock only what the strategy needs
type mockDeps struct{}
func (m mockDeps) slaThresholdFor(_ *policy.ControlDefinition) time.Duration { return 24 * time.Hour }
func (m mockDeps) continuityLimit() time.Duration { return 12 * time.Hour }
func (m mockDeps) logger() *slog.Logger { return slog.Default() }
func (m mockDeps) predicateParser() policy.PredicateParser { return nil }

After the refactor, strategies went from untestable (coupled to Runner) to independently testable.

Pattern 2: Slim a Fat Interface

The Problem

The Control interface had 8 methods:

// BEFORE: Fat interface — every implementor must provide 8 methods
type Control interface {
    ID() kernel.ControlID
    Description() string
    Severity() Severity
    ComplianceProfiles() []string
    ComplianceRefs() map[string]string
    ProfileRationale(profile string) string
    ProfileSeverityOverride(profile string) Severity
    Evaluate(snap asset.Snapshot) Result
}

Every control implementation had to provide 7 getter methods that all did the same thing: return a field from a Definition struct. The getters were boilerplate — 14 lines per control, identical across all 14 controls.

The Fix

Slim to 2 methods. Return a struct for the metadata:

// AFTER: 2-method interface — return struct for metadata
type Control interface {
    Def() Definition    // ← returns struct, not 7 methods
    Evaluate(snap asset.Snapshot) Result
}

The Definition struct carries all the metadata:

type Definition struct {
    id                kernel.ControlID
    description       string
    severity          Severity
    complianceProfiles []string
    complianceRefs    map[string]string
    // ...
}

func (d Definition) ID() kernel.ControlID { return d.id }
func (d Definition) Severity() Severity   { return d.severity }
// ... accessor methods on the struct, not the interface

Callers changed from ctrl.ID() to ctrl.Def().ID():

// BEFORE
controlID := ctrl.ID()
severity := ctrl.Severity()
refs := ctrl.ComplianceRefs()

// AFTER
controlID := ctrl.Def().ID()
severity := ctrl.Def().Severity()
refs := ctrl.Def().ComplianceRefs()

One extra .Def() call. But the interface dropped from 8 methods to 2. New controls only implement Evaluate — the metadata comes from the Definition struct built with functional options:

// Construction with functional options — no method boilerplate
type accessBlockPublic struct {
    Definition
}

func init() {
    ControlRegistry.MustRegister(&accessBlockPublic{
        Definition: NewDefinition(
            WithID("CTL.S3.CONTROLS.001"),
            WithSeverity(Critical),
            WithComplianceRef("hipaa", "§164.312(a)(1)"),
        ),
    })
}

func (ctl *accessBlockPublic) Evaluate(snap asset.Snapshot) Result {
    // Only the evaluation logic — no getter boilerplate
}

After the refactor — 14 controls lost 7 boilerplate methods each.

Pattern 3: Port Interfaces with Domain-Only Types

The Problem

A port interface in app/contracts imported a type from internal/core/evaluation/remediation:

// BEFORE: Port contaminated with business logic package
package contracts

import "github.com/sufield/stave/internal/core/evaluation/remediation"

type EnrichedResult struct {
    Findings []remediation.Finding  // ← port imports domain implementation
}

The port (in the app layer) depended on a specific domain package. Adapters that implemented the port had to import remediation even if they only needed the finding's ID and severity. The dependency arrow pointed inward (correct direction) but the coupling was too tight.

The Fix

Define a boundary type in the port package using only types the port already imports:

// AFTER: Port uses its own boundary type
package contracts

import (
    "github.com/sufield/stave/internal/core/evaluation"
    policy "github.com/sufield/stave/internal/core/controldef"
)

type EnrichedFinding struct {
    Finding     evaluation.Finding
    Remediation policy.RemediationSpec
}

type EnrichedResult struct {
    Findings []EnrichedFinding  // ← uses only types already in contracts
}

The enrichment pipeline maps at the boundary:

// Boundary conversion in the app layer
func enrich(findings []remediation.Finding) []contracts.EnrichedFinding {
    result := make([]contracts.EnrichedFinding, len(findings))
    for i, f := range findings {
        result[i] = contracts.EnrichedFinding{
            Finding:     f.Finding,
            Remediation: f.RemediationSpec,
        }
    }
    return result
}

Adapters convert back to remediation.Finding only when they need the full type — via local toRemediationFindings helpers.

After the refactor — port boundary no longer imports business logic packages.

Pattern 4: One-Method Interfaces at the Boundary

The Problem

Infrastructure capabilities were injected as concrete function types or large interfaces:

// BEFORE: Bare function type mixed with other concerns
type Runner struct {
    Logger      *slog.Logger
    Clock       func() time.Time      // ← bare function, no testability signal
    Hasher      func([]byte) string   // ← bare function
    Controls    []ControlDefinition
    MaxUnsafe   time.Duration
}

func() time.Time is technically an interface with one method — but it has no name, no documentation, and no discoverable implementations.

The Fix

Named one-method interfaces in a ports package:

// AFTER: Named interfaces with concrete implementations
package ports

type Clock interface {
    Now() time.Time
}

type RealClock struct{}
func (RealClock) Now() time.Time { return time.Now().UTC() }

type FixedClock time.Time
func (f FixedClock) Now() time.Time { return time.Time(f) }

type Digester interface {
    Digest(components []string, sep byte) kernel.Digest
}

type Verifier interface {
    Verify(data []byte, sig kernel.Signature) error
}

The consumer declares the dependency as a named interface:

type Assessor struct {
    Clock  ports.Clock     // ← named interface, not func() time.Time
    Hasher ports.Digester  // ← named interface, not func([]byte) string
}

Testing uses the provided implementations — no mocking framework needed:

// Test: deterministic time
assessor := &Assessor{
    Clock: ports.FixedClock(time.Date(2026, 1, 15, 0, 0, 0, 0, time.UTC)),
}

Each interface has exactly one method. Go's implicit interface satisfaction means any type with a Now() time.Time method satisfies Clock — including FixedClock, RealClock, or any test stub.

Pattern 5: Remove Unnecessary Interface Threading

The Problem

An IdentityGenerator interface was threaded through 4 levels of the call stack:

// BEFORE: Interface threaded through entire chain
func NewPlanner(idGen ports.IdentityGenerator) *Planner { ... }
func NewMapper(idGen ports.IdentityGenerator) *Mapper { ... }

type publicExposurePlanner struct {
    idGen ports.IdentityGenerator  // ← carried but used once at the end
}

func (p *publicExposurePlanner) Plan(findings []Finding) []RemediationPlan {
    for _, f := range findings {
        plan := RemediationPlan{
            ID: p.idGen.GenerateID("plan", string(f.ControlID), string(f.AssetID)),
            // ...
        }
    }
}

The ID generator was injected into the Planner, carried through the Mapper, and used at one point: generating plan IDs. Four constructors accepted it. Four structs stored it. One call site used it.

The Fix

Generate IDs at the boundary, not inside the domain:

// AFTER: Domain logic is pure — IDs assigned at boundary
func (p *publicExposurePlanner) Plan(findings []Finding) []RemediationPlan {
    for _, f := range findings {
        plan := RemediationPlan{
            ID: "",  // ← empty, assigned later at boundary
            // ...
        }
    }
}

// Boundary function assigns IDs after domain logic completes
func AssignPlanIDs(gen ports.IdentityGenerator, plans []RemediationPlan) {
    for i := range plans {
        plans[i].ID = gen.GenerateID("plan", ...)
    }
}

The Planner and Mapper are now pure domain types with no infrastructure dependencies. AssignPlanIDs is called once at the boundary after enrichment. The interface is accepted at the boundary, not threaded through the domain.

After the refactor — removed IdentityGenerator from 4 constructors and 4 struct fields.

The Rules

Rule	Before	After
Consumer defines the interface	Strategy imports `*Runner`	Strategy defines `strategyDeps` (4 methods)
Return structs, not interfaces	`Control` interface with 8 methods	`Def()` returns `Definition` struct
Ports use only domain types	Port imports `remediation.Finding`	Port defines `EnrichedFinding` boundary type
Name your one-method interfaces	`func() time.Time`	`ports.Clock` with `Now() time.Time`
Don't thread interfaces through domain	`IdentityGenerator` in 4 constructors	`AssignPlanIDs` at boundary

How to Find Violations

# Fat interfaces (more than 3 methods)
grep -rn 'type.*interface {' --include='*.go' -A 10 | grep -c 'func\b' | sort -rn

# Concrete type dependencies that should be interfaces
grep -rn '\*Runner\|\*Engine\|\*Service' --include='*.go' | grep 'struct {' | grep -v '_test.go'

# Interface threading (same interface in multiple constructors)
grep -rn 'ports\.' --include='*.go' | grep 'func New' | sort

# Port contamination (ports importing implementation packages)
grep -rn 'import' internal/app/contracts/ --include='*.go' | grep -v 'core/\|kernel\|asset'

The last command finds port packages importing implementation packages — the signal for Pattern 3.

The Payoff

Before these refactorings, testing the evaluation engine required constructing the full Runner with 12 fields. After, testing a strategy requires a 4-method mock. Testing the Planner requires no mocks at all — it's a pure function.

The interface count went down, not up. Fat interfaces were slimmed. Unnecessary interfaces were removed. The remaining interfaces are small (1-4 methods), defined at the consumer, and satisfied implicitly.

That's the Go way: interfaces should be discovered, not designed.

These 5 patterns were applied across 60 refactorings in Stave, an offline configuration safety evaluator.