@nielspeter/eess 0.2.1 → 0.4.0

package/dist/selection-memo.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Memoize a builder's materialized selection — plan 0096.
+ *
+ * ## Why this exists
+ *
+ * Plan 0096 makes every family expose the set its conditions receive, so that
+ * `diagnose()`'s preview and (in plan 0098) the floor read the **same
+ * computation** the gate reads rather than a parallel one. Two readers of one
+ * method means the walk would run twice per rule — and `doctor` calls
+ * `diagnose()` once per rule file, so on a 600-file project a rule file with ten
+ * smell rules paid seconds to compute ten integers.
+ *
+ * ## Why a WeakMap and not an instance field
+ *
+ * Because a field would be **wrong**, not merely different. These builders are
+ * copy-on-write: every chain method returns `this.copy()`, which is
+ * `shallowClone` — `Object.assign(clone, source)` over own enumerable
+ * properties. A memo stored on the instance is therefore copied onto a builder
+ * that has just been given a **different predicate**, and the clone answers with
+ * its parent's selection. That is a stale-evidence bug of exactly the kind this
+ * plan exists to prevent, and it would have been hard to see: the number is
+ * plausible, and only a test that narrows *after* materializing would catch it.
+ *
+ * A `WeakMap` keyed on the builder has no such hazard by construction. A clone
+ * is a different object, so a different key, so no entry. Nothing to clear, no
+ * `copy()` override to remember in five families, and the entry is collected
+ * with the builder.
+ *
+ * ## Why a factory rather than one shared map
+ *
+ * So the element type survives without an assertion. One `WeakMap<object,
+ * unknown[]>` shared by every family would need a cast on the way out, which
+ * [ADR-005](../../../adr/005-no-any-no-type-assertions.md) forbids — and the
+ * honest alternatives (a `filter` with an always-true type predicate) are worse:
+ * they compile, allocate, and lie.
+ *
+ * @example
+ * const selectionOf = selectionMemo<ArchFunction>()
+ *
+ * private selected(): ArchFunction[] {
+ *   return selectionOf(this, () =>
+ *     this.getElements().filter((e) => this._predicates.every((p) => p.test(e))),
+ *   )
+ * }
+ */
+export declare function selectionMemo<T>(): (owner: object, compute: () => T[]) => T[];
+//# sourceMappingURL=selection-memo.d.ts.map

package/dist/selection-memo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selection-memo.d.ts","sourceRoot":"","sources":["../src/selection-memo.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,aAAa,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,EAAE,CAmB7E"}

package/dist/selection-memo.js

@@ -0,0 +1,68 @@
+import { registerCacheReset } from './cache-registry.js';
+/**
+ * Memoize a builder's materialized selection — plan 0096.
+ *
+ * ## Why this exists
+ *
+ * Plan 0096 makes every family expose the set its conditions receive, so that
+ * `diagnose()`'s preview and (in plan 0098) the floor read the **same
+ * computation** the gate reads rather than a parallel one. Two readers of one
+ * method means the walk would run twice per rule — and `doctor` calls
+ * `diagnose()` once per rule file, so on a 600-file project a rule file with ten
+ * smell rules paid seconds to compute ten integers.
+ *
+ * ## Why a WeakMap and not an instance field
+ *
+ * Because a field would be **wrong**, not merely different. These builders are
+ * copy-on-write: every chain method returns `this.copy()`, which is
+ * `shallowClone` — `Object.assign(clone, source)` over own enumerable
+ * properties. A memo stored on the instance is therefore copied onto a builder
+ * that has just been given a **different predicate**, and the clone answers with
+ * its parent's selection. That is a stale-evidence bug of exactly the kind this
+ * plan exists to prevent, and it would have been hard to see: the number is
+ * plausible, and only a test that narrows *after* materializing would catch it.
+ *
+ * A `WeakMap` keyed on the builder has no such hazard by construction. A clone
+ * is a different object, so a different key, so no entry. Nothing to clear, no
+ * `copy()` override to remember in five families, and the entry is collected
+ * with the builder.
+ *
+ * ## Why a factory rather than one shared map
+ *
+ * So the element type survives without an assertion. One `WeakMap<object,
+ * unknown[]>` shared by every family would need a cast on the way out, which
+ * [ADR-005](../../../adr/005-no-any-no-type-assertions.md) forbids — and the
+ * honest alternatives (a `filter` with an always-true type predicate) are worse:
+ * they compile, allocate, and lie.
+ *
+ * @example
+ * const selectionOf = selectionMemo<ArchFunction>()
+ *
+ * private selected(): ArchFunction[] {
+ *   return selectionOf(this, () =>
+ *     this.getElements().filter((e) => this._predicates.every((p) => p.test(e))),
+ *   )
+ * }
+ */
+export function selectionMemo() {
+    let cache = new WeakMap();
+    // Same staleness profile as `element-cache.ts`, so the same escape hatch — a
+    // consumer holding a builder across a mutation of the underlying ts-morph
+    // project gets the pre-mutation selection back, and identity has not changed
+    // so nothing else can notice. That is worse here than in the element cache:
+    // BOTH readers go through this memo, so a stale entry is a stale VERDICT and
+    // a stale count that agree with each other. Reasoning about the clone hazard
+    // and stopping one short of this one would read as "considered and safe".
+    registerCacheReset(() => {
+        cache = new WeakMap();
+    });
+    return (owner, compute) => {
+        const cached = cache.get(owner);
+        if (cached !== undefined)
+            return cached;
+        const computed = compute();
+        cache.set(owner, computed);
+        return computed;
+    };
+}
+//# sourceMappingURL=selection-memo.js.map

