@nielspeter/eess-ts 0.2.1 → 0.5.0

package/dist/core/check-all.js

@@ -0,0 +1,150 @@
+import { ArchRuleError, EMITTER_PASS_WITHOUT_EVIDENCE, finishPreset, mergeCollectResults, } from '@nielspeter/eess';
+import { UNSUPPRESSABLE } from '@nielspeter/eess/internal';
+import { callerAggregates, writeReport } from './execute-rule.js';
+import { dedupeConfigFindings } from '@nielspeter/eess/internal';
+import { suppressionNotice } from '@nielspeter/eess/internal';
+import { writeStderr } from '@nielspeter/eess/internal';
+import { edgeCoverageNotice, resetEdgeCoverage, untestedRules } from '@nielspeter/eess/internal';
+import { commentSuppressionNotice, resetCommentSuppression } from '@nielspeter/eess/internal';
+/**
+ * Run an array of rules (e.g. a spread preset) and throw one aggregated
+ * `ArchRuleError` if any **error-severity** violation is found. Warn-severity
+ * violations are reported but never throw — the same severity contract as the
+ * CLI `check`. This is the test-file terminal for the returning form:
+ *
+ * ```ts
+ * checkAll(layeredArchitecture(p, opts))
+ * checkAll([...recommended(p), ...layeredArchitecture(p, opts)])
+ * ```
+ *
+ * Each builder's `.violations()` already carries its stamped severity
+ * (via `.asSeverity()`), so aggregation and severity are preserved across the
+ * whole array — one readable error listing every error-severity violation.
+ */
+export function checkAll(rules, options) {
+    // Per run, like `runCheck` — a second `checkAll` in one vitest file must
+    // not inherit the first's rules.
+    resetEdgeCoverage();
+    resetCommentSuppression();
+    // **The receipt survives the aggregation** — plan 0263 Phase 2, and the reason
+    // ADR-014's row for this door stayed `pending` after plan 0235 shipped the
+    // contract. This line used to be `rules.flatMap((rule) => rule.violations())`,
+    // and a `flatMap` over receipts yields a bare array: every `examined` on the
+    // floor, and the evidence gate never reached. Measured before the change,
+    // `checkAll([{ violations: () => [] }])` returned silently — a rule file
+    // exporting an evidence-free builder passed through this door without a word,
+    // which is bug 0206's shape at a different seam.
+    //
+    // `mergeCollectResults` is the kernel's one merge (ADR-014 §7) and is
+    // fail-closed **per member**, so one evidence-free builder among twenty is
+    // named rather than absorbed by the others' counts.
+    // **The empty array answers for itself, because the kernel's message cannot.**
+    // `mergeCollectResults([])` is zero examined and undeclared, so the gate below
+    // fires `emitter/pass-without-evidence` — correct. But that finding's remedy
+    // names `expectEmpty: true` in a preset's report options and `.expectEmpty()`
+    // on a builder, and at THIS door there is no preset and no builder to call it
+    // on: `CheckOptions` carries `baseline`, `diff` and `format` only. A finding
+    // whose every stated remedy is unreachable is ADR-009 rule 2's failure, and
+    // `emitter-findings.ts` records that this exact message was once rewritten for
+    // exactly that reason. Four reviewers caught it being recreated here.
+    //
+    // So this door states the remedy a `checkAll` caller can actually act on. The
+    // finding stays unsuppressable and error-severity like its sibling; only the
+    // text is this door's.
+    if (rules.length === 0) {
+        throw new ArchRuleError([
+            {
+                rule: EMITTER_PASS_WITHOUT_EVIDENCE,
+                ruleId: EMITTER_PASS_WITHOUT_EVIDENCE,
+                element: EMITTER_PASS_WITHOUT_EVIDENCE,
+                file: '',
+                line: 0,
+                message: 'checkAll() was called with no rules, so this run examined nothing and cannot ' +
+                    'report a pass. Pass the rules you meant to check. If the array is computed — ' +
+                    "a preset in `report: 'builders'` mode, say — the emptiness is upstream, and " +
+                    'the preset is where it has to be declared or fixed; there is no declaration ' +
+                    'form at this door.',
+                suggestion: 'Pass the rules you meant to check. If the array is computed and legitimately ' +
+                    'empty, declare that where it is built — skipping the checkAll() call instead ' +
+                    'removes the check rather than satisfying it. ' +
+                    UNSUPPRESSABLE,
+                bypassFilters: true,
+            },
+        ]);
+    }
+    const receipt = mergeCollectResults(rules.map((rule) => rule.violations()));
+    // ADR-008: this function owns its reporting below, so the gate runs under
+    // `report: 'return'` and hands the findings back instead of emitting them.
+    // An emitter finding carries `bypassFilters`, so it survives both the baseline
+    // (`packages/core/src/baseline.ts:283`) and the diff filter, and it is
+    // error-severity, so it rides the throw at the bottom.
+    //
+    // One option, one finding (plan 0074). A preset fans a single bad option out
+    // across every generated rule, and only an aggregation point can see that.
+    let violations = dedupeConfigFindings(finishPreset(receipt, { report: 'return' }));
+    if (options?.baseline) {
+        violations = options.baseline.filterNew(violations);
+    }
+    // `checkAll` filters once for the whole array, so like the CLI it can state
+    // the real number (plan 0071). The per-rule terminals cannot — see
+    // `core/diff-disclosure.ts`.
+    let notice;
+    if (options?.diff) {
+        const before = violations.length;
+        violations = options.diff.filterToChanged(violations);
+        notice = suppressionNotice(before - violations.length, options.diff.size, options.diff.baseBranch);
+        if (notice !== undefined)
+            writeStderr(notice);
+    }
+    // `reason` is rendered as each violation's "Why:" line on the terminal path
+    // (`format.ts`: `v.because ?? reason`), so a RUN-level notice must not travel
+    // that way — it would appear as the justification for an unrelated finding.
+    // `summary.reason` in JSON is genuinely run-level, so it goes there, and
+    // stderr carries it for every other format. Found by sabotage: removing the
+    // `writeStderr` call left the tests green because the notice was reaching
+    // stderr through the "Why:" line instead.
+    // Bug 0203 — the third emitter, and the same contract `executeCheck` and
+    // `deliver()` now honour. A `checkAll()` at module scope used to print its
+    // findings before an aggregating caller saw them, and the caller then reported
+    // the same violations again off the throw below.
+    //
+    // **Suppress exactly what rides the throw, and nothing else** — ADR-008's
+    // amendment, and this function is the case that gives it teeth. The throw at the
+    // bottom carries only the ERROR-severity subset, so warn-severity findings ride
+    // nothing. Suppressing them too is not "the caller will report it", it is
+    // deleting them: measured, four warn findings produced and discarded under
+    // `✓ eess-ts — 4 rules across 1 file · 0 failing`, exit 0. A fake green through
+    // this package's own CLI. The first version of this guard did exactly that.
+    //
+    // The flag defaults to `false`, so `checkAll()` in a test file — where nobody
+    // aggregates — still prints everything, exactly as before.
+    const ridesTheThrow = (v) => (v.severity ?? 'error') === 'error';
+    const toWrite = callerAggregates() ? violations.filter((v) => !ridesTheThrow(v)) : violations;
+    if (toWrite.length > 0 || (!callerAggregates() && options?.format === 'json')) {
+        writeReport(toWrite, options?.format, options?.format === 'json' ? notice : undefined, untestedRules());
+    }
+    // Bug 0015 reaches the in-test path too. `checkAll` is the vitest-side
+    // equivalent of `runCheck`, and a disclosure the recommended runner never
+    // shows is a disclosure that does not exist — the same argument that got
+    // `diagnose()` exported for the vitest half of the audience. The residual,
+    // stated: a bare `.check()` per rule has no run boundary to reset or report
+    // at, so it still shows nothing.
+    if (options?.format !== 'json') {
+        const coverage = edgeCoverageNotice();
+        if (coverage !== undefined)
+            writeStderr(`${coverage}\n`);
+    }
+    // Inline exclusion comments, same footnote position and the same reason. Kept
+    // out of the JSON prose for the same reason coverage is: a consumer parsing
+    // that document gets the identities structurally, not as a sentence to grep.
+    if (options?.format !== 'json') {
+        const suppressed = commentSuppressionNotice();
+        if (suppressed !== undefined)
+            writeStderr(`${suppressed}\n`);
+    }
+    const errors = violations.filter(ridesTheThrow);
+    if (errors.length > 0) {
+        throw new ArchRuleError(errors);
+    }
+}
+//# sourceMappingURL=check-all.js.map

