@nielspeter/eess 0.2.1 → 0.4.0

package/dist/terminal-builder.js

@@ -1,29 +1,64 @@
+import { zeroExaminedViolation, deadGlobViolation, unmetExpectNonEmptyViolation, zeroLoadedSourceViolation, expiredExpectEmptyViolation, } from './vacuity-findings.js';
+import { UNSUPPRESSABLE } from './unsuppressable.js';
 import { isSilent } from './silent-exclusion.js';
 import { executeCheck, executeWarn, applyFilters } from './execute-rule.js';
+import { shallowClone } from './shallow-clone.js';
 /**
  * Abstract base class for builders that share the terminal method pattern
  * (because, rule, excluding, check, warn, severity) but have different
  * element collection and evaluation models.
  *
  * Used by SliceRuleBuilder, SchemaRuleBuilder, ResolverRuleBuilder,
- * PairFinalBuilder, and SmellBuilder — all of which implement the same
- * terminal methods but differ in how they collect and evaluate elements.
- *
- * RuleBuilder<T> does NOT extend this because it predates it and has
- * additional concerns (predicate/condition pipeline, fork semantics).
+ * PairFinalBuilder, SmellBuilder, CorrespondenceBuilder, TsconfigBuilder, and
+ * (as of plan 0088 Phase 4) RuleBuilder — all of which implement the same
+ * terminal methods and now share evidence-of-examination (ADR-010) alongside
+ * evaluation-model differences.
  */
 export class TerminalBuilder {
     _reason;
     _metadata;
     _exclusions = [];
     _silentIndices = new Set();
+    /** ADR-010 part 3 — `.expectEmpty()`/`.expectNonEmpty()`. `undefined` = no declaration. */
+    _expectEmpty;
+    /**
+     * Declare that this rule's examined set is expected to be empty. A pass is
+     * legitimate only while the declaration stays true — the day a unit is
+     * examined, this rule reddens (ADR-010 part 3's expiry property). The
+     * complement of `expectNonEmpty()`; declaring both is nonsensical and the
+     * later call wins (last-write, matching `.rule()`'s own semantics).
+     */
+    expectEmpty() {
+        const next = this.copy();
+        next._expectEmpty = true;
+        return next;
+    }
+    /**
+     * Declare that this rule's examined set must be non-empty — the opposite
+     * assertion, for a corpus the author has positive knowledge should never
+     * legitimately be empty. Unlike a bare, undeclared rule, this **overrides
+     * `assertsCardinality()`'s exemption**: a `.notExist()`-shaped condition
+     * that finds zero subjects normally passes silently (emptiness satisfies
+     * what it asserts) — but if the author declared `.expectNonEmpty()`, that
+     * silence is exactly what they said should never happen, so it reddens
+     * instead, naming the declaration as the reason. This is the real
+     * difference from not declaring anything: without it, a `.notExist()` rule
+     * over an accidentally-emptied corpus (a glob typo, a temporarily-missing
+     * folder) passes and says nothing; with it, that same emptiness is caught.
+     */
+    expectNonEmpty() {
+        const next = this.copy();
+        next._expectEmpty = false;
+        return next;
+    }
     /**
      * Attach a human-readable rationale to the rule.
      * Included in violation messages when `.check()` throws.
      */
     because(reason) {
-        this._reason = reason;
-        return this;
+        const next = this.copy();
+        next._reason = reason;
+        return next;
     }
     /**
      * Attach rich metadata to the rule.
@@ -32,11 +67,12 @@ export class TerminalBuilder {
      * If `metadata.because` is set, it also sets the reason (same as `.because()`).
      */
     rule(metadata) {
-        this._metadata = metadata;
+        const next = this.copy();
+        next._metadata = metadata;
         if (metadata.because) {
-            this._reason = metadata.because;
+            next._reason = metadata.because;
         }
-        return this;
+        return next;
     }
     /**
      * Exclude specific elements from violation reporting.
@@ -50,16 +86,17 @@ export class TerminalBuilder {
      * Emits a warning if an exclusion matches zero violations (stale exclusion).
      */
     excluding(...patterns) {
+        const next = this.copy();
         for (const p of patterns) {
             if (isSilent(p)) {
-                this._exclusions.push(p.pattern);
-                this._silentIndices.add(this._exclusions.length - 1);
+                next._exclusions.push(p.pattern);
+                next._silentIndices.add(next._exclusions.length - 1);
             }
             else {
-                this._exclusions.push(p);
+                next._exclusions.push(p);
             }
         }
-        return this;
+        return next;
     }
     /**
      * Return a structured description of this rule without executing it.
@@ -75,13 +112,20 @@ export class TerminalBuilder {
             imperative: this._metadata?.imperative,
         };
     }
+    /** This rule's own account of itself, for `vacuity-findings.ts`. */
+    facts() {
+        return {
+            ruleClass: { name: this.constructor.name },
+            reason: this._reason,
+            describeRule: () => this.describeRule(),
+        };
+    }
     /**
      * Execute the rule and return violations after exclusion filtering.
      * Does not throw — use for programmatic access (presets, aggregation).
      */
     violations() {
-        const raw = this.collectViolations();
-        return applyFilters(raw, {
+        return applyFilters(this.evidencedViolations(), {
             reason: this._reason,
             metadata: this._metadata,
             exclusions: this._exclusions,
@@ -95,8 +139,7 @@ export class TerminalBuilder {
      * @param options - Optional baseline, diff filtering, and output format
      */
     check(options) {
-        const violations = this.collectViolations();
-        executeCheck(violations, {
+        executeCheck(this.evidencedViolations(), {
             reason: this._reason,
             metadata: this._metadata,
             exclusions: this._exclusions,
@@ -110,14 +153,77 @@ export class TerminalBuilder {
      * @param options - Optional baseline, diff filtering, and output format
      */
     warn(options) {
-        const violations = this.collectViolations();
-        executeWarn(violations, {
+        executeWarn(this.evidencedViolations(), {
             reason: this._reason,
             metadata: this._metadata,
             exclusions: this._exclusions,
             silentIndices: this._silentIndices,
         }, options);
     }
+    /**
+     * ADR-010 — the evidence gate. Calls `collectViolations()` once and turns
+     * its `{ violations, examined, sourceEmpty }` verdict into the
+     * `ArchViolation[]` every terminal method still emits, applying the
+     * declared-empty precedence:
+     *
+     * - `examined === 0`, `sourceEmpty === true`: ADR-010 part 3's precedence
+     *   rule — "an empty project outranks every token." The family's own
+     *   upstream source (files loaded, a diagram parsed) produced nothing at
+     *   all, before any predicate ran. Neither `.expectEmpty()` nor
+     *   `assertsCardinality()` can rescue this: there is no selection to
+     *   widen, and a `.notExist()`-shaped condition "passing" against an
+     *   instrument that never loaded anything is not evidence of anything.
+     *   Always an unsuppressable configuration finding.
+     * - `examined === 0`, `.expectNonEmpty()` declared: the caller has positive
+     *   knowledge this corpus should never be empty — this OVERRIDES
+     *   `assertsCardinality()`'s exemption (a `.notExist()` rule that would
+     *   otherwise pass silently on zero subjects reddens instead, since silent
+     *   emptiness is exactly what the declaration rules out). Fails, naming the
+     *   unmet declaration.
+     * - `examined === 0`, no `.expectEmpty()` declared: the rule's own
+     *   instrument is broken (a dead selector, an unreachable seam) — this is
+     *   a configuration finding, unsuppressable (`bypassFilters`), not a silent
+     *   pass. This is the guarantee ADR-009/010 exist for.
+     * - `examined === 0`, `.expectEmpty()` declared: satisfied. Passes.
+     * - `examined === 0`, `assertsCardinality()` true (and no `.expectNonEmpty()`
+     *   override above): the rule's own conditions are satisfied BY emptiness
+     *   (e.g. `.notExist()`) — a different exemption from `.expectEmpty()`,
+     *   because it is a property of what the condition asserts, not a caller's
+     *   declaration about the corpus. Passes, with no finding at all (not even
+     *   a silent one — the condition already reported truthfully that it found
+     *   nothing wrong).
+     * - `examined > 0`, `.expectEmpty()` declared: the declaration has expired
+     *   — a unit was examined despite the author's "this stays empty" claim.
+     *   Fails, appending an expiry finding to whatever `collectViolations()`
+     *   found (never replacing it — the underlying findings are still real).
+     * - `examined > 0`, no declaration or `.expectNonEmpty()` (the ordinary
+     *   case — `.expectNonEmpty()` has nothing left to assert once subjects
+     *   exist): the rule's own violations stand as computed.
+     */
+    evidencedViolations() {
+        const { violations, examined, sourceEmpty, deadGlob } = this.collectViolations();
+        if (examined === 0) {
+            if (sourceEmpty === true)
+                return [...violations, zeroLoadedSourceViolation(this.facts())];
+            if (this._expectEmpty === true)
+                return violations;
+            if (this._expectEmpty === false)
+                return [...violations, unmetExpectNonEmptyViolation(this.facts())];
+            if (this.assertsCardinality())
+                return violations;
+            // A specific dead-glob explanation, when the dialect could compute
+            // one, outranks the generic zero-examined message — both name the
+            // same underlying fact, and the specific one is strictly more
+            // actionable (it names the actual glob and why it can never match).
+            if (deadGlob !== undefined)
+                return [...violations, deadGlobViolation(this.facts(), deadGlob)];
+            return [...violations, zeroExaminedViolation(this.facts())];
+        }
+        if (this._expectEmpty === true) {
+            return [...violations, expiredExpectEmptyViolation(this.facts(), examined)];
+        }
+        return violations;
+    }
     /**
      * Execute the rule with the given severity.
      * `.severity('error')` is equivalent to `.check()`.
@@ -131,5 +237,143 @@ export class TerminalBuilder {
             this.warn();
         }
     }
+    /**
+     * An independent copy of this builder.
+     *
+     * **A held selection is immutable** (a bug class ported alongside the
+     * kernel — plan 0088 Phase 4, matching `ts-archunit`'s own documented
+     * "bug 0016"). Before this, every chain method mutated `this` in place:
+     *
+     * ```ts
+     * const repos = classes(p).that().extend('BaseRepository')
+     * repos.that().haveNameEndingWith('Legacy').should().notExist().check()
+     * repos.should().beExported().check()   // silently narrowed to Legacy too
+     * ```
+     *
+     * A held selection reused for a second rule silently inherited the first
+     * rule's narrowing, exclusions, and rule id — found live in this repo's own
+     * test suite once the ADR-010 evidence gate stopped treating "examined
+     * zero units because a stale narrowing ate the selection" as an ordinary,
+     * silent pass. `because`/`rule`/`excluding`/`expectEmpty`/`expectNonEmpty`
+     * on `TerminalBuilder`, and `that`/`addPredicate`/`addCondition` on
+     * `RuleBuilder`, all return a copy rather than mutating `this`.
+     *
+     * Subclasses with additional fields beyond `TerminalBuilder`'s own MUST
+     * override this (see `RuleBuilder.copy()`) and call `super.copy()` first.
+     */
+    copy() {
+        const clone = shallowClone(this);
+        clone.adoptFilterState(this);
+        clone._metadata = this._metadata ? { ...this._metadata } : undefined;
+        return clone;
+    }
+    /**
+     * Give this builder independent copies of another's filter state.
+     *
+     * `copy()` shallow-copies every field via `Object.assign`, so without this
+     * a copy would share its source's `_exclusions` array and `_silentIndices`
+     * set by reference — `.excluding()` on one would silently mutate the
+     * other, the exact hazard `copy()` exists to close, one field deeper.
+     */
+    adoptFilterState(source) {
+        this._exclusions = [...source._exclusions];
+        this._silentIndices = new Set(source._silentIndices);
+    }
+    /**
+     * Is this rule's own assertion satisfied by an empty examined set, as a
+     * matter of what it asserts (`.notExist()`-shaped), not a caller's
+     * `.expectEmpty()` declaration? Default `false` — most families have no
+     * such condition and stay covered by the ordinary zero-examined gate.
+     * `RuleBuilder` overrides this to check its own `_conditions` against the
+     * kernel's `assertsCardinality()` registry (ADR-010, `cardinality.ts`).
+     */
+    assertsCardinality() {
+        return false;
+    }
+}
+/**
+ * The configuration finding for a rule that asserts nothing — bug 0155.
+ *
+ * An assertion-less rule — subjects found, nothing asserted about them —
+ * cannot fail, so it certifies nothing while reading as coverage.
+ *
+ * **The guard was unreachable, not merely quiet.** It used to read
+ * `_conditions.length === 0 && _phase === 'predicate'`, and `should()` sets
+ * the phase to `'condition'`, so for every rule shape the DSL documents it
+ * could never fire — the defect passed in total silence, never even reaching
+ * the stderr warning it was routed to. Hence no `_phase` term at the call
+ * site.
+ *
+ * **A finding, not a warning**, per ADR-009 rule 1's discriminator: the remedy
+ * is not optional. There is no state in which "keeps asserting nothing" is
+ * correct — add a condition, or delete the rule. The two rules ADR-009 names
+ * as deliberately `warn` (`no-silent-catch`, `no-empty-bodies`) warn *because*
+ * they carry suppressible false positives a reader must judge case by case.
+ * This carries none.
+ *
+ * **A declared emptiness expectation is an assertion**, so `_expectEmpty`
+ * exempts a rule from this gate. `.expectNonEmpty()` reddens when the corpus
+ * it says must never be empty becomes empty; `.expectEmpty()` reddens the day
+ * the set it says must stay empty gains a member. Neither lives in
+ * `_conditions`. Without that term the gate called a working corpus guard
+ * assertion-less and told its author to "add a condition or delete the rule" —
+ * both of which destroy the guard — and for `.expectEmpty()` reported two
+ * findings for one fault. Found in PR #71's review.
+ *
+ * **Placed AFTER the zero-examined branch**, so a dead selector still reports
+ * as a dead selector. Measured: `resideInFolder('srcc/**')` with no condition
+ * reports the dead glob, not this finding. An earlier draft of this docstring
+ * (and of the changeset and bug record) claimed the opposite — "reports the
+ * missing assertion only" — and justified it as gate-first. Both were wrong:
+ * `getElements()` and the predicate filter already ran, so the ordering saves
+ * no work, and the behaviour is the reverse. The real precedence is the better
+ * one, and is now stated as what it is: this finding fires only when subjects
+ * were actually selected.
+ *
+ * **Exported** rather than private to `RuleBuilder`. Its five siblings
+ * (`zeroExaminedViolation`, `deadGlobViolation`, `unmetExpectNonEmptyViolation`,
+ * `expiredExpectEmptyViolation`, `zeroLoadedSourceViolation`) have since moved to
+ * `vacuity-findings.ts`; this one stayed, because unlike them it is constructed
+ * from a builder's own condition list rather than from `RuleFacts` alone. The *detection* has to stay per-builder —
+ * `TerminalBuilder` has no `_conditions` — but a private constructor meant
+ * `eess-ts`'s slice/schema/resolver builders could not reuse it and were left
+ * warning while the kernel's rules failed: the same defect, one DSL, four
+ * different answers.
+ *
+ * `bypassFilters` makes it a **configuration** finding — `error` regardless of
+ * `.asSeverity('warn')`, refused by `.excluding()`, skipped by diff and
+ * baseline. It reports that the rule's own instrument is broken, not a fault
+ * in what was examined, so a filter aimed at the latter must not suppress it.
+ */
+export function assertionLessViolation(ruleId, advice) {
+    const remedy = advice ??
+        'Add a condition after .should() (a predicate-only method such as ' +
+            'areExported/areAsync filters elements, it does not assert), or delete the rule.';
+    // `message` is the diagnosis; `suggestion` is the remedy. Keeping them
+    // DISTINCT matters: `remedyRepeatsMessage()` suppresses a `Fix:` line only
+    // when it is byte-identical to `What:`, so folding the remedy into both
+    // printed the whole thing twice — plan 0147's double-print, which an earlier
+    // draft of this function reintroduced by appending UNSUPPRESSABLE to a
+    // suggestion that already repeated the message.
+    const message = `Rule '${ruleId}' selects subjects but asserts nothing about them, so it ` +
+        `cannot fail and certifies nothing.`;
+    return {
+        rule: ruleId,
+        element: ruleId,
+        file: '',
+        line: 0,
+        message,
+        // The `.expectNonEmpty()` carve-out is named ON PURPOSE. It satisfies this
+        // gate (a declared emptiness expectation IS an assertion), so an agent
+        // told "add a condition, or delete the rule" and liking neither will find
+        // that one token clears the finding — and on a non-empty corpus
+        // `.expectNonEmpty()` asserts nothing further. ADR-009 rule 3: a marker an
+        // agent can stamp to go green is worse than no marker unless the cost is
+        // stated, so state it here rather than let it be discovered.
+        suggestion: `${remedy} (\`.expectNonEmpty()\` also satisfies this gate, but asserts ` +
+            `only that the corpus is non-empty — it is not a substitute for the ` +
+            `condition you meant.) ${UNSUPPRESSABLE}`,
+        bypassFilters: true,
+    };
 }
 //# sourceMappingURL=terminal-builder.js.map

package/dist/terminal-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"terminal-builder.js","sourceRoot":"","sources":["../src/terminal-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"terminal-builder.js","sourceRoot":"","sources":["../src/terminal-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,4BAA4B,EAC5B,yBAAyB,EACzB,2BAA2B,GAC5B,MAAM,uBAAuB,CAAA;AAE9B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAMpD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAChD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAmCjD;;;;;;;;;;GAUG;AACH,MAAM,OAAgB,eAAe;IACzB,OAAO,CAAS;IAChB,SAAS,CAAe;IACxB,WAAW,GAAwB,EAAE,CAAA;IACrC,cAAc,GAAgB,IAAI,GAAG,EAAE,CAAA;IACjD,2FAA2F;IACjF,YAAY,CAAU;IAEhC;;;;;;OAMG;IACH,WAAW;QACT,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QACxB,IAAI,CAAC,YAAY,GAAG,IAAI,CAAA;QACxB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,cAAc;QACZ,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QACxB,IAAI,CAAC,YAAY,GAAG,KAAK,CAAA;QACzB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,MAAc;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QACxB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;QACrB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,QAAsB;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QACxB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAA;QACzB,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;YACrB,IAAI,CAAC,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAA;QACjC,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;;;;;;OAUG;IACH,SAAS,CAAC,GAAG,QAA+C;QAC1D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QACxB,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChB,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAA;gBAChC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;YACtD,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YAC1B,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;OAGG;IACH,YAAY;QACV,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,SAAS;YACrC,EAAE,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE;YACtB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,IAAI,CAAC,SAAS,EAAE,UAAU;YACtC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI;YAC1B,UAAU,EAAE,IAAI,CAAC,SAAS,EAAE,UAAU;SACvC,CAAA;IACH,CAAC;IAED,oEAAoE;IAC5D,KAAK;QACX,OAAO;YACL,SAAS,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE;YAC1C,MAAM,EAAE,IAAI,CAAC,OAAO;YACpB,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE;SACxC,CAAA;IACH,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,OAAO,YAAY,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE;YAC9C,MAAM,EAAE,IAAI,CAAC,OAAO;YACpB,QAAQ,EAAE,IAAI,CAAC,SAAS;YACxB,UAAU,EAAE,IAAI,CAAC,WAAW;YAC5B,aAAa,EAAE,IAAI,CAAC,cAAc;SACnC,CAAC,CAAA;IACJ,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAsB;QAC1B,YAAY,CACV,IAAI,CAAC,mBAAmB,EAAE,EAC1B;YACE,MAAM,EAAE,IAAI,CAAC,OAAO;YACpB,QAAQ,EAAE,IAAI,CAAC,SAAS;YACxB,UAAU,EAAE,IAAI,CAAC,WAAW;YAC5B,aAAa,EAAE,IAAI,CAAC,cAAc;SACnC,EACD,OAAO,CACR,CAAA;IACH,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,OAAsB;QACzB,WAAW,CACT,IAAI,CAAC,mBAAmB,EAAE,EAC1B;YACE,MAAM,EAAE,IAAI,CAAC,OAAO;YACpB,QAAQ,EAAE,IAAI,CAAC,SAAS;YACxB,UAAU,EAAE,IAAI,CAAC,WAAW;YAC5B,aAAa,EAAE,IAAI,CAAC,cAAc;SACnC,EACD,OAAO,CACR,CAAA;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACK,mBAAmB;QACzB,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAA;QAChF,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;YACnB,IAAI,WAAW,KAAK,IAAI;gBAAE,OAAO,CAAC,GAAG,UAAU,EAAE,yBAAyB,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;YACzF,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI;gBAAE,OAAO,UAAU,CAAA;YACjD,IAAI,IAAI,CAAC,YAAY,KAAK,KAAK;gBAC7B,OAAO,CAAC,GAAG,UAAU,EAAE,4BAA4B,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;YACpE,IAAI,IAAI,CAAC,kBAAkB,EAAE;gBAAE,OAAO,UAAU,CAAA;YAChD,mEAAmE;YACnE,kEAAkE;YAClE,8DAA8D;YAC9D,oEAAoE;YACpE,IAAI,QAAQ,KAAK,SAAS;gBAAE,OAAO,CAAC,GAAG,UAAU,EAAE,iBAAiB,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAA;YAC7F,OAAO,CAAC,GAAG,UAAU,EAAE,qBAAqB,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;QAC7D,CAAC;QACD,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;YAC/B,OAAO,CAAC,GAAG,UAAU,EAAE,2BAA2B,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAA;QAC7E,CAAC;QACD,OAAO,UAAU,CAAA;IACnB,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,KAAuB;QAC9B,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;YACtB,IAAI,CAAC,KAAK,EAAE,CAAA;QACd,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,EAAE,CAAA;QACb,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACO,IAAI;QACZ,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAA;QAChC,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAA;QAC5B,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;QACpE,OAAO,KAAK,CAAA;IACd,CAAC;IAED;;;;;;;OAOG;IACO,gBAAgB,CAAC,MAAuB;QAChD,IAAI,CAAC,WAAW,GAAG,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC,CAAA;QAC1C,IAAI,CAAC,cAAc,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,CAAA;IACtD,CAAC;IAYD;;;;;;;OAOG;IACO,kBAAkB;QAC1B,OAAO,KAAK,CAAA;IACd,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc,EAAE,MAAe;IACpE,MAAM,MAAM,GACV,MAAM;QACN,mEAAmE;YACjE,iFAAiF,CAAA;IACrF,uEAAuE;IACvE,2EAA2E;IAC3E,wEAAwE;IACxE,6EAA6E;IAC7E,uEAAuE;IACvE,gDAAgD;IAChD,MAAM,OAAO,GACX,SAAS,MAAM,2DAA2D;QAC1E,oCAAoC,CAAA;IACtC,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,MAAM;QACf,IAAI,EAAE,EAAE;QACR,IAAI,EAAE,CAAC;QACP,OAAO;QACP,2EAA2E;QAC3E,uEAAuE;QACvE,0EAA0E;QAC1E,gEAAgE;QAChE,2EAA2E;QAC3E,yEAAyE;QACzE,6DAA6D;QAC7D,UAAU,EACR,GAAG,MAAM,gEAAgE;YACzE,qEAAqE;YACrE,yBAAyB,cAAc,EAAE;QAC3C,aAAa,EAAE,IAAI;KACpB,CAAA;AACH,CAAC"}

package/dist/type-guards.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The narrowings this codebase needs at its JS-interop edges, in one place.
+ *
+ * [ADR-005](../../../adr/005-no-any-no-type-assertions.md) forbids `as` and
+ * prescribes type guards. The guards existed — `isRecord` was written **twice**,
+ * verbatim, in `tsconfig/tsconfig-builder.ts` and `cli/commands/init.ts` — while a
+ * third site cast instead of calling either.
+ * [ts-archunit Bug 0049](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0049-the-type-assertion-self-check-selected-classes.md).
+ *
+ * A duplicated predicate is not a style problem in this repo: bug 0044 was a
+ * measurement error caused by exactly that, and the fix was to delete the
+ * duplicate rather than to test both copies.
+ */
+/**
+ * A plain object, indexable by string.
+ *
+ * Excludes `null`, which `typeof` does not — and excludes **arrays**, which is
+ * load-bearing rather than tidy. Both retired copies had `!Array.isArray(value)`
+ * and the first draft of this shared one did not, which would have quietly
+ * widened `tsconfig-builder`'s deep-compare and `init`'s tsconfig reader to accept
+ * an array as a record. Consolidating two copies means picking one, and picking
+ * the weaker one is how a refactor becomes a defect.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * A value that can be called with no arguments.
+ *
+ * Narrower than it looks, and deliberately so: the return type is `unknown`, so
+ * every caller has to establish what came back rather than inheriting a claim.
+ *
+ * This exists because *removing* a cast is not automatically an improvement.
+ * Dropping `(exported as () => unknown)()` after a `typeof === 'function'` check
+ * left `exported` typed as `Function`, which trades an ADR-005 violation for an
+ * `@typescript-eslint/no-unsafe-call` error — the same unchecked call, differently
+ * spelled. A predicate narrows to a signature and satisfies both.
+ */
+export declare function isNullaryCallable(value: unknown): value is () => unknown;
+//# sourceMappingURL=type-guards.d.ts.map

package/dist/type-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.d.ts","sourceRoot":"","sources":["../src/type-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,OAAO,CAExE"}

package/dist/type-guards.js

@@ -0,0 +1,42 @@
+/**
+ * The narrowings this codebase needs at its JS-interop edges, in one place.
+ *
+ * [ADR-005](../../../adr/005-no-any-no-type-assertions.md) forbids `as` and
+ * prescribes type guards. The guards existed — `isRecord` was written **twice**,
+ * verbatim, in `tsconfig/tsconfig-builder.ts` and `cli/commands/init.ts` — while a
+ * third site cast instead of calling either.
+ * [ts-archunit Bug 0049](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0049-the-type-assertion-self-check-selected-classes.md).
+ *
+ * A duplicated predicate is not a style problem in this repo: bug 0044 was a
+ * measurement error caused by exactly that, and the fix was to delete the
+ * duplicate rather than to test both copies.
+ */
+/**
+ * A plain object, indexable by string.
+ *
+ * Excludes `null`, which `typeof` does not — and excludes **arrays**, which is
+ * load-bearing rather than tidy. Both retired copies had `!Array.isArray(value)`
+ * and the first draft of this shared one did not, which would have quietly
+ * widened `tsconfig-builder`'s deep-compare and `init`'s tsconfig reader to accept
+ * an array as a record. Consolidating two copies means picking one, and picking
+ * the weaker one is how a refactor becomes a defect.
+ */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * A value that can be called with no arguments.
+ *
+ * Narrower than it looks, and deliberately so: the return type is `unknown`, so
+ * every caller has to establish what came back rather than inheriting a claim.
+ *
+ * This exists because *removing* a cast is not automatically an improvement.
+ * Dropping `(exported as () => unknown)()` after a `typeof === 'function'` check
+ * left `exported` typed as `Function`, which trades an ADR-005 violation for an
+ * `@typescript-eslint/no-unsafe-call` error — the same unchecked call, differently
+ * spelled. A predicate narrows to a signature and satisfies both.
+ */
+export function isNullaryCallable(value) {
+    return typeof value === 'function';
+}
+//# sourceMappingURL=type-guards.js.map

package/dist/type-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-guards.js","sourceRoot":"","sources":["../src/type-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAC7E,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,OAAO,KAAK,KAAK,UAAU,CAAA;AACpC,CAAC"}

package/dist/unsuppressable.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The one sentence that tells a reader a configuration finding has no escape
+ * hatch — [ADR-009](../../../adr/009-agent-first-failure-surfaces.md) rule 3.
+ *
+ * Stated on the finding rather than inside each remedy so the per-shape advice
+ * stays one sentence each and this stays one sentence in one place. Measured
+ * before it existed: a reader given only the remedy tries `.asSeverity('warn')`,
+ * `.excluding()`, the baseline and `--changed` — four CI cycles — because
+ * nothing told them those were refused.
+ *
+ * ## Why it lives here rather than inline
+ *
+ * It was written twice, inline, at two sites in `terminal-builder.ts`, and
+ * prettier had already split the second copy across lines. Two copies of a
+ * sentence that enumerates a list is the shape that goes stale: the code grew a
+ * sixth refusing surface and both copies still named five.
+ *
+ * ## The list is a claim, so it is guarded
+ *
+ * `tests/core/unsuppressable-sentence.test.ts` derives the refusing mechanisms
+ * **behaviourally** — one probe each — and compares that set against the names
+ * parsed out of this string. Disagreement fails in both directions: naming a
+ * mechanism that does not refuse (bug 0017's shape) and refusing by a mechanism
+ * this does not name. The second is what actually happened.
+ *
+ * The sixth surface is the inline `// eess-exclude` comment, refused in
+ * `execute-rule.ts` by the `v.bypassFilters === true ||` clause. It was omitted
+ * while it was hard to reach; [ts-archunit bug 0041](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0041-an-exclusion-comment-is-a-no-op-for-most-conditions.md)
+ * made inline comments work for every condition family, so an agent reading a
+ * five-item list and inferring exhaustiveness now reaches for the one mechanism
+ * the sentence forgot to mention.
+ */
+export declare const UNSUPPRESSABLE: string;
+/**
+ * The declaration half, appended ONLY by the zero-examined producer.
+ *
+ * It used to live in {@link UNSUPPRESSABLE}, which every configuration finding
+ * carries — so it was stapled to findings a declaration cannot settle. Measured:
+ * on the assertion-gate finding ("this detector has no pattern") and on a dead
+ * selector glob, adding `.expectEmpty()` changes nothing, because both are
+ * decided before any declaration is consulted. The reader declares, re-runs, and
+ * gets the identical failure with the identical advice — ADR-009 rule 2's loop,
+ * introduced by the sentence written to close one.
+ *
+ * On the dead-glob kind it was worse than a no-op: there `overrides: { id: 'off' }`
+ * IS the working exit and declaring is not, so the message steered the reader off
+ * the only door that opens.
+ *
+ * Zero-examined is the one kind a declaration actually settles.
+ */
+export declare const DECLARE_INSTEAD: string;
+/** The mechanism names the sentence claims to refuse, for the parity guard. */
+export declare const UNSUPPRESSABLE_MECHANISMS: readonly [".warn()", ".asSeverity('warn')", ".excluding()", "// eess-exclude", "baseline", "diff-aware"];
+//# sourceMappingURL=unsuppressable.d.ts.map

package/dist/unsuppressable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsuppressable.d.ts","sourceRoot":"","sources":["../src/unsuppressable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,cAAc,QAe6D,CAAA;AAExF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,QAEqC,CAAA;AAEjE,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,0GAO5B,CAAA"}

package/dist/unsuppressable.js

@@ -0,0 +1,76 @@
+/**
+ * The one sentence that tells a reader a configuration finding has no escape
+ * hatch — [ADR-009](../../../adr/009-agent-first-failure-surfaces.md) rule 3.
+ *
+ * Stated on the finding rather than inside each remedy so the per-shape advice
+ * stays one sentence each and this stays one sentence in one place. Measured
+ * before it existed: a reader given only the remedy tries `.asSeverity('warn')`,
+ * `.excluding()`, the baseline and `--changed` — four CI cycles — because
+ * nothing told them those were refused.
+ *
+ * ## Why it lives here rather than inline
+ *
+ * It was written twice, inline, at two sites in `terminal-builder.ts`, and
+ * prettier had already split the second copy across lines. Two copies of a
+ * sentence that enumerates a list is the shape that goes stale: the code grew a
+ * sixth refusing surface and both copies still named five.
+ *
+ * ## The list is a claim, so it is guarded
+ *
+ * `tests/core/unsuppressable-sentence.test.ts` derives the refusing mechanisms
+ * **behaviourally** — one probe each — and compares that set against the names
+ * parsed out of this string. Disagreement fails in both directions: naming a
+ * mechanism that does not refuse (bug 0017's shape) and refusing by a mechanism
+ * this does not name. The second is what actually happened.
+ *
+ * The sixth surface is the inline `// eess-exclude` comment, refused in
+ * `execute-rule.ts` by the `v.bypassFilters === true ||` clause. It was omitted
+ * while it was hard to reach; [ts-archunit bug 0041](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0041-an-exclusion-comment-is-a-no-op-for-most-conditions.md)
+ * made inline comments work for every condition family, so an agent reading a
+ * five-item list and inferring exhaustiveness now reaches for the one mechanism
+ * the sentence forgot to mention.
+ */
+export const UNSUPPRESSABLE = "This finding cannot be suppressed: not by .warn(), .asSeverity('warn'), " +
+    '.excluding(), a `// eess-exclude` comment, a baseline, or diff-aware mode. ' +
+    // The seventh thing an agent tries, and the one you least want it to learn.
+    // Measured: `recommended(p)` over a mis-scoped project reports four findings,
+    // each carrying the sentence above; adding `overrides: { id: 'off' }` reports
+    // three. One config line removed a finding that had just told the reader, in a
+    // sentence guarded by a parity test, that it could not be removed.
+    //
+    // Naming it here rather than leaving it discoverable by elimination: an agent
+    // that hits six walls and then finds `'off'` documented in `docs/presets.md`
+    // will stamp it, which is ADR-009 rule 1's trained-suppression dynamic produced
+    // by our own gate. It is NOT added to `UNSUPPRESSABLE_MECHANISMS`, because that
+    // list is the set the parity guard proves DO refuse — and this one does not.
+    "A preset's overrides: { id: 'off' } does remove it, by deleting the rule " +
+    'entirely — that is not a suppression, it is a permanent decision that never expires.';
+/**
+ * The declaration half, appended ONLY by the zero-examined producer.
+ *
+ * It used to live in {@link UNSUPPRESSABLE}, which every configuration finding
+ * carries — so it was stapled to findings a declaration cannot settle. Measured:
+ * on the assertion-gate finding ("this detector has no pattern") and on a dead
+ * selector glob, adding `.expectEmpty()` changes nothing, because both are
+ * decided before any declaration is consulted. The reader declares, re-runs, and
+ * gets the identical failure with the identical advice — ADR-009 rule 2's loop,
+ * introduced by the sentence written to close one.
+ *
+ * On the dead-glob kind it was worse than a no-op: there `overrides: { id: 'off' }`
+ * IS the working exit and declaring is not, so the message steered the reader off
+ * the only door that opens.
+ *
+ * Zero-examined is the one kind a declaration actually settles.
+ */
+export const DECLARE_INSTEAD = 'If the rule genuinely has nothing to check, declare that instead — a declaration ' +
+    'is an assertion that expires, where deleting the rule is not.';
+/** The mechanism names the sentence claims to refuse, for the parity guard. */
+export const UNSUPPRESSABLE_MECHANISMS = [
+    '.warn()',
+    ".asSeverity('warn')",
+    '.excluding()',
+    '// eess-exclude',
+    'baseline',
+    'diff-aware',
+];
+//# sourceMappingURL=unsuppressable.js.map

package/dist/unsuppressable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsuppressable.js","sourceRoot":"","sources":["../src/unsuppressable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,MAAM,cAAc,GACzB,0EAA0E;IAC1E,6EAA6E;IAC7E,4EAA4E;IAC5E,8EAA8E;IAC9E,8EAA8E;IAC9E,+EAA+E;IAC/E,mEAAmE;IACnE,EAAE;IACF,8EAA8E;IAC9E,6EAA6E;IAC7E,gFAAgF;IAChF,gFAAgF;IAChF,6EAA6E;IAC7E,2EAA2E;IAC3E,sFAAsF,CAAA;AAExF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,eAAe,GAC1B,mFAAmF;IACnF,+DAA+D,CAAA;AAEjE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,SAAS;IACT,qBAAqB;IACrB,cAAc;IACd,iBAAiB;IACjB,UAAU;IACV,YAAY;CACJ,CAAA"}