mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/crap-engine.js

@@ -1,12 +1,5 @@
 import { coverageForMethodInEntry } from './coverage-utils.js';
-// `finalizeMethodRowsWithBaseline` (Story #4981) lives in
-// crap-baseline-join.js — `resolveRawRow`, the per-row policy it shares with
-// `finalizeMethodRows` below, is imported from there so the two stay a
-// single implementation.
 import { resolveRawRow } from './crap-baseline-join.js';
-// `COORDINATE_ORIGINAL` / `COORDINATE_TRANSPILED` / `crapFormula` (Story
-// #4866 / this module's original home) now live in crap-coordinates.js —
-// re-exported here so every existing importer of this module is unaffected.
 import {
   COORDINATE_ORIGINAL,
   COORDINATE_TRANSPILED,
@@ -19,73 +12,19 @@ import { analyzeModule } from './escomplex-kernel.js';
 export { COORDINATE_ORIGINAL, COORDINATE_TRANSPILED, crapFormula };
 
 /**
- * Sentinel returned by {@link calculateCrapForSource} for a source the kernel
- * cannot parse. Deliberately **not** `[]`: a caller receiving an empty array
- * cannot tell an unscorable file from one with no methods, which is how a
- * parse failure used to reach the baseline as a silent zero (Story #5311).
+ * Returned for a source the kernel cannot parse — never `[]`, which would be
+ * indistinguishable from a file with no methods.
  */
 export const UNSCORABLE = null;
 
-// The kernel's code generator predates the Babel AST its own parser emits, so
-// ordinary modern syntax (`?.`, `await` or a regex in a loop head, object
-// spread in a default parameter) aborts `analyzeModule` for the WHOLE file —
-// see `escomplex-ast-compat.js` for the defect and the upstream status.
-//
-// Story #5311: the install belongs here, at the scoring kernel, because this
-// is where both CRAP scorers converge — `calculateCrapForSource` (the worker
-// path) and `crap-utils.js#analyzeOnce` (the serial path, which reaches this
-// module for `methodRowsFromReport`). It used to be reached only as a side
-// effect of `maintainability-engine.js` sitting somewhere in the serial path's
-// import graph, which the worker's graph never included: 362 methods across
-// 21 files scored zero via workers and scored fine serially, and
-// `POOL_SERIAL_THRESHOLD` makes the worker path the only one a real repo
-// takes. Anchoring it at the kernel makes the next worker entrypoint correct
-// by construction rather than by an import nobody would guess is load-bearing.
+// Without the AST compat shim, modern syntax aborts `analyzeModule` for the
+// whole file. Installed here, where the worker and serial scorers converge,
+// so every entrypoint gets it by construction.
 installAstCompat();
 
 /**
- * Derive the raw per-method CRAP rows from an escomplex report.
- *
- * Single-sourced between `calculateCrapForSource` (CRAP-only path) and
- * `analyzeOnce` (combined MI + CRAP path) so the two cannot drift on how a
- * method's line is remapped or its coverage joined — the parity the
- * combined-parity suite asserts.
- *
- * **Coordinates (Story #4775, corrected by Story #4866).** `mapLine`
- * translates escomplex's `lineStart` — which is in *transpiled* coordinates
- * for a TS/TSX source — into the *original source* coordinates istanbul's
- * `fnMap` uses. A `null` mapper means the two coordinate systems already
- * coincide (plain JavaScript).
- *
- * #4775 let an unresolvable line fall back to the un-remapped value, which
- * made one scan emit rows in two coordinate systems with nothing on the row
- * saying which. Each row now records its own `coordinateSystem`, and an
- * un-remapped row joins no coverage at all: joining a transpiled line against
- * an original-source `fnMap` does not merely miss, it can land inside an
- * unrelated function's range and mis-attribute that function's coverage. An
- * honest `coverage: null` lets the scanner's `requireCoverage` policy decide,
- * exactly as it does for a genuinely uninstrumented method.
- *
- * @param {object|null} report An `escomplex.analyzeModule` report.
- * @param {object|null} coverageForFile Istanbul coverage entry for this file.
- * @param {((line: number) => number|null)|null} [mapLine]
- * @returns {Array<{
- *   method: string,
- *   anonymous: boolean,
- *   startLine: number,
- *   cyclomatic: number,
- *   coverage: number|null,
- *   crap: number|null,
- *   coordinateSystem: 'original'|'transpiled',
- * }>}
- */
-/**
- * Resolve one method's line into a coordinate and the provenance of that
- * coordinate — the single place the rule lives.
- *
- * No mapper means the source was never transpiled, so its line already IS an
- * original-source coordinate. A mapper that resolves yields one. A mapper
- * that does not leaves the transpiled line, said so.
+ * No mapper: already original coordinates. An unresolved mapping stays
+ * transpiled, and says so.
  *
  * @param {number} rawStartLine escomplex's `lineStart`.
  * @param {((line: number) => number|null)|null} mapLine
@@ -101,13 +40,28 @@ function resolveCoordinate(rawStartLine, mapLine) {
     : { startLine: rawStartLine, coordinateSystem: COORDINATE_TRANSPILED };
 }
 
+/**
+ * Raw per-method CRAP rows, shared by the CRAP-only and combined MI paths.
+ * A row still in transpiled coordinates joins no coverage: a transpiled line
+ * can land inside an unrelated function's `fnMap` range and mis-attribute it.
+ *
+ * @param {object|null} report An `escomplex.analyzeModule` report.
+ * @param {object|null} coverageForFile Istanbul coverage entry for this file.
+ * @param {((line: number) => number|null)|null} [mapLine]
+ * @returns {Array<{
+ *   method: string,
+ *   anonymous: boolean,
+ *   startLine: number,
+ *   cyclomatic: number,
+ *   coverage: number|null,
+ *   crap: number|null,
+ *   coordinateSystem: 'original'|'transpiled',
+ * }>}
+ */
 export function methodRowsFromReport(report, coverageForFile, mapLine = null) {
   const methods = report?.methods ?? [];
-  // Identities are derived over the WHOLE method list, before any row is
-  // skipped, and read back by index (Story #4969). Deriving them from the
-  // surviving rows instead would let an unscorable method's absence shift its
-  // siblings' ordinals — reintroducing, through the back door, exactly the
-  // position dependence this replaces.
+  // Derive identities over the whole list before skipping, so a skipped
+  // method cannot shift its siblings' ordinals.
   const identities = deriveMethodIdentities(methods);
   const rows = [];
   for (const [i, m] of methods.entries()) {
@@ -136,43 +90,11 @@ export function methodRowsFromReport(report, coverageForFile, mapLine = null) {
 }
 
 /**
- * Apply the scanner's `requireCoverage` policy to raw method rows and report
- * how much of the coverage join actually landed.
- *
- * Two policies, one honest each way (Story #4775, fix part 3):
- *
- *   - `requireCoverage: true` — an unresolved method is skipped and counted,
- *     exactly as before. The baseline stays a record of measured code.
- *   - `requireCoverage: false` — an unresolved method scores as **0%
- *     covered** (`crap = c² + c`, the formula's own treatment of untested
- *     code) and lands in the baseline. Previously the flag only stopped
- *     whole *files* being skipped while each individual method was still
- *     dropped, which made it a no-op for baseline population — the caller
- *     asked for "score it anyway" and got silence.
- *
- * **Absent coverage is not zero coverage (Story #4871).** The 0%-covered
- * inference above is only defensible when a coverage **artifact** exists and
- * simply reports nothing for this method — "the tests ran and never reached
- * it" is a measurement. When no artifact was produced at all — a freshly
- * initialized story worktree, whose `coverage/` directory does not exist —
- * nothing was measured, and filling the gap with 0% manufactures a maximal
- * CRAP out of an absent observation, failing the first commit on files the
- * change never touched. `coverageAvailable: false` therefore makes such a
- * method **unscorable** under either policy: skipped and counted, never
- * filled. It is deliberately keyed on the artifact, not the per-file entry,
- * so `requireCoverage: false` keeps meaning "score untested code" whenever a
- * real coverage run stands behind the verdict.
- *
- * **Unjoinable is not untested (Story #4901).** Both policies above are about
- * a method whose coverage is *absent*; neither is about one whose coverage
- * could not be **joined**. A transpiled `startLine` is the latter — not in
- * the coordinate space the `fnMap` or the baseline is keyed against — so 0%
- * is not a measurement but a number invented for it, and `crapFormula(c, 0)`
- * is the maximal `c² + c`. Excluded under **either** policy, and counted.
- *
- * `resolvedMethods` / `totalMethods` count the *join*, not the fill, which is
- * what makes them a health signal for the updater's fail-closed
- * resolution-rate floor — so the exclusion is applied *after* both counters.
+ * Apply `requireCoverage`: `true` skips an unresolved method; `false` scores
+ * it 0% covered. With no coverage artifact at all (`coverageAvailable:
+ * false`) or a transpiled (unjoinable) line, the method is skipped under
+ * either policy — absent or unjoinable is not untested. The counters measure
+ * the join, not the fill, for the resolution-rate floor.
  *
  * @param {Array<object>} rawRows Rows from `methodRowsFromReport`.
  * @param {{requireCoverage?: boolean, coverageAvailable?: boolean}} [opts]
@@ -207,37 +129,17 @@ export function finalizeMethodRows(
   return { rows, skippedMethodsNoCoverage, resolvedMethods, totalMethods };
 }
 
-// The incremental-mode join (Story #4981) lives in crap-baseline-join.js;
-// re-exported here so it stays reachable from the scoring kernel's existing
-// public surface.
 export { finalizeMethodRowsWithBaseline } from './crap-baseline-join.js';
 
 /**
- * Score each method in a JavaScript source for Change Risk Anti-Patterns
- * (CRAP): `c² · (1 − cov)³ + c`, where `c` is cyclomatic complexity and `cov`
- * is the per-method statement-coverage ratio in [0, 1].
- *
- * Kernel contract:
- *   - Pure (no I/O, no AST parse beyond the one delegated to escomplex via
- *     `analyzeModule`).
- *   - Methods whose coverage cannot be resolved from `coverageForFile` —
- *     including every method whose line stayed in transpiled coordinates —
- *     produce `coverage: null` and `crap: null`. Callers apply their own
- *     `requireCoverage` policy at the scanner level (`finalizeMethodRows`);
- *     this kernel never decides to skip.
- *   - A parse error returns {@link UNSCORABLE} (`null`) — the file could not
- *     be scored at all, which is a different fact from "it has no methods"
- *     (`[]`). Story #5311: returning `[]` for both collapsed them, and every
- *     caller's drop path for an unscorable file became unreachable — the
- *     whole parse-failure class landed in the baseline as a clean zero.
- *     Callers MUST branch on `rows === null` before iterating.
+ * Pure CRAP scoring kernel (`c² · (1 − cov)³ + c`); never skips — unresolved
+ * coverage yields `null` fields. Callers MUST branch on `rows === null`
+ * ({@link UNSCORABLE}) before iterating.
  *
  * @param {string} source JavaScript source text (possibly transpiled).
- * @param {object|null} coverageForFile The inner value from a
- *   `coverage-final.json` map keyed by this file's path, or null when no
- *   coverage data is available for this file.
+ * @param {object|null} coverageForFile This file's `coverage-final.json` entry.
  * @param {((line: number) => number|null)|null} [mapLine] Transpiled →
- *   original line resolver; see `methodRowsFromReport`.
+ *   original line resolver.
  * @returns {Array<{
  *   method: string,
  *   anonymous: boolean,
@@ -264,22 +166,9 @@ export function calculateCrapForSource(
 }
 
 /**
- * Derive the deterministic single-axis fixes that would bring a method at
- * cyclomatic complexity `c` at or under the `target` CRAP score.
- *
- * Two orthogonal remediations are surfaced:
- *   - `minComplexityAt100Cov`: branch count a refactor must reach so that,
- *     even untested, the method would pass (`CRAP@cov=1 = c` → `c ≤ target`).
- *     Computed as `floor(sqrt(target))`.
- *   - `minCoverageAtCurrentComplexity`: ratio a test-addition must reach at
- *     the current complexity to pass, derived by inverting the formula:
- *     `cov = 1 − ((target − c) / c²)^(1/3)`. Null when unachievable — i.e.
- *     `c > target` (CRAP at 100% coverage still exceeds the target) or when
- *     `c ≤ 0` (no branches; coverage is meaningless).
- *
- * Callers apply the target convention: `baseline` for regressions,
- * `newMethodCeiling` for new violations. The helper stays scalar so it can
- * be re-used by MI-parity output or future guidance surfaces.
+ * Single-axis fixes bringing a method under `target`: the complexity to reach
+ * (`floor(sqrt(target))`), and the coverage needed at current complexity
+ * (`1 − ((target − c) / c²)^(1/3)`; null when `c > target` or `c ≤ 0`).
  *
  * @param {{ cyclomatic: number, target: number }} params
  * @returns {{
@@ -297,8 +186,6 @@ export function deriveFixGuidance({ cyclomatic, target } = {}) {
 
   let minCoverageAtCurrentComplexity = null;
   if (c > 0 && t >= c) {
-    // `(t - c) / c²` lies in `[0, 1]` for `t ∈ [c, c + c²]`; Math.cbrt stays
-    // real-valued for any input so a numeric clamp is the only safeguard.
     const ratio = (t - c) / (c * c);
     const minCov = 1 - Math.cbrt(ratio);
     minCoverageAtCurrentComplexity = Math.max(0, Math.min(1, minCov));

package/.agents/scripts/lib/crap-method-identity.js

@@ -1,32 +1,13 @@
-/**
- * crap-method-identity.js — order-independent identity for the methods an
- * escomplex report describes (Story #4969).
- *
- * Split out of `crap-engine.js` deliberately. That module is the CRAP scoring
- * kernel — parse, remap a line, join coverage, apply the formula — and naming
- * a method is a different question from scoring one: it reads the shape of the
- * scope tree and nothing about coverage or complexity. Keeping the walker here
- * leaves the kernel's contract ("pure, no I/O, one method in, one score out")
- * legible instead of half-buried under a tree traversal.
- */
+/** Order-independent identity for the methods of an escomplex report. */
 
 /**
- * The label `typhonjs-escomplex-commons` gives a function it cannot name
- * (Story #4969).
- *
- * The `N` is a per-module counter incremented during the AST walk, so it
- * numbers a function by its *position among its anonymous siblings* rather
- * than by anything about the function itself. Inserting or deleting one
- * anonymous function renumbers every later one in the file — and 34.6% of this
- * repository's CRAP rows were keyed on exactly that. See
- * `deriveMethodIdentities` for what replaces it.
+ * escomplex's label for an unnamed function: a file-wide positional counter,
+ * so one insertion renumbers every later anonymous function.
  */
 const ESCOMPLEX_ANON_LABEL_RE = /^<anon method-\d+>$/;
 
 /**
- * True for a `method` value that is a derived anonymous identity rather than a
- * name the source actually carries — either this module's `<anon …>` identity
- * or escomplex's superseded ordinal label.
+ * True for a derived anonymous identity (ours or escomplex's).
  *
  * @param {unknown} method
  * @returns {boolean}
@@ -36,11 +17,8 @@ export function isAnonymousMethodLabel(method) {
 }
 
 /**
- * Coerce a method's escomplex line span into a usable numeric pair. A method
- * missing either bound still has to take a deterministic place in the scope
- * tree, so it collapses to a zero-width span rather than being dropped: an
- * identity that varies with how the parser failed would be worse than one that
- * is merely coarse.
+ * A missing bound collapses to a zero-width span, never a drop, so the
+ * method keeps a deterministic place in the scope tree.
  *
  * @param {{lineStart?: unknown, lineEnd?: unknown}} m
  * @returns {{lineStart: number, lineEnd: number}}
@@ -52,53 +30,16 @@ function spanOf(m) {
 }
 
 /**
- * Give every method in an escomplex report an identity that does not depend on
- * how many anonymous functions happen to precede it (Story #4969).
- *
- * **Named methods are untouched** — their identity is the name escomplex
- * reported, exactly as before, so no named row is re-keyed by this change.
- *
- * **An anonymous method is identified by where it sits, not by when it was
- * counted.** The identity is `<anon {scope path}>`, where the path is the
- * chain of enclosing methods from the module down to the method itself. Each
- * link contributes a name if it has one, otherwise its parameter list plus an
- * ordinal among the siblings that share *that exact parent and that exact
- * parameter list*:
- *
- * ```text
- *   <anon (p)#0>                                        module-scope, first (p) arrow
- *   <anon buildDefaultCrapScorer/(files,opts)#0>        inside a named function
- *   <anon buildDefaultCrapScorer/(files,opts)#0/(r)#0>  inside that one
- * ```
- *
- * **Why the parameter list and not the body.** The identity has to survive an
- * edit *to* the method — a method that gains a branch must still be recognised
- * as the same method, or a genuine complexity regression would read as a brand
- * new function and score against the new-method ceiling instead of its own
- * baseline. That rules out anything derived from the body: a source or
- * normalized-AST hash re-keys the row on the very edit the gate exists to
- * catch. A parameter list is stable across the edits CRAP measures, and it
- * partitions same-scope siblings finely enough that the residual ordinal is
- * almost always `#0`.
- *
- * **The residual.** Within one parent *and* one parameter list, siblings are
- * still told apart by source order, so inserting a same-signature sibling
- * *before* an existing one still shifts it. That residual is irreducible:
- * anything that distinguishes two same-scope, same-signature functions has to
- * read their bodies, and reading their bodies re-keys them on every edit. The
- * blast radius drops from "every anonymous function in the file" to "the
- * same-signature siblings of one scope".
- *
- * Emission order is load-bearing and guaranteed: escomplex walks the AST
- * pre-order, so a method's ancestors are always emitted before it. That lets a
- * single forward pass with an open-ancestor stack resolve every parent in
- * O(n), and it makes the innermost enclosing method the most recent one still
- * open.
+ * Named methods keep their name. An anonymous one becomes `<anon {scope
+ * path}>`, e.g. `<anon build/(files,opts)#0/(r)#0>`: each enclosing link is a
+ * name, or a parameter list plus an ordinal among siblings with the same
+ * parent and parameter list. Never derived from the body — that would re-key
+ * a method on the very edit the gate must catch. Relies on escomplex's
+ * pre-order emission (ancestors first) for a single-pass ancestor stack.
  *
  * @param {Array<object>} methods `report.methods` from escomplex.
- * @returns {Array<{method: string, anonymous: boolean}>} One entry per input
- *   method, index-aligned with `methods` and spreadable straight onto a row.
- *   The scope path itself stays internal — only the identity leaves.
+ * @returns {Array<{method: string, anonymous: boolean}>} Index-aligned with
+ *   `methods`.
  */
 export function deriveMethodIdentities(methods) {
   const identities = [];
@@ -109,7 +50,6 @@ export function deriveMethodIdentities(methods) {
 
   for (const m of methods ?? []) {
     const { lineStart, lineEnd } = spanOf(m);
-    // Close every ancestor whose span has ended before this method begins.
     while (
       openAncestors.length > 0 &&
       openAncestors[openAncestors.length - 1].lineEnd < lineStart
@@ -127,10 +67,8 @@ export function deriveMethodIdentities(methods) {
     if (name === '' || ESCOMPLEX_ANON_LABEL_RE.test(name)) {
       const params = Array.isArray(m?.paramNames) ? m.paramNames : [];
       const signature = `(${params.join(',')})`;
-      // NUL separates the two halves because it is the one character a scope
-      // path can never contain — a printable delimiter could be produced by a
-      // parameter name and silently merge two distinct buckets. Spelled as an
-      // escape: a literal NUL byte would make this file binary to git and grep.
+      // NUL can never appear in a scope path; keep it an escape (a raw NUL
+      // makes the file binary to git).
       const bucket = `${parentPath}\u0000${signature}`;
       const ordinal = ordinals.get(bucket) ?? 0;
       ordinals.set(bucket, ordinal + 1);