package/dist/core/check-all.js.map

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

package/dist/core/combinators.d.ts

@@ -0,0 +1,48 @@
+import type { Predicate } from '@nielspeter/eess';
+import type { TypeMatcher } from './type-matcher.js';
+/**
+ * Negates a predicate or type matcher.
+ *
+ * Accepts both `Predicate<T>` objects (used in `.that()` chains) and
+ * `TypeMatcher` functions (used in `.should()` condition arguments).
+ *
+ * @example
+ * // Negate a predicate:
+ * functions(p).that().satisfy(not(areAsync())).should()...
+ *
+ * // Negate a type matcher:
+ * .should().haveReturnTypeMatching(not(matching(/void/)))
+ */
+export declare function not<T>(input: Predicate<T>): Predicate<T>;
+export declare function not(input: TypeMatcher): TypeMatcher;
+/**
+ * Combines predicates or type matchers with AND logic.
+ *
+ * All inputs must be the same kind: either all `Predicate<T>` or all
+ * `TypeMatcher`. Requires at least one argument.
+ *
+ * @example
+ * // Combine predicates:
+ * functions(p).that().satisfy(and(areAsync(), areExported())).should()...
+ *
+ * // Combine type matchers:
+ * .should().haveReturnTypeMatching(and(matching(/Promise/), not(matching(/void/))))
+ */
+export declare function and<T>(...predicates: Predicate<T>[]): Predicate<T>;
+export declare function and(...matchers: TypeMatcher[]): TypeMatcher;
+/**
+ * Combines predicates or type matchers with OR logic.
+ *
+ * All inputs must be the same kind: either all `Predicate<T>` or all
+ * `TypeMatcher`. Requires at least one argument.
+ *
+ * @example
+ * // Combine predicates:
+ * functions(p).that().satisfy(or(areAsync(), areExported())).should()...
+ *
+ * // Combine type matchers:
+ * .should().haveReturnTypeMatching(or(matching(/Promise/), matching(/Collection/)))
+ */
+export declare function or<T>(...predicates: Predicate<T>[]): Predicate<T>;
+export declare function or(...matchers: TypeMatcher[]): TypeMatcher;
+//# sourceMappingURL=combinators.d.ts.map

