mandrel 2.59.0 → 2.61.0

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

@@ -1,35 +1,26 @@
 /**
- * coverage-capture.js — ensure `coverage/coverage-final.json` is present and
- * fresh before any CRAP gate (close-validation pre-flight, pre-push, CI) reads
- * it. The CRAP scorer treats "no coverage" as "skip the method" under the
- * default `requireCoverage: true` policy, so a missing or stale artifact
- * silently weakens the gate. This helper closes that hole by capturing
- * coverage in-band when it is missing or older than the CRAP-target sources.
- *
- * Pure functions live here; the spawn wiring lives in
- * `.agents/scripts/coverage-capture.js` (CLI). Importers test freshness via
- * `isCoverageFresh` and decide whether to delegate to `runCapture`.
+ * Keep `coverage/coverage-final.json` present and fresh before a CRAP gate
+ * reads it: the scorer skips uncovered methods, so a stale artifact silently
+ * weakens the gate.
  */
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { LOCK_WAIT_EXPIRED_EXIT_CODE } from './full-suite-lock.js';
+import {
+  groupSpawnOptions,
+  superviseGroup,
+  TIMEOUT_EXIT_CODE,
+} from './process-group.js';
 import {
   isScorableSourceFile,
   SCORABLE_SOURCE_EXT_RE,
 } from './source-extensions.js';
 
 /**
- * Walk a directory tree and return the newest mtime (ms since epoch) seen
- * across the scorable source files (`source-extensions.js`) — the same set
- * the CRAP scanner walks, so freshness tracks exactly what the gate scores.
- * Symlinks, missing dirs, and unreadable nodes resolve to 0.
- *
- * A 0 return means "discovery found nothing", which {@link isCoverageFresh}
- * treats as an absence of evidence rather than as freshness — see its
- * `no-sources` contract.
- *
- * Exported for unit testing.
+ * Newest mtime across the scorable sources the CRAP scanner walks; unreadable
+ * nodes are skipped. 0 means "found nothing", never "fresh".
  *
  * @param {string} cwd Absolute repo root.
  * @param {string[]} targetDirs Repo-relative directories to scan.
@@ -74,11 +65,8 @@ export function newestSourceMtime(cwd, targetDirs, io = {}) {
 }
 
 /**
- * Resolve the capture-stamp path that sits next to the coverage artifact.
- * The stamp persists the content digest of the CRAP-target sources at the
- * moment coverage was last captured, so freshness can be decided by content
- * rather than mtime (mtime churns on branch switches / checkouts even when
- * content is unchanged).
+ * The stamp records the sources' content digest at capture time, so freshness
+ * survives mtime churn from checkouts.
  *
  * @param {string} cwd Absolute repo root.
  * @param {string} coveragePath Repo-relative coverage artifact path.
@@ -92,13 +80,8 @@ export function captureStampPath(cwd, coveragePath) {
 }
 
 /**
- * Fold every dirty scorable working-tree file under the scanned dirs into
- * `hash`, and report how many there were.
- *
- * Dirty files are not represented by their index blob SHA, so their on-disk
- * bytes (or absence) go in explicitly. Split out of
- * {@link computeContentDigest} to keep that function's complexity at its
- * committed CRAP floor.
+ * Fold dirty scorable files' on-disk bytes (or absence) into `hash`; their
+ * index blob SHA does not represent them.
  *
  * @param {{
  *   hash: import('node:crypto').Hash,
@@ -127,19 +110,10 @@ function foldDirtySources({ hash, cwd, readFileSync, porcelain }) {
 }
 
 /**
- * Compute a stable content digest of the scorable sources
- * (`source-extensions.js`) under `targetDirs`: the `git ls-files -s` listing (mode + blob SHA + path) of
- * tracked content, plus the on-disk bytes of any dirty working-tree files.
- * Checkout/branch churn leaves blob SHAs untouched, so the digest only moves
- * when content actually changes.
- *
- * Returns `null` when the digest cannot be computed (git unavailable, not a
- * repo, empty target list) so callers can fall back to the mtime heuristic.
- * A target list that matches **no** scorable file is the same "unavailable"
- * case, not a digest over zero files: this path is the primary freshness
- * test, so returning a real hash of empty input would pin the artifact
- * permanently fresh and make the mtime path's fail-closed verdict
- * unreachable (Story #5076).
+ * Digest of the scorable sources under `targetDirs`: `git ls-files -s` of
+ * tracked content plus dirty files' bytes, so it moves only on content change.
+ * `null` means unavailable (no git, no dirs, or zero matching files — a hash
+ * of empty input would pin the artifact permanently fresh).
  *
  * @param {string} cwd Absolute repo root.
  * @param {string[]} targetDirs Repo-relative directories to digest.
@@ -175,9 +149,6 @@ export function computeContentDigest(cwd, targetDirs, io = {}) {
       readFileSync,
       porcelain: git('status', '--porcelain', '--', ...dirs),
     });
-    // Discovery found nothing to digest: hashing the empty input would yield
-    // a constant that can never go stale, so report "unavailable" instead and
-    // let the caller's fail-closed mtime path decide.
     if (tracked.length + scorableDirty === 0) return null;
     return hash.digest('hex');
   } catch {
@@ -186,16 +157,9 @@ export function computeContentDigest(cwd, targetDirs, io = {}) {
 }
 
 /**
- * Persist the capture stamp next to the coverage artifact. Best-effort: a
- * 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).
+ * Best-effort: a write failure returns `false` (next check falls back to
+ * mtime). Full-scope callers omit `scope`, keeping the `{ digest, capturedAt }`
+ * shape.
  *
  * @param {{
  *   cwd: string,
@@ -234,16 +198,10 @@ 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.
+ *   falls through to the mtime heuristic.
  */
 function readStampForScope(stamp, requireScope) {
   if (typeof stamp?.digest !== 'string' || stamp.digest.length === 0) {
@@ -257,33 +215,11 @@ function readStampForScope(stamp, requireScope) {
 }
 
 /**
- * Decide whether the existing coverage artifact is "fresh".
- *
- * Primary test (content-aware, Story #3982): when a capture stamp exists
- * next to the artifact, compare its persisted digest against the current
- * content digest of `targetDirs`. Equal digests → fresh; different → stale.
- * Branch switches and checkouts that bump mtimes without changing content
- * no longer invalidate coverage.
- *
- * Fallback (stamp absent / unreadable / digest unavailable): the original
- * mtime heuristic — artifact at least as new as the newest source file
- * under `targetDirs`. Missing files, missing target dirs, or any IO error
- * resolve to `false` so the caller captures rather than trusting stale data.
- *
- * **Both paths fail closed on an empty source set (Story #5076).** Finding no
- * scorable source under `targetDirs` means the check learned nothing, so it
- * reports `{ fresh: false, reason: 'no-sources' }` and the caller captures.
- * The alternative — treating "found nothing" as "nothing changed" — is how a
- * `js|mjs`-only selector left the CRAP gate green while measuring nothing in
- * every TypeScript consumer.
- *
- * **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.
+ * Stamp digest vs current digest when a stamp exists; otherwise artifact
+ * mtime vs newest source. IO errors resolve stale. Both paths fail closed
+ * (`no-sources`) on an empty source set — "found nothing" is not "nothing
+ * changed". An incremental stamp never satisfies a full-scope probe; a stamp
+ * with no `scope` is full-scope.
  *
  * @param {{
  *   coveragePath: string,
@@ -345,9 +281,6 @@ export function isCoverageFresh({
     statSync,
     readdirSync,
   });
-  // Source discovery found nothing. That is an absence of evidence, never a
-  // freshness guarantee — trusting it silently disables the capture (and with
-  // it the CRAP gate) for any tree the walk cannot see (Story #5076).
   if (newestSrc === 0) return { fresh: false, reason: 'no-sources' };
   return coverageMtime >= newestSrc
     ? { fresh: true, reason: 'fresh' }
@@ -355,14 +288,8 @@ export function isCoverageFresh({
 }
 
 /**
- * Render a freshness verdict for the operator-facing capture log.
- *
- * Every reason but `no-sources` speaks for itself. That one does not: failing
- * closed on an empty source walk is correct, but bare it reads as an
- * unexplained full capture on every run, and the cause is far more often a
- * `targetDirs` that does not name the project's sources than a genuine
- * recapture — so the walked dirs and the key to fix are named inline
- * (Story #5076).
+ * `no-sources` usually means a misconfigured `targetDirs`, so it names the
+ * walked dirs and the key to fix.
  *
  * @param {{ reason?: string }} freshness Verdict from {@link isCoverageFresh}.
  * @param {string[]} targetDirs The CRAP scan scope that was walked.
@@ -375,37 +302,19 @@ export function describeFreshness(freshness, targetDirs) {
   return `${reason} — no scorable source file found under [${dirs}]; if that does not name this project's sources, fix quality.gates.crap.targetDirs`;
 }
 
-/**
- * The invocation that deposits capture credit for a Story branch. Named in
- * the uncredited-capture announcement so a reader of a close log sees the
- * command that would have avoided the cost, not just the cost.
- */
 const CREDITING_INVOCATION =
   'node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>';
 
 /**
- * Announce — and, when the consumer requires credit, refuse — a full-suite
- * capture that no committed stamp covers.
- *
- * Every caller invokes this immediately before it would spawn the suite, and
- * the ordering is the whole point. The capture itself is the most expensive
- * thing a close does; discovering that it ran uncredited is only actionable
- * while it is still ahead of you, not once it is visible as a `durationMs`
- * in `validation-evidence.json` twelve minutes later.
- *
- * The probe is read-only by construction: every caller has already decided
- * to capture by the time it runs, and it writes nothing — so it never takes
- * the full-suite host lock and can never itself be the reason a close waits.
+ * Announce (or, under `--require-credited`, refuse) an uncredited full-suite
+ * capture — before the spawn, while it is still actionable. Read-only, so it
+ * never takes the host lock.
  *
  * @param {{
  *   requireCredited?: boolean,
  *   logger: { info: Function, warn: Function, error: Function },
- * }} opts `requireCredited` comes from the CLI's `--require-credited`
- *   argument, which the close gate passes when
- *   `delivery.execution.requireCreditedCapture` is set (default false →
- *   announce and run). Story #5278: it is deliberately NOT read from config
- *   here — that made the refusal cover the depositing invocation too, leaving
- *   no way to earn the credit it demanded.
+ * }} opts `requireCredited` is a per-invocation CLI opt-in, never config:
+ *   from config it would also refuse the invocation that deposits credit.
  * @returns {number | null} A non-zero exit code the caller MUST return
  *   without spawning the suite, or `null` to proceed with the capture.
  */
@@ -424,48 +333,25 @@ function announceUncreditedCapture({ requireCredited = false, logger }) {
 }
 
 /**
- * Compose the uncredited-capture probe over a capture runner, so the
- * announcement is structurally inseparable from the spawn it describes.
- *
- * This mirrors `lockedCapture`, and for the same reason: there are two
- * capture paths (full-scope and incremental) and neither should have to
- * remember the policy. Wrapping the runner they share means a third path
- * added later inherits the probe for free, and that the warning can never be
- * emitted for a capture that does not happen — or omitted for one that does.
+ * Wrap a capture runner so the announcement is inseparable from the spawn.
+ * Composes outside `lockedCapture`, so a refusal never acquires the lock.
  *
- * It composes OUTSIDE `lockedCapture`, so a refusal costs nothing: the host
- * lock is never acquired for a run that is about to be declined.
- *
- * @param {(opts: object) => number} runCaptureFn The (possibly already
- *   lock-wrapped) capture runner.
+ * @param {(opts: object) => Promise<number>|number} runCaptureFn
  * @param {{ requireCredited?: boolean, logger: object }} policy
- * @returns {(opts?: object) => number} A runner returning the capture's exit
- *   code, or a non-zero refusal code without having spawned anything.
+ * @returns {(opts?: object) => Promise<number>} Exit code, or a refusal code
+ *   without spawning.
  */
 export function creditedCapture(runCaptureFn, { requireCredited, logger }) {
-  return (captureOpts = {}) => {
+  return async (captureOpts = {}) => {
     const refusal = announceUncreditedCapture({ requireCredited, logger });
-    return refusal === null ? runCaptureFn(captureOpts) : refusal;
+    return refusal === null ? await runCaptureFn(captureOpts) : refusal;
   };
 }
 
 /**
- * Write the capture stamp for a run that has just finished — but only when
- * the tree it measured is still the tree on disk (Story #5278).
- *
- * The stamp is a claim about content: "coverage/coverage-final.json reflects
- * sources digesting to X". Computing X *after* the suite finishes makes that
- * claim false whenever anything moved while the suite ran — a sibling
- * worktree's write, a rebase, an editor save minutes into a ten-minute run.
- * The digest taken **before** the spawn is the one the run actually measured,
- * so that is the value written, and a post-run digest that disagrees means
- * the artifact describes a tree nobody has any more: no stamp is written at
- * all, and the next reader captures rather than crediting a run against
- * sources it never saw.
- *
- * A `null` on either digest is "unavailable", not "changed" — the same
- * fail-open the pre-#5278 code had, since without a digest there is nothing
- * to stamp.
+ * Stamp the pre-spawn digest (the tree the run measured), and write nothing
+ * when the post-run digest differs — the artifact then describes a tree no
+ * longer on disk. A `null` post-digest is "unavailable", not "changed".
  *
  * @param {{
  *   preDigest: string|null,
@@ -520,12 +406,7 @@ export function stampCapturedTree({
 }
 
 /**
- * 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.
+ * Changed files under a `targetDirs` prefix, forward-slash-normalised.
  *
  * @param {string[]} changedFiles
  * @param {string[]} targetDirs
@@ -543,11 +424,7 @@ export function filterFilesUnderTargets(changedFiles, targetDirs) {
 }
 
 /**
- * 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.
- *
- * An empty changed-file list returns `false`.
+ * Pre-push fast path: skip capture when nothing in CRAP scope changed.
  *
  * @param {string[]} changedFiles
  * @param {string[]} targetDirs
@@ -557,75 +434,73 @@ export function anyChangedUnderTargets(changedFiles, targetDirs) {
   return filterFilesUnderTargets(changedFiles, targetDirs).length > 0;
 }
 
-/**
- * Exit code surfaced when the bounded `npm run test:coverage` spawn was
- * killed by the timeout watchdog. Matches the GNU `timeout(1)` convention so
- * the close-validation caller can branch on "hang" (124) vs. "tests failed"
- * (any other non-zero status). Story #2136 / Task #2142.
- */
-export const COVERAGE_TIMEOUT_EXIT_CODE = 124;
+/** GNU `timeout(1)` code, so callers tell a hang (124) from failing tests. */
+export const COVERAGE_TIMEOUT_EXIT_CODE = TIMEOUT_EXIT_CODE;
 
 /**
- * Spawn `npm run test:coverage` in `cwd` with a bounded wall clock. Inherits
- * stdio so the operator sees the raw test output. Returns the exit status; a
- * non-zero exit means the caller should propagate the failure (a broken test
- * suite cannot be papered over by the CRAP gate).
- *
- * The `timeoutMs` budget is enforced by `spawnSync` with `killSignal:
- * 'SIGKILL'` — Node fires the signal at the budget boundary and the result
- * surfaces with `signal: 'SIGKILL'`. We translate that into the GNU
- * `timeout(1)` convention exit code 124 so callers can pattern-match a
- * runaway runner without inspecting signal names.
- *
- * The spawn takes **no positional file arguments**. Story #4981 forwarded the
- * changed-file list as `npm run test:coverage -- <files...>` on the premise
- * that a test runner treats trailing positionals as filters over the suite.
- * Node's runner does not: it treats each path as a test file to execute, so a
- * forwarded *source* file runs as a trivially-passing test and the real suite
- * never runs. `run-coverage.js` discarded the list, which is the only reason
- * that never bit; Story #5063 measured it and Story #5065 removed the
- * plumbing rather than leave a parameter whose obvious "fix" empties the
- * coverage artifact.
+ * Spawn `npm run test:coverage` asynchronously as its own process group, so
+ * the lock heartbeat keeps running and a timeout or signal kills every
+ * worker. Takes no positional file args: node's runner would execute a
+ * forwarded source file as a test instead of filtering the suite.
  *
  * @param {{
  *   cwd: string,
  *   timeoutMs?: number,
- *   runner?: typeof spawnSync,
+ *   spawnImpl?: typeof spawn,
  *   log?: (m: string) => void,
  * }} opts
- * @returns {number}
+ * @returns {Promise<number>}
  */
 export function runCapture({
   cwd,
   timeoutMs,
-  runner = spawnSync,
+  spawnImpl = spawn,
   log = () => {},
 } = {}) {
   const args = ['run', 'test:coverage'];
   log(`[coverage-capture] ▶ npm ${args.join(' ')}`);
-  const spawnOpts = {
-    cwd,
-    stdio: 'inherit',
-    shell: process.platform === 'win32',
-    killSignal: 'SIGKILL',
-  };
-  if (
-    typeof timeoutMs === 'number' &&
-    Number.isFinite(timeoutMs) &&
-    timeoutMs > 0
-  ) {
-    spawnOpts.timeout = timeoutMs;
-  }
-  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
-  // caller can distinguish a hang from a normal test-suite failure.
-  if (res?.signal === 'SIGKILL') {
-    log(
-      `[coverage-capture] ⏱ npm run test:coverage exceeded ${timeoutMs}ms — killed (SIGKILL). Returning exit ${COVERAGE_TIMEOUT_EXIT_CODE}.`,
+  return new Promise((resolve) => {
+    const child = spawnImpl('npm', args, {
+      cwd,
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+      ...groupSpawnOptions(),
+    });
+    const supervisor = superviseGroup(child, { timeoutMs });
+    child.on('error', () => {
+      supervisor.release();
+      resolve(1);
+    });
+    child.on('exit', (code) => {
+      supervisor.release();
+      if (!supervisor.timedOut) {
+        resolve(code ?? 1);
+        return;
+      }
+      log(
+        `[coverage-capture] ⏱ npm run test:coverage exceeded ${timeoutMs}ms — killed its process group. Returning exit ${COVERAGE_TIMEOUT_EXIT_CODE}.`,
+      );
+      resolve(COVERAGE_TIMEOUT_EXIT_CODE);
+    });
+  });
+}
+
+/**
+ * Report a non-zero capture; an expired lock wait is not a failing suite.
+ *
+ * @param {number} code
+ * @param {{ info: Function, error: Function }} logger
+ * @returns {number}
+ */
+export function reportCaptureFailure(code, logger) {
+  if (code === LOCK_WAIT_EXPIRED_EXIT_CODE) {
+    logger.info(
+      `[coverage-capture] ⏸ the full-suite lock wait expired and this capture was deferred — no suite ran. Exiting ${code}.`,
     );
-    return COVERAGE_TIMEOUT_EXIT_CODE;
+    return code;
   }
-  return res.status ?? 1;
+  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;
 }

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

@@ -4,12 +4,7 @@ const COVERAGE_INDEX = Symbol('coverage-utils.coverage-index');
 const ENTRY_INDEX = Symbol('coverage-utils.entry-index');
 
 /**
- * Load and parse an istanbul/c8 `coverage-final.json` artifact.
- *
- * Returns the parsed object (keyed by absolute file path) on success, or
- * `null` when the file is missing, unreadable, non-JSON, or structurally
- * unusable. Never throws — consumers treat a null map as "no coverage
- * available" and apply their own `requireCoverage` policy.
+ * Never throws; `null` for any missing or unusable artifact.
  *
  * @param {string} coveragePath
  * @returns {object|null}
@@ -37,12 +32,7 @@ function stripLeadingDotSlash(p) {
 }
 
 /**
- * Build a single-pass index over a parsed `coverage-final.json` map.
- *
- * Returns `{map, byNormalizedSuffix}` where `byNormalizedSuffix` is a
- * `Map<string, object>` keyed by the POSIX-normalized form of each original
- * key. Lookups that need exact-equality or `/`-bounded suffix matching
- * consult that Map without re-enumerating `Object.keys(map)` on every call.
+ * Entries keyed by POSIX-normalized path.
  *
  * @param {object|null} map
  * @returns {{map: object|null, byNormalizedSuffix: Map<string, object>}}
@@ -72,15 +62,8 @@ function getCoverageIndex(map) {
 }
 
 /**
- * Locate the coverage entry for a repo-relative path.
- *
- * `coverage-final.json` keys are typically absolute, platform-specific paths,
- * while callers pass POSIX-ish repo-relative strings. Match by exact equality
- * or by `/`-bounded suffix so we tolerate both Windows and POSIX producers.
- * If two distinct keys both end with the same `/`-bounded suffix (duplicate
- * basenames in different trees), the suffix is ambiguous — return null
- * rather than picking the first iteration-order hit and silently scoring
- * the wrong file.
+ * Match a repo-relative path to an absolute key by exact or `/`-bounded
+ * suffix. An ambiguous suffix returns null rather than scoring the wrong file.
  */
 function findFileEntry(map, relPath) {
   if (!map || !relPath) return null;
@@ -103,8 +86,6 @@ function findFileEntry(map, relPath) {
 export { findFileEntry as findCoverageEntry };
 
 /**
- * Does the map contain any entry whose path matches `relPath`?
- *
  * @param {object|null} map
  * @param {string} relPath
  * @returns {boolean}
@@ -114,17 +95,8 @@ export function hasCoverageFor(map, relPath) {
 }
 
 /**
- * Build a per-entry index that turns method-coverage lookups from
- * `O(fnCount + statementCount)` per call into `O(method-line-span)`.
- *
- * - `fnByStartLine`: maps either `decl.start.line` or `loc.start.line` to the
- *   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.
+ * Per-entry index making a method lookup `O(method-line-span)`. Functions are
+ * keyed by both `decl` and `loc` start lines (producers differ).
  *
  * @param {object|null} entry One inner value from a `coverage-final.json` map.
  */
@@ -181,36 +153,15 @@ export function buildEntryIndex(entry) {
 }
 
 /**
- * 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.
+ * escomplex and istanbul can disagree by one line on a function's start
+ * (decorator, leading `export`, multi-line params); wider would claim a
+ * neighbour.
  */
 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."
+ * Exact start line, else innermost containing range, else nearest `decl`
+ * within `DECL_MATCH_WINDOW`; `null` means "no data", not "untested".
  *
  * @param {{fnByStartLine: Map, fnLocByStartLine: Map, fnRanges: Array}} idx
  * @param {number} startLine
@@ -264,23 +215,9 @@ function getEntryIndex(entry) {
 }
 
 /**
- * Compute the statement-coverage ratio for a single method inside a single
- * file's coverage entry.
- *
- * The ratio is the fraction of statements whose `start.line` falls within the
- * function's `loc` range that were executed at least once. An empty range
- * 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.
+ * Executed fraction of statements in the method's range (0 for an empty
+ * range, `null` for no data). `startLine` MUST be in original-source
+ * coordinates. The entry index is cached on the entry.
  *
  * @param {object|null} entry One inner value from a `coverage-final.json` map.
  * @param {number} startLine The method's start line, in entry coordinates.
@@ -307,8 +244,6 @@ export function coverageForMethodInEntry(entry, startLine) {
 }
 
 /**
- * Look up per-method coverage in a full coverage map.
- *
  * @param {object|null} map Parsed `coverage-final.json`.
  * @param {string} relPath Repo-relative path of the source file.
  * @param {number} startLine The method's start line, in entry coordinates.