@nielspeter/eess 0.2.2 → 0.5.0

package/dist/rule-description.d.ts

@@ -1,3 +1,4 @@
+import type { RuleMetadata } from './rule-metadata.js';
 /**
  * Structured description of a rule, returned by `.describe()`.
  * Used by the `explain` CLI subcommand to dump active rules as JSON.
@@ -8,7 +9,88 @@ export interface RuleDescription {
     because?: string;
     suggestion?: string;
     docs?: string;
-    /** One-line imperative for AI-agent prompts (see {@link RuleMetadata.imperative}). */
+    /** Imperative "Do NOT … / MUST …" sentence for agent system prompts. */
     imperative?: string;
 }
+/**
+ * A rule that can describe itself.
+ *
+ * `RuleBuilderLike` declares only `violations()` — deliberately, so a caller can
+ * pass a plain object — while every builder in `src/` implements `describeRule()`.
+ * So reading a rule's id or remedy needs a narrowing, and that narrowing existed
+ * in **three** places with two different implementations: `cli/commands/explain.ts`
+ * and two test files.
+ *
+ * One owner, because a duplicated predicate is not a style problem here:
+ * [ts-archunit bug 0044](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0044-an-inline-exclusion-comment-has-no-feedback-channel.md)
+ * was a measurement error caused by exactly that, and the fix was to delete the
+ * duplicate rather than to test both copies.
+ *
+ * `DiagnosableRule` and `orphanExclusions` are NOT copies of this: they declare
+ * `describeRule?` as an optional structural member of their own input type, which
+ * is a different mechanism and correct where it is used.
+ */
+export interface Describable {
+    describeRule: () => RuleDescription;
+}
+/**
+ * Does this value describe itself?
+ *
+ * Cast-free, and that is the point: the version in `explain.ts` read
+ * `(value as Record<string, unknown>)['describeRule']`, an ADR-005 breach in
+ * shipped source with no `eslint-disable` and no interop boundary to justify it.
+ * It was also unnecessary — once `value` is narrowed to `object`, `'describeRule'
+ * in value` narrows enough for the property access to compile, which is what the
+ * two test copies already did.
+ */
+export declare function isDescribable(value: unknown): value is Describable;
+/**
+ * The metadata half of a rule's description — one projection, four callers.
+ *
+ * `id`, `because`, `suggestion` and `docs` are read off `RuleMetadata` the same
+ * way everywhere. `rule` and `imperative` are the two axes that genuinely vary,
+ * so they are parameters rather than something this function guesses:
+ *
+ * - `rule` — the base `TerminalBuilder` says `id ?? 'unnamed'` (a SENTINEL that
+ *   `dedupe-config-findings.ts` keys on, not an identity), a `RuleBuilder` says
+ *   the assembled `ruleDescriptionOf(...)` sentence, and several `eess-ts`
+ *   subclasses override it again on top of `...super.describeRule()`.
+ * - `imperativeFallback` — what to say for an agent prompt when the author
+ *   declared no `imperative`. `eess-ts`'s `RuleDeclaration` falls back to the
+ *   reason and its `describeRuleOf` to a derived Do-NOT/MUST sentence; the
+ *   kernel has no fallback, and that is not an oversight this extraction
+ *   quietly fixed — `imperative` is read only by `eess-ts`'s
+ *   `explain --format agent`, and `eess-mermaid`'s `explain` does not project
+ *   the field at all. The kernel has no consumer to be wrong for.
+ *
+ * The four bodies were otherwise identical, which `no-copy-paste` reported as a
+ * 93% cluster.
+ */
+export declare function ruleDescriptionFrom(opts: {
+    metadata: RuleMetadata | undefined;
+    reason: string | undefined;
+    rule: string;
+    imperativeFallback?: string;
+}): RuleDescription;
+/**
+ * A rule's English description, assembled from what it declared.
+ *
+ * `subject` is the noun the rule opens with when its builder has one — the
+ * GraphQL builders say `schema that ... should ...` and
+ * `resolvers that ... should ...`; the general builders open with `that`. That
+ * one word was the only difference between four copies of this function, which
+ * `no-copy-paste` reported as a cluster at 100%.
+ *
+ * An empty predicate or condition list contributes nothing rather than an empty
+ * clause, so a rule that never reached `.should()` reads `that X` and not
+ * `that X should ` — the missing half is what `assertionAdvice` then reports.
+ *
+ * `slice-rule-builder.ts` is deliberately NOT a caller: its description is a
+ * different sentence (`slices [a, b] should ...`), not this one with a prefix.
+ */
+export declare function ruleDescriptionOf(predicates: readonly {
+    description: string;
+}[], conditions: readonly {
+    description: string;
+}[], subject?: string): string;
 //# sourceMappingURL=rule-description.d.ts.map

