mandrel 2.16.0 → 2.17.0

package/.agents/scripts/lib/close-validation/projections/crap.js

@@ -0,0 +1,303 @@
+// .agents/scripts/lib/close-validation/projections/crap.js
+/**
+ * crap.js — pre-merge CRAP ceiling projection helper (Story #4776).
+ *
+ * The CRAP analogue of `projections/maintainability.js`. Both answer the
+ * same operator question before the merge runs: *given what this branch
+ * changed, which committed baseline rows would the post-merge tree breach,
+ * and what is the exact remedy?*
+ *
+ * Advisory only. `check-baselines` already fails close-validation closed on
+ * a real regression; duplicating that here would double-gate the same
+ * defect. What this projection adds is the **refresh** half of the loop —
+ * naming the breaching methods and the `npm run crap:update` +
+ * `baseline-refresh:` remedy while the operator still has the branch in
+ * hand, so a corrected baseline does not rot back into staleness.
+ *
+ * The helper never throws and never mutates anything. Every failure path
+ * resolves to `{ ok: true, breaches: [], skipped: '<reason>' }` so the
+ * caller can treat the advisory as best-effort.
+ *
+ * Post-merge approximation: CRAP needs a coverage join, so — unlike the MI
+ * projection, which scores a `git show` blob — the scorer reads the working
+ * tree. Close-validation runs inside the Story worktree at the branch tip,
+ * which is exactly the content a squash-merge lands, so the approximation is
+ * exact whenever the merge applies cleanly.
+ */
+
+import path from 'node:path';
+import {
+  compareCrap,
+  filterRowsByFileScope,
+} from '../../baselines/kinds/crap.js';
+import { loadFile as loadBaselineFile } from '../../baselines/reader.js';
+import { diffNameOnly } from '../../changed-files.js';
+import { loadCoverage } from '../../coverage-utils.js';
+import { scanAndScore } from '../../crap-utils.js';
+import { cachedGitFetchSync } from '../../git/cached-fetch.js';
+import { gitSpawn as defaultGitSpawn } from '../../git-utils.js';
+import { MISSING_ARG_REASONS, validateProjectionInputs } from './inputs.js';
+
+/**
+ * Default absolute tolerance on a projected CRAP score, shared with
+ * `check-crap`'s regression arm: floating-point noise must not register as
+ * a breach.
+ */
+export const DEFAULT_CRAP_TOLERANCE = 0.001;
+
+/** Framework default for the new-method ceiling (`gates.crap.newMethodCeiling`). */
+export const DEFAULT_NEW_METHOD_CEILING = 30;
+
+/** Extensions the CRAP scanner can score. */
+const SCORABLE = /\.(?:js|mjs|cjs|ts|tsx)$/;
+
+/**
+ * Map the shared predicate's fine-grained `missing-*` reason onto the
+ * `missing-args` skipped-reason the sibling MI projection reports, so both
+ * projections speak one vocabulary at the advisory boundary.
+ *
+ * @param {string} reason
+ * @returns {string}
+ */
+function normaliseSkipReason(reason) {
+  return MISSING_ARG_REASONS.has(reason) ? 'missing-args' : reason;
+}
+
+/**
+ * Read the committed CRAP baseline and re-key its rows onto the `file`
+ * field `compareCrap` matches on (the on-disk v2 envelope keys on `path`).
+ * Returns `[]` when the baseline is absent or unreadable — the caller maps
+ * that to the `no-baseline` skip.
+ *
+ * Deliberately module-local: `projectCrapBreaches`'s `loadBaseline` default
+ * is the single production door to it, and tests inject their own loader.
+ * Exporting it would add a second entry point nothing in production reaches
+ * — which is precisely the orphaning this Story exists to stop.
+ *
+ * @param {string} baselinePath absolute path to `baselines/crap.json`
+ * @returns {Array<{file: string, method: string, startLine: number, crap: number}>}
+ */
+function loadCrapBaselineRows(baselinePath) {
+  let envelope;
+  try {
+    envelope = loadBaselineFile(baselinePath, { kind: 'crap' });
+  } catch {
+    return [];
+  }
+  const rows = Array.isArray(envelope?.rows) ? envelope.rows : [];
+  return rows.map((row) => ({
+    file: row.path,
+    method: row.method,
+    startLine: row.startLine,
+    crap: row.crap,
+  }));
+}
+
+/**
+ * Build the default working-tree CRAP scorer. Returns an async callable
+ * `(files) => rows | null`; `null` signals "coverage artifact missing under
+ * `requireCoverage`", which the projection reports as the `no-coverage`
+ * skip rather than as a clean run.
+ *
+ * @param {{
+ *   cwd: string,
+ *   targetDirs?: string[],
+ *   ignoreGlobs?: string[],
+ *   requireCoverage?: boolean,
+ *   coveragePath?: string,
+ * }} opts
+ * @returns {(files: string[]) => Promise<Array<object>|null>}
+ */
+export function createCrapScorer({
+  cwd,
+  targetDirs = [],
+  ignoreGlobs = [],
+  requireCoverage = true,
+  coveragePath = 'coverage/coverage-final.json',
+} = {}) {
+  return async (files) => {
+    const abs = path.isAbsolute(coveragePath)
+      ? coveragePath
+      : path.resolve(cwd, coveragePath);
+    const coverage = loadCoverage(abs);
+    if (!coverage && requireCoverage) return null;
+    const { rows } = await scanAndScore({
+      targetDirs,
+      coverage,
+      requireCoverage,
+      cwd,
+      ignoreGlobs,
+      scopeFiles: files,
+    });
+    return rows ?? [];
+  };
+}
+
+/**
+ * Refresh `origin/<baseBranch>` so the diff range resolves even when close
+ * has not reached its own base-sync step. Routed through the shared fetch
+ * cache so a story-init fetch in the same run satisfies it for free.
+ *
+ * @param {string} cwd
+ * @param {string} baseBranch
+ * @param {{ gitSpawn: typeof defaultGitSpawn }} git
+ * @returns {{ ok: true } | { ok: false, detail: string }}
+ */
+function refreshBaseRef(cwd, baseBranch, git) {
+  const res = cachedGitFetchSync(cwd, baseBranch, { gitSpawn: git.gitSpawn });
+  if (res.status !== 0) {
+    return {
+      ok: false,
+      detail: res.stderr || res.stdout || `exit ${res.status}`,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Enumerate the Story branch's changed files, narrowed to the extensions
+ * the CRAP scanner can score.
+ *
+ * @param {{ cwd: string, baseBranch: string, storyBranch: string, git: { gitSpawn: typeof defaultGitSpawn } }} opts
+ * @returns {{ ok: true, files: string[] } | { ok: false, detail: string }}
+ */
+function diffScorableFiles({ cwd, baseBranch, storyBranch, git }) {
+  try {
+    const files = diffNameOnly({
+      range: `origin/${baseBranch}...${storyBranch}`,
+      cwd,
+      gitSpawn: git.gitSpawn,
+    });
+    return { ok: true, files: files.filter((f) => SCORABLE.test(f)) };
+  } catch (err) {
+    return { ok: false, detail: err.message };
+  }
+}
+
+/**
+ * Project the post-merge CRAP scores for every file changed on the Story
+ * branch and return the subset of methods that would breach either their
+ * committed baseline row or, for methods with no baseline row, the
+ * configured `newMethodCeiling`.
+ *
+ * Baseline rows are narrowed to the changed-file set before the compare so
+ * every untouched file's rows are not spuriously reported as removed.
+ *
+ * @param {{
+ *   cwd: string,
+ *   baseBranch: string,
+ *   storyBranch: string,
+ *   baselinePath: string,
+ *   newMethodCeiling?: number,
+ *   tolerance?: number,
+ *   git?: { gitSpawn: typeof defaultGitSpawn },
+ *   loadBaseline?: (path: string) => Array<object>,
+ *   scoreFiles?: (files: string[]) => Promise<Array<object>|null>|Array<object>|null,
+ * }} opts
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   breaches: Array<object>,
+ *   skipped?: string,
+ *   detail?: string,
+ * }>}
+ */
+export async function projectCrapBreaches({
+  cwd,
+  baseBranch,
+  storyBranch,
+  baselinePath,
+  newMethodCeiling = DEFAULT_NEW_METHOD_CEILING,
+  tolerance = DEFAULT_CRAP_TOLERANCE,
+  git = { gitSpawn: defaultGitSpawn },
+  loadBaseline = loadCrapBaselineRows,
+  scoreFiles,
+} = {}) {
+  const skip = (reason, detail) => ({
+    ok: true,
+    breaches: [],
+    skipped: reason,
+    ...(detail === undefined ? {} : { detail }),
+  });
+
+  const validation = validateProjectionInputs({
+    cwd,
+    baseBranch,
+    storyBranch,
+    baselinePath,
+  });
+  if (!validation.ok) return skip(normaliseSkipReason(validation.reason));
+
+  const baselineRows = loadBaseline(baselinePath);
+  if (!Array.isArray(baselineRows) || baselineRows.length === 0) {
+    return skip('no-baseline');
+  }
+
+  const fetched = refreshBaseRef(cwd, baseBranch, git);
+  if (!fetched.ok) return skip('fetch-failed', fetched.detail);
+
+  const diffed = diffScorableFiles({ cwd, baseBranch, storyBranch, git });
+  if (!diffed.ok) return skip('diff-failed', diffed.detail);
+  if (diffed.files.length === 0) return skip('no-scorable-files');
+
+  const scorer =
+    typeof scoreFiles === 'function' ? scoreFiles : createCrapScorer({ cwd });
+  let currentRows;
+  try {
+    currentRows = await scorer(diffed.files);
+  } catch (err) {
+    return skip('score-failed', err?.message ?? String(err));
+  }
+  if (currentRows === null || currentRows === undefined) {
+    return skip('no-coverage');
+  }
+  if (currentRows.length === 0) return skip('no-scored-methods');
+
+  const scopeSet = new Set(diffed.files);
+  const result = compareCrap({
+    currentRows,
+    baselineRows: filterRowsByFileScope(baselineRows, scopeSet),
+    newMethodCeiling,
+    tolerance,
+  });
+  const breaches = result.violations ?? [];
+  return { ok: breaches.length === 0, breaches };
+}
+
+/**
+ * Render one breach as an advisory bullet. New-method breaches name the
+ * ceiling they cleared; regressions name the baseline row they exceeded.
+ *
+ * @param {object} b
+ * @returns {string}
+ */
+function formatBreach(b) {
+  const where = `${b.file}::${b.method} (line ${b.startLine})`;
+  const projected = Number(b.crap ?? 0).toFixed(2);
+  if (b.kind === 'new') {
+    return `  • ${where}  projected=${projected}  ceiling=${b.ceiling}  [new method]`;
+  }
+  const baseline = Number(b.baseline ?? 0).toFixed(2);
+  return `  • ${where}  projected=${projected}  baseline=${baseline}  [${b.kind}]`;
+}
+
+/**
+ * Render the pre-merge CRAP advisory as a human-readable multi-line log
+ * block, naming every breaching method and the exact refresh remedy.
+ * Returns `null` when there is nothing to surface so callers can `if` past
+ * the log call without a string-empty check.
+ *
+ * @param {Awaited<ReturnType<typeof projectCrapBreaches>>} result
+ * @returns {string | null}
+ */
+export function formatCrapProjection(result) {
+  if (!result || !Array.isArray(result.breaches)) return null;
+  if (result.breaches.length === 0) return null;
+  const lines = [
+    `[close-validation] ⚠ Pre-merge CRAP projection: ${result.breaches.length} method(s) would breach post-merge:`,
+  ];
+  for (const b of result.breaches) lines.push(formatBreach(b));
+  lines.push(
+    '[close-validation]   To land cleanly, run `npm run crap:update` and commit the refreshed baseline with a `baseline-refresh:` tagged subject (non-empty body) on the story branch before re-running close.',
+  );
+  return lines.join('\n');
+}

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/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.
  */