mandrel 2.16.0 → 2.18.0

package/.agents/scripts/lib/close-validation/runner.js

@@ -19,6 +19,7 @@ import {
 } from './commands.js';
 import { DEFAULT_GATES, partitionGates } from './gates.js';
 import { defaultGateRunner } from './process.js';
+import { runProjectionAdvisories as defaultRunProjections } from './projections/advisories.js';
 import { defaultGetHeadSha } from './projections/head-sha.js';
 
 /** @typedef {import('./gates.js').Gate} Gate */
@@ -90,10 +91,23 @@ function applyChangedFileScope({ gate, spawnCwd, log }) {
  * story-close uses it to drive `phaseTimer.mark(...)` for per-gate
  * wall-clock telemetry. Errors thrown from the hook propagate.
  *
+ * Projection advisories (Story #4776): when `baseBranch` and `storyBranch`
+ * are both supplied and every gate passed, the maintainability and CRAP
+ * pre-merge projections run through `projections/advisories.js` and log
+ * their advisories to the same `log` sink the gates use. They are advisory
+ * by construction — the returned `ok` is decided entirely by the gates, so
+ * a projected breach never fails a close. They are skipped after a gate
+ * failure, where the operator needs the failing gate's evidence, not a
+ * baseline-refresh nudge.
+ *
  * @param {{
  *   cwd: string,
  *   worktreePath?: string,
  *   gates?: Gate[],
+ *   baseBranch?: string|null,
+ *   storyBranch?: string|null,
+ *   config?: object|null,
+ *   runProjections?: typeof defaultRunProjections,
  *   runner?: (cmd: string, args: string[], opts: { cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void }) => Promise<{ status: number }> | { status: number },
  *   log?: (m: string) => void,
  *   onGateStart?: (gate: Gate) => void,
@@ -114,6 +128,10 @@ export async function runCloseValidation({
   runner = defaultGateRunner,
   log = () => {},
   onGateStart,
+  baseBranch = null,
+  storyBranch = null,
+  config = null,
+  runProjections = defaultRunProjections,
   storyId = null,
   standalone = false,
   useEvidence = true,
@@ -346,5 +364,55 @@ export async function runCloseValidation({
     );
   }
 
+  // ── Phase 3: advisory projections ───────────────────────────────────
+  // Story #4776 — the projection layer's live call site. Deliberately
+  // outside the `ok` computation: a projected breach informs, it never
+  // fails a close.
+  if (failed.length === 0) {
+    await runAdvisoryProjections({
+      runProjections,
+      cwd: spawnCwd,
+      baseBranch,
+      storyBranch,
+      config,
+      log,
+    });
+  }
+
   return { ok: failed.length === 0, failed, skipped };
 }
+
+/**
+ * Phase 3 helper — run the advisory projections, absorbing every failure.
+ *
+ * No-ops without a branch pair to diff (resume / legacy callers), and can
+ * never influence the close verdict: the caller has already decided `ok`
+ * before this runs, and a throw here is logged, not propagated.
+ *
+ * @param {{
+ *   runProjections: typeof defaultRunProjections,
+ *   cwd: string,
+ *   baseBranch: string|null,
+ *   storyBranch: string|null,
+ *   config: object|null,
+ *   log: (m: string) => void,
+ * }} opts
+ * @returns {Promise<void>}
+ */
+async function runAdvisoryProjections({
+  runProjections,
+  cwd,
+  baseBranch,
+  storyBranch,
+  config,
+  log,
+}) {
+  if (!(baseBranch && storyBranch)) return;
+  try {
+    await runProjections({ cwd, baseBranch, storyBranch, config, log });
+  } catch (err) {
+    log(
+      `[close-validation]   ⚠ projection advisories skipped: ${err?.message ?? err}`,
+    );
+  }
+}

package/.agents/scripts/lib/config/gates/crap.schema.js

@@ -13,6 +13,13 @@ export const CRAP_GATE = {
     targetDirs: LIST_OR_EXTENDER_OF_STRINGS,
     newMethodCeiling: { type: 'integer', minimum: 1 },
     requireCoverage: { type: 'boolean' },
+    // Story #4775 — fail-closed floor on the per-method coverage JOIN: the
+    // fraction of methods that must resolve a coverage entry, counted only
+    // over files that HAVE one, before `update-crap-baseline.js` will
+    // persist. A broken join is silent by construction (unresolved methods
+    // are simply absent), so the updater refuses rather than writing a thin
+    // baseline and logging it as success. Default 0.75.
+    minMethodResolutionRate: { type: 'number', minimum: 0, maximum: 1 },
     friction: {
       type: 'object',
       properties: { markerKey: { type: 'string', minLength: 1 } },

package/.agents/scripts/lib/config/quality.js

@@ -88,6 +88,15 @@ export const CRAP_GATE_DEFAULTS = Object.freeze({
   // semantics.
   refreshTimeoutMs: 60_000,
   ignoreGlobs: Object.freeze([]),
+  // Story #4775 — fail-closed floor on the per-method coverage JOIN. The
+  // fraction of methods that must resolve a coverage entry, counted only over
+  // files that HAVE one, before `update-crap-baseline.js` will persist. A
+  // broken join is silent by construction (unresolved methods are simply
+  // absent from the baseline), so the updater refuses rather than writing a
+  // thin baseline and logging it as success. 0.75 sits far above a healthy
+  // run (a repo with fresh coverage resolves ~98%) and far below the 4–6%
+  // signature of a coordinate-system mismatch.
+  minMethodResolutionRate: 0.75,
 });
 
 /** Framework defaults for the coverage gate. */
@@ -121,6 +130,15 @@ export const MAINTAINABILITY_GATE_DEFAULTS = Object.freeze({
   // spawned by the baseline-attribution refresh path. Defaults to 60 s.
   refreshTimeoutMs: 60_000,
   ignoreGlobs: Object.freeze([]),
+  // Story #4775 — fail-closed floor on the per-method coverage JOIN. The
+  // fraction of methods that must resolve a coverage entry, counted only over
+  // files that HAVE one, before `update-crap-baseline.js` will persist. A
+  // broken join is silent by construction (unresolved methods are simply
+  // absent from the baseline), so the updater refuses rather than writing a
+  // thin baseline and logging it as success. 0.75 sits far above a healthy
+  // run (a repo with fresh coverage resolves ~98%) and far below the 4–6%
+  // signature of a coordinate-system mismatch.
+  minMethodResolutionRate: 0.75,
 });
 
 /**
@@ -144,6 +162,7 @@ const CRAP_GATE_KEYS = new Set([
   'refreshTag',
   'refreshTimeoutMs',
   'ignoreGlobs',
+  'minMethodResolutionRate',
 ]);
 
 const COVERAGE_GATE_KEYS = new Set([
@@ -205,6 +224,22 @@ function warnUnknownKeys(userBlock, knownKeys, blockLabel) {
  * @param {{ coveragePath: string }} coverageGate resolved coverage gate
  * @returns {object} flattened legacy-bag view that existing callers read
  */
+/**
+ * Clamp a user-supplied method-resolution floor into `[0, 1]`. A
+ * non-numeric, non-finite, or out-of-range value falls back to the framework
+ * default rather than silently disabling the guard (a floor of `NaN` would
+ * compare false against every rate and never fire).
+ *
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+function resolveResolutionRate(value, fallback) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  if (value < 0 || value > 1) return fallback;
+  return value;
+}
+
 export function resolveMaintainabilityCrap(
   userCrap,
   gateScoping,
@@ -227,6 +262,7 @@ export function resolveMaintainabilityCrap(
         DEFAULT_CRAP_TOLERANCE.value,
       ),
       requireCoverage: defaults.requireCoverage,
+      minMethodResolutionRate: defaults.minMethodResolutionRate,
       friction: { ...defaults.friction },
       refreshTag: defaults.refreshTag,
       refreshTimeoutMs: defaults.refreshTimeoutMs,
@@ -248,6 +284,10 @@ export function resolveMaintainabilityCrap(
       toleranceScalar(defaults.tolerance, DEFAULT_CRAP_TOLERANCE.value),
     ),
     requireCoverage: userCrap.requireCoverage ?? defaults.requireCoverage,
+    minMethodResolutionRate: resolveResolutionRate(
+      userCrap.minMethodResolutionRate,
+      defaults.minMethodResolutionRate,
+    ),
     friction: { ...defaults.friction, ...(userCrap.friction ?? {}) },
     refreshTag: userCrap.refreshTag ?? defaults.refreshTag,
     refreshTimeoutMs: resolvePositiveIntegerMs(

package/.agents/scripts/lib/config/temp-paths.js

@@ -274,6 +274,33 @@ export function tempRootFrom(config) {
     : 'temp';
 }
 
+/**
+ * Directory segment (under `tempRoot`) holding every orchestration run log —
+ * the close gate transcripts (`close-gates-<sid>.log`) and the terse-result
+ * detail dumps (`story-init-result-<sid>.log`, `sync-result-<branch>.log`, …).
+ *
+ * Story #4794: the four writers that land here each hand-rolled the temp path
+ * from a literal `temp` segment joined onto their own cwd, which ignores
+ * `project.paths.tempRoot` entirely. On a consumer that relocates its temp
+ * root, the writers wrote to `<cwd>/temp/` while every reader — including the
+ * retention purge — resolved the configured root, so the artifacts were
+ * invisible to the tooling meant to manage them. Routing all four through this
+ * helper also picks up main-checkout anchoring for free, so a close running
+ * from a Story worktree lands its logs in the same tree the host reads.
+ */
+export const ORCHESTRATION_DIRNAME = 'orchestration';
+
+/**
+ * `<tempRoot>/orchestration/` — resolved against the configured temp root and
+ * anchored to the main checkout, like every other helper in this module.
+ *
+ * @param {object} [config]
+ * @returns {string}
+ */
+export function orchestrationLogDir(config) {
+  return path.join(anchorTempRoot(tempRootFrom(config)), ORCHESTRATION_DIRNAME);
+}
+
 const runId = (id) => {
   if (!Number.isInteger(id) || id <= 0) {
     throw new Error(`[temp-paths] runId must be a positive integer; got ${id}`);

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -352,12 +352,81 @@ const AUDIT_TO_STORIES_SCHEMA = {
   additionalProperties: false,
 };
 
+/**
+ * `delivery.tempRetention` — auto-purge of spent temp artifacts (Story #4794).
+ *
+ * `enabled` defaults to `true`: reclaiming a landed Story's gate transcripts
+ * and evidence is the behaviour, and the knob exists to turn it off. `classes`
+ * lets an operator keep one family while purging the rest; `staleDays` is the
+ * age floor for the families no Story id can be recovered from (audit reports,
+ * abandoned `plan-<slug>/` dirs).
+ */
+const TEMP_RETENTION_SCHEMA = {
+  type: 'object',
+  description:
+    'Story #4794. Auto-purge of spent temp artifacts once their Story lands. ' +
+    'Classification is an allowlist: only the declared classes below are ever ' +
+    'deleted, so operator scratch files under tempRoot are reported with their ' +
+    'size and left alone. signals.ndjson is never purged by any path.',
+  properties: {
+    enabled: {
+      type: 'boolean',
+      description:
+        "Master switch. Default true — reclaiming a landed Story's gate " +
+        'transcripts and validation evidence is the behaviour, and this knob ' +
+        'turns it off. When false every purge path is a reported no-op.',
+    },
+    staleDays: {
+      type: 'integer',
+      minimum: 1,
+      description:
+        'Age floor (days, default 7) for the families no Story id can be ' +
+        'recovered from — roster-level audit reports and abandoned ' +
+        'plan-<slug>/ dirs. Story-keyed artifacts do not wait for it: they are ' +
+        'purged as soon as their merge is confirmed.',
+    },
+    classes: {
+      type: 'object',
+      description:
+        'Per-class opt-out. Each defaults to true; set one false to keep that ' +
+        'family while the rest are purged.',
+      properties: {
+        orchestrationLogs: {
+          type: 'boolean',
+          description:
+            '<tempRoot>/orchestration/*.log — close gate transcripts and ' +
+            'terse-result detail dumps.',
+        },
+        validationEvidence: {
+          type: 'boolean',
+          description:
+            'Per-Story validation-evidence.json, lifecycle.ndjson, and ' +
+            'manifest.md under the standalone and per-run story trees.',
+        },
+        auditResults: {
+          type: 'boolean',
+          description: '<tempRoot>/audits/ — audit lens reports.',
+        },
+        planDirs: {
+          type: 'boolean',
+          description:
+            '<tempRoot>/plan-<slug>/ — abandoned plan authoring dirs. ' +
+            'Age-floored only; the current run is always excluded.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  additionalProperties: false,
+};
+
 export const DELIVERY_SCHEMA = {
   type: 'object',
   properties: {
     execution: EXECUTION_SCHEMA,
     lease: LEASE_SCHEMA,
     docsFreshness: DOCS_FRESHNESS_SCHEMA,
+    tempRetention: TEMP_RETENTION_SCHEMA,
     deliverRunner: DELIVER_RUNNER_SCHEMA,
     worktreeIsolation: WORKTREE_ISOLATION_SCHEMA,
     signals: SIGNALS_SCHEMA,

package/.agents/scripts/lib/coverage-utils.js

@@ -121,6 +121,8 @@ export function hasCoverageFor(map, relPath) {
  *   raw `fnMap` entry — so callers may key by the escomplex `lineStart`
  *   (which can match either, depending on producer).
  * - `fnLocByStartLine`: same keying, value is `{fnStart, fnEnd}` derived once.
+ * - `fnRanges`: every function's `{fnStart, fnEnd, declLine}` triple, used by
+ *   the containment / nearest-decl fallbacks when exact-line keying misses.
  * - `statementsByLine`: `Map<line, {total, covered}>` so range scans don't
  *   re-walk the full statement map.
  *
@@ -129,9 +131,10 @@ export function hasCoverageFor(map, relPath) {
 export function buildEntryIndex(entry) {
   const fnByStartLine = new Map();
   const fnLocByStartLine = new Map();
+  const fnRanges = [];
   const statementsByLine = new Map();
   if (!entry || typeof entry !== 'object') {
-    return { fnByStartLine, fnLocByStartLine, statementsByLine };
+    return { fnByStartLine, fnLocByStartLine, fnRanges, statementsByLine };
   }
   const fnMap = entry.fnMap ?? {};
   const statementMap = entry.statementMap ?? {};
@@ -152,6 +155,13 @@ export function buildEntryIndex(entry) {
       fnByStartLine.set(locLine, f);
       fnLocByStartLine.set(locLine, loc);
     }
+    if (fnStart !== null && fnEnd !== null) {
+      fnRanges.push({
+        fnStart,
+        fnEnd,
+        declLine: typeof declLine === 'number' ? declLine : fnStart,
+      });
+    }
   }
 
   for (const stmtId of Object.keys(statementMap)) {
@@ -167,7 +177,76 @@ export function buildEntryIndex(entry) {
     if ((statementHits[stmtId] ?? 0) > 0) bucket.covered += 1;
   }
 
-  return { fnByStartLine, fnLocByStartLine, statementsByLine };
+  return { fnByStartLine, fnLocByStartLine, fnRanges, statementsByLine };
+}
+
+/**
+ * How far from a `fnMap` declaration line a method start may sit and still
+ * be considered the same function.
+ *
+ * Even after remapping to original-source coordinates (Story #4775), a
+ * method's start and istanbul's `decl.start.line` do not always agree on the
+ * token: escomplex anchors on the function node, istanbul on the declaration
+ * it instruments, and a decorator, a leading `export`, or a multi-line
+ * parameter list puts them one line apart. One line of slack absorbs that
+ * without letting an unrelated neighbouring function be claimed.
+ */
+const DECL_MATCH_WINDOW = 1;
+
+/**
+ * Resolve the `{fnStart, fnEnd}` range of the function a method start line
+ * belongs to, in the coordinate system of the coverage entry.
+ *
+ * Three strategies, most precise first:
+ *
+ *   1. **Exact** — the line keys a `fnMap` `decl.start.line` or
+ *      `loc.start.line`. This is the pre-#4775 behaviour and still wins, so
+ *      every already-resolving row keeps its exact prior value.
+ *   2. **Containment** — the innermost function whose `loc` range contains
+ *      the line. Smallest span wins, so a nested callback is preferred over
+ *      the enclosing function that also contains the line.
+ *   3. **Nearest declaration** — the closest `decl` line within
+ *      `DECL_MATCH_WINDOW`, which absorbs the ±1 token disagreement between
+ *      escomplex's method start and istanbul's declaration line.
+ *
+ * Returns `null` when none of the three finds a function — the caller
+ * surfaces that as "no data" rather than "tested zero times."
+ *
+ * @param {{fnByStartLine: Map, fnLocByStartLine: Map, fnRanges: Array}} idx
+ * @param {number} startLine
+ * @returns {{fnStart: number, fnEnd: number}|null}
+ */
+function resolveFnRangeForLine(idx, startLine) {
+  if (typeof startLine !== 'number') return null;
+  if (idx.fnByStartLine.has(startLine)) {
+    const loc = idx.fnLocByStartLine.get(startLine);
+    if (loc && loc.fnStart !== null && loc.fnEnd !== null) return loc;
+  }
+  const ranges = idx.fnRanges ?? [];
+  let innermost = null;
+  let innermostSpan = Number.POSITIVE_INFINITY;
+  for (const range of ranges) {
+    if (startLine < range.fnStart || startLine > range.fnEnd) continue;
+    const span = range.fnEnd - range.fnStart;
+    if (span < innermostSpan) {
+      innermostSpan = span;
+      innermost = range;
+    }
+  }
+  if (innermost) return { fnStart: innermost.fnStart, fnEnd: innermost.fnEnd };
+
+  let nearest = null;
+  let nearestDist = Number.POSITIVE_INFINITY;
+  for (const range of ranges) {
+    const dist = Math.abs(range.declLine - startLine);
+    if (dist > DECL_MATCH_WINDOW) continue;
+    if (dist < nearestDist) {
+      nearestDist = dist;
+      nearest = range;
+    }
+  }
+  if (nearest) return { fnStart: nearest.fnStart, fnEnd: nearest.fnEnd };
+  return null;
 }
 
 function getEntryIndex(entry) {
@@ -193,22 +272,26 @@ function getEntryIndex(entry) {
  * returns 0. A missing / malformed entry or no matching function returns
  * `null` so the caller can distinguish "no data" from "tested zero times."
  *
+ * `startLine` MUST be in the coverage entry's own (original-source)
+ * coordinate system. Callers scoring transpiled TypeScript remap escomplex's
+ * transpiled `lineStart` first — see `transpileIfNeeded`'s `withLineMap`
+ * option (Story #4775). Matching is exact-then-containment-then-nearest-decl;
+ * see `resolveFnRangeForLine`.
+ *
  * The first call on a given entry builds and caches a per-entry index via a
  * non-enumerable Symbol property; consecutive method lookups in the same
  * file pay the build cost exactly once.
  *
  * @param {object|null} entry One inner value from a `coverage-final.json` map.
- * @param {number} startLine The escomplex `lineStart` for the method.
+ * @param {number} startLine The method's start line, in entry coordinates.
  * @returns {number|null}
  */
 export function coverageForMethodInEntry(entry, startLine) {
   if (!entry || typeof entry !== 'object') return null;
   const idx = getEntryIndex(entry);
-  if (!idx.fnByStartLine.has(startLine)) return null;
-  const loc = idx.fnLocByStartLine.get(startLine);
-  if (!loc) return null;
-  const { fnStart, fnEnd } = loc;
-  if (fnStart === null || fnEnd === null) return null;
+  const range = resolveFnRangeForLine(idx, startLine);
+  if (!range) return null;
+  const { fnStart, fnEnd } = range;
 
   let total = 0;
   let covered = 0;
@@ -228,7 +311,7 @@ export function coverageForMethodInEntry(entry, startLine) {
  *
  * @param {object|null} map Parsed `coverage-final.json`.
  * @param {string} relPath Repo-relative path of the source file.
- * @param {number} startLine The escomplex `lineStart` for the method.
+ * @param {number} startLine The method's start line, in entry coordinates.
  * @returns {number|null} Coverage in [0, 1], or null when the file or method
  *   is absent.
  */

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

@@ -1,6 +1,108 @@
 import escomplex from 'typhonjs-escomplex';
 import { coverageForMethodInEntry } from './coverage-utils.js';
 
+/**
+ * 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).** `mapLine` translates escomplex's
+ * `lineStart` — which is in *transpiled* coordinates for a TS/TSX source —
+ * into the *original source* coordinates istanbul's `fnMap` uses. Without it
+ * the join compares two different coordinate systems and either misses or,
+ * worse, collides with an unrelated function. A `null` mapper means the two
+ * coordinate systems already coincide (plain JavaScript), and a line the map
+ * cannot resolve falls back to the un-remapped value rather than dropping the
+ * method outright. The remapped line is also what the row reports, so a
+ * persisted row points at a line the reader can actually open.
+ *
+ * @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,
+ *   startLine: number,
+ *   cyclomatic: number,
+ *   coverage: number|null,
+ *   crap: number|null,
+ * }>}
+ */
+export function methodRowsFromReport(report, coverageForFile, mapLine = null) {
+  const methods = report?.methods ?? [];
+  const rows = [];
+  for (const m of methods) {
+    const rawStartLine = m?.lineStart;
+    if (typeof rawStartLine !== 'number') continue;
+    const mapped = typeof mapLine === 'function' ? mapLine(rawStartLine) : null;
+    const startLine = typeof mapped === 'number' ? mapped : rawStartLine;
+    const cyclomatic = m?.cyclomatic ?? 0;
+    const coverage = coverageForFile
+      ? coverageForMethodInEntry(coverageForFile, startLine)
+      : null;
+    const crap = coverage === null ? null : crapFormula(cyclomatic, coverage);
+    rows.push({ method: m.name, startLine, cyclomatic, coverage, crap });
+  }
+  return rows;
+}
+
+/**
+ * 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.
+ *
+ * `resolvedMethods` / `totalMethods` count the *join*, not the fill: a
+ * method scored 0% because its coverage was unresolved counts as
+ * unresolved. That is what makes them usable as a health signal for the
+ * updater's fail-closed resolution-rate floor.
+ *
+ * @param {Array<object>} rawRows Rows from `methodRowsFromReport`.
+ * @param {{requireCoverage?: boolean}} [opts]
+ * @returns {{
+ *   rows: Array<object>,
+ *   skippedMethodsNoCoverage: number,
+ *   resolvedMethods: number,
+ *   totalMethods: number,
+ * }}
+ */
+export function finalizeMethodRows(rawRows, { requireCoverage = true } = {}) {
+  const rows = [];
+  let skippedMethodsNoCoverage = 0;
+  let resolvedMethods = 0;
+  let totalMethods = 0;
+  for (const mr of rawRows ?? []) {
+    totalMethods += 1;
+    const unresolved = mr.crap === null || mr.coverage === null;
+    if (!unresolved) resolvedMethods += 1;
+    if (unresolved && requireCoverage) {
+      skippedMethodsNoCoverage += 1;
+      continue;
+    }
+    const coverage = unresolved ? 0 : mr.coverage;
+    const crap = unresolved ? crapFormula(mr.cyclomatic, 0) : mr.crap;
+    rows.push({
+      method: mr.method,
+      startLine: mr.startLine,
+      cyclomatic: mr.cyclomatic,
+      coverage,
+      crap,
+    });
+  }
+  return { rows, skippedMethodsNoCoverage, resolvedMethods, totalMethods };
+}
+
 /**
  * Score each method in a JavaScript source for Change Risk Anti-Patterns
  * (CRAP): `c² · (1 − cov)³ + c`, where `c` is cyclomatic complexity and `cov`
@@ -11,15 +113,17 @@ import { coverageForMethodInEntry } from './coverage-utils.js';
  *     `analyzeModule`).
  *   - Methods whose coverage cannot be resolved from `coverageForFile`
  *     produce `coverage: null` and `crap: null`. Callers apply their own
- *     `requireCoverage` policy at the scanner level; this kernel never
- *     decides to skip.
+ *     `requireCoverage` policy at the scanner level (`finalizeMethodRows`);
+ *     this kernel never decides to skip.
  *   - A parse error returns an empty array — the file is unscorable, not
  *     zero-complexity.
  *
- * @param {string} source JavaScript source text.
+ * @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 {((line: number) => number|null)|null} [mapLine] Transpiled →
+ *   original line resolver; see `methodRowsFromReport`.
  * @returns {Array<{
  *   method: string,
  *   startLine: number,
@@ -28,32 +132,18 @@ import { coverageForMethodInEntry } from './coverage-utils.js';
  *   crap: number|null,
  * }>}
  */
-export function calculateCrapForSource(source, coverageForFile) {
+export function calculateCrapForSource(
+  source,
+  coverageForFile,
+  mapLine = null,
+) {
   let report;
   try {
     report = escomplex.analyzeModule(source);
   } catch {
     return [];
   }
-  const methods = report?.methods ?? [];
-  const rows = [];
-  for (const m of methods) {
-    const startLine = m?.lineStart;
-    if (typeof startLine !== 'number') continue;
-    const cyclomatic = m?.cyclomatic ?? 0;
-    const coverage = coverageForFile
-      ? coverageForMethodInEntry(coverageForFile, startLine)
-      : null;
-    const crap = coverage === null ? null : crapFormula(cyclomatic, coverage);
-    rows.push({
-      method: m.name,
-      startLine,
-      cyclomatic,
-      coverage,
-      crap,
-    });
-  }
-  return rows;
+  return methodRowsFromReport(report, coverageForFile, mapLine);
 }
 
 /**