mandrel 2.28.0 → 2.30.0

package/.agents/scripts/lib/coverage-capture-fullscope.js

@@ -0,0 +1,105 @@
+/**
+ * coverage-capture-fullscope.js — the full-scope (pre-#4981, and still the
+ * default) capture path for `coverage-capture.js`.
+ *
+ * Hoisted out of the CLI shell's `runCoverageCapture` verbatim (Story
+ * #4981) so that function's cyclomatic complexity does not grow with the
+ * incremental-mode branch alongside it — this is a relocation, not new
+ * logic; behaviour is byte-for-byte the pre-#4981 body.
+ */
+import path from 'node:path';
+import { anyChangedUnderTargets } from './coverage-capture.js';
+
+/**
+ * Run the `--skip-when-no-crap-files` check (when requested), the
+ * content-digest freshness probe, and — when stale — the full-repo
+ * `npm run test:coverage` capture + stamp write.
+ *
+ * @param {{
+ *   crap: object,
+ *   coverage: object,
+ *   args: { skipWhenNoCrapFiles: boolean, ref: string, cwd: string },
+ *   getChangedFilesImpl: Function,
+ *   isCoverageFreshImpl: Function,
+ *   runCaptureImpl: Function,
+ *   computeContentDigestImpl: Function,
+ *   writeCaptureStampImpl: Function,
+ *   logger: { info: Function, warn: Function, error: Function },
+ * }} opts
+ * @returns {number} process exit code
+ */
+export function runFullScopeCapture({
+  crap,
+  coverage,
+  args,
+  getChangedFilesImpl,
+  isCoverageFreshImpl,
+  runCaptureImpl,
+  computeContentDigestImpl,
+  writeCaptureStampImpl,
+  logger,
+}) {
+  if (args.skipWhenNoCrapFiles) {
+    let changed;
+    try {
+      changed = getChangedFilesImpl({ ref: args.ref, cwd: args.cwd });
+    } catch (err) {
+      // A bad ref must not silently relax the gate. Fall through to the
+      // freshness check so coverage still gets captured if needed.
+      logger.warn(
+        `[coverage-capture] ⚠ ${err?.message ?? err} — falling back to freshness check.`,
+      );
+      changed = null;
+    }
+    if (changed && !anyChangedUnderTargets(changed, crap.targetDirs)) {
+      logger.info(
+        `[coverage-capture] No changed files under [${crap.targetDirs.join(', ')}] — skipping capture.`,
+      );
+      return 0;
+    }
+  }
+
+  const freshness = isCoverageFreshImpl({
+    coveragePath: crap.coveragePath,
+    targetDirs: crap.targetDirs,
+    cwd: args.cwd,
+  });
+  if (freshness.fresh) {
+    logger.info(
+      `[coverage-capture] Coverage at ${path.resolve(args.cwd, crap.coveragePath)} is ${freshness.reason} — skipping capture.`,
+    );
+    return 0;
+  }
+
+  logger.info(
+    `[coverage-capture] Coverage at ${crap.coveragePath} is ${freshness.reason}; running npm run test:coverage…`,
+  );
+  const code = runCaptureImpl({
+    cwd: args.cwd,
+    timeoutMs: coverage?.timeoutMs,
+    log: (m) => logger.info(m),
+  });
+  if (code !== 0) {
+    logger.error(
+      `[coverage-capture] ✖ npm run test:coverage exited ${code}. Fix failing tests or coverage-threshold breaches before re-running the CRAP gate.`,
+    );
+    return code;
+  }
+
+  // Persist the content digest next to the fresh artifact so subsequent
+  // freshness checks are content-aware (mtime churn from branch switches no
+  // longer invalidates). Best-effort — a missing stamp just means the next
+  // check falls back to the mtime heuristic.
+  const digest = computeContentDigestImpl(args.cwd, crap.targetDirs);
+  if (
+    digest &&
+    writeCaptureStampImpl({
+      cwd: args.cwd,
+      coveragePath: crap.coveragePath,
+      digest,
+    })
+  ) {
+    logger.info('[coverage-capture] Wrote content-digest capture stamp.');
+  }
+  return code;
+}

package/.agents/scripts/lib/coverage-capture-incremental.js

