@nielspeter/eess-ts 0.2.0 → 0.4.0

package/dist/core/import-options.js

@@ -26,4 +26,68 @@ export function isTypeOnlyImport(decl) {
     const specifiers = decl.getNamedImports();
     return specifiers.length > 0 && specifiers.every((s) => s.isTypeOnly());
 }
+/**
+ * Check whether a re-export is purely type-only (no runtime dependency).
+ *
+ * The `export … from` analogue of {@link isTypeOnlyImport}, and **both halves of
+ * the disjunction are needed** — measured, the two spellings put the flag in
+ * different places:
+ *
+ * | form                            | `decl.isTypeOnly()` | specifiers |
+ * | ------------------------------- | ------------------- | ---------- |
+ * | `export type { X } from 's'`    | **true**            | false      |
+ * | `export { type X } from 's'`    | false               | **true**   |
+ * | `export type * from 's'`        | **true**            | (none)     |
+ * | `export { X } from 's'`         | false               | false      |
+ *
+ * No default or namespace analogue exists, verified: there is no way to write a
+ * re-export that binds a runtime value while every named specifier is
+ * type-only, so this needs none of {@link isTypeOnlyImport}'s guards. A bare
+ * `export * from 's'` has no named specifiers and is runtime, which is why the
+ * second half requires a non-empty list.
+ */
+export function isTypeOnlyReExport(decl) {
+    if (decl.isTypeOnly())
+        return true;
+    const specifiers = decl.getNamedExports();
+    return specifiers.length > 0 && specifiers.every((s) => s.isTypeOnly());
+}
+/**
+ * Split a variadic glob API's arguments, without a type assertion.
+ *
+ * Five entry points take `...args: [string[], ImportOptions] | string[]` —
+ * `onlyImportFrom`, `notImportFrom`, `dependOn`, `importFrom`, `importFromAny` —
+ * so a caller can write either `f('a', 'b')` or `f(['a', 'b'], { … })`. TypeScript
+ * cannot narrow a tuple-union rest parameter from `Array.isArray(args[0])`, which
+ * is true and was the stated reason for **ten** `as` casts across three files:
+ *
+ * ```ts
+ * const globs: string[] = Array.isArray(args[0]) ? args[0] : (args as string[])
+ * const options = Array.isArray(args[0]) && args.length > 1 ? (args[1] as ImportOptions) : undefined
+ * ```
+ *
+ * [ADR-005](../../../../adr/005-no-any-no-type-assertions.md) prescribes a type guard,
+ * and a guard does narrow it: `.filter((a): a is string => …)` produces `string[]`
+ * with no assertion, and `typeof second === 'object'` narrows the options. The
+ * casts were avoidable; only the direct narrowing was not.
+ *
+ * One owner rather than five copies, which is the other half. The dispatch was
+ * duplicated five times, and a duplicated predicate in this repo has already
+ * caused a measurement error once —
+ * [ts-archunit bug 0044](https://github.com/nielspeter/ts-archunit/blob/main/bugs/fixed/0044-an-inline-exclusion-comment-has-no-feedback-channel.md).
+ */
+export function splitGlobArgs(args) {
+    const [first, second] = args;
+    if (Array.isArray(first)) {
+        return {
+            globs: first,
+            options: typeof second === 'object' && second !== null && !Array.isArray(second)
+                ? second
+                : undefined,
+        };
+    }
+    // The variadic form: every argument is a glob string. The predicate is what
+    // makes this cast-free — `filter` alone would leave the union in place.
+    return { globs: args.filter((a) => typeof a === 'string'), options: undefined };
+}
 //# sourceMappingURL=import-options.js.map

package/dist/core/import-options.js.map