package/dist/core/combinators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"combinators.d.ts","sourceRoot":"","sources":["../../src/core/combinators.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAOpD;;;;;;;;;;;;GAYG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;AACzD,wBAAgB,GAAG,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CAAA;AAsBpD;;;;;;;;;;;;GAYG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;AACnE,wBAAgB,GAAG,CAAC,GAAG,QAAQ,EAAE,WAAW,EAAE,GAAG,WAAW,CAAA;AAK5D;;;;;;;;;;;;GAYG;AACH,wBAAgB,EAAE,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAAA;AAClE,wBAAgB,EAAE,CAAC,GAAG,QAAQ,EAAE,WAAW,EAAE,GAAG,WAAW,CAAA"}

package/dist/core/combinators.js

@@ -0,0 +1,49 @@
+import { combineGlobs, negateGlobs, assertHomogeneous as kernelAssertHomogeneous, } from '@nielspeter/eess/internal';
+export function not(input) {
+    if (typeof input === 'function') {
+        return (type) => !input(type);
+    }
+    return {
+        description: `not (${input.description})`,
+        test: (element) => !input.test(element),
+        // Negation-normal-form push-down: `op` inverts as well as `polarity`.
+        // `not(unsatisfiable)` selects everything, so a negated site is
+        // over-selection rather than vacuity and can never be a fault — but a
+        // `not` nested inside the subtree flips it back, which is why this cannot
+        // just flip polarity. See `negateGlobs`.
+        globs: input.globs && negateGlobs(input.globs),
+    };
+}
+/** The kernel's, with this dialect's noun for the function kind. */
+function assertHomogeneous(inputs) {
+    kernelAssertHomogeneous(inputs, 'TypeMatcher');
+}
+export function and(...inputs) {
+    return combine(inputs, 'all');
+}
+export function or(...inputs) {
+    return combine(inputs, 'any');
+}
+/**
+ * The body `and()` and `or()` share — see the kernel's `combine()`, which this
+ * mirrors for `TypeMatcher`. Three choices must agree (quantifier, joining
+ * word, glob node) and deriving all three from `op` is what makes a mismatch
+ * unreachable: pairing `some` with an `'all'` glob node reports a live selector
+ * as dead.
+ */
+function combine(inputs, op) {
+    assertHomogeneous(inputs);
+    const holds = (xs, f) => op === 'all' ? xs.every(f) : xs.some(f);
+    if (typeof inputs[0] === 'function') {
+        const matchers = inputs.filter((input) => typeof input === 'function');
+        const fn = (type) => holds(matchers, (m) => m(type));
+        return fn;
+    }
+    const predicates = inputs.filter((input) => typeof input !== 'function');
+    return {
+        description: predicates.map((p) => p.description).join(op === 'all' ? ' and ' : ' or '),
+        test: (element) => holds(predicates, (p) => p.test(element)),
+        globs: combineGlobs(op, predicates.map((p) => p.globs)),
+    };
+}
+//# sourceMappingURL=combinators.js.map