package/dist/selection-memo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selection-memo.js","sourceRoot":"","sources":["../src/selection-memo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,UAAU,aAAa;IAC3B,IAAI,KAAK,GAAG,IAAI,OAAO,EAAe,CAAA;IACtC,6EAA6E;IAC7E,0EAA0E;IAC1E,6EAA6E;IAC7E,4EAA4E;IAC5E,6EAA6E;IAC7E,6EAA6E;IAC7E,0EAA0E;IAC1E,kBAAkB,CAAC,GAAG,EAAE;QACtB,KAAK,GAAG,IAAI,OAAO,EAAe,CAAA;IACpC,CAAC,CAAC,CAAA;IACF,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACxB,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAC/B,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAA;QACvC,MAAM,QAAQ,GAAG,OAAO,EAAE,CAAA;QAC1B,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;QAC1B,OAAO,QAAQ,CAAA;IACjB,CAAC,CAAA;AACH,CAAC"}

package/dist/shallow-clone.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A same-prototype shallow copy of a builder.
+ *
+ * The one place in the codebase that reaches for `Object.create` /
+ * `Object.getPrototypeOf`, which are the JS-interop boundary ADR-005's
+ * `eslint-disable` carve-out exists for. Every copy-on-write builder goes
+ * through here so that carve-out is written once and reviewed once.
+ *
+ * Shallow is deliberate. It gives the clone its own *slots*, which is what
+ * makes `next._x = ...` safe; a field holding a mutable container still needs
+ * the owning class to replace it, which is what the `copy()` overrides do.
+ * A deep clone would instead copy ts-morph `Project` graphs — the opposite of
+ * cheap, and it would break identity comparisons on `SourceFile`.
+ *
+ * Class fields declared with a constructor parameter property (`private
+ * readonly project`) are ordinary instance properties at runtime, so they come
+ * across too: a clone is built against the same project, without re-loading it.
+ */
+export declare function shallowClone<T extends object>(source: T): T;
+//# sourceMappingURL=shallow-clone.d.ts.map

package/dist/shallow-clone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shallow-clone.d.ts","sourceRoot":"","sources":["../src/shallow-clone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAO3D"}

package/dist/shallow-clone.js

@@ -0,0 +1,27 @@
+/**
+ * A same-prototype shallow copy of a builder.
+ *
+ * The one place in the codebase that reaches for `Object.create` /
+ * `Object.getPrototypeOf`, which are the JS-interop boundary ADR-005's
+ * `eslint-disable` carve-out exists for. Every copy-on-write builder goes
+ * through here so that carve-out is written once and reviewed once.
+ *
+ * Shallow is deliberate. It gives the clone its own *slots*, which is what
+ * makes `next._x = ...` safe; a field holding a mutable container still needs
+ * the owning class to replace it, which is what the `copy()` overrides do.
+ * A deep clone would instead copy ts-morph `Project` graphs — the opposite of
+ * cheap, and it would break identity comparisons on `SourceFile`.
+ *
+ * Class fields declared with a constructor parameter property (`private
+ * readonly project`) are ordinary instance properties at runtime, so they come
+ * across too: a clone is built against the same project, without re-loading it.
+ */
+export function shallowClone(source) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- Object.getPrototypeOf returns `any`
+    const proto = Object.getPrototypeOf(source);
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- Object.create returns `any`
+    const clone = Object.create(proto);
+    Object.assign(clone, source);
+    return clone;
+}
+//# sourceMappingURL=shallow-clone.js.map

