mandrel 2.16.0 → 2.17.0

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);
 }
 
 /**

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

@@ -2,15 +2,15 @@ import fs from 'node:fs';
 import path from 'node:path';
 import escomplex from 'typhonjs-escomplex';
 import { canonicalise as canonicalisePath } from './baselines/path-canon.js';
-import {
-  coverageForMethodInEntry,
-  findCoverageEntry,
-} from './coverage-utils.js';
+import { findCoverageEntry } from './coverage-utils.js';
 import { POOL_SERIAL_THRESHOLD, runOnPool } from './cpu-pool.js';
-import { crapFormula } from './crap-engine.js';
+import { finalizeMethodRows, methodRowsFromReport } from './crap-engine.js';
 import { Logger } from './Logger.js';
 import { scanDirectory } from './maintainability-utils.js';
-import { resolveTsTranspilerVersion, transpileIfNeeded } from './transpile.js';
+import {
+  prepareSourceForScoring,
+  resolveTsTranspilerVersion,
+} from './transpile.js';
 
 const CRAP_WORKER_URL = new URL('./workers/crap-worker.js', import.meta.url);
 const COMBINED_MI_CRAP_WORKER_URL = new URL(
@@ -201,6 +201,103 @@ export function buildBaselineEnvelope({
   };
 }
 
+/**
+ * How many files to name when reporting the worst unresolved offenders. Long
+ * enough to point at a pattern, short enough to stay a readable CLI message.
+ */
+const WORST_OFFENDER_LIMIT = 5;
+
+/**
+ * Method-resolution telemetry (Story #4775, fix part 4).
+ *
+ * The updater used to persist a 100-row baseline built from 5023 dropped
+ * methods and log it as success — the rot that let a broken coverage join
+ * sit undetected for five weeks across three repos. These three helpers
+ * carry the counters that make a thin result *visible* and therefore
+ * refusable.
+ *
+ * The rate is deliberately measured over files that **do** have a coverage
+ * entry: a file the test run never touched has no join to fail, so counting
+ * it would dilute the signal the floor is meant to catch.
+ */
+function newResolutionAccumulator() {
+  return { resolved: 0, total: 0, byFile: [] };
+}
+
+function accumulateResolution(acc, relPath, result) {
+  if (result?.hasCoverageEntry !== true) return;
+  const total = result.totalMethods ?? 0;
+  if (total === 0) return;
+  const resolved = result.resolvedMethods ?? 0;
+  acc.resolved += resolved;
+  acc.total += total;
+  if (resolved < total) {
+    acc.byFile.push({ file: relPath, unresolved: total - resolved, total });
+  }
+}
+
+function summarizeResolution(acc) {
+  const worstFiles = [...acc.byFile]
+    .sort((a, b) => b.unresolved - a.unresolved || a.file.localeCompare(b.file))
+    .slice(0, WORST_OFFENDER_LIMIT);
+  return {
+    resolvedMethods: acc.resolved,
+    joinableMethods: acc.total,
+    rate: acc.total === 0 ? 1 : acc.resolved / acc.total,
+    worstFiles,
+  };
+}
+
+/**
+ * Minimum number of joinable methods before the resolution-rate floor is
+ * enforced. A diff-scoped run can legitimately touch a handful of methods,
+ * where one unresolved method is a 50% rate and says nothing about the health
+ * of the join. Below this sample the rate is reported, never enforced.
+ */
+const MIN_RESOLUTION_SAMPLE = 25;
+
+/**
+ * Fail-closed guard on the per-method coverage join (Story #4775, fix part 4).
+ *
+ * The updater used to persist a 100-row baseline distilled from 5023 dropped
+ * methods and log it as a success — which is exactly how a broken join stayed
+ * invisible for five weeks across three repositories. A thin result is now a
+ * refusal: the caller throws before anything is written, and the message names
+ * the rate, the counts, and the files carrying the most unresolved methods so
+ * the operator can tell "my tests do not cover that" apart from "the join is
+ * broken".
+ *
+ * Returns `null` when the run may proceed, or the operator-facing message when
+ * it must not.
+ *
+ * @param {{resolvedMethods: number, joinableMethods: number, rate: number,
+ *   worstFiles: Array<{file: string, unresolved: number, total: number}>}
+ *   | undefined} resolution
+ * @param {number} floor
+ * @returns {string|null}
+ */
+export function checkResolutionFloor(resolution, floor) {
+  if (!resolution) return null;
+  const { joinableMethods = 0, resolvedMethods = 0, rate = 1 } = resolution;
+  if (joinableMethods < MIN_RESOLUTION_SAMPLE) return null;
+  if (rate >= floor) return null;
+  const worst = (resolution.worstFiles ?? [])
+    .map((w) => `         - ${w.file} (${w.unresolved}/${w.total} unresolved)`)
+    .join('\n');
+  return (
+    `[CRAP] Refusing to persist: only ${resolvedMethods}/${joinableMethods} ` +
+    `method(s) (${(rate * 100).toFixed(1)}%) resolved a coverage entry in files ` +
+    `that HAVE coverage — below the ${(floor * 100).toFixed(1)}% floor ` +
+    '(delivery.quality.gates.crap.minMethodResolutionRate).\n' +
+    '       A baseline built from a broken join is not sparse, it is wrong: ' +
+    'unresolved methods are absent and coincidental line collisions are ' +
+    'mis-attributed.\n' +
+    (worst ? `       Worst unresolved files:\n${worst}\n` : '') +
+    "       Regenerate coverage ('npm run test:coverage') and re-run; if the " +
+    'rate stays low the coverage artifact and the scanned tree disagree.'
+  );
+}
+
 /**
  * Parse `source` exactly once with escomplex and derive both the
  * maintainability score and the raw CRAP method rows from that single report.
@@ -216,6 +313,10 @@ export function buildBaselineEnvelope({
  *
  * @param {string} source Prepared (possibly transpiled) JavaScript source text.
  * @param {object|null} coverageForFile Istanbul coverage entry for this file.
+ * @param {((line: number) => number|null)|null} [mapLine] Transpiled →
+ *   original-source line resolver from `transpileIfNeeded(…, {withLineMap:
+ *   true})`; `null` for JavaScript, whose coordinates already match the
+ *   coverage entry's.
  * @returns {{
  *   report: object,
  *   miScore: number,
@@ -229,7 +330,7 @@ export function buildBaselineEnvelope({
  *   parseError: boolean,
  * }}
  */