@@ -1 +1 @@
-{"version":3,"file":"import-options.js","sourceRoot":"","sources":["../../src/core/import-options.ts"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAuB;IACtD,0DAA0D;IAC1D,IAAI,IAAI,CAAC,UAAU,EAAE;QAAE,OAAO,IAAI,CAAA;IAClC,2CAA2C;IAC3C,IAAI,IAAI,CAAC,gBAAgB,EAAE;QAAE,OAAO,KAAK,CAAA;IACzC,6CAA6C;IAC7C,IAAI,IAAI,CAAC,kBAAkB,EAAE;QAAE,OAAO,KAAK,CAAA;IAC3C,sDAAsD;IACtD,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,EAAE,CAAA;IACzC,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAA;AACzE,CAAC"}
+{"version":3,"file":"import-options.js","sourceRoot":"","sources":["../../src/core/import-options.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAuB;IACtD,0DAA0D;IAC1D,IAAI,IAAI,CAAC,UAAU,EAAE;QAAE,OAAO,IAAI,CAAA;IAClC,2CAA2C;IAC3C,IAAI,IAAI,CAAC,gBAAgB,EAAE;QAAE,OAAO,KAAK,CAAA;IACzC,6CAA6C;IAC7C,IAAI,IAAI,CAAC,kBAAkB,EAAE;QAAE,OAAO,KAAK,CAAA;IAC3C,sDAAsD;IACtD,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,EAAE,CAAA;IACzC,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAA;AACzE,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAuB;IACxD,IAAI,IAAI,CAAC,UAAU,EAAE;QAAE,OAAO,IAAI,CAAA;IAClC,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,EAAE,CAAA;IACzC,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAA;AACzE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,aAAa,CAAC,IAAoD;IAIhF,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IAC5B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,OAAO,EACL,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;gBACrE,CAAC,CAAC,MAAM;gBACR,CAAC,CAAC,SAAS;SAChB,CAAA;IACH,CAAC;IACD,4EAA4E;IAC5E,wEAAwE;IACxE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,CAAA;AAC9F,CAAC"}

package/dist/core/line-index.d.ts

@@ -0,0 +1,3 @@
+import type { Node } from 'ts-morph';
+export declare function countCodeLines(node: Node): number;
+//# sourceMappingURL=line-index.d.ts.map

package/dist/core/line-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-index.d.ts","sourceRoot":"","sources":["../../src/core/line-index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,UAAU,CAAA;AA8NhD,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAYjD"}

package/dist/core/line-index.js

@@ -0,0 +1,229 @@
+import { SyntaxKind } from 'ts-morph';
+import { registerCacheReset } from '@nielspeter/eess';
+/**
+ * The per-file line index behind `linesOfCode`.
+ *
+ * **Why this is in `core/` and not beside `linesOfCode` in `helpers/`.** It is a
+ * cache over ts-morph state, and this package already has three of those —
+ * `element-cache.ts`, `descendant-cache.ts`, `module-edges.ts` — each of which
+ * registers a reset and drops per-file entries on `onModified`. The first cut of
+ * this index lived in `helpers/`, followed neither convention, and reintroduced
+ * the exact defect the other three exist to document. Caches live here, next to
+ * their siblings, where the convention is visible.
+ */
+/**
+ * Comment kinds ts-morph surfaces as ordinary leaves in `getChildren()`.
+ *
+ * The compiler treats these as trivia and omits them; ts-morph deliberately does
+ * not, which is useful everywhere else and is exactly what `linesOfCode` must
+ * undo. Measured: without this set a body of 4 code lines and 3 comment lines
+ * counted 7.
+ */
+const NON_CODE_KINDS = new Set([
+    SyntaxKind.SingleLineCommentTrivia,
+    SyntaxKind.MultiLineCommentTrivia,
+]);
+/**
+ * Count the lines of a node that actually carry code.
+ *
+ * Physical source lines, excluding comments and blank lines. A line holding only
+ * `}` still counts — it is a source line; this is not a statement count.
+ *
+ * **Why not the span.**
+ * [Bug 0170](../../../../work/bugs/0170-linesofcode-counts-comments-so-documentation-reads-as-size.md):
+ * this was `end - start + 1`, which measures documentation as size. In this repo
+ * that put two rules in direct conflict — `eess/jsdoc-on-public-methods` requires
+ * a doc block on every public method, and `eess/max-class-lines` then counted
+ * those blocks, so satisfying the first rule broke the second. Measured across
+ * this source, six of nine class findings and two of four method findings were
+ * comment lines alone.
+ *
+ * The old docstring justified the span by saying it "avoids the fragility of
+ * text-based comment stripping". That reason is sound and it is why this counts
+ * TOKENS rather than matching comment syntax in text: comments are trivia, so
+ * they are never tokens, and they drop out structurally. Nothing is stripped.
+ *
+ * Comments have to be skipped by hand even so: ts-morph does not hide them the
+ * way the compiler's own tree does — `getChildren()` hands back
+ * `SingleLineCommentTrivia` and `MultiLineCommentTrivia` as ordinary leaves, and
+ * JSDoc as a child node. JSDoc is the sharpest of the three, because
+ * `getStartLineNumber()` excludes it while `getChildren()` returns it, so
+ * counting it made an element measure LARGER than its own span —
+ * `complexity.test.ts` pins against that as a corpus-wide invariant.
+ */
+/**
+ * Character offset of the first character of each line, ascending.
+ *
+ * Measured, this is the whole performance story. Walking every token in this
+ * repo's source costs 99ms and reading their POSITIONS costs 21ms — but asking
+ * ts-morph for their line NUMBERS costs 523ms, five times the walk. `getStart()`
+ * returns a number the AST already holds; `getStartLineNumber()` resolves it
+ * against the file's text on every call.
+ *
+ * So positions come from the AST and the offset-to-line mapping is done here,
+ * against a table built once per file. That mapping is pure arithmetic over
+ * newline offsets — it is not text-based comment detection, which would be
+ * genuinely fragile (a regex literal containing `//` cannot be told from a
+ * comment without parsing). Deciding what is a comment stays the AST's job.
+ */
+let lineStartsByFile = new WeakMap();
+function lineStartsOf(sourceFile) {
+    const cached = lineStartsByFile.get(sourceFile);
+    if (cached !== undefined)
+        return cached;
+    const text = sourceFile.getFullText();
+    const starts = [0];
+    for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) === NEWLINE)
+            starts.push(i + 1);
+    }
+    lineStartsByFile.set(sourceFile, starts);
+    return starts;
+}
+const NEWLINE = 10;
+/**
+ * The 1-based line holding a character offset.
+ *
+ * The count of line starts at or before the offset IS the line number, because
+ * the table begins with 0 for line 1.
+ */
+function lineAt(lineStarts, pos) {
+    return countUpTo(lineStarts, pos);
+}
+/**
+ * Every line of a source file that carries at least one token, ascending.
+ *
+ * Computed once per file and cached. Per-subject walking re-visited a method's
+ * tokens for every enclosing rule — `maxClassLines` walks the class, then
+ * `maxMethodLines` walks each method inside it.
+ *
+ * Dropped when the file is modified, via the listener in {@link watchOnce}.
+ * **Object identity is not enough here and never was.** A `SourceFile`'s
+ * identity SURVIVES an edit — `module-edges.ts` measured it, `descendant-cache.ts`
+ * records the same trap one level down, and the first cut of this index asserted
+ * the opposite and shipped the third instance of it.
+ *
+ * The failure is not "returns the previous number". Positions come from the AST
+ * and stay fresh while the table goes stale, so the two are read against each
+ * other and the answer corresponds to nothing: measured, a class that grew from
+ * 5 code lines to 8 reported 6.
+ */
+let codeLinesByFile = new WeakMap();
+const watched = new WeakSet();
+/**
+ * Join `resetProjectCache()`, the documented consumer escape hatch.
+ *
+ * **This registration is UNPROVEN, and saying so is the point.** Measured:
+ * emptying this callback leaves all 3,523 `packages/ts` tests green. That is not
+ * an oversight to fix with a cleverer test — it follows from what the
+ * registration is FOR. Correctness is already carried by the per-file
+ * `onModified` listener in {@link watchOnce}, which fires on every mutation path
+ * (and which IS proven — removing it reddens two rows in `complexity.test.ts`).
+ * What this adds is **memory reclamation on an explicit reset**: a consumer done
+ * with a large project can drop the tables without waiting for the `WeakMap` keys
+ * to become unreachable.
+ *
+ * A property with no observable correctness signature cannot have a break class,
+ * and this file's own rule two functions down — "a redundant guard is an
+ * unprovable one" — is why that is recorded here rather than left to look
+ * tested. Do not add a test that calls `resetProjectCache()` and asserts the next
+ * measurement is correct: it is correct either way, and such a row would pass
+ * over a deleted callback, which is worse than no row at all.
+ */
+registerCacheReset(() => {
+    lineStartsByFile = new WeakMap();
+    codeLinesByFile = new WeakMap();
+});
+/**
+ * Register the per-file invalidation listener, once.
+ *
+ * Not once per cache miss: a watch session re-evaluating rules would otherwise
+ * accumulate a listener per rule execution. Both maps drop together, because the
+ * same edit invalidates both.
+ *
+ * The closure reads `lineStartsByFile` / `codeLinesByFile` as **live bindings**
+ * rather than capturing them, which is what keeps invalidation working after
+ * `registerCacheReset` replaces the maps — `descendant-cache.ts` records that
+ * capturing by value made a post-reset edit invisible and passed the suite.
+ *
+ * `onModified` fires on every mutation path that matters here — measured:
+ * `addMethod`, `replaceWithText`, and `createSourceFile(path, text,
+ * { overwrite: true })`, which is the fixture shape this repo's own guidance
+ * prescribes and the one that returned a wrong number for every case after the
+ * first.
+ */
+function watchOnce(sourceFile) {
+    if (watched.has(sourceFile))
+        return;
+    watched.add(sourceFile);
+    sourceFile.onModified(() => {
+        lineStartsByFile.delete(sourceFile);
+        codeLinesByFile.delete(sourceFile);
+    });
+}
+function codeLinesOf(sourceFile) {
+    const cached = codeLinesByFile.get(sourceFile);
+    if (cached !== undefined)
+        return cached;
+    const lineStarts = lineStartsOf(sourceFile);
+    const lines = new Set();
+    const visit = (current) => {
+        if (NON_CODE_KINDS.has(current.getKind()))
+            return;
+        // JSDoc spans many kinds; the prefix is what they share.
+        if (current.getKindName().startsWith('JSDoc'))
+            return;
+        const children = current.getChildren();
+        if (children.length === 0) {
+            addTokenLines(lines, lineStarts, current);
+            return;
+        }
+        for (const child of children)
+            visit(child);
+    };
+    visit(sourceFile);
+    const sorted = [...lines].sort((a, b) => a - b);
+    codeLinesByFile.set(sourceFile, sorted);
+    return sorted;
+}
+/**
+ * Mark every line a leaf token occupies. Multi-line tokens exist — a template
+ * literal, a long string — and every line they cover is code.
+ */
+function addTokenLines(lines, lineStarts, token) {
+    const first = lineAt(lineStarts, token.getStart());
+    // `getEnd()` is exclusive, so the last character is one before it. Clamped,
+    // because a zero-width node has `getEnd() === getStart()`.
+    const last = lineAt(lineStarts, Math.max(token.getStart(), token.getEnd() - 1));
+    for (let line = first; line <= last; line++)
+        lines.add(line);
+}
+/** How many entries of an ascending array are `<= value`. */
+function countUpTo(sorted, value) {
+    let low = 0;
+    let high = sorted.length;
+    while (low < high) {
+        const mid = (low + high) >>> 1;
+        // `?? -Infinity` satisfies noUncheckedIndexedAccess without a non-null
+        // assertion (ADR-005); `mid` is always in range, so it never applies.
+        if ((sorted[mid] ?? -Infinity) <= value)
+            low = mid + 1;
+        else
+            high = mid;
+    }
+    return low;
+}
+export function countCodeLines(node) {
+    const sourceFile = node.getSourceFile();
+    // ONE registration, here rather than in each accessor. Both maps drop on the
+    // same event, so a call in either accessor made the other's redundant — and a
+    // redundant guard is an unprovable one: removing either alone left the suite
+    // green. At the single entry, removing it reddens the invalidation tests.
+    watchOnce(sourceFile);
+    const lineStarts = lineStartsOf(sourceFile);
+    const lines = codeLinesOf(sourceFile);
+    const first = lineAt(lineStarts, node.getStart());
+    const last = lineAt(lineStarts, Math.max(node.getStart(), node.getEnd() - 1));
+    return countUpTo(lines, last) - countUpTo(lines, first - 1);
+}
+//# sourceMappingURL=line-index.js.map

