@nielspeter/eess 0.2.2 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @nielspeter/eess
 
-The dialect-independent **kernel** of the [eess](../../README.md) family.
+The dialect-independent **kernel** of the [eess](https://github.com/nielspeter/eess/blob/main/README.md) family.
 
 This package is the engine every eess dialect runs on. It knows nothing about TypeScript, Mermaid, or any specific artifact format; it is generic over the element type being validated.
 
@@ -16,8 +16,8 @@ This package is the engine every eess dialect runs on. It knows nothing about Ty
 
 You normally don't install this directly — you install a dialect:
 
-- [`@nielspeter/eess-ts`](../ts) — TypeScript
-- [`@nielspeter/eess-mermaid`](../mermaid) — Mermaid class diagrams
+- [`@nielspeter/eess-ts`](https://www.npmjs.com/package/@nielspeter/eess-ts) — TypeScript
+- [`@nielspeter/eess-mermaid`](https://www.npmjs.com/package/@nielspeter/eess-mermaid) — Mermaid class diagrams
 
 Install `@nielspeter/eess` directly only when authoring a new dialect or a cross-dialect tool on top of the kernel.
 

package/dist/assertion-advice.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The assertion-less remedy, by state — bug 0155.
+ *
+ * A pure function of three facts about a rule, deliberately outside
+ * `RuleBuilder`: the class is gated at 300 lines and 20 methods by this repo's
+ * own `arch.internal.rules.ts`, and this capability pushed it over both. It is
+ * also genuinely independent of the builder — three inputs, one string — so a
+ * dialect builder with its own hierarchy can reuse it rather than reinvent the
+ * wording.
+ *
+ * **Branches on `reachedShould`/`misplaced`, never on the builder's phase:**
+ * `.should().that()` lands back in the predicate phase having reached
+ * `.should()`, and any phase-derived message would tell that author a
+ * verifiable falsehood.
+ */
+interface AssertionState {
+    /** Whether `.should()` was ever reached. */
+    readonly reachedShould: boolean;
+    /** Descriptions of predicate-only methods written after `.should()`. */
+    readonly misplaced: readonly string[];
+    /** How many conditions the rule actually carries. */
+    readonly conditionCount: number;
+}
+export declare function assertionAdviceFor(state: AssertionState): string;
+export {};
+//# sourceMappingURL=assertion-advice.d.ts.map

package/dist/assertion-advice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertion-advice.d.ts","sourceRoot":"","sources":["../src/assertion-advice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,UAAU,cAAc;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,qDAAqD;IACrD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAChC;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAmChE"}

package/dist/assertion-advice.js

@@ -0,0 +1,29 @@
+export function assertionAdviceFor(state) {
+    if (!state.reachedShould) {
+        return ('This rule never reached .should(), so it asserts nothing and can never fail. ' +
+            'Add .should() and a condition, or delete the rule.');
+    }
+    if (state.misplaced.length > 0) {
+        const names = state.misplaced.map((d) => `"${d}"`).join(', ');
+        const one = state.misplaced.length === 1;
+        const verb = one ? 'is a predicate, which filters' : 'are predicates, which filter';
+        const it = one ? 'it' : 'them';
+        // Two faults, two remedies. With conditions present the rule is not
+        // "asserting nothing" in the reader's sense — it asserts something over a
+        // set the misplaced predicate silently shrank. Telling this author to
+        // "add a condition" would name a fix that leaves the rule as broken.
+        if (state.conditionCount > 0) {
+            return (`This rule's ${names} ${verb} subjects rather than asserting anything about them, ` +
+                `and ${one ? 'it comes' : 'they come'} after .should() — so ${it} narrowed the ` +
+                "selection this rule's conditions are evaluated over, and if that narrowed it to " +
+                `nothing the conditions hold vacuously. Move ${it} before .should(), where the ` +
+                'filtering is explicit.');
+        }
+        return (`This rule asserts nothing: ${names} ${verb} subjects rather than asserting ` +
+            `anything about them. Move ${it} before .should(), then add a condition.`);
+    }
+    return ('This rule reached .should() but no condition follows, so it asserts nothing and can ' +
+        'never fail. Add a condition after .should() — or, if this rule is generated from ' +
+        'configuration, skip generating it when there is nothing to assert.');
+}
+//# sourceMappingURL=assertion-advice.js.map

package/dist/assertion-advice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertion-advice.js","sourceRoot":"","sources":["../src/assertion-advice.ts"],"names":[],"mappings":"AAwBA,MAAM,UAAU,kBAAkB,CAAC,KAAqB;IACtD,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;QACzB,OAAO,CACL,+EAA+E;YAC/E,oDAAoD,CACrD,CAAA;IACH,CAAC;IACD,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC7D,MAAM,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,CAAA;QACxC,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,8BAA8B,CAAA;QACnF,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAA;QAC9B,oEAAoE;QACpE,0EAA0E;QAC1E,sEAAsE;QACtE,qEAAqE;QACrE,IAAI,KAAK,CAAC,cAAc,GAAG,CAAC,EAAE,CAAC;YAC7B,OAAO,CACL,eAAe,KAAK,IAAI,IAAI,uDAAuD;gBACnF,OAAO,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,yBAAyB,EAAE,gBAAgB;gBAChF,kFAAkF;gBAClF,+CAA+C,EAAE,+BAA+B;gBAChF,wBAAwB,CACzB,CAAA;QACH,CAAC;QACD,OAAO,CACL,8BAA8B,KAAK,IAAI,IAAI,kCAAkC;YAC7E,6BAA6B,EAAE,0CAA0C,CAC1E,CAAA;IACH,CAAC;IACD,OAAO,CACL,sFAAsF;QACtF,mFAAmF;QACnF,oEAAoE,CACrE,CAAA;AACH,CAAC"}

package/dist/baseline.d.ts

@@ -16,6 +16,33 @@ export interface BaselineEntry {
     line: number;
     /** Stable identity hash: sha256(rule + element + message) */
     hash: string;
+    /**
+     * The measurement this entry accepted, for a metric finding
+     * (`ArchViolation.measured`). Absent for every non-metric entry, so a
+     * baseline with no metric findings is byte-identical to one without this
+     * field at all.
+     */
+    measured?: number;
+    /**
+     * What {@link measured} counts — `code-lines`, `methods`, `complexity`.
+     *
+     * Written since [bug 0171](../../../work/bugs/0171-a-metric-unit-change-silently-loosens-every-baselined-ratchet.md).
+     * An accepted ceiling is a number IN A UNIT, and comparing across a change of
+     * unit does not measure a regression — it moves the bar. Absent on entries
+     * written before stamping, which {@link Baseline.isKnown} treats as "unknown
+     * unit": comparable only for metrics whose meaning has never changed.
+     *
+     * No dialect on the kernel emits `measured` today; this is here so the hole
+     * cannot open silently in the one that does, and so the two copies of this
+     * file do not disagree about what a baseline entry means.
+     */
+    measuredUnit?: string;
+}
+/** A measurement an entry accepted, and what that number counts (bug 0171). */
+interface AcceptedMeasurement {
+    value: number;
+    /** `undefined` on entries written before unit stamping. */
+    unit?: string;
 }
 /**
  * The baseline file structure.
@@ -31,19 +58,32 @@ export interface BaselineFile {
 /**
  * Compute a stable hash for a violation.
  *
- * Uses rule + element + message as identity. This survives:
+ * Uses `violation.identity` when the condition set one (a canonical,
+ * position-independent key — see `ArchViolation.identity`'s own doc comment);
+ * otherwise falls back to rule + element + message. The fallback survives:
  * - Line number changes (code moved)
  * - Unrelated code changes in the same file
  *
  * Does NOT survive:
  * - Rule description changes (rewording .because())
  * - Element renames (class renamed)
- * - Message text changes (condition wording updated)
+ * - Message text changes (condition wording updated) — including a message
+ *   that embeds a line number, which changes whenever code shifts above the
+ *   match. A condition that reports such a message sets `identity` instead
+ *   of relying on this fallback.
  *
  * This is intentional — if the rule or element changes,
  * the violation should be re-evaluated.
+ *
+ * `root`, when supplied, is scrubbed out of both fields via
+ * `normalizeIdentityText` before hashing — an `identity` string that
+ * interpolates a file path (e.g. `identifyMatches`'s per-declaration
+ * identities) otherwise embeds the absolute checkout path, and the same
+ * baseline generated on two machines (or locally vs. CI) would never match.
+ * Omitted, hashing is unchanged — this stays opt-in so a caller with no
+ * portability need (or no discoverable root) pays nothing for it.
  */
-export declare function hashViolation(violation: ArchViolation): string;
+export declare function hashViolation(violation: ArchViolation, root?: string): string;
 /**
  * Load a baseline from a JSON file.
  *
@@ -67,17 +107,42 @@ export declare function generateBaseline(violations: ArchViolation[], outputPath
 export declare class Baseline {
     private readonly knownHashes;
     private readonly baselineDir;
-    constructor(knownHashes: Set<string>, baselineDir: string);
+    /** Computed once at load time — must match `generateBaseline()`'s root for entries to line up. */
+    private readonly root?;
+    /** hash -> accepted measurement, for metric findings. */
+    private readonly accepted;
+    constructor(knownHashes: Set<string>, baselineDir: string, 
+    /** Computed once at load time — must match `generateBaseline()`'s root for entries to line up. */
+    root?: string | undefined, 
+    /** hash -> accepted measurement, for metric findings. */
+    accepted?: Map<string, AcceptedMeasurement>);
     /**
      * Check if a violation is known (exists in the baseline).
      * Known violations are filtered out — they don't cause failures.
+     *
+     * For a metric finding (`violation.measured` set), "known" is a **ratchet**,
+     * not hash equality: the finding is known if the baseline has an accepted
+     * measurement for this identity AND the current measurement is no worse
+     * than what was accepted. Identity alone (the hash) cannot express this —
+     * it deliberately excludes the count, so an improved measurement keeps the
+     * same hash as a regressed one, and hash-only matching would treat both as
+     * "known" alike. Comparing the two numbers is what tells them apart: an
+     * improvement stays known (still <= accepted), a regression does not (now >
+     * accepted), even though neither changed which entry it matches.
      */
     isKnown(violation: ArchViolation): boolean;
     /**
      * Filter out known violations, returning only new ones.
+     *
+     * A `bypassFilters` configuration finding is never treated as known, even
+     * if an older or hand-edited baseline file happens to carry a matching
+     * hash — `generateBaseline()` no longer writes these, but a baseline
+     * generated before that fix (or hand-edited) must not be able to
+     * resurrect the suppression this defends against.
      */
     filterNew(violations: ArchViolation[]): ArchViolation[];
     /** Number of known violations in the baseline */
     get size(): number;
 }
+export {};
 //# sourceMappingURL=baseline.d.ts.map

package/dist/baseline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAA;IACZ,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAA;IACZ,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAA;IACnB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,qBAAqB;IACrB,UAAU,EAAE,aAAa,EAAE,CAAA;CAC5B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,aAAa,GAAG,MAAM,CAG9D;AAUD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,QAAQ,CA6B3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,aAAa,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAmBtF;AAED;;GAEG;AACH,qBAAa,QAAQ;IAEjB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,WAAW;gBADX,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,WAAW,EAAE,MAAM;IAGtC;;;OAGG;IACH,OAAO,CAAC,SAAS,EAAE,aAAa,GAAG,OAAO;IAI1C;;OAEG;IACH,SAAS,CAAC,UAAU,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE;IAIvD,iDAAiD;IACjD,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}
+{"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAInD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAA;IACZ,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAA;IACZ,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,+EAA+E;AAC/E,UAAU,mBAAmB;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AA6BD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAA;IACnB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,qBAAqB;IACrB,UAAU,EAAE,aAAa,EAAE,CAAA;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAa7E;AAUD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,QAAQ,CAwC3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,aAAa,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAgCtF;AAED;;GAEG;AACH,qBAAa,QAAQ;IAEjB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,kGAAkG;IAClG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;IACtB,yDAAyD;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBALR,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,WAAW,EAAE,MAAM;IACpC,kGAAkG;IACjF,IAAI,CAAC,EAAE,MAAM,YAAA;IAC9B,yDAAyD;IACxC,QAAQ,GAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAa;IAGzE;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,SAAS,EAAE,aAAa,GAAG,OAAO;IAU1C;;;;;;;;OAQG;IACH,SAAS,CAAC,UAAU,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE;IAIvD,iDAAiD;IACjD,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/baseline.js

@@ -1,23 +1,73 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
+import { discoverIdentityRoot, normalizeIdentityText } from './identity-root.js';
+import { writeStderr } from './stderr.js';
+/**
+ * Units whose meaning has never changed, so an entry predating unit stamping is
+ * still safely comparable against one.
+ *
+ * `code-lines` is deliberately absent: an unstamped `lines` entry was written
+ * when the metric counted a SPAN, so its number is denominated in something no
+ * longer produced. Comparing across that raises the ceiling silently.
+ */
+const MEANING_NEVER_CHANGED = new Set([
+    'methods',
+    'parameters',
+    'properties',
+    'named-exports',
+    'complexity',
+]);
+/**
+ * Whether a stored measurement may be compared against a current one. Fails
+ * CLOSED — anything but a demonstrable match is incomparable, because assuming
+ * agreement is how a ratchet loosens without anyone being told (ADR-010).
+ */
+function measurementComparable(stored, current) {
+    if (stored === current)
+        return true;
+    if (stored === undefined)
+        return current !== undefined && MEANING_NEVER_CHANGED.has(current);
+    return false;
+}
 /**
  * Compute a stable hash for a violation.
  *
- * Uses rule + element + message as identity. This survives:
+ * Uses `violation.identity` when the condition set one (a canonical,
+ * position-independent key — see `ArchViolation.identity`'s own doc comment);
+ * otherwise falls back to rule + element + message. The fallback survives:
  * - Line number changes (code moved)
  * - Unrelated code changes in the same file
  *
  * Does NOT survive:
  * - Rule description changes (rewording .because())
  * - Element renames (class renamed)
- * - Message text changes (condition wording updated)
+ * - Message text changes (condition wording updated) — including a message
+ *   that embeds a line number, which changes whenever code shifts above the
+ *   match. A condition that reports such a message sets `identity` instead
+ *   of relying on this fallback.
  *
  * This is intentional — if the rule or element changes,
  * the violation should be re-evaluated.
+ *
+ * `root`, when supplied, is scrubbed out of both fields via
+ * `normalizeIdentityText` before hashing — an `identity` string that
+ * interpolates a file path (e.g. `identifyMatches`'s per-declaration
+ * identities) otherwise embeds the absolute checkout path, and the same
+ * baseline generated on two machines (or locally vs. CI) would never match.
+ * Omitted, hashing is unchanged — this stays opt-in so a caller with no
+ * portability need (or no discoverable root) pays nothing for it.
  */
-export function hashViolation(violation) {
-    const content = `${violation.rule}::${violation.element}::${violation.message}`;
+export function hashViolation(violation, root) {
+    const scrub = (text) => root === undefined ? text : normalizeIdentityText(text, root);
+    // `rule` is always part of the hash, even when `identity` is set — two
+    // different rules that happened to produce the same identity string (e.g.
+    // two metric conditions on the same class) must not collide in one
+    // baseline entry.
+    const subject = violation.identity !== undefined
+        ? violation.identity
+        : `${violation.element}::${violation.message}`;
+    const content = `${scrub(violation.rule)}::${scrub(subject)}`;
     return createHash('sha256').update(content).digest('hex').slice(0, 16);
 }
 /**
@@ -36,9 +86,10 @@ function toRelativePath(absolutePath, baselineDir) {
 export function withBaseline(baselinePath) {
     const resolved = path.resolve(baselinePath);
     const baselineDir = path.dirname(resolved);
+    const root = discoverIdentityRoot(baselineDir);
     if (!fs.existsSync(resolved)) {
         // No baseline file = no known violations = all violations are new
-        return new Baseline(new Set(), baselineDir);
+        return new Baseline(new Set(), baselineDir, root);
     }
     const raw = fs.readFileSync(resolved, 'utf-8');
     const parsed = JSON.parse(raw);
@@ -46,17 +97,26 @@ export function withBaseline(baselinePath) {
         typeof parsed !== 'object' ||
         !('violations' in parsed) ||
         !Array.isArray(parsed.violations)) {
-        console.warn(`[eess] Invalid baseline file format at ${resolved} — treating as empty`);
-        return new Baseline(new Set(), baselineDir);
+        writeStderr(`[eess] Invalid baseline file format at ${resolved} — treating as empty`);
+        return new Baseline(new Set(), baselineDir, root);
     }
     const violations = parsed.violations;
     const hashes = new Set();
+    const accepted = new Map();
     for (const entry of violations) {
         if (entry && typeof entry === 'object' && 'hash' in entry && typeof entry.hash === 'string') {
             hashes.add(entry.hash);
+            if ('measured' in entry && typeof entry.measured === 'number') {
+                accepted.set(entry.hash, {
+                    value: entry.measured,
+                    unit: 'measuredUnit' in entry && typeof entry.measuredUnit === 'string'
+                        ? entry.measuredUnit
+                        : undefined,
+                });
+            }
         }
     }
-    return new Baseline(hashes, baselineDir);
+    return new Baseline(hashes, baselineDir, root, accepted);
 }
 /**
  * Generate a baseline file from a list of violations.
@@ -70,11 +130,24 @@ export function withBaseline(baselinePath) {
 export function generateBaseline(violations, outputPath) {
     const resolved = path.resolve(outputPath);
     const baselineDir = path.dirname(resolved);
-    const entries = violations.map((v) => ({
+    const root = discoverIdentityRoot(baselineDir);
+    // A bypassFilters configuration finding (ADR-010) can never legitimately
+    // become "known, pre-existing debt" — it means the rule's own instrument
+    // is broken right now. Recording it would let a future run of `check
+    // --baseline` silently treat a dead selector as already-accepted.
+    const entries = violations
+        .filter((v) => v.bypassFilters !== true)
+        .map((v) => ({
         rule: v.rule,
         file: toRelativePath(v.file, baselineDir),
         line: v.line,
-        hash: hashViolation(v),
+        hash: hashViolation(v, root),
+        // Written only for metric findings, so a baseline with none is
+        // byte-identical to one from before this field existed.
+        ...(v.measured === undefined ? {} : { measured: v.measured }),
+        // Bug 0171: what that number counts, so a later change to the metric
+        // cannot silently re-denominate an accepted ceiling.
+        ...(v.measuredUnit === undefined ? {} : { measuredUnit: v.measuredUnit }),
     }));
     const baseline = {
         generatedAt: new Date().toISOString(),
@@ -90,22 +163,55 @@ export function generateBaseline(violations, outputPath) {
 export class Baseline {
     knownHashes;
     baselineDir;
-    constructor(knownHashes, baselineDir) {
+    root;
+    accepted;
+    constructor(knownHashes, baselineDir, 
+    /** Computed once at load time — must match `generateBaseline()`'s root for entries to line up. */
+    root, 
+    /** hash -> accepted measurement, for metric findings. */
+    accepted = new Map()) {
         this.knownHashes = knownHashes;
         this.baselineDir = baselineDir;
+        this.root = root;
+        this.accepted = accepted;
     }
     /**
      * Check if a violation is known (exists in the baseline).
      * Known violations are filtered out — they don't cause failures.
+     *
+     * For a metric finding (`violation.measured` set), "known" is a **ratchet**,
+     * not hash equality: the finding is known if the baseline has an accepted
+     * measurement for this identity AND the current measurement is no worse
+     * than what was accepted. Identity alone (the hash) cannot express this —
+     * it deliberately excludes the count, so an improved measurement keeps the
+     * same hash as a regressed one, and hash-only matching would treat both as
+     * "known" alike. Comparing the two numbers is what tells them apart: an
+     * improvement stays known (still <= accepted), a regression does not (now >
+     * accepted), even though neither changed which entry it matches.
      */
     isKnown(violation) {
-        return this.knownHashes.has(hashViolation(violation));
+        const hash = hashViolation(violation, this.root);
+        if (violation.measured === undefined)
+            return this.knownHashes.has(hash);
+        const acceptedMeasurement = this.accepted.get(hash);
+        if (acceptedMeasurement === undefined)
+            return false;
+        // Bug 0171: `<=` means nothing until both numbers count the same thing.
+        if (!measurementComparable(acceptedMeasurement.unit, violation.measuredUnit))
+            return false;
+        return violation.measured <= acceptedMeasurement.value;
     }
     /**
      * Filter out known violations, returning only new ones.
+     *
+     * A `bypassFilters` configuration finding is never treated as known, even
+     * if an older or hand-edited baseline file happens to carry a matching
+     * hash — `generateBaseline()` no longer writes these, but a baseline
+     * generated before that fix (or hand-edited) must not be able to
+     * resurrect the suppression this defends against.
      */
     filterNew(violations) {
-        return violations.filter((v) => !this.isKnown(v));
+        return violations.filter((v) => v.bypassFilters === true || !this.isKnown(v));
     }
     /** Number of known violations in the baseline */
     get size() {

package/dist/baseline.js.map

@@ -1 +1 @@
-{"version":3,"file":"baseline.js","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"baseline.js","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"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"}

package/dist/cache-registry.d.ts

@@ -0,0 +1,14 @@
+/** Register a cache's reset. Call once, at module scope. */
+export declare function registerCacheReset(reset: () => void): void;
+/**
+ * Drop every registered cache.
+ *
+ * Called by `resetProjectCache()`. The caches are keyed on object identity, so
+ * a caller who obtains projects through `project()` / `workspace()` is already
+ * covered — those functions hand back a new object. This is the escape hatch
+ * for a consumer holding an `ArchProject` **they** built across a mutation of
+ * the underlying ts-morph project, where identity does not change and the
+ * cached population would otherwise be frozen.
+ */
+export declare function clearRegisteredCaches(): void;
+//# sourceMappingURL=cache-registry.d.ts.map

package/dist/cache-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-registry.d.ts","sourceRoot":"","sources":["../src/cache-registry.ts"],"names":[],"mappings":"AAmBA,4DAA4D;AAC5D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,IAAI,GAAG,IAAI,CAE1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}

package/dist/cache-registry.js

@@ -0,0 +1,37 @@
+/**
+ * Where invalidatable caches register themselves.
+ *
+ * This module exists to break an import cycle, and the cycle was found by this
+ * repository's own `beFreeOfCycles` rule rather than by review. Wiring
+ * `resetProjectCache()` directly to `clearElementCaches()` made
+ * `project.ts → element-cache.ts → project.ts` — the back edge being
+ * `import type { ArchProject }`, which counts, because dependency conditions
+ * have seen type-expression edges since v0.28.0.
+ *
+ * So the registry depends on nothing. `element-cache.ts` and `module-edges.ts`
+ * register a reset closure here; `project.ts` calls {@link clearRegisteredCaches}
+ * and never learns what is in it.
+ *
+ * A `WeakMap` cannot be enumerated, so "clear" means "replace the map". Each
+ * cache contributes the closure that replaces its own.
+ */
+const resets = [];
+/** Register a cache's reset. Call once, at module scope. */
+export function registerCacheReset(reset) {
+    resets.push(reset);
+}
+/**
+ * Drop every registered cache.
+ *
+ * Called by `resetProjectCache()`. The caches are keyed on object identity, so
+ * a caller who obtains projects through `project()` / `workspace()` is already
+ * covered — those functions hand back a new object. This is the escape hatch
+ * for a consumer holding an `ArchProject` **they** built across a mutation of
+ * the underlying ts-morph project, where identity does not change and the
+ * cached population would otherwise be frozen.
+ */
+export function clearRegisteredCaches() {
+    for (const reset of resets)
+        reset();
+}
+//# sourceMappingURL=cache-registry.js.map

package/dist/cache-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-registry.js","sourceRoot":"","sources":["../src/cache-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,GAAmB,EAAE,CAAA;AAEjC,4DAA4D;AAC5D,MAAM,UAAU,kBAAkB,CAAC,KAAiB;IAClD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AACpB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB;IACnC,KAAK,MAAM,KAAK,IAAI,MAAM;QAAE,KAAK,EAAE,CAAA;AACrC,CAAC"}

package/dist/cardinality.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Declare that this condition is satisfied by an empty selection.
+ *
+ * **A registry, because a symbol was forgeable.** The first version keyed a
+ * module-private `unique symbol` onto the condition, reasoning that a consumer
+ * could not import it to name the key. They do not need to import it — four
+ * shipped conditions carry it as an own property, and `notExist` is publicly
+ * exported, so:
+ *
+ * ```ts
+ * const stolen = Object.getOwnPropertySymbols(notExist())[0]
+ * const mine = { description: 'x', evaluate: () => [], [stolen]: true }
+ * ```
+ *
+ * Measured: an honest condition on an empty selection produces **1** configuration
+ * finding and that forgery produces **0**. One line, through documented exports,
+ * to exempt any rule from the empty-selection gate — the gate this library is
+ * named around, and precisely the `.allowEmpty()` hazard the symbol was chosen to
+ * prevent.
+ *
+ * Found by review, immediately after the identical hole was closed in
+ * [ts-archunit plan 0081](https://github.com/nielspeter/ts-archunit/blob/main/plans/completed/0081-a-condition-declares-discovery-ownership.md)'s
+ * symbol — while this one was being cited in that module's docstring as the safe
+ * precedent. The lesson is worth more than the fix: **"module-private" describes
+ * the binding, not the value.** A symbol keyed onto a public object is unlisted,
+ * not unreachable.
+ *
+ * `WeakSet` membership cannot be read off an object, copied, or forged: a caller
+ * would need this module's binding, and it is not exported. Weak so a condition is
+ * not retained after its rule is discarded.
+ */
+export declare function marksAssertsCardinality<T extends object>(condition: T): T;
+/** Is this condition satisfied by an empty selection? */
+export declare function assertsCardinality(condition: object): boolean;
+//# sourceMappingURL=cardinality.d.ts.map

package/dist/cardinality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cardinality.d.ts","sourceRoot":"","sources":["../src/cardinality.ts"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,SAAS,EAAE,CAAC,GAAG,CAAC,CAGzE;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE7D"}

package/dist/cardinality.js

@@ -0,0 +1,65 @@
+/**
+ * The cardinality exemption, keyed so that only this library can set it.
+ *
+ * Plan 0074 (R3b), and specifically constraint 2 of 0069's appendix:
+ *
+ * > `Condition` is a public export and `defineCondition` is its sanctioned
+ * > constructor. If the flag is expressible there, it is a one-line silent
+ * > opt-out on any user condition — the hazard the Decisions section used to
+ * > reject `.allowEmpty()`, relocated onto the condition object. A
+ * > module-private `unique symbol`, with no `defineCondition` parameter, closes
+ * > it by construction (ADR-009 rule 3's corollary).
+ *
+ * A first cut of this shipped as a plain `assertsCardinality?: true` property,
+ * which is exactly the rejected shape: `Condition` is exported from
+ * `src/index.ts`, so any user object literal could set it and silence the
+ * empty-selection gate on any rule, permanently and invisibly. That is
+ * `.allowEmpty()` wearing a different hat.
+ *
+ * This symbol is **not** re-exported from `src/index.ts`, and `package.json`'s
+ * `exports` map has no wildcard subpath, so a consumer cannot import it to
+ * name the key. The escape hatch users *do* get is `.expectEmpty()`, which is
+ * an assertion that fails when the selection stops being empty — not a
+ * silencer.
+ */
+const CARDINALITY_ASSERTERS = new WeakSet();
+/**
+ * Declare that this condition is satisfied by an empty selection.
+ *
+ * **A registry, because a symbol was forgeable.** The first version keyed a
+ * module-private `unique symbol` onto the condition, reasoning that a consumer
+ * could not import it to name the key. They do not need to import it — four
+ * shipped conditions carry it as an own property, and `notExist` is publicly
+ * exported, so:
+ *
+ * ```ts
+ * const stolen = Object.getOwnPropertySymbols(notExist())[0]
+ * const mine = { description: 'x', evaluate: () => [], [stolen]: true }
+ * ```
+ *
+ * Measured: an honest condition on an empty selection produces **1** configuration
+ * finding and that forgery produces **0**. One line, through documented exports,
+ * to exempt any rule from the empty-selection gate — the gate this library is
+ * named around, and precisely the `.allowEmpty()` hazard the symbol was chosen to
+ * prevent.
+ *
+ * Found by review, immediately after the identical hole was closed in
+ * [ts-archunit plan 0081](https://github.com/nielspeter/ts-archunit/blob/main/plans/completed/0081-a-condition-declares-discovery-ownership.md)'s
+ * symbol — while this one was being cited in that module's docstring as the safe
+ * precedent. The lesson is worth more than the fix: **"module-private" describes
+ * the binding, not the value.** A symbol keyed onto a public object is unlisted,
+ * not unreachable.
+ *
+ * `WeakSet` membership cannot be read off an object, copied, or forged: a caller
+ * would need this module's binding, and it is not exported. Weak so a condition is
+ * not retained after its rule is discarded.
+ */
+export function marksAssertsCardinality(condition) {
+    CARDINALITY_ASSERTERS.add(condition);
+    return condition;
+}
+/** Is this condition satisfied by an empty selection? */
+export function assertsCardinality(condition) {
+    return CARDINALITY_ASSERTERS.has(condition);
+}
+//# sourceMappingURL=cardinality.js.map

package/dist/cardinality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cardinality.js","sourceRoot":"","sources":["../src/cardinality.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,qBAAqB,GAAG,IAAI,OAAO,EAAU,CAAA;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,uBAAuB,CAAmB,SAAY;IACpE,qBAAqB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;IACpC,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAClD,OAAO,qBAAqB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;AAC7C,CAAC"}

package/dist/check-options.d.ts

@@ -22,6 +22,20 @@ export interface BaselineFilter {
 export interface DiffFilterLike {
     /** Filter violations to only those in changed files. */
     filterToChanged(violations: ArchViolation[]): ArchViolation[];
+    /**
+     * How many files this filter considers changed, or a negative number when it
+     * could not tell (`DiffFilter` returns -1 when git was unavailable).
+     *
+     * **Optional, and the disclosure degrades rather than guesses.** This is a
+     * structural interface, so a consumer may pass any object with
+     * `filterToChanged`; when `size` is absent the suppression notice omits the
+     * file count instead of inventing one. What it never omits is the suppressed
+     * count itself, because the caller derives that by subtraction rather than
+     * asking the filter (see `core/diff-disclosure.ts`).
+     */
+    readonly size?: number;
+    /** The branch diffed against, when the filter knows it. Optional, as `size`. */
+    readonly baseBranch?: string;
 }
 /**
  * Options passed to .check() and .warn() to filter violations.

package/dist/check-options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-options.d.ts","sourceRoot":"","sources":["../src/check-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAA;AAEzD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,SAAS,CAAC,UAAU,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAAA;CACxD;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,eAAe,CAAC,UAAU,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAAA;CAC9D;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,iDAAiD;IACjD,IAAI,CAAC,EAAE,cAAc,CAAA;IACrB,wDAAwD;IACxD,MAAM,CAAC,EAAE,YAAY,CAAA;CACtB"}
+{"version":3,"file":"check-options.d.ts","sourceRoot":"","sources":["../src/check-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAA;AAEzD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,SAAS,CAAC,UAAU,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAAA;CACxD;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,eAAe,CAAC,UAAU,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAAA;IAC7D;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,gFAAgF;IAChF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,iDAAiD;IACjD,IAAI,CAAC,EAAE,cAAc,CAAA;IACrB,wDAAwD;IACxD,MAAM,CAAC,EAAE,YAAY,CAAA;CACtB"}