package/dist/shallow-clone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shallow-clone.js","sourceRoot":"","sources":["../src/shallow-clone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAAmB,MAAS;IACtD,0GAA0G;IAC1G,MAAM,KAAK,GAAW,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,CAAA;IACnD,kGAAkG;IAClG,MAAM,KAAK,GAAM,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACrC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAC5B,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/stderr.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Write one message to stderr so it survives a test runner.
+ *
+ * A trailing newline is added when absent, because the call sites this replaced
+ * used `console.warn`, which appends one — omitting it at ten call sites is a
+ * mistake waiting to happen, and a message run onto the next is the defect this
+ * channel exists to avoid.
+ */
+export declare function writeStderr(message: string): void;
+/**
+ * Reset the lazily-attached listener. **Tests only** — a suite that asserts on
+ * the attachment needs to observe it happening rather than inherit it from
+ * whichever earlier test wrote first.
+ */
+export declare function resetStderrGuardForTests(): void;
+//# sourceMappingURL=stderr.d.ts.map

package/dist/stderr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stderr.d.ts","sourceRoot":"","sources":["../src/stderr.ts"],"names":[],"mappings":"AA8CA;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAQjD;AAED;;;;GAIG;AAEH,wBAAgB,wBAAwB,IAAI,IAAI,CAG/C"}

package/dist/stderr.js

@@ -0,0 +1,73 @@
+/**
+ * The library's single stderr channel.
+ *
+ * [ts-archunit Bug 0024](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0024-warn-terminal-is-invisible-inside-a-test-runner.md):
+ * every library-originated message went through `console.warn`, and vitest's
+ * default reporter **intercepts** console output and replays it only for
+ * **failing** tests. `.warn()` never fails a test, so its output was always
+ * dropped. Measured on a real child `vitest run` with the default reporter: a
+ * passing test whose rule has 4 real violations printed **nothing** — zero
+ * occurrences of the violation text.
+ *
+ * That silence was not confined to `.warn()`. The stale-exclusion warning, the
+ * unused-exclusion warning, the exclusion-comment parse warnings, the
+ * invalid-baseline warning, the diff-aware fallback warning and `expression()`'s
+ * escape-hatch warning were all invisible in a passing test — five files' worth.
+ * A finding nobody reads has not been reported (ADR-009 rule 1).
+ *
+ * **The EPIPE guard is not optional, and it is why this is a function rather
+ * than a bare write.** Node's `Console` is constructed with `ignoreErrors: true`
+ * and swallows write errors; `process.stderr.write` does not. With a closed
+ * downstream pipe — `eess-ts check 2>&1 | head` — the error arrives
+ * **asynchronously**, so neither `try`/`catch` nor the write callback can see
+ * it, and the process dies with an uncaught EPIPE. Measured over 20 000 lines:
+ *
+ *     bare process.stderr.write            node exits 1
+ *     with an 'error' listener attached    node exits 0
+ *     console.warn                         node exits 0
+ *
+ * `writeReport` already wrote to `process.stderr` unguarded, so that exit-1 was
+ * a live defect before this existed: a piped `check` could fail for EPIPE rather
+ * than for findings, and the two are indistinguishable from the exit code.
+ *
+ * A persistent listener rather than `once`: `once` removes itself after the
+ * first error, leaving a second EPIPE uncaught, and re-adding per write leaks
+ * listeners. One listener, attached lazily, never removed — the same trade
+ * `ignoreErrors: true` makes, and the reason it is documented here rather than
+ * hidden.
+ *
+ * **The accepted cost:** vitest annotates intercepted console output with the
+ * test that produced it (`stderr | file > test name`), and a direct write loses
+ * that. For a violation report the rule's own identity is in the message, so the
+ * loss is real but small — and being attributed to a test that never printed is
+ * worse than being unattributed.
+ */
+let listenerAttached = false;
+/**
+ * Write one message to stderr so it survives a test runner.
+ *
+ * A trailing newline is added when absent, because the call sites this replaced
+ * used `console.warn`, which appends one — omitting it at ten call sites is a
+ * mistake waiting to happen, and a message run onto the next is the defect this
+ * channel exists to avoid.
+ */
+export function writeStderr(message) {
+    if (!listenerAttached) {
+        // See the module docstring: the EPIPE is asynchronous, so this listener is
+        // the only thing that can catch it.
+        process.stderr.on('error', () => { });
+        listenerAttached = true;
+    }
+    process.stderr.write(message.endsWith('\n') ? message : `${message}\n`);
+}
+/**
+ * Reset the lazily-attached listener. **Tests only** — a suite that asserts on
+ * the attachment needs to observe it happening rather than inherit it from
+ * whichever earlier test wrote first.
+ */
+// eess-exclude eess/no-unused-exports: re-exported from `src/index.ts`; this gate does not count a barrel `export … from` re-export as usage — see work/bugs/0168
+export function resetStderrGuardForTests() {
+    process.stderr.removeAllListeners('error');
+    listenerAttached = false;
+}
+//# sourceMappingURL=stderr.js.map