package/dist/core/combinators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"combinators.js","sourceRoot":"","sources":["../../src/core/combinators.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,YAAY,EACZ,WAAW,EACX,iBAAiB,IAAI,uBAAuB,GAC7C,MAAM,2BAA2B,CAAA;AAiBlC,MAAM,UAAU,GAAG,CAAI,KAAiC;IACtD,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;QAChC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAC/B,CAAC;IACD,OAAO;QACL,WAAW,EAAE,QAAQ,KAAK,CAAC,WAAW,GAAG;QACzC,IAAI,EAAE,CAAC,OAAU,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC;QAC1C,sEAAsE;QACtE,gEAAgE;QAChE,sEAAsE;QACtE,0EAA0E;QAC1E,yCAAyC;QACzC,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC;KAC/C,CAAA;AACH,CAAC;AAED,oEAAoE;AACpE,SAAS,iBAAiB,CAAI,MAAsC;IAClE,uBAAuB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;AAChD,CAAC;AAiBD,MAAM,UAAU,GAAG,CAAI,GAAG,MAAsC;IAC9D,OAAO,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;AAC/B,CAAC;AAiBD,MAAM,UAAU,EAAE,CAAI,GAAG,MAAsC;IAC7D,OAAO,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,SAAS,OAAO,CACd,MAAsC,EACtC,EAAiB;IAEjB,iBAAiB,CAAC,MAAM,CAAC,CAAA;IACzB,MAAM,KAAK,GAAG,CAAI,EAAgB,EAAE,CAAoB,EAAW,EAAE,CACnE,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IAEzC,IAAI,OAAO,MAAM,CAAC,CAAC,CAAC,KAAK,UAAU,EAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAwB,EAAE,CAAC,OAAO,KAAK,KAAK,UAAU,CAAC,CAAA;QAC5F,MAAM,EAAE,GAAgB,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;QACjE,OAAO,EAAE,CAAA;IACX,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAyB,EAAE,CAAC,OAAO,KAAK,KAAK,UAAU,CAAC,CAAA;IAC/F,OAAO;QACL,WAAW,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;QACvF,IAAI,EAAE,CAAC,OAAU,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/D,KAAK,EAAE,YAAY,CACjB,EAAE,EACF,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAC/B;KACF,CAAA;AACH,CAAC"}

package/dist/core/descendant-cache.d.ts

@@ -0,0 +1,36 @@
+import type { Node, SyntaxKind } from 'ts-morph';
+/**
+ * Every descendant of `node` with the given kind, walked once per file version.
+ *
+ * A drop-in replacement for `node.getDescendantsOfKind(kind)`. Returns
+ * `readonly` because the array is shared: a caller that sorted or spliced it
+ * would corrupt every later matcher over the same body.
+ */
+export declare function descendantsOfKind(node: Node, kind: SyntaxKind): readonly Node[];
+/**
+ * Every descendant of `node`, walked once per file version.
+ *
+ * The kind-independent twin of {@link descendantsOfKind}, for `findMatchesBroad`
+ * — the strategy `expression()` and `comment()` take, having no `syntaxKinds` to
+ * narrow by.
+ *
+ * **Measured** on this repository, 1,698 function bodies / 117,949 descendants,
+ * ts-morph's wrapper cache already warm:
+ *
+ *     getDescendants()          49 ms   <- what this removes
+ *     + getText() on each       71 ms
+ *     + regex test on each      68 ms
+ *
+ * The walk is roughly three quarters of a broad matcher's cost; the filter is the
+ * rest and is not shareable — `expression()`'s regex differs per matcher.
+ * (`comment()`'s dedup state was the other half of this until bug 0034 removed
+ * it; the filter is still per-matcher.) End to end, six successive broad
+ * rules over the same bodies: **~57 ms each becomes ~17 ms each.**
+ *
+ * The memory objection — that this retains every wrapper in every body rather
+ * than one kind's worth — does not survive checking. ts-morph's own
+ * `ForgetfulNodeCache` already holds every wrapper it creates for the lifetime of
+ * the `SourceFile`, so the array adds N references, not N objects.
+ */
+export declare function allDescendants(node: Node): readonly Node[];
+//# sourceMappingURL=descendant-cache.d.ts.map

