@nielspeter/eess 0.2.2 → 0.5.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.
 
@@ -12,14 +12,107 @@ This package is the engine every eess dialect runs on. It knows nothing about Ty
 - Baseline mode, diff-aware filtering, exclusions, and the terminal/GitHub/JSON formatters
 - `definePredicate` / `defineCondition` — extension points for advanced users
 
+## Two entry points
+
+`@nielspeter/eess` publishes two:
+
+| Specifier                   | What it is                                                                                                                                          |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@nielspeter/eess`          | The public API. Everything below is documented here, and a change to it is a versioned change.                                                      |
+| `@nielspeter/eess/internal` | Family plumbing the sibling dialects share — cache registries, stderr guards, suppression counters, identity hashing, glob-tree internals. Not API. |
+
+You want the root. `/internal` exists so the dialects can share one engine without
+each name they touch becoming a public commitment; it is published because npm has
+no way to ship a package-private module, not because it is for you. Nothing there is
+documented, and no dialect re-exports it _as its own API_. Two names — `DiskSet`
+and `OnDisk` — are also on `@nielspeter/eess-ts`'s root, where they are eess-ts's
+own types that happen to share a name; that is the whole of the overlap.
+
+Breaking something here is still a versioned change and still needs a changeset
+(ADR-011 clause 4). What you are not owed is migration guidance, because it is not
+API. See
+[ADR-011](https://github.com/nielspeter/eess/blob/main/adr/011-the-kernels-public-api-is-explicit.md).
+
+If a symbol you used disappeared from the root, it moved here — the import path is
+the only change.
+
+## Kernel API reference
+
+The fluent surface (`RuleBuilder`, `Predicate`, `Condition`, the combinators, the
+formatters) is covered in the [docs site](https://nielspeter.github.io/eess/). This
+section covers the supporting types you will meet in signatures.
+
+### Reporting and severity
+
+A preset never emits on its own — the caller owns emission (ADR-008).
+
+- **`ReportMode`** — `'throw' | 'return' | 'warn'`. What a finisher does with findings: raise an `ArchRuleError`, hand them back, or print them as advisory and continue.
+- **`ReportOptions`** — the emission controls: `format` (terminal/json/github) and `reason`, the rationale threaded into the output.
+- **`RuleSeverity`** — `'error' | 'warn' | 'off'`, the value of a per-rule override.
+- **`PresetBaseOptions`** — what every preset accepts: an `overrides` map of rule id → `RuleSeverity`, plus the reporting controls. Extend it when you write a preset so `{ report: 'return' }` works without your own plumbing.
+- **`RuleBuilderLike`** — the one-method shape (`violations()`) a preset needs from anything it dispatches, so a preset is not coupled to a dialect's builder class.
+- **`Dispatchable`** — what `dispatchRule` accepts: a builder that can produce violations _and_ name itself, so the dispatcher can apply a per-rule override to it. Strictly more than `RuleBuilderLike`; that one is the narrower shape used where only the findings matter.
+- **`isArchRuleError(err)`** — use this instead of `instanceof ArchRuleError` when catching. `instanceof` compares class identity, so it returns `false` whenever two copies of the package are on disk — a nested `node_modules`, or a rule file loaded through a separate module registry. The check is structural (the stamped `name` plus the `violations` array), so it survives that. The thrown shape itself — `violations: ArchViolation[]` — is public either way.
+- **`ArchConfigError`** / **`isArchConfigError(err)`** — thrown when a _rule_ is misconfigured (bad arguments to a condition, a malformed rule file), as opposed to `ArchRuleError`, which means the _architecture_ is wrong. Two different faults with two different audiences: one tells a rule author they mistyped something, the other tells a team their code drifted. Carries `subject` — the condition, predicate or file at fault — so a caller can route the failure without parsing the message. `isArchConfigError` is structural for the same two-copies-on-disk reason as `isArchRuleError`.
+- **`ArchFix`** — a machine-applicable edit on a violation: `file`, a `[start, end)` character span, and the `replacement` text. This is what `--fix` applies.
+
+### The JSON report
+
+`--format json` emits an **`ArchJsonReport`**: a `summary` (`total`, `errors`, `warnings`, `reason`), then **`ArchJsonViolation`** entries, plus **`ArchJsonSuppression`** for findings silenced by an `eess-exclude` comment and **`ArchJsonUntestedAllowlist`** for allowlists nothing exercised. Import these to type a tool that consumes eess output rather than re-declaring the shape.
+
+### Filtering a run
+
+- **`BaselineFilter`** — decides whether an already-accepted finding is suppressed by the baseline file.
+- **`DiffFilterLike`** — decides whether a finding falls inside the changed region, for `--changed` runs.
+
+Both are interfaces so a host can supply its own; the kernel ships implementations.
+
+### Correspondence
+
+`correspondence()` binds two `Selection`s and checks they agree in both directions.
+
+- **`CorrespondenceOptions`** — its argument: the `left` and `right` selections, a join strategy, and optional per-side `suggest` callbacks for the two-sided message.
+- **`KeyBy`** — the fast join: a key extracted per element, giving an O(n+m) match. Prefer it. The fallback `matchBy` predicate is O(n×m).
+- **`RelationSpec`** — what `preserveRelations()` takes: how to read edges from each side, so the check covers relationships and not just membership.
+- **`ElementInfo`** — the `name` / `file` / `line` a dialect reports for one element, which is what the message and the violation's location are built from.
+
+### Declaring globs (for custom predicates)
+
+A predicate written with `definePredicate` should declare the globs it matches on.
+Without that it is opaque, so a vacuity diagnosis cannot tell "matched nothing
+because the glob is dead" from "matched nothing because nothing was there" — and
+any `or()` containing it becomes undiagnosable too.
+
+- **`globNode(leaf)`** — wrap a single declared glob into a tree. The common case.
+- **`globAnyOf(globs, kind, base?)`** — declare several alternatives at once.
+- **`DeclaredGlob`** — one glob with its `kind` and `base`. **`GlobKind`** is what the glob matches against (`'file-path' | 'parent-dir' | 'import-target' | 'specifier' | 'literal'`) and **`GlobBase`** is what it is resolved against (`'absolute' | 'tsconfig-relative' | 'normalized'`).
+- **`GlobTree<L>`** — the `and`/`any` tree the declarations form; **`DeclaredGlobs`** is that tree over `DeclaredGlob`, and **`GlobLeaf<L>`** is one position in it.
+- **`OpaqueGlob`** — the explicit "this branch cannot be described" marker. Honest, and it is what keeps an undeclared predicate from silently reading as a dead one.
+- **`GlobSite`** — a declared glob plus where it was written; **`GlobPosition`** is that where (`'selector' | 'discovery' | 'condition' | 'exclusion'`), which is what lets a diagnosis point at the glob you actually got wrong.
+- **`GlobNode`** — the tree over `GlobSite`, i.e. a fully-stamped declaration ready to diagnose.
+
+### Coverage evidence
+
+- **`EdgeCoverage`** — one rule's evidence: how many `subjects` it saw, how many `edges` it actually tested, and a `reason` when that number is zero.
+- **`UntestedReason`** — why zero: `'no-edges'` (nothing to test, usually correct), `'all-filtered'` (edges existed and every one was filtered out), `'none-matched'` (edges existed and none matched the allowlist). The distinction is the point — a rule that tested nothing should say which of the three it was, per ADR-010.
+
 ## Who uses it
 
 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.
 
-Install `@nielspeter/eess` directly only when authoring a new dialect or a cross-dialect tool on top of the kernel.
+**If that is you, `/internal` is your surface, not a wall.** The two sentences above look
+like they contradict each other — "not for you", then "install it if you are writing a
+dialect" — so to be explicit: a dialect author is exactly who `/internal` exists for, and
+the five in this repo import from it. What the root alone gives you is the rule-authoring
+vocabulary, not the engine. Nothing there is documented and it changes without migration
+notes, so treat it as a contract you re-check on each kernel bump; if you are building a
+dialect you intend to publish, open an issue and we will work out what belongs on the root.
 
 ## License
 

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-generator.d.ts

@@ -5,6 +5,15 @@ import type { ArchViolation } from './violation.js';
  * Used to generate a baseline: run all rules, collect violations,
  * write them to a baseline file.
  *
+ * **This bypasses the evidence gate, deliberately and knowingly** — see ADR-014
+ * and proposal 011 ask C. Prefer a dialect's `baseline` command, which gates per
+ * rule file and refuses a builder that certified nothing.
+ *
+ * **Not the same function as `eess-ts`'s `collectViolations`.** This one takes
+ * builders with a throwing `check()` and harvests the `ArchRuleError`; the
+ * dialect's takes builders with a non-throwing `violations()`. Same name, same
+ * `@example`, different contract.
+ *
  * @example
  * const violations = collectViolations(
  *   classes(p).that().extend('Base').should().notContain(call('parseInt')),

package/dist/baseline-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"baseline-generator.d.ts","sourceRoot":"","sources":["../src/baseline-generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAGnD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC,GAAG,aAAa,EAAE,CAc5F"}
+{"version":3,"file":"baseline-generator.d.ts","sourceRoot":"","sources":["../src/baseline-generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAGnD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC,GAAG,aAAa,EAAE,CAc5F"}

package/dist/baseline-generator.js

@@ -5,6 +5,15 @@ import { ArchRuleError } from './errors.js';
  * Used to generate a baseline: run all rules, collect violations,
  * write them to a baseline file.
  *
+ * **This bypasses the evidence gate, deliberately and knowingly** — see ADR-014
+ * and proposal 011 ask C. Prefer a dialect's `baseline` command, which gates per
+ * rule file and refuses a builder that certified nothing.
+ *
+ * **Not the same function as `eess-ts`'s `collectViolations`.** This one takes
+ * builders with a throwing `check()` and harvests the `ArchRuleError`; the
+ * dialect's takes builders with a non-throwing `violations()`. Same name, same
+ * `@example`, different contract.
+ *
  * @example
  * const violations = collectViolations(
  *   classes(p).that().extend('Base').should().notContain(call('parseInt')),

package/dist/baseline-generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"baseline-generator.js","sourceRoot":"","sources":["../src/baseline-generator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAG,QAAsC;IACzE,MAAM,aAAa,GAAoB,EAAE,CAAA;IAEzC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,OAAO,CAAC,KAAK,EAAE,CAAA;QACjB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;gBACnC,aAAa,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,CAAA;YACzC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,aAAa,CAAA;AACtB,CAAC"}
+{"version":3,"file":"baseline-generator.js","sourceRoot":"","sources":["../src/baseline-generator.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAG,QAAsC;IACzE,MAAM,aAAa,GAAoB,EAAE,CAAA;IAEzC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,OAAO,CAAC,KAAK,EAAE,CAAA;QACjB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;gBACnC,aAAa,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,CAAA;YACzC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,aAAa,CAAA;AACtB,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/fixed/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