package/dist/rule-description.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule-description.d.ts","sourceRoot":"","sources":["../src/rule-description.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB"}
+{"version":3,"file":"rule-description.d.ts","sourceRoot":"","sources":["../src/rule-description.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,eAAe,CAAA;CACpC;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAIlE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,QAAQ,EAAE,YAAY,GAAG,SAAS,CAAA;IAClC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B,GAAG,eAAe,CASlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,SAAS;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,EAAE,EAC9C,UAAU,EAAE,SAAS;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,EAAE,EAC9C,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAOR"}

package/dist/rule-description.js

@@ -1,2 +1,76 @@
-export {};
+/**
+ * Does this value describe itself?
+ *
+ * Cast-free, and that is the point: the version in `explain.ts` read
+ * `(value as Record<string, unknown>)['describeRule']`, an ADR-005 breach in
+ * shipped source with no `eslint-disable` and no interop boundary to justify it.
+ * It was also unnecessary — once `value` is narrowed to `object`, `'describeRule'
+ * in value` narrows enough for the property access to compile, which is what the
+ * two test copies already did.
+ */
+export function isDescribable(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    if (!('describeRule' in value))
+        return false;
+    return typeof value.describeRule === 'function';
+}
+/**
+ * The metadata half of a rule's description — one projection, four callers.
+ *
+ * `id`, `because`, `suggestion` and `docs` are read off `RuleMetadata` the same
+ * way everywhere. `rule` and `imperative` are the two axes that genuinely vary,
+ * so they are parameters rather than something this function guesses:
+ *
+ * - `rule` — the base `TerminalBuilder` says `id ?? 'unnamed'` (a SENTINEL that
+ *   `dedupe-config-findings.ts` keys on, not an identity), a `RuleBuilder` says
+ *   the assembled `ruleDescriptionOf(...)` sentence, and several `eess-ts`
+ *   subclasses override it again on top of `...super.describeRule()`.
+ * - `imperativeFallback` — what to say for an agent prompt when the author
+ *   declared no `imperative`. `eess-ts`'s `RuleDeclaration` falls back to the
+ *   reason and its `describeRuleOf` to a derived Do-NOT/MUST sentence; the
+ *   kernel has no fallback, and that is not an oversight this extraction
+ *   quietly fixed — `imperative` is read only by `eess-ts`'s
+ *   `explain --format agent`, and `eess-mermaid`'s `explain` does not project
+ *   the field at all. The kernel has no consumer to be wrong for.
+ *
+ * The four bodies were otherwise identical, which `no-copy-paste` reported as a
+ * 93% cluster.
+ */
+export function ruleDescriptionFrom(opts) {
+    return {
+        rule: opts.rule,
+        id: opts.metadata?.id,
+        because: opts.reason,
+        suggestion: opts.metadata?.suggestion,
+        docs: opts.metadata?.docs,
+        imperative: opts.metadata?.imperative ?? opts.imperativeFallback,
+    };
+}
+/**
+ * A rule's English description, assembled from what it declared.
+ *
+ * `subject` is the noun the rule opens with when its builder has one — the
+ * GraphQL builders say `schema that ... should ...` and
+ * `resolvers that ... should ...`; the general builders open with `that`. That
+ * one word was the only difference between four copies of this function, which
+ * `no-copy-paste` reported as a cluster at 100%.
+ *
+ * An empty predicate or condition list contributes nothing rather than an empty
+ * clause, so a rule that never reached `.should()` reads `that X` and not
+ * `that X should ` — the missing half is what `assertionAdvice` then reports.
+ *
+ * `slice-rule-builder.ts` is deliberately NOT a caller: its description is a
+ * different sentence (`slices [a, b] should ...`), not this one with a prefix.
+ */
+export function ruleDescriptionOf(predicates, conditions, subject) {
+    const predicateDesc = predicates.map((p) => p.description).join(' and ');
+    const conditionDesc = conditions.map((c) => c.description).join(' and ');
+    const parts = subject === undefined ? [] : [subject];
+    if (predicateDesc)
+        parts.push(`that ${predicateDesc}`);
+    if (conditionDesc)
+        parts.push(`should ${conditionDesc}`);
+    return parts.join(' ');
+}
 //# sourceMappingURL=rule-description.js.map

package/dist/rule-description.js.map

@@ -1 +1 @@
-{"version":3,"file":"rule-description.js","sourceRoot":"","sources":["../src/rule-description.ts"],"names":[],"mappings":""}
+{"version":3,"file":"rule-description.js","sourceRoot":"","sources":["../src/rule-description.ts"],"names":[],"mappings":"AAsCA;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IAC7D,IAAI,CAAC,CAAC,cAAc,IAAI,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAC5C,OAAO,OAAO,KAAK,CAAC,YAAY,KAAK,UAAU,CAAA;AACjD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAKnC;IACC,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,EAAE,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE;QACrB,OAAO,EAAE,IAAI,CAAC,MAAM;QACpB,UAAU,EAAE,IAAI,CAAC,QAAQ,EAAE,UAAU;QACrC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI;QACzB,UAAU,EAAE,IAAI,CAAC,QAAQ,EAAE,UAAU,IAAI,IAAI,CAAC,kBAAkB;KACjE,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAA8C,EAC9C,UAA8C,EAC9C,OAAgB;IAEhB,MAAM,aAAa,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACxE,MAAM,aAAa,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACxE,MAAM,KAAK,GAAa,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAA;IAC9D,IAAI,aAAa;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,aAAa,EAAE,CAAC,CAAA;IACtD,IAAI,aAAa;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,aAAa,EAAE,CAAC,CAAA;IACxD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACxB,CAAC"}

package/dist/rule-metadata.d.ts

@@ -14,10 +14,27 @@ export interface RuleMetadata {
     /** Link to documentation — ADR, wiki, style guide */
     docs?: string;
     /**
-     * One-line imperative statement of the rule for an AI-agent system prompt,
-     * e.g. `'Do NOT call eval()'`. Surfaced by `explain --format agent`; falls
-     * back to the rule description when unset.
+     * Imperative one-liner for AI-agent system prompts, e.g.
+     * "Do NOT throw new Error() in repositories". Surfaced by
+     * `explain --format agent`. When unset, a heuristic is derived from the
+     * rule's predicate/condition description.
      */
     imperative?: string;
+    /**
+     * How the AUTHOR of this rule spells "I declare this empty" — plan 0099.
+     *
+     * Set by whoever constructs the rule, because only they know. A preset sets
+     * `expectEmpty: ['<id>']` because that is what its user can type; a builder
+     * author leaves it unset and gets `.expectEmpty()`.
+     *
+     * Core used to derive this from the rule id starting with `preset/`, which it
+     * cannot verify: that is false for a hand-written `.rule({ id: 'preset/...' })`,
+     * for a third-party preset that never extended `PresetBaseOptions`, and for a
+     * preset that forwards `overrides` but not `expectEmpty`. A prefix is a naming
+     * convention, not a capability, and the remedy has to name a call the reader
+     * can actually make ([ADR-009](../../../adr/009-agent-first-failure-surfaces.md)
+     * rule 2).
+     */
+    declarationSpelling?: string;
 }
 //# sourceMappingURL=rule-metadata.d.ts.map

package/dist/rule-metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule-metadata.d.ts","sourceRoot":"","sources":["../src/rule-metadata.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,EAAE,CAAC,EAAE,MAAM,CAAA;IAEX,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB"}
+{"version":3,"file":"rule-metadata.d.ts","sourceRoot":"","sources":["../src/rule-metadata.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,EAAE,CAAC,EAAE,MAAM,CAAA;IAEX,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B"}

package/dist/selection-memo.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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, () => matchingElements(this.getElements(), this._predicates))
+ * }
+ */
+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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;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,66 @@
+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, () => matchingElements(this.getElements(), this._predicates))
+ * }
+ */
+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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;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/silent-exclusion.d.ts