package/dist/core/descendant-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descendant-cache.d.ts","sourceRoot":"","sources":["../../src/core/descendant-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAc,UAAU,EAAE,MAAM,UAAU,CAAA;AA0I5D;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS,IAAI,EAAE,CA0B/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,IAAI,EAAE,CAe1D"}

package/dist/core/descendant-cache.js

@@ -0,0 +1,117 @@
+import { registerCacheReset } from '@nielspeter/eess/internal';
+import { invalidateOnModify } from './invalidate-on-modify.js';
+let byFile = new WeakMap();
+/** The kind-independent walk, in the same per-file lifetime as {@link byFile}. */
+let allByFile = new WeakMap();
+const watched = new WeakSet();
+registerCacheReset(() => {
+    byFile = new WeakMap();
+    allByFile = new WeakMap();
+});
+/**
+ * Register the invalidation listener for a file, once.
+ *
+ * Not once per cache miss: a watch session that re-evaluates rules would
+ * otherwise accumulate one listener per rule execution. Both maps are dropped
+ * together, because the same event invalidates both.
+ *
+ * The closure reads `byFile` / `allByFile` as **live bindings** rather than
+ * capturing them, which is what keeps invalidation working after
+ * `registerCacheReset` replaces the maps. Capturing by value made a post-reset
+ * edit invisible and passed the entire suite — there is a test named for it.
+ */
+function watchOnce(sourceFile) {
+    invalidateOnModify(sourceFile, watched, (file) => {
+        byFile.delete(file);
+        allByFile.delete(file);
+    });
+}
+/**
+ * Whether a cached list can still be read.
+ *
+ * Endpoints only, and that is not a heuristic: ts-morph's
+ * `ForgetfulNodeCache.forgetLastPoint` forgets a whole created-in-block set at
+ * once, so a partially-forgotten list is not a shape the mechanism produces.
+ * Walking the full list on every hit would cost what this module exists to save.
+ */
+function usable(nodes) {
+    const first = nodes[0];
+    if (first === undefined)
+        return true;
+    const last = nodes[nodes.length - 1];
+    return !first.wasForgotten() && last !== undefined && !last.wasForgotten();
+}
+/**
+ * Every descendant of `node` with the given kind, walked once per file version.
+ *
+ * A drop-in replacement for `node.getDescendantsOfKind(kind)`. Returns
+ * `readonly` because the array is shared: a caller that sorted or spliced it
+ * would corrupt every later matcher over the same body.
+ */
+export function descendantsOfKind(node, kind) {
+    const sourceFile = node.getSourceFile();
+    let perNode = byFile.get(sourceFile);
+    if (perNode === undefined) {
+        perNode = new Map();
+        byFile.set(sourceFile, perNode);
+    }
+    watchOnce(sourceFile);
+    let byKind = perNode.get(node);
+    if (byKind === undefined) {
+        byKind = new Map();
+        perNode.set(node, byKind);
+    }
+    const hit = byKind.get(kind);
+    // `usable`, not just `!== undefined`. A forget point forgets the walked
+    // DESCENDANTS while the key node stays live and unforgotten, so serving the
+    // cached list makes the next read throw where an uncached walk succeeded.
+    // Measured as a regression against `main`, through the rule path: 1 violation
+    // before, `InvalidOperationError` after. Re-walking is the correct answer —
+    // the nodes are gone, so the list is simply wrong.
+    if (hit !== undefined && usable(hit))
+        return hit;
+    const walked = node.getDescendantsOfKind(kind);
+    byKind.set(kind, walked);
+    return walked;
+}
+/**
+ * Every descendant of `node`, walked once per file version.
+ *
+ * The kind-independent twin of {@link descendantsOfKind}, for `findMatchesBroad`
+ * — the strategy `expression()` and `comment()` take, having no `syntaxKinds` to
+ * narrow by.
+ *
+ * **Measured** on this repository, 1,698 function bodies / 117,949 descendants,
+ * ts-morph's wrapper cache already warm:
+ *
+ *     getDescendants()          49 ms   <- what this removes
+ *     + getText() on each       71 ms
+ *     + regex test on each      68 ms
+ *
+ * The walk is roughly three quarters of a broad matcher's cost; the filter is the
+ * rest and is not shareable — `expression()`'s regex differs per matcher.
+ * (`comment()`'s dedup state was the other half of this until bug 0034 removed
+ * it; the filter is still per-matcher.) End to end, six successive broad
+ * rules over the same bodies: **~57 ms each becomes ~17 ms each.**
+ *
+ * The memory objection — that this retains every wrapper in every body rather
+ * than one kind's worth — does not survive checking. ts-morph's own
+ * `ForgetfulNodeCache` already holds every wrapper it creates for the lifetime of
+ * the `SourceFile`, so the array adds N references, not N objects.
+ */
+export function allDescendants(node) {
+    const sourceFile = node.getSourceFile();
+    let perNode = allByFile.get(sourceFile);
+    if (perNode === undefined) {
+        perNode = new Map();
+        allByFile.set(sourceFile, perNode);
+    }
+    watchOnce(sourceFile);
+    const hit = perNode.get(node);
+    if (hit !== undefined && usable(hit))
+        return hit;
+    const walked = node.getDescendants();
+    perNode.set(node, walked);
+    return walked;
+}
+//# sourceMappingURL=descendant-cache.js.map