package/dist/stderr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stderr.js","sourceRoot":"","sources":["../src/stderr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,IAAI,gBAAgB,GAAG,KAAK,CAAA;AAE5B;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,2EAA2E;QAC3E,oCAAoC;QACpC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QACpC,gBAAgB,GAAG,IAAI,CAAA;IACzB,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,CAAA;AACzE,CAAC;AAED;;;;GAIG;AACH,kKAAkK;AAClK,MAAM,UAAU,wBAAwB;IACtC,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAA;IAC1C,gBAAgB,GAAG,KAAK,CAAA;AAC1B,CAAC"}

package/dist/terminal-builder.d.ts

@@ -3,23 +3,78 @@ import type { CheckOptions } from './check-options.js';
 import type { RuleMetadata } from './rule-metadata.js';
 import type { RuleDescription } from './rule-description.js';
 import type { SilentExclusion } from './silent-exclusion.js';
+/**
+ * A rule's verdict, carrying evidence of examination alongside the findings —
+ * ADR-010. `examined` is the count of units the family's own examining seam
+ * actually iterated (never a count of matches, never upstream discovery like
+ * files loaded) — each concrete `collectViolations()` names its own unit.
+ *
+ * `sourceEmpty` — ADR-010 part 3's precedence rule: "an empty project
+ * outranks every token." Set `true` when `examined === 0` because the
+ * family's own upstream source (files loaded, a diagram parsed, an SDL
+ * string) produced nothing at all — BEFORE any predicate/selection
+ * narrowed it — as distinct from a predicate narrowing a non-empty source
+ * down to zero. This is a stronger claim than a bare zero-examined dead
+ * selector: `.expectEmpty()` cannot rescue it, because there is no
+ * selection to widen — the instrument itself never loaded anything to
+ * examine. Omit (or `false`) when the distinction doesn't apply (the
+ * family has no separate source/selection stages) or the zero came from
+ * narrowing, not upstream emptiness.
+ */
+export interface CollectResult {
+    readonly violations: ArchViolation[];
+    readonly examined: number;
+    readonly sourceEmpty?: boolean;
+    /**
+     * A specific dead-glob explanation for a zero-examined rule, pre-formatted
+     * by the dialect that computed it (`RuleBuilder.deadGlobDiagnosis()`) —
+     * the kernel never touches picomatch or a project type to build this
+     * itself. `undefined` means no diagnosis is available (no glob declared,
+     * or the declared glob isn't actually dead), which falls through to the
+     * generic zero-examined finding the same as before this field existed.
+     */
+    readonly deadGlob?: string;
+}
 /**
  * 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 declare abstract class TerminalBuilder {
     protected _reason?: string;
     protected _metadata?: RuleMetadata;
-    private readonly _exclusions;
-    private readonly _silentIndices;
+    protected _exclusions: (string | RegExp)[];
+    protected _silentIndices: Set<number>;
+    /** ADR-010 part 3 — `.expectEmpty()`/`.expectNonEmpty()`. `undefined` = no declaration. */
+    protected _expectEmpty?: boolean;
+    /**
+     * 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(): this;
+    /**
+     * 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(): this;
     /**
      * Attach a human-readable rationale to the rule.
      * Included in violation messages when `.check()` throws.
@@ -49,6 +104,8 @@ export declare abstract class TerminalBuilder {
      * Used by the `explain` CLI subcommand.
      */
     describeRule(): RuleDescription;