package/dist/core/line-index.js.map

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

package/dist/core/metric-violation.d.ts

@@ -0,0 +1,86 @@
+import type { Node } from 'ts-morph';
+import type { ArchViolation } from '@nielspeter/eess';
+/**
+ * A finding whose message states a **measurement** — bug 0012.
+ *
+ * Metric conditions write the measured value into the message:
+ *
+ *     Big has 10 methods (max: 5) — consider splitting into focused classes
+ *
+ * `hashViolation` identifies a violation by its message, so the identity moved
+ * whenever the measurement moved — **in either direction**. Baseline a class at
+ * 10 methods, delete two, and the finding was reported as new:
+ *
+ *     10 → 10   green ✓
+ *     10 → 12   red   ✓  (worse)
+ *     10 → 8    RED   ✗  (better — the defect)
+ *     10 → 5    green ✓  (under the threshold)
+ *
+ * Paying down the debt failed CI, and kept failing on every incremental step
+ * until the class dropped under the threshold entirely. A team that split four
+ * methods out of an 87-method service got a red build for its trouble. The
+ * external audit that motivated this recommends adopting these rules "behind a
+ * ratchet (accept today's god objects, block new regressions)" and records them
+ * at **zero uses** — the ratchet they were told to use did not work.
+ *
+ * ## Why identity alone cannot fix it
+ *
+ * Bug 0010 added `identity` for messages that state a derived population, and
+ * applying it naively here trades one failure for a worse one:
+ *
+ * | identity contains | improving to 8 | regressing to 12 |
+ * | ----------------- | -------------- | ---------------- |
+ * | the count         | **red** ✗      | red ✓            |
+ * | no count          | green ✓        | **green** ✗      |
+ *
+ * Dropping the count turns the baseline into a mute button. Identity answers
+ * "is this the same finding?", and a metric needs "is it **worse** than what we
+ * accepted?" — a comparison, not an equality. So this carries both: a stable
+ * identity that finds the entry, and `measured`, which the baseline stores and
+ * compares. See `Baseline.isKnown`.
+ *
+ * **Ten sites produce these, not the eight the bug enumerated.** That table was
+ * built by grepping the `has N <noun>` message shape, which misses the two
+ * complexity conditions — `has cyclomatic complexity N` puts the number last.
+ * Both were left on `createViolation` in the first cut of this fix while the
+ * docs already claimed complexity was ratcheted, so a reader would have removed
+ * their CI escape hatch for a gate that still fired on every improvement. Found
+ * by review; a mechanical enumeration by *shape* is not one by *behaviour*.
+ */
+export declare function metricViolation(node: Node, options: {
+    /**
+     * What is being measured — `methods`, `lines`, `parameters`, `properties`,
+     * `named-exports`. Part of the identity, so one element can carry several
+     * metric findings without them colliding.
+     */
+    metric: string;
+    /** The measurement now. Compared against the baselined value, not equated. */
+    measured: number;
+    /**
+     * What `measured` COUNTS, when that is not simply the metric's name.
+     *
+     * The baseline persists this and refuses to compare across a change of unit
+     * ([bug 0171](../../../../work/bugs/0171-a-metric-unit-change-silently-loosens-every-baselined-ratchet.md)).
+     * `lines` is why it exists: the metric kept its name while `linesOfCode`
+     * changed from counting a span to counting code, so identity still matched
+     * and every baselined ceiling silently tripled. A metric whose name already
+     * says what it counts — `methods`, `parameters` — needs nothing here.
+     */
+    unit?: string;
+    message: string;
+    /**
+     * The element's qualified name, when `getElementName` would under-qualify it.
+     *
+     * Members need this: `getElementName(member)` returns the bare `save`, while
+     * the message already says `UserRepo.save`. Two classes with a `save` method
+     * would otherwise be one entry.
+     */
+    qualifiedName?: string;
+}, context: {
+    rule: string;
+    because?: string;
+    suggestion?: string;
+    ruleId?: string;
+    docs?: string;
+}): ArchViolation;
+//# sourceMappingURL=metric-violation.d.ts.map