@@ -0,0 +1,116 @@
+/**
+ * coverage-capture-incremental.js — the incremental-mode capture path for
+ * `coverage-capture.js` (Story #4981).
+ *
+ * Split into its own module (rather than added inline to the CLI shell) so
+ * the Story's opt-in branch lands as new code, not a same-file expansion of
+ * `runCoverageCapture`. Every collaborator is injected — no seam differs
+ * from the ones `coverage-capture.js` already exposes on its `deps`
+ * parameter (`.agents/rules/test-seams.md` rules 1-2, 4).
+ */
+import path from 'node:path';
+
+/**
+ * Run the incremental capture path when
+ * `delivery.quality.gates.crap.incrementalCoverage.enabled` is true.
+ *
+ * Returns the process exit code when incremental mode handled the run
+ * (skip, capture, or a capture failure), or `null` when the caller should
+ * fall through to the full-scope path — either incremental mode is
+ * disabled, or the changed-files ref could not be resolved (a
+ * misconfiguration must not silently relax the gate).
+ *
+ * @param {{
+ *   crap: object,
+ *   coverage: object,
+ *   args: { ref: string, cwd: string },
+ *   getChangedFilesImpl: Function,
+ *   filterFilesUnderTargetsImpl: Function,
+ *   isCoverageFreshImpl: Function,
+ *   runCaptureImpl: Function,
+ *   computeContentDigestImpl: Function,
+ *   writeCaptureStampImpl: Function,
+ *   logger: { info: Function, warn: Function, error: Function },
+ * }} opts
+ * @returns {number | null}
+ */
+export function tryIncrementalCapture({
+  crap,
+  coverage,
+  args,
+  getChangedFilesImpl,
+  filterFilesUnderTargetsImpl,
+  isCoverageFreshImpl,
+  runCaptureImpl,
+  computeContentDigestImpl,
+  writeCaptureStampImpl,
+  logger,
+}) {
+  if (crap.incrementalCoverage?.enabled !== true) return null;
+
+  const ref = crap.incrementalCoverage.baseRef || args.ref;
+  let changed = null;
+  try {
+    changed = getChangedFilesImpl({ ref, cwd: args.cwd });
+  } catch (err) {
+    logger.warn(
+      `[coverage-capture] ⚠ incremental mode: ${err?.message ?? err} — falling back to full-scope capture.`,
+    );
+    return null;
+  }
+
+  const scopedFiles = filterFilesUnderTargetsImpl(changed, crap.targetDirs);
+  if (scopedFiles.length === 0) {
+    logger.info(
+      `[coverage-capture] Incremental mode: no changed files under [${crap.targetDirs.join(', ')}] vs ${ref} — skipping capture.`,
+    );
+    return 0;
+  }
+
+  const freshness = isCoverageFreshImpl({
+    coveragePath: crap.coveragePath,
+    targetDirs: crap.targetDirs,
+    cwd: args.cwd,
+    requireScope: 'incremental',
+  });
+  if (freshness.fresh) {
+    logger.info(
+      `[coverage-capture] Coverage at ${path.resolve(args.cwd, crap.coveragePath)} is ${freshness.reason} (incremental) — skipping capture.`,
+    );
+    return 0;
+  }
+
+  logger.info(
+    `[coverage-capture] Incremental mode: capturing coverage scoped to ${scopedFiles.length} changed file(s) under [${crap.targetDirs.join(', ')}]…`,
+  );
+  const code = runCaptureImpl({
+    cwd: args.cwd,
+    timeoutMs: coverage?.timeoutMs,
+    log: (m) => logger.info(m),
+    files: scopedFiles,
+  });
+  if (code !== 0) {
+    logger.error(
+      `[coverage-capture] ✖ npm run test:coverage exited ${code}. Fix failing tests or coverage-threshold breaches before re-running the CRAP gate.`,
+    );
+    return code;
+  }
+
+  const digest = computeContentDigestImpl(args.cwd, crap.targetDirs);
+  if (
+    digest &&
+    writeCaptureStampImpl({
+      cwd: args.cwd,
+      coveragePath: crap.coveragePath,
+      digest,
+      scope: 'incremental',
+      files: scopedFiles,
+      ref,
+    })
+  ) {
+    logger.info(
+      '[coverage-capture] Wrote content-digest capture stamp (incremental scope).',
+    );
+  }
+  return code;
+}

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