+    /** This rule's own account of itself, for `vacuity-findings.ts`. */
+    private facts;
     /**
      * Execute the rule and return violations after exclusion filtering.
      * Does not throw — use for programmatic access (presets, aggregation).
@@ -68,6 +125,47 @@ export declare abstract class TerminalBuilder {
      * @param options - Optional baseline, diff filtering, and output format
      */
     warn(options?: CheckOptions): void;
+    /**
+     * 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.
+     */
+    private evidencedViolations;
     /**
      * Execute the rule with the given severity.
      * `.severity('error')` is equivalent to `.check()`.
@@ -75,9 +173,111 @@ export declare abstract class TerminalBuilder {
      */
     severity(level: 'error' | 'warn'): void;
     /**
-     * Subclasses implement this to collect and evaluate violations.
+     * 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.
+     */
+    protected copy(): this;
+    /**
+     * 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.
+     */
+    protected adoptFilterState(source: TerminalBuilder): void;
+    /**
+     * Subclasses implement this to collect and evaluate violations, and to
+     * report how many units they examined (ADR-010) — counted at the family's
+     * own examining seam, in whatever unit that family names as its own
+     * (post-predicate subjects for `RuleBuilder`, bodies compared for
+     * `SmellBuilder`, the key sets of both sides for `correspondence()`).
      * Called lazily during `.check()` / `.warn()`.
      */
-    protected abstract collectViolations(): ArchViolation[];
+    protected abstract collectViolations(): CollectResult;
+    /**
+     * 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`).
+     */
+    protected assertsCardinality(): boolean;
 }
+/**
+ * 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 declare function assertionLessViolation(ruleId: string, advice?: string): ArchViolation;
 //# sourceMappingURL=terminal-builder.d.ts.map

package/dist/terminal-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terminal-builder.d.ts","sourceRoot":"","sources":["../src/terminal-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAI5D;;;;;;;;;;;GAWG;AACH,8BAAsB,eAAe;IACnC,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IAC1B,SAAS,CAAC,SAAS,CAAC,EAAE,YAAY,CAAA;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0B;IACtD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IAExD;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK7B;;;;;OAKG;IACH,IAAI,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;IAQlC;;;;;;;;;;OAUG;IACH,SAAS,CAAC,GAAG,QAAQ,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,eAAe,CAAC,EAAE,GAAG,IAAI;IAYnE;;;OAGG;IACH,YAAY,IAAI,eAAe;IAW/B;;;OAGG;IACH,UAAU,IAAI,aAAa,EAAE;IAU7B;;;;;OAKG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAcnC;;;;;OAKG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAclC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IAQvC;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,iBAAiB,IAAI,aAAa,EAAE;CACxD"}
+{"version":3,"file":"terminal-builder.d.ts","sourceRoot":"","sources":["../src/terminal-builder.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAK5D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,aAAa,EAAE,CAAA;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;;;;;GAUG;AACH,8BAAsB,eAAe;IACnC,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IAC1B,SAAS,CAAC,SAAS,CAAC,EAAE,YAAY,CAAA;IAClC,SAAS,CAAC,WAAW,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAK;IAC/C,SAAS,CAAC,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAY;IACjD,2FAA2F;IAC3F,SAAS,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;IAEhC;;;;;;OAMG;IACH,WAAW,IAAI,IAAI;IAMnB;;;;;;;;;;;;OAYG;IACH,cAAc,IAAI,IAAI;IAMtB;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAM7B;;;;;OAKG;IACH,IAAI,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;IASlC;;;;;;;;;;OAUG;IACH,SAAS,CAAC,GAAG,QAAQ,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,eAAe,CAAC,EAAE,GAAG,IAAI;IAanE;;;OAGG;IACH,YAAY,IAAI,eAAe;IAW/B,oEAAoE;IACpE,OAAO,CAAC,KAAK;IAQb;;;OAGG;IACH,UAAU,IAAI,aAAa,EAAE;IAS7B;;;;;OAKG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAanC;;;;;OAKG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAalC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,OAAO,CAAC,mBAAmB;IAqB3B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI;IAQvC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,SAAS,CAAC,IAAI,IAAI,IAAI;IAOtB;;;;;;;OAOG;IACH,SAAS,CAAC,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAKzD;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,CAAC,iBAAiB,IAAI,aAAa;IAErD;;;;;;;OAOG;IACH,SAAS,CAAC,kBAAkB,IAAI,OAAO;CAGxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAiCrF"}