package/dist/core/metric-violation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-violation.d.ts","sourceRoot":"","sources":["../../src/core/metric-violation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AACpC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAGrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,EACV,OAAO,EAAE;IACP;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,EACD,OAAO,EAAE;IACP,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,GACA,aAAa,CAkCf"}

package/dist/core/metric-violation.js

@@ -0,0 +1,132 @@
+import { createViolation, enclosingScopeName, getElementName } from './violation.js';
+/**
+ * A finding whose message states a **measurement** — bug 0012.
+ *
+ * Metric conditions write the measured value into the message:
+ *
+ *     Big has 10 methods (max: 5) — consider splitting into focused classes
+ *
+ * `hashViolation` identifies a violation by its message, so the identity moved
+ * whenever the measurement moved — **in either direction**. Baseline a class at
+ * 10 methods, delete two, and the finding was reported as new:
+ *
+ *     10 → 10   green ✓
+ *     10 → 12   red   ✓  (worse)
+ *     10 → 8    RED   ✗  (better — the defect)
+ *     10 → 5    green ✓  (under the threshold)
+ *
+ * Paying down the debt failed CI, and kept failing on every incremental step
+ * until the class dropped under the threshold entirely. A team that split four
+ * methods out of an 87-method service got a red build for its trouble. The
+ * external audit that motivated this recommends adopting these rules "behind a
+ * ratchet (accept today's god objects, block new regressions)" and records them
+ * at **zero uses** — the ratchet they were told to use did not work.
+ *
+ * ## Why identity alone cannot fix it
+ *
+ * Bug 0010 added `identity` for messages that state a derived population, and
+ * applying it naively here trades one failure for a worse one:
+ *
+ * | identity contains | improving to 8 | regressing to 12 |
+ * | ----------------- | -------------- | ---------------- |
+ * | the count         | **red** ✗      | red ✓            |
+ * | no count          | green ✓        | **green** ✗      |
+ *
+ * Dropping the count turns the baseline into a mute button. Identity answers
+ * "is this the same finding?", and a metric needs "is it **worse** than what we
+ * accepted?" — a comparison, not an equality. So this carries both: a stable
+ * identity that finds the entry, and `measured`, which the baseline stores and
+ * compares. See `Baseline.isKnown`.
+ *
+ * **Ten sites produce these, not the eight the bug enumerated.** That table was
+ * built by grepping the `has N <noun>` message shape, which misses the two
+ * complexity conditions — `has cyclomatic complexity N` puts the number last.
+ * Both were left on `createViolation` in the first cut of this fix while the
+ * docs already claimed complexity was ratcheted, so a reader would have removed
+ * their CI escape hatch for a gate that still fired on every improvement. Found
+ * by review; a mechanical enumeration by *shape* is not one by *behaviour*.
+ */
+export function metricViolation(node, options, context) {
+    const base = createViolation(node, options.message, context);
+    return {
+        ...base,
+        // The qualified name reaches `element` too, not only `identity` — bug 0068's
+        // first consequence. `createViolation` derives it with `getElementName`,
+        // which resolves an unnamed node up to its nearest named ancestor, so a
+        // finding ABOUT an object-literal function was labelled with the ENCLOSING
+        // function's name while its own message named it correctly. `element` is
+        // what the terminal prints, what the JSON reports, and one of the three
+        // fields string-form `.excluding()` matches by exact membership
+        // (`execute-rule.ts`), so the disagreement also made an exclusion written
+        // against the printed name silently miss.
+        element: options.qualifiedName ?? base.element,
+        // File, element and metric — never the value. The value is the thing being
+        // ratcheted, so putting it here makes every change a new finding, which is
+        // the bug. Leaving the FILE out is the other half, and it was shipped once:
+        // two classes named `Big` in different files produced one identity, one
+        // hash, and `withBaseline`'s last-write-wins picked whichever ceiling came
+        // last — measured, a real 10 → 15 regression was silently accepted while
+        // the sibling sat at 20. That is bug 0028's shape recreated inside bug
+        // 0012's fix, and `ArchViolation.identity`'s own contract forbids it: "two
+        // distinct violations sharing one identity are one violation to the
+        // baseline, and accepting either accepts both."
+        //
+        // A path here is portable: `hashViolation` scrubs identity through
+        // `normalizeIdentityText(text, root)`, which is what that scrub is for.
+        identity: `${node.getSourceFile().getFilePath()}::${identityName(node, options.qualifiedName)}::${options.metric}`,
+        measured: options.measured,
+        // Defaults to the metric's own name: for `methods` or `parameters` the name
+        // IS the unit, and only a metric that can change what it counts under a
+        // stable name needs to say so explicitly.
+        measuredUnit: options.unit ?? options.metric,
+    };
+}
+/**
+ * The name segment of a metric identity: the subject's own name, **prefixed by the
+ * name of whatever encloses it**, so that two subjects sharing a name in one file
+ * are still two identities.
+ *
+ * Measured, across every function shape — neither name alone is sufficient:
+ *
+ * | shape                                | own name            | enclosing scope | identity segment          |
+ * | ------------------------------------ | ------------------- | --------------- | ------------------------- |
+ * | two factories returning `{build}`    | `build`, `build`    | `makeBeta`, `makeGamma` | `makeBeta.build`, … |
+ * | an arrow inside a named function     | `errorResponseBuilder` | `makeAlpha`  | `makeAlpha.errorResponseBuilder` |
+ * | a top-level `function takesFive`     | `takesFive`         | none            | `takesFive` — unchanged   |
+ * | a class method via `functions()`     | `Repo.save`         | `Repo`          | `Repo.save` — already carries it |
+ *
+ * Two mistakes are recorded here because both shipped and both were found by
+ * review rather than by reasoning:
+ *
+ * 1. **The own name alone** (bug 0068's first fix) moved the collision instead of
+ *    closing it: `owningBindingName` deliberately declines to prefix a literal
+ *    returned from a factory, so both `build`s are just `build`.
+ * 2. **`getElementName` is not a scope.** It returns the node's OWN name when the
+ *    node has one and only walks ancestors otherwise — so for method shorthand
+ *    (`{ build() {} }`, a `MethodDeclaration`) it returned `build`, the prefix was
+ *    skipped, and the fix worked for the arrow spelling of the same code and not
+ *    for this one. The scope now comes from `enclosingScopeName`, which always
+ *    walks from the parent.
+ *
+ * There is deliberately **no `own === scope` short-circuit**: a nested function
+ * whose name equals its enclosing function's (`function save() { return { save:
+ * … } }`) is exactly the case that needs the prefix, and equality of strings
+ * cannot tell "the scope is me" from "the scope happens to share my name".
+ *
+ * Known limit, stated rather than papered over: a literal in a **call argument**
+ * at module level (`register({ handler: … })`) has no enclosing named
+ * declaration, so two of them in one file still share an identity. Nothing stable
+ * distinguishes them — that is bug 0067's territory ("there is no right name
+ * yet"), not this one's.
+ */
+function identityName(node, qualifiedName) {
+    const own = qualifiedName ?? getElementName(node);
+    const scope = enclosingScopeName(node);
+    if (scope === undefined)
+        return own;
+    // Already carries it — a class method's `Repo.save` under scope `Repo`.
+    if (own.startsWith(`${scope}.`) || own.endsWith(`.${scope}`))
+        return own;
+    return `${scope}.${own}`;
+}
+//# sourceMappingURL=metric-violation.js.map