package/dist/core/descendant-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descendant-cache.js","sourceRoot":"","sources":["../../src/core/descendant-cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AA4F9D,IAAI,MAAM,GAAG,IAAI,OAAO,EAAiC,CAAA;AACzD,kFAAkF;AAClF,IAAI,SAAS,GAAG,IAAI,OAAO,EAA0C,CAAA;AACrE,MAAM,OAAO,GAAG,IAAI,OAAO,EAAc,CAAA;AAEzC,kBAAkB,CAAC,GAAG,EAAE;IACtB,MAAM,GAAG,IAAI,OAAO,EAAiC,CAAA;IACrD,SAAS,GAAG,IAAI,OAAO,EAA0C,CAAA;AACnE,CAAC,CAAC,CAAA;AAEF;;;;;;;;;;;GAWG;AACH,SAAS,SAAS,CAAC,UAAsB;IACvC,kBAAkB,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;QAC/C,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACnB,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,MAAM,CAAC,KAAsB;IACpC,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;IACtB,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IACpC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IACpC,OAAO,CAAC,KAAK,CAAC,YAAY,EAAE,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAA;AAC5E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAU,EAAE,IAAgB;IAC5D,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,EAAE,CAAA;IACvC,IAAI,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;IACpC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,GAAG,IAAI,GAAG,EAAgB,CAAA;QACjC,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;IACjC,CAAC;IACD,SAAS,CAAC,UAAU,CAAC,CAAA;IAErB,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC9B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,GAAG,IAAI,GAAG,EAA+B,CAAA;QAC/C,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IAC3B,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC5B,wEAAwE;IACxE,4EAA4E;IAC5E,0EAA0E;IAC1E,8EAA8E;IAC9E,4EAA4E;IAC5E,mDAAmD;IACnD,IAAI,GAAG,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAA;IAEhD,MAAM,MAAM,GAAG,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAA;IAC9C,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACxB,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,cAAc,CAAC,IAAU;IACvC,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,EAAE,CAAA;IACvC,IAAI,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;IACvC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAA;QAC1C,SAAS,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;IACpC,CAAC;IACD,SAAS,CAAC,UAAU,CAAC,CAAA;IAErB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC7B,IAAI,GAAG,KAAK,SAAS,IAAI,MAAM,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAA;IAEhD,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc,EAAE,CAAA;IACpC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACzB,OAAO,MAAM,CAAA;AACf,CAAC"}