@nielspeter/eess-ts 0.2.1 → 0.5.0

package/dist/core/import-options.d.ts

@@ -1,4 +1,4 @@
-import type { ImportDeclaration } from 'ts-morph';
+import type { ExportDeclaration, ImportDeclaration } from 'ts-morph';
 /**
  * Options for import-related conditions and predicates.
  */
@@ -10,7 +10,11 @@ export interface ImportOptions {
      * Type-only imports are erased at compile time and create no runtime dependency.
      * Useful for layer isolation rules where type-sharing is acceptable.
      *
-     * Default: false (all imports checked, for backward compatibility).
+     * Default: **per condition.** `false` — count every import — for `dependOn`,
+     * `importFrom`, `notImportFrom`, `onlyImportFrom`, `notDependOn` and
+     * `respectLayerOrder`, which ask whether the code is *coupled*. `true` for
+     * `beFreeOfCycles`, which asks whether the module is *evaluated*: an erased import
+     * cannot contribute to an initialization cycle. See `docs/slices.md`.
      */
     ignoreTypeImports?: boolean;
 }
@@ -29,4 +33,53 @@ export interface ImportOptions {
  * - `import * as Foo from '...'` (namespace import is runtime)
  */
 export declare function isTypeOnlyImport(decl: ImportDeclaration): boolean;
+/**
+ * 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 declare function isTypeOnlyReExport(decl: ExportDeclaration): boolean;
+/**
+ * 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 declare function splitGlobArgs(args: readonly (string[] | ImportOptions | string)[]): {
+    globs: string[];
+    options: ImportOptions | undefined;
+};
 //# sourceMappingURL=import-options.d.ts.map

package/dist/core/import-options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-options.d.ts","sourceRoot":"","sources":["../../src/core/import-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAEjD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAUjE"}
+{"version":3,"file":"import-options.d.ts","sourceRoot":"","sources":["../../src/core/import-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAEpE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAUjE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAInE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,GAAG,aAAa,GAAG,MAAM,CAAC,EAAE,GAAG;IACnF,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,OAAO,EAAE,aAAa,GAAG,SAAS,CAAA;CACnC,CAcA"}

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/invalidate-on-modify.d.ts

@@ -0,0 +1,20 @@
+import type { SourceFile } from 'ts-morph';
+/**
+ * Drop a file's cached derivations the first time it is modified, registering
+ * the listener exactly once.
+ *
+ * `descendant-cache.ts` and `line-index.ts` each carried this. They are the two
+ * per-file memo caches in this package, so they need the same invalidation and
+ * had the same code for it — `no-copy-paste` reported it at 100%.
+ *
+ * **`invalidate` is a callback rather than the caches themselves, and that is
+ * not a style choice.** Both modules RESET by reassigning their `WeakMap`s
+ * (`byFile = new WeakMap(...)`), so a listener holding the map objects would go
+ * on deleting from the map that was replaced, leaving the live one stale. A
+ * callback reads the module's current bindings at the moment it fires.
+ *
+ * `watched` stays the caller's, because it is reset alongside the caches it
+ * guards.
+ */
+export declare function invalidateOnModify(sourceFile: SourceFile, watched: WeakSet<SourceFile>, invalidate: (file: SourceFile) => void): void;
+//# sourceMappingURL=invalidate-on-modify.d.ts.map

package/dist/core/invalidate-on-modify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidate-on-modify.d.ts","sourceRoot":"","sources":["../../src/core/invalidate-on-modify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAE1C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,EAC5B,UAAU,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GACrC,IAAI,CAMN"}

package/dist/core/invalidate-on-modify.js

@@ -0,0 +1,26 @@
+/**
+ * Drop a file's cached derivations the first time it is modified, registering
+ * the listener exactly once.
+ *
+ * `descendant-cache.ts` and `line-index.ts` each carried this. They are the two
+ * per-file memo caches in this package, so they need the same invalidation and
+ * had the same code for it — `no-copy-paste` reported it at 100%.
+ *
+ * **`invalidate` is a callback rather than the caches themselves, and that is
+ * not a style choice.** Both modules RESET by reassigning their `WeakMap`s
+ * (`byFile = new WeakMap(...)`), so a listener holding the map objects would go
+ * on deleting from the map that was replaced, leaving the live one stale. A
+ * callback reads the module's current bindings at the moment it fires.
+ *
+ * `watched` stays the caller's, because it is reset alongside the caches it
+ * guards.
+ */
+export function invalidateOnModify(sourceFile, watched, invalidate) {
+    if (watched.has(sourceFile))
+        return;
+    watched.add(sourceFile);
+    sourceFile.onModified(() => {
+        invalidate(sourceFile);
+    });
+}
+//# sourceMappingURL=invalidate-on-modify.js.map

package/dist/core/invalidate-on-modify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidate-on-modify.js","sourceRoot":"","sources":["../../src/core/invalidate-on-modify.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAsB,EACtB,OAA4B,EAC5B,UAAsC;IAEtC,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;QAAE,OAAM;IACnC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;IACvB,UAAU,CAAC,UAAU,CAAC,GAAG,EAAE;QACzB,UAAU,CAAC,UAAU,CAAC,CAAA;IACxB,CAAC,CAAC,CAAA;AACJ,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;AA6NhD,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAYjD"}

package/dist/core/line-index.js

@@ -0,0 +1,227 @@
+import { SyntaxKind } from 'ts-morph';
+import { registerCacheReset } from '@nielspeter/eess/internal';
+import { invalidateOnModify } from './invalidate-on-modify.js';
+/**
+ * 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/fixed/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) {
+    invalidateOnModify(sourceFile, watched, (file) => {
+        lineStartsByFile.delete(file);
+        codeLinesByFile.delete(file);
+    });
+}
+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/fixed/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"}