-export function analyzeOnce(source, coverageForFile) {
+export function analyzeOnce(source, coverageForFile, mapLine = null) {
   let report;
   try {
     report = escomplex.analyzeModule(source);
@@ -238,18 +339,7 @@ export function analyzeOnce(source, coverageForFile) {
   }
   const miScore =
     typeof report.maintainability === 'number' ? report.maintainability : 0;
-  const methods = report?.methods ?? [];
-  const crapRows = [];
-  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);
-    crapRows.push({ method: m.name, startLine, cyclomatic, coverage, crap });
-  }
+  const crapRows = methodRowsFromReport(report, coverageForFile, mapLine);
   return { report, miScore, crapRows, parseError: false };
 }
 
@@ -348,6 +438,7 @@ export async function scanAndScore({
   const rows = [];
   let skippedFilesNoCoverage = 0;
   let skippedMethodsNoCoverage = 0;
+  const resolution = newResolutionAccumulator();
   for (const { item, result } of perFile) {
     if (!result) continue; // unrecoverable per-file failure: drop silently to match pre-pool semantics
     if (result.skippedFileNoCoverage) {
@@ -366,6 +457,7 @@ export async function scanAndScore({
       continue;
     }
     skippedMethodsNoCoverage += result.skippedMethodsNoCoverage ?? 0;
+    accumulateResolution(resolution, item.relPath, result);
     for (const mr of result.rows) {
       rows.push({
         file: item.relPath,
@@ -390,6 +482,7 @@ export async function scanAndScore({
     scannedFiles,
     skippedFilesNoCoverage,
     skippedMethodsNoCoverage,
+    resolution: summarizeResolution(resolution),
   };
 }
 
@@ -408,50 +501,33 @@ function scoreFileSerial({ abs, relPath, requireCoverage }, coverage) {
       skippedFileNoCoverage: true,
       rows: [],
       skippedMethodsNoCoverage: 0,
+      hasCoverageEntry: false,
+      resolvedMethods: 0,
+      totalMethods: 0,
     };
   }
-  let source;
-  try {
-    source = fs.readFileSync(abs, 'utf-8');
-  } catch {
-    return {
-      skippedFileNoCoverage: false,
-      rows: null,
-      skippedMethodsNoCoverage: 0,
-    };
-  }
-  const prepared = transpileIfNeeded(abs, source);
-  if (prepared === null) {
-    return {
-      skippedFileNoCoverage: false,
-      rows: null,
-      skippedMethodsNoCoverage: 0,
-    };
-  }
-  const { crapRows, parseError } = analyzeOnce(prepared, entry);
-  if (parseError) {
-    return {
-      skippedFileNoCoverage: false,
-      rows: null,
-      skippedMethodsNoCoverage: 0,
-    };
-  }
-  const rows = [];
-  let skippedMethodsNoCoverage = 0;
-  for (const mr of crapRows) {
-    if (mr.crap === null || mr.coverage === null) {
-      skippedMethodsNoCoverage += 1;
-      continue;
-    }
-    rows.push({
-      method: mr.method,
-      startLine: mr.startLine,
-      cyclomatic: mr.cyclomatic,
-      coverage: mr.coverage,
-      crap: mr.crap,
-    });
-  }
-  return { skippedFileNoCoverage: false, rows, skippedMethodsNoCoverage };
+  const dropped = {
+    skippedFileNoCoverage: false,
+    rows: null,
+    skippedMethodsNoCoverage: 0,
+    hasCoverageEntry: entry !== null,
+    resolvedMethods: 0,
+    totalMethods: 0,
+  };
+  const prepared = prepareSourceForScoring(abs);
+  if (prepared.error) return dropped;
+  const { crapRows, parseError } = analyzeOnce(
+    prepared.code,
+    entry,
+    prepared.mapLine,
+  );
+  if (parseError) return dropped;
+  const finalized = finalizeMethodRows(crapRows, { requireCoverage });
+  return {
+    skippedFileNoCoverage: false,
+    hasCoverageEntry: entry !== null,
+    ...finalized,
+  };
 }
 
 async function scoreFilesViaPool(queue, coverage) {
@@ -494,33 +570,24 @@ async function scoreFilesViaPool(queue, coverage) {
  */
 function scoreFileCombinedSerial({ abs, relPath, requireCoverage }, coverage) {
   const entry = findCoverageEntry(coverage, relPath);
-  let source;
-  try {
-    source = fs.readFileSync(abs, 'utf-8');
-  } catch {
-    return {
-      relPath,
-      miScore: null,
-      skippedFileNoCoverage: false,
-      crapRows: null,
-      skippedMethodsNoCoverage: 0,
-    };
-  }
-  const prepared = transpileIfNeeded(abs, source);
-  if (prepared === null) {
+  const prepared = prepareSourceForScoring(abs);
+  if (prepared.error) {
     return {
       relPath,
-      miScore: 0,
+      miScore: prepared.error === 'read' ? null : 0,
       skippedFileNoCoverage: false,
       crapRows: null,
       skippedMethodsNoCoverage: 0,
+      hasCoverageEntry: entry !== null,
+      resolvedMethods: 0,
+      totalMethods: 0,
     };
   }
   const {
     miScore,
     crapRows: rawCrapRows,
     parseError,
-  } = analyzeOnce(prepared, entry);
+  } = analyzeOnce(prepared.code, entry, prepared.mapLine);
   if (parseError) {
     return {
       relPath,
@@ -528,6 +595,9 @@ function scoreFileCombinedSerial({ abs, relPath, requireCoverage }, coverage) {
       skippedFileNoCoverage: false,
       crapRows: null,
       skippedMethodsNoCoverage: 0,
+      hasCoverageEntry: entry !== null,
+      resolvedMethods: 0,
+      totalMethods: 0,
     };
   }
   if (requireCoverage && entry === null) {
@@ -537,29 +607,22 @@ function scoreFileCombinedSerial({ abs, relPath, requireCoverage }, coverage) {
       skippedFileNoCoverage: true,
       crapRows: [],
       skippedMethodsNoCoverage: 0,
+      hasCoverageEntry: false,
+      resolvedMethods: 0,
+      totalMethods: 0,
     };
   }
-  const crapRows = [];
-  let skippedMethodsNoCoverage = 0;
-  for (const mr of rawCrapRows) {
-    if (mr.crap === null || mr.coverage === null) {
-      skippedMethodsNoCoverage += 1;
-      continue;
-    }
-    crapRows.push({
-      method: mr.method,
-      startLine: mr.startLine,
-      cyclomatic: mr.cyclomatic,
-      coverage: mr.coverage,
-      crap: mr.crap,
-    });
-  }
+  const { rows, skippedMethodsNoCoverage, resolvedMethods, totalMethods } =
+    finalizeMethodRows(rawCrapRows, { requireCoverage });
   return {
     relPath,
     miScore,
     skippedFileNoCoverage: false,
-    crapRows,
+    crapRows: rows,
     skippedMethodsNoCoverage,
+    hasCoverageEntry: entry !== null,
+    resolvedMethods,
+    totalMethods,
   };
 }
 
@@ -693,6 +756,7 @@ export async function scanAndScoreCombined({
   const crapRows = [];
   let skippedFilesNoCoverage = 0;
   let skippedMethodsNoCoverage = 0;
+  const resolution = newResolutionAccumulator();
 
   for (const { item, result } of perFile) {
     if (!result) continue; // unrecoverable per-file failure: drop silently
@@ -716,6 +780,7 @@ export async function scanAndScoreCombined({
       continue;
     }
     skippedMethodsNoCoverage += result.skippedMethodsNoCoverage ?? 0;
+    accumulateResolution(resolution, item.relPath, result);
     for (const mr of result.crapRows) {
       crapRows.push({
         file: item.relPath,
@@ -750,6 +815,7 @@ export async function scanAndScoreCombined({
       scannedFiles,
       skippedFilesNoCoverage,
       skippedMethodsNoCoverage,
+      resolution: summarizeResolution(resolution),
     },
   };
 }