@@ -34,5 +34,17 @@ export declare function silent(pattern: string | RegExp): SilentExclusion;
  * Check whether a value is a SilentExclusion.
  */
 export declare function isSilent(value: unknown): value is SilentExclusion;
+/**
+ * Record `patterns` into a builder's exclusion state, tracking which are silent.
+ *
+ * A free function over the two collections rather than a method, because the two
+ * builders that need it sit in incompatible class hierarchies — `eess-ts` has
+ * `RuleDeclaration -> TerminalBuilder -> RuleBuilder` where the kernel has two
+ * levels — so inheritance cannot share it. It mutates only what it is handed,
+ * so no private state crosses a package boundary.
+ *
+ * The two copies were byte-identical (`no-copy-paste` reported 100%).
+ */
+export declare function recordExclusions(patterns: readonly (string | RegExp | SilentExclusion)[], exclusions: (string | RegExp)[], silentIndices: Set<number>): void;
 export {};
 //# sourceMappingURL=silent-exclusion.d.ts.map

package/dist/silent-exclusion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"silent-exclusion.d.ts","sourceRoot":"","sources":["../src/silent-exclusion.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,QAAA,MAAM,MAAM,EAAE,OAAO,MAAmC,CAAA;AAExD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;IACjC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,CAAA;CACxB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,eAAe,CAEhE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAEjE"}
+{"version":3,"file":"silent-exclusion.d.ts","sourceRoot":"","sources":["../src/silent-exclusion.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,QAAA,MAAM,MAAM,EAAE,OAAO,MAAmC,CAAA;AAExD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;IACjC,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,CAAA;CACxB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,eAAe,CAEhE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAEjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,eAAe,CAAC,EAAE,EACxD,UAAU,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EAC/B,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,GACzB,IAAI,CASN"}

package/dist/silent-exclusion.js

@@ -27,4 +27,26 @@ export function silent(pattern) {
 export function isSilent(value) {
     return typeof value === 'object' && value !== null && SILENT in value;
 }
+/**
+ * Record `patterns` into a builder's exclusion state, tracking which are silent.
+ *
+ * A free function over the two collections rather than a method, because the two
+ * builders that need it sit in incompatible class hierarchies — `eess-ts` has
+ * `RuleDeclaration -> TerminalBuilder -> RuleBuilder` where the kernel has two
+ * levels — so inheritance cannot share it. It mutates only what it is handed,
+ * so no private state crosses a package boundary.
+ *
+ * The two copies were byte-identical (`no-copy-paste` reported 100%).
+ */
+export function recordExclusions(patterns, exclusions, silentIndices) {
+    for (const p of patterns) {
+        if (isSilent(p)) {
+            exclusions.push(p.pattern);
+            silentIndices.add(exclusions.length - 1);
+        }
+        else {
+            exclusions.push(p);
+        }
+    }
+}
 //# sourceMappingURL=silent-exclusion.js.map

package/dist/silent-exclusion.js.map

@@ -1 +1 @@
-{"version":3,"file":"silent-exclusion.js","sourceRoot":"","sources":["../src/silent-exclusion.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,GAAkB,MAAM,CAAC,kBAAkB,CAAC,CAAA;AAcxD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,MAAM,CAAC,OAAwB;IAC7C,OAAO,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAA;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,CAAA;AACvE,CAAC"}
+{"version":3,"file":"silent-exclusion.js","sourceRoot":"","sources":["../src/silent-exclusion.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,GAAkB,MAAM,CAAC,kBAAkB,CAAC,CAAA;AAcxD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,MAAM,CAAC,OAAwB;IAC7C,OAAO,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAA;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,CAAA;AACvE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAwD,EACxD,UAA+B,EAC/B,aAA0B;IAE1B,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;YAChB,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAA;YAC1B,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QAC1C,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACpB,CAAC;IACH,CAAC;AACH,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"}