@@ -151,10 +151,20 @@ export function computeContentDigest(cwd, targetDirs, io = {}) {
  * write failure returns `false` rather than throwing — the worst case is a
  * fall back to the mtime heuristic on the next freshness check.
  *
+ * `scope` / `files` / `ref` are Story #4981 additions for incremental-mode
+ * capture. They are written to the stamp **only when the caller supplies
+ * `scope`** — the default (full-scope) call sites never pass it, so the
+ * emitted JSON stays the exact `{ digest, capturedAt }` shape byte-for-byte
+ * (AC-5). `isCoverageFresh` reads `scope` back to refuse letting a scoped
+ * stamp satisfy a full-scope freshness probe (AC-4).
+ *
  * @param {{
  *   cwd: string,
  *   coveragePath: string,
  *   digest: string,
+ *   scope?: 'full' | 'incremental',
+ *   files?: string[],
+ *   ref?: string,
  *   writeFileSync?: typeof fs.writeFileSync,
  * }} opts
  * @returns {boolean} True when the stamp was written.
@@ -163,13 +173,20 @@ export function writeCaptureStamp({
   cwd,
   coveragePath,
   digest,
+  scope,
+  files,
+  ref,
   writeFileSync = fs.writeFileSync,
 }) {
   if (typeof digest !== 'string' || digest.length === 0) return false;
+  const payload = { digest, capturedAt: new Date().toISOString() };
+  if (scope !== undefined) payload.scope = scope;
+  if (Array.isArray(files)) payload.files = [...files].sort();
+  if (typeof ref === 'string' && ref.length > 0) payload.ref = ref;
   try {
     writeFileSync(
       captureStampPath(cwd, coveragePath),
-      `${JSON.stringify({ digest, capturedAt: new Date().toISOString() }, null, 2)}\n`,
+      `${JSON.stringify(payload, null, 2)}\n`,
     );
     return true;
   } catch {
@@ -177,6 +194,29 @@ export function writeCaptureStamp({
   }
 }
 
+/**
+ * Read a persisted capture stamp's digest and scope tag back into the shape
+ * `isCoverageFresh` needs, applying the Story #4981 scope-asymmetry rule
+ * (AC-4) in one place. Extracted so the parent function's own branching
+ * stays under the cyclomatic ceiling.
+ *
+ * @param {{digest?: unknown, scope?: unknown} | null} stamp
+ * @param {'full' | 'incremental'} requireScope
+ * @returns {{ digest: string } | { scopeMismatch: true } | null} `null`
+ *   means the stamp is missing/unreadable/digest-less — fall through to the
+ *   mtime heuristic.
+ */
+function readStampForScope(stamp, requireScope) {
+  if (typeof stamp?.digest !== 'string' || stamp.digest.length === 0) {
+    return null;
+  }
+  const stampScope = stamp.scope === 'incremental' ? 'incremental' : 'full';
+  if (stampScope === 'incremental' && requireScope !== 'incremental') {
+    return { scopeMismatch: true };
+  }
+  return { digest: stamp.digest };
+}
+
 /**
  * Decide whether the existing coverage artifact is "fresh".
  *
@@ -191,22 +231,32 @@ export function writeCaptureStamp({
  * under `targetDirs`. Missing files, missing target dirs, or any IO error
  * resolve to `false` so the caller captures rather than trusting stale data.
  *
+ * **Scope asymmetry (Story #4981, AC-4).** A stamp written by an incremental
+ * capture (`scope: 'incremental'`) only covers the files the diff touched —
+ * it must never satisfy a caller that requires the full-scope guarantee
+ * (`requireScope` defaults to `'full'`, matching every pre-existing caller
+ * byte-for-byte). A full-scope stamp (or a legacy stamp with no `scope`
+ * field, which predates this Story and is therefore full-scope by
+ * construction) satisfies either probe.
+ *
  * @param {{
  *   coveragePath: string,
  *   targetDirs: string[],
  *   cwd: string,
+ *   requireScope?: 'full' | 'incremental',
  *   statSync?: typeof fs.statSync,
  *   readdirSync?: typeof fs.readdirSync,
  *   existsSync?: typeof fs.existsSync,
  *   readFileSync?: typeof fs.readFileSync,
  *   computeDigest?: typeof computeContentDigest,
  * }} opts
- * @returns {{ fresh: boolean, reason: 'missing' | 'stale' | 'fresh' | 'no-sources' }}
+ * @returns {{ fresh: boolean, reason: 'missing' | 'stale' | 'fresh' | 'no-sources' | 'scope-mismatch' }}
  */
 export function isCoverageFresh({
   coveragePath,
   targetDirs,
   cwd,
+  requireScope = 'full',
   statSync = fs.statSync,
   readdirSync = fs.readdirSync,
   existsSync = fs.existsSync,
@@ -224,10 +274,14 @@ export function isCoverageFresh({
     } catch {
       // Corrupt/unreadable stamp → fall through to the mtime heuristic.
     }
-    if (typeof stamp?.digest === 'string' && stamp.digest.length > 0) {
+    const resolved = readStampForScope(stamp, requireScope);
+    if (resolved?.scopeMismatch) {
+      return { fresh: false, reason: 'scope-mismatch' };
+    }
+    if (resolved) {
       const current = computeDigest(cwd, targetDirs);
       if (typeof current === 'string' && current.length > 0) {
-        return current === stamp.digest
+        return current === resolved.digest
           ? { fresh: true, reason: 'fresh' }
           : { fresh: false, reason: 'stale' };
       }
@@ -251,28 +305,42 @@ export function isCoverageFresh({
     : { fresh: false, reason: 'stale' };
 }
 
+/**
+ * Narrow `changedFiles` to the subset that lives under one of `targetDirs`.
+ *
+ * Both inputs are forward-slash-normalised; `targetDirs` are matched as path
+ * prefixes followed by `/`. Shared by `anyChangedUnderTargets` (the pre-push
+ * fast-path boolean) and the incremental-coverage scope resolver (Story
+ * #4981), which needs the actual file list rather than a yes/no.
+ *
+ * @param {string[]} changedFiles
+ * @param {string[]} targetDirs
+ * @returns {string[]} Forward-slash-normalised matches, in `changedFiles` order.
+ */
+export function filterFilesUnderTargets(changedFiles, targetDirs) {
+  if (!Array.isArray(changedFiles) || changedFiles.length === 0) return [];
+  if (!Array.isArray(targetDirs) || targetDirs.length === 0) return [];
+  const norms = targetDirs
+    .filter((d) => typeof d === 'string' && d.length > 0)
+    .map((d) => d.replace(/\\/g, '/').replace(/\/+$/, ''));
+  return changedFiles
+    .map((file) => String(file).replace(/\\/g, '/'))
+    .filter((f) => norms.some((dir) => f === dir || f.startsWith(`${dir}/`)));
+}
+
 /**
  * Decide whether any of `changedFiles` lives under one of `targetDirs`.
  * Used by the pre-push fast-path so we can skip the (slow) coverage capture
  * when the push touches only files outside the CRAP scoring scope.
  *
- * Both inputs are forward-slash-normalised; `targetDirs` are matched as path
- * prefixes followed by `/`. An empty changed-file list returns `false`.
+ * An empty changed-file list returns `false`.
  *
  * @param {string[]} changedFiles
  * @param {string[]} targetDirs
  * @returns {boolean}
  */
 export function anyChangedUnderTargets(changedFiles, targetDirs) {
-  if (!Array.isArray(changedFiles) || changedFiles.length === 0) return false;
-  if (!Array.isArray(targetDirs) || targetDirs.length === 0) return false;
-  const norms = targetDirs
-    .filter((d) => typeof d === 'string' && d.length > 0)
-    .map((d) => d.replace(/\\/g, '/').replace(/\/+$/, ''));
-  return changedFiles.some((file) => {
-    const f = String(file).replace(/\\/g, '/');
-    return norms.some((dir) => f === dir || f.startsWith(`${dir}/`));
-  });
+  return filterFilesUnderTargets(changedFiles, targetDirs).length > 0;
 }
 
 /**
@@ -295,11 +363,20 @@ export const COVERAGE_TIMEOUT_EXIT_CODE = 124;
  * `timeout(1)` convention exit code 124 so callers can pattern-match a
  * runaway runner without inspecting signal names.
  *
+ * `files` (Story #4981) scopes the spawn to a file list — `npm run
+ * test:coverage -- <files...>`, the standard npm convention for forwarding
+ * argv to the underlying script (which most test runners, including Node's
+ * own, treat as positional file filters). Omitted or empty means the
+ * default full-scope invocation, byte-identical to the pre-#4981 argv
+ * (AC-5); a non-empty list makes the scope observable on the emitted
+ * command line (AC-1).
+ *
  * @param {{
  *   cwd: string,
  *   timeoutMs?: number,
  *   runner?: typeof spawnSync,
  *   log?: (m: string) => void,
+ *   files?: string[] | null,
  * }} opts
  * @returns {number}
  */
@@ -308,8 +385,15 @@ export function runCapture({
   timeoutMs,
   runner = spawnSync,
   log = () => {},
+  files = null,
 } = {}) {
-  log('[coverage-capture] ▶ npm run test:coverage');
+  const scopedFiles = Array.isArray(files) && files.length > 0 ? files : null;
+  const args = [
+    'run',
+    'test:coverage',
+    ...(scopedFiles ? ['--', ...scopedFiles] : []),
+  ];
+  log(`[coverage-capture] ▶ npm ${args.join(' ')}`);
   const spawnOpts = {
     cwd,
     stdio: 'inherit',
@@ -323,7 +407,7 @@ export function runCapture({
   ) {
     spawnOpts.timeout = timeoutMs;
   }
-  const res = runner('npm', ['run', 'test:coverage'], spawnOpts);
+  const res = runner('npm', args, spawnOpts);
   // A timeout-induced kill surfaces as `signal: 'SIGKILL'` (or, on some
   // platforms, as a non-numeric status). Either signal indicates the
   // watchdog tripped — surface the GNU `timeout` convention 124 so the

package/.agents/scripts/lib/crap-baseline-index.js

@@ -0,0 +1,46 @@
+/**
+ * crap-baseline-index.js — per-file method-identity indexing over a CRAP
+ * baseline's rows (Story #4981).
+ *
+ * Split out of `crap-engine.js` (rather than added inline) so the join
+ * support lands as a new file, not a same-file expansion of the module the
+ * scoring kernel already lives in. Deliberately dependency-free: both
+ * `crap-engine.js` (which needs `methodIdentityKey` inside
+ * `finalizeMethodRowsWithBaseline`) and `baselines/kinds/crap.js` (which
+ * needs the file-scoped index) import FROM here, and this module imports
+ * from neither — the only shape that keeps the edge one-directional.
+ */
+
+/**
+ * Per-file half of the method-identity key `baselines/kinds/crap.js`'s
+ * `crapRowKey` composes with the file path (`${path}::${method}@${startLine}`).
+ * The path component is redundant once a row set is already narrowed to one
+ * file, which is exactly what `indexBaselineRowsByFile` does below.
+ *
+ * @param {{method: string, startLine: number}} row
+ * @returns {string}
+ */
+export function methodIdentityKey(row) {
+  return `${row.method}@${row.startLine}`;
+}
+
+/**
+ * Index baseline rows (accepts either the `{file, method, startLine, crap}`
+ * legacy shape `compareCrap`/`scanAndScore` use, or the on-disk `{path, ...}`
+ * shape) by file, then by `methodIdentityKey`, for O(1) per-method lookup —
+ * exactly the shape `crap-engine.js#finalizeMethodRowsWithBaseline`'s
+ * `baselineByKey` expects.
+ *
+ * @param {Array<{file?: string, path?: string, method: string, startLine: number, crap: number}>} baselineRows
+ * @returns {Map<string, Map<string, {crap: number}>>} file → (method@startLine → row)
+ */
+export function indexBaselineRowsByFile(baselineRows) {
+  const byFile = new Map();
+  for (const row of baselineRows ?? []) {
+    const file = row?.file ?? row?.path;
+    if (typeof file !== 'string' || file.length === 0) continue;
+    if (!byFile.has(file)) byFile.set(file, new Map());
+    byFile.get(file).set(methodIdentityKey(row), row);
+  }
+  return byFile;
+}

package/.agents/scripts/lib/crap-baseline-join.js

@@ -0,0 +1,153 @@
+/**
+ * crap-baseline-join.js — the incremental-coverage CRAP join (Story #4981).
+ *
+ * Split out of `crap-engine.js` into its own file (rather than added inline)
+ * so the Story's join logic lands as new code, not a same-file expansion of
+ * the pre-existing scoring kernel. Imports its coordinate/formula
+ * primitives from `crap-coordinates.js` (not `crap-engine.js`) and its
+ * identity key from `crap-baseline-index.js` — both leaf modules — so this
+ * file stays a one-directional consumer with no edge back into
+ * `crap-engine.js`.
+ */
+import { methodIdentityKey } from './crap-baseline-index.js';
+import {
+  COORDINATE_ORIGINAL,
+  COORDINATE_TRANSPILED,
+  crapFormula,
+} from './crap-coordinates.js';
+
+/**
+ * Apply the standard `requireCoverage` policy to a single raw method row.
+ * The per-row half of `crap-engine.js#finalizeMethodRows`'s loop body,
+ * extracted (Story #4981) so `finalizeMethodRowsWithBaseline`, below, can
+ * apply the exact same per-row policy to a method whose file was NOT in the
+ * diff scope but whose baseline row could not be found — the fail-closed
+ * path AC-3 requires.
+ *
+ * @param {object} mr A raw row from `methodRowsFromReport`.
+ * @param {{requireCoverage: boolean, coverageAvailable: boolean}} opts
+ * @returns {{ resolved: boolean, row: object | null }} `row: null` means the
+ *   method is skipped-and-counted; `resolved` tracks the join outcome
+ *   (independent of whether the row survives the skip policy).
+ */
+export function resolveRawRow(mr, { requireCoverage, coverageAvailable }) {
+  const unresolved = mr.crap === null || mr.coverage === null;
+  const resolved = !unresolved;
+  // Unjoinable is not untested (Story #4901).
+  if (
+    mr.coordinateSystem === COORDINATE_TRANSPILED ||
+    (unresolved && (requireCoverage || !coverageAvailable))
+  ) {
+    return { resolved, row: null };
+  }
+  const coverage = unresolved ? 0 : mr.coverage;
+  const crap = unresolved ? crapFormula(mr.cyclomatic, 0) : mr.crap;
+  // Everything the scan decided is carried forward; this step overrides only
+  // what its own policy resolves. Spreading rather than re-listing each field
+  // is why the row's identity marker (Story #4969) and its provenance
+  // (Story #4866) survive the step without a line each to remember them —
+  // a hand-rebuilt row is how a marker silently stops reaching the baseline.
+  return {
+    resolved,
+    row: {
+      ...mr,
+      coverage,
+      crap,
+      coordinateSystem: mr.coordinateSystem ?? COORDINATE_ORIGINAL,
+    },
+  };
+}
+
+/**
+ * Incremental-mode join (Story #4981): resolve a file's raw method rows
+ * against its committed CRAP-baseline rows instead of requiring fresh
+ * coverage, for a file the diff did NOT touch.
+ *
+ * Rationale: `coverage-capture`'s incremental mode only runs the consumer's
+ * test suite scoped to the diff, so an untouched file's coverage entry may
+ * legitimately be absent even though nothing about that file's methods
+ * changed. Requiring a fresh join for it would either (a) skip-and-count
+ * every one of its methods under `requireCoverage: true`, weakening the
+ * gate's signal for the vast majority of the tree on every run, or (b) score
+ * them at an invented 0% under `requireCoverage: false`, manufacturing a
+ * maximal CRAP for code the diff never touched. Neither is a measurement.
+ *
+ * The join key is `${method}@${startLine}` — the per-file half of the
+ * composite identity `kinds/crap.js#crapRowKey` uses for the full baseline
+ * compare (`${path}::${method}@${startLine}`); callers pass in a
+ * per-file-scoped `baselineByKey` map so this function stays path-agnostic.
+ *
+ * **Fail-closed (AC-3).** `touched: true` (the file WAS in the diff) or a
+ * missing/empty `baselineByKey` reproduces `crap-engine.js#finalizeMethodRows`
+ * exactly — this is the pre-#4981 per-row policy, so a caller that never
+ * opts in sees byte-identical behaviour (AC-5). For an untouched file, a
+ * method whose baseline row cannot be found (new method, moved line, or a
+ * baseline that simply never carried it) is NOT invented — it falls back to
+ * the same per-row `requireCoverage` skip-and-count policy, via the shared
+ * `resolveRawRow`. A method whose coordinate system is transpiled is never
+ * resolved from the baseline either, for the same un-joinable reason
+ * `resolveRawRow` excludes it (Story #4901).
+ *
+ * @param {Array<object>} rawRows Rows from `methodRowsFromReport`, all for
+ *   the SAME file.
+ * @param {{
+ *   requireCoverage?: boolean,
+ *   coverageAvailable?: boolean,
+ *   touched?: boolean,
+ *   baselineByKey?: Map<string, {crap: number}> | null,
+ * }} [opts]
+ * @returns {{
+ *   rows: Array<object>,
+ *   skippedMethodsNoCoverage: number,
+ *   resolvedMethods: number,
+ *   totalMethods: number,
+ * }}
+ */
+export function finalizeMethodRowsWithBaseline(
+  rawRows,
+  {
+    requireCoverage = true,
+    coverageAvailable = true,
+    touched = true,
+    baselineByKey = null,
+  } = {},
+) {
+  const useBaseline = !touched && baselineByKey && baselineByKey.size > 0;
+  const rows = [];
+  let skippedMethodsNoCoverage = 0;
+  let resolvedMethods = 0;
+  let totalMethods = 0;
+  for (const mr of rawRows ?? []) {
+    totalMethods += 1;
+    if (useBaseline) {
+      const base =
+        mr.coordinateSystem === COORDINATE_TRANSPILED
+          ? undefined
+          : baselineByKey.get(methodIdentityKey(mr));
+      if (base && typeof base.crap === 'number') {
+        resolvedMethods += 1;
+        rows.push({
+          ...mr,
+          coverage: null,
+          crap: base.crap,
+          resolvedFromBaseline: true,
+          coordinateSystem: mr.coordinateSystem ?? COORDINATE_ORIGINAL,
+        });
+        continue;
+      }
+    }
+    // Touched file, no baseline scope, or no baseline row for this method —
+    // fail closed to the standard policy rather than inventing a verdict.
+    const resolution = resolveRawRow(mr, {
+      requireCoverage,
+      coverageAvailable,
+    });
+    if (resolution.resolved) resolvedMethods += 1;
+    if (resolution.row === null) {
+      skippedMethodsNoCoverage += 1;
+      continue;
+    }
+    rows.push(resolution.row);
+  }
+  return { rows, skippedMethodsNoCoverage, resolvedMethods, totalMethods };
+}

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

@@ -0,0 +1,43 @@
+/**
+ * crap-coordinates.js — the CRAP kernel's two line-coordinate-system
+ * constants and the CRAP formula itself.
+ *
+ * Deliberately dependency-free (Story #4981 split, pulled out of
+ * `crap-engine.js`): both `crap-engine.js` and `crap-baseline-join.js`
+ * need these, and having either import them from the other would close a
+ * cycle. `crap-engine.js` re-exports the two constants so its existing
+ * importers (`baselines/kinds/crap.js`, `crap-utils.js`, tests) are
+ * unaffected.
+ */
+
+/**
+ * The two line coordinate systems a CRAP row's `startLine` can be expressed
+ * in (Story #4866).
+ *
+ * `original` — the coordinates of the file a reader can open, and the ones
+ * istanbul's `fnMap` is keyed against. A JavaScript source is already in this
+ * system; a TS/TSX source reaches it only through a successful sourcemap
+ * lookup.
+ *
+ * `transpiled` — escomplex's own coordinates over the emitted JavaScript,
+ * kept only when the sourcemap has no entry originating on the method's
+ * generated line. Such a row is NOT an original-source coordinate and must
+ * never be presented as one: it cannot be joined to coverage, and it cannot
+ * be compared against a baseline row carrying the other provenance.
+ */
+export const COORDINATE_ORIGINAL = 'original';
+export const COORDINATE_TRANSPILED = 'transpiled';
+
+/**
+ * CRAP formula, exported for callers that need to derive target scores or
+ * `fixGuidance` values without re-scoring source.
+ *
+ * @param {number} cyclomatic
+ * @param {number} coverage In [0, 1].
+ * @returns {number}
+ */
+export function crapFormula(cyclomatic, coverage) {
+  const c = Number(cyclomatic) || 0;
+  const cov = Math.max(0, Math.min(1, Number(coverage) || 0));
+  return c * c * (1 - cov) ** 3 + c;
+}