package/dist/core/metric-violation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-violation.js","sourceRoot":"","sources":["../../src/core/metric-violation.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAU,EACV,OA6BC,EACD,OAMC;IAED,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;IAC5D,OAAO;QACL,GAAG,IAAI;QACP,6EAA6E;QAC7E,yEAAyE;QACzE,wEAAwE;QACxE,2EAA2E;QAC3E,yEAAyE;QACzE,wEAAwE;QACxE,gEAAgE;QAChE,0EAA0E;QAC1E,0CAA0C;QAC1C,OAAO,EAAE,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC,OAAO;QAC9C,2EAA2E;QAC3E,2EAA2E;QAC3E,4EAA4E;QAC5E,wEAAwE;QACxE,2EAA2E;QAC3E,yEAAyE;QACzE,uEAAuE;QACvE,2EAA2E;QAC3E,oEAAoE;QACpE,gDAAgD;QAChD,EAAE;QACF,mEAAmE;QACnE,wEAAwE;QACxE,QAAQ,EAAE,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC,WAAW,EAAE,KAAK,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,aAAa,CAAC,KAAK,OAAO,CAAC,MAAM,EAAE;QAClH,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,4EAA4E;QAC5E,wEAAwE;QACxE,0CAA0C;QAC1C,YAAY,EAAE,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,MAAM;KAC7C,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,SAAS,YAAY,CAAC,IAAU,EAAE,aAAiC;IACjE,MAAM,GAAG,GAAG,aAAa,IAAI,cAAc,CAAC,IAAI,CAAC,CAAA;IACjD,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAA;IACtC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,GAAG,CAAA;IACnC,wEAAwE;IACxE,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,KAAK,GAAG,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,KAAK,EAAE,CAAC;QAAE,OAAO,GAAG,CAAA;IACxE,OAAO,GAAG,KAAK,IAAI,GAAG,EAAE,CAAA;AAC1B,CAAC"}