mandrel 2.60.0 → 2.62.0

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

@@ -1,20 +1,6 @@
 /**
- * Pure helpers for the per-file coverage baseline gate.
- *
- * The gate replaces c8's global `lines/branches/functions` thresholds
- * with per-file floors recorded in `baselines/coverage.json`, mirroring
- * how `baselines/maintainability.json` tracks per-file MI scores.
- *
- * Scoring inputs:
- *   - `coverage/coverage-final.json` written by `c8 report` (every file
- *     c8 instrumented during the run, regardless of include/exclude).
- *   - `.c8rc.cjs` `include` / `exclude` globs — applied here so the
- *     baseline only records the same scope `c8 report --include=…` prints.
- *
- * Imported by `update-coverage-baseline.js` (writes the baseline) and
- * `check-coverage-baseline.js` (compares current → baseline). Kept pure
- * so the regression-comparison logic is unit-testable without spawning
- * the full coverage pipeline.
+ * Per-file coverage floors in `baselines/coverage.json`, scoped by the c8
+ * `include`/`exclude` globs (coverage-final.json holds every instrumented file).
  */
 
 import fs from 'node:fs';
@@ -24,26 +10,17 @@ import { write, writeFile } from './baselines/writer.js';
 
 const COVERAGE_FINAL_PATH = 'coverage/coverage-final.json';
 export const COVERAGE_BASELINE_PATH = 'baselines/coverage.json';
-// Absolute floating-point tolerance (percentage points). Values in the
-// baseline are stored to two decimals, so anything below 0.01 is noise.
+// Percentage points; baselines store two decimals.
 export const COVERAGE_TOLERANCE = 0.01;
-// Noise headroom (in instrumentation events) granted to small-denominator
-// files. A file with N branches has a per-event resolution of 100/N% — one
-// branch flipping covered↔uncovered between runs is the natural noise floor
-// under non-deterministic Windows/Node 22 V8 instrumentation. We absorb up
-// to one event of slack per axis. Anything beyond one event is real signal.
+// One instrumentation event of slack per axis: V8 coverage flaps by a single
+// event between runs (notably Windows/Node 22).
 const NOISE_EVENT_HEADROOM = 1.0;
 
 function toForwardSlash(p) {
   return p.replace(/\\/g, '/');
 }
 
-/**
- * Build a (file → bool) predicate from c8 `include` / `exclude` glob
- * arrays. Mirrors c8's own scope rule: a file is in scope when at least
- * one `include` matches AND no `exclude` matches. Uses picomatch with
- * c8's defaults (`dot: true` so dotfiles like `.agents/...` match).
- */
+/** c8's scope rule: some `include` matches and no `exclude` does. */
 export function buildScopePredicate({ include = [], exclude = [] } = {}) {
   const inc =
     include.length === 0 ? () => true : picomatch(include, { dot: true });
@@ -56,17 +33,8 @@ export function buildScopePredicate({ include = [], exclude = [] } = {}) {
 }
 
 /**
- * Given one entry from `coverage-final.json` (the per-file istanbul
- * record), compute `{ lines, branches, functions }` percentages.
- *
- * Definitions match what `c8 check-coverage` enforces:
- *   - lines:     covered statements   / total statements
- *   - branches:  covered branch arms  / total branch arms (b is a map of arrays)
- *   - functions: covered functions    / total functions
- *
- * Returns `null` for any axis that has no denominators (a file with
- * zero functions has no defined function-coverage). The caller should
- * treat `null` axes as a no-op when comparing.
+ * Percentages as `c8 check-coverage` defines them; an axis with no
+ * denominator is `null` (a no-op when comparing).
  */
 export function scoreEntry(entry) {
   const sMap = entry?.s ?? {};
@@ -103,13 +71,7 @@ export function scoreEntry(entry) {
   };
 }
 
-/**
- * Convert the raw `coverage-final.json` payload into a `{ relPath →
- * {lines, branches, functions} }` map, dropping any entry that fails
- * the c8 scope predicate. `cwd` is the repo root; entry keys in
- * coverage-final.json are absolute paths and need relativising to
- * match the baseline file's stable, repo-relative keys.
- */
+/** In-scope entries keyed by repo-relative path (raw keys are absolute). */
 export function scoreCoverageFinal({ raw, cwd, scope }) {
   const inScope = scope ?? buildScopePredicate({});
   const out = {};
@@ -121,17 +83,7 @@ export function scoreCoverageFinal({ raw, cwd, scope }) {
   return out;
 }
 
-/**
- * Read + parse `coverage-final.json`. Throws a helpful error when the
- * file is missing — that's the operator-facing signal that they need
- * to run `npm run test:coverage` first.
- *
- * Story #1737: the per-file gate now reads `coveragePath` from
- * `delivery.quality.gates.coverage` instead of the hardcoded
- * `coverage/coverage-final.json`. Callers pass the resolved path via
- * `opts.coveragePath`; the legacy default is preserved for tests that
- * still spin up a tmp tree without a config.
- */
+/** Throws, naming the capture command, when the artifact is missing. */
 export function readCoverageFinal(cwd, opts = {}, fsImpl) {
   const resolvedFs = fsImpl ?? fs;
   const coveragePath =
@@ -149,12 +101,6 @@ export function readCoverageFinal(cwd, opts = {}, fsImpl) {
   return JSON.parse(resolvedFs.readFileSync(abs, 'utf8'));
 }
 
-/**
- * Read the baseline. Returns `null` (not `{}`) when the file is
- * missing so the checker can distinguish "no baseline yet" (warn +
- * pass) from "baseline exists but is empty" (treat every in-scope
- * file as new = fail).
- */
 function isEnvelopeShape(parsed) {
   return (
     parsed &&
@@ -179,15 +125,14 @@ function projectEnvelopeToFlat(envelope) {
 }
 
 function normaliseParsedBaseline(parsed) {
-  // Story #1891: the writer ships envelope-shape baselines
-  // (`$schema`, `kernelVersion`, `generatedAt`, `rollup`, `rows`). The
-  // legacy reader contract returns a flat `{ file: { lines, branches,
-  // functions } }` map, so we project rows back to that shape for
-  // backwards-compatible consumers (Story #1892 migrates them off the
-  // flat shape).
+  // Readers expect the flat `{ file: scores }` map, not the envelope.
   return isEnvelopeShape(parsed) ? projectEnvelopeToFlat(parsed) : parsed;
 }
 
+/**
+ * `null` (not `{}`) when missing: "no baseline yet" passes with a warning,
+ * while an empty baseline fails every in-scope file as new.
+ */
 export function readBaseline(cwd, fsImpl = fs) {
   const abs = path.resolve(cwd, COVERAGE_BASELINE_PATH);
   if (!fsImpl.existsSync(abs)) return null;
@@ -219,15 +164,12 @@ function writeEnvelopeViaFsImpl(abs, envelope, fsImpl) {
 }
 
 function dispatchEnvelopeWrite(abs, envelope, fsImpl) {
-  // Honour the injected fsImpl seam for tests that pass `memfs` or a spy —
-  // fall through to the writer's atomic write when `fsImpl === fs`.
   return fsImpl === fs
     ? writeFile(abs, envelope)
     : writeEnvelopeViaFsImpl(abs, envelope, fsImpl);
 }
 
-// Story #1974 — read prior envelope rows[] for epsilon + scope merge.
-// Returns `null` on read or parse failure (regression-fail-safe).
+// Prior rows for the epsilon/scope merge; `null` on any read failure.
 function readPriorRows(abs, fsImpl) {
   try {
     const parsed = JSON.parse(fsImpl.readFileSync(abs, 'utf8'));
@@ -239,10 +181,6 @@ function readPriorRows(abs, fsImpl) {
 
 export function writeBaseline(cwd, baseline, fsImpl = fs, opts = {}) {
   const abs = path.resolve(cwd, COVERAGE_BASELINE_PATH);
-  // Story #1891: route through the shared baseline writer (envelope shape).
-  // Story #1974: optional `opts.scope` / `opts.epsilon` thread through so
-  // manual refreshes can opt in to diff-scoped writes + epsilon
-  // stabilization; absent both, behaviour is identical to pre-#1974.
   const prior =
     opts.prior !== undefined ? opts.prior : readPriorRows(abs, fsImpl);
   const envelope = write({
@@ -256,19 +194,7 @@ export function writeBaseline(cwd, baseline, fsImpl = fs, opts = {}) {
   return abs;
 }
 
-/**
- * Compute the per-axis tolerance (in percentage points) for a file.
- *
- * Small-denominator files (a handful of branches, statements, or functions)
- * are dominated by single-instrumentation-event noise: one branch flipping
- * covered↔uncovered between Windows/Node 22 CI runs is worth `100/N`
- * percentage points. We absorb up to `NOISE_EVENT_HEADROOM` events of slack
- * — anything beyond that is real signal. Large files retain the strict
- * `COVERAGE_TOLERANCE` floor (essentially zero) because their per-event
- * resolution is already sub-percent.
- *
- * Exported for tests.
- */
+/** Per-axis tolerance: at least one event's worth (`100/N` points). */
 export function axisToleranceFor(
   denominator,
   baseTolerance = COVERAGE_TOLERANCE,
@@ -279,25 +205,9 @@ export function axisToleranceFor(
 }
 
 /**
- * Compare current per-file scores to the baseline and classify each
- * file. The classification feeds the CLI's exit-code decision and the
- * human-readable summary.
- *
- *   regressions  — file in both, any axis dropped > per-axis tolerance.
- *                  Per-axis tolerance is denominator-aware: a file with
- *                  N branches gets up to 100/N percentage points of slack
- *                  (one instrumentation event), so single-event Node 22
- *                  CI flap on tiny files no longer trips the gate.
- *   newFiles     — file in current, missing from baseline. The CLI
- *                  treats this as a hard failure ("run coverage:update")
- *                  because a brand-new untested CLI shell would
- *                  otherwise sail through with 0% coverage.
- *   removedFiles — file in baseline, missing from current. Usually
- *                  benign (file deleted or renamed); the CLI reports
- *                  but does not fail on these.
- *   improvements — file in both, every axis ≥ baseline + tolerance on
- *                  the axes both records have. Reported for visibility
- *                  so operators know when to ratchet.
+ * Classify files: `regressions` (an axis dropped beyond tolerance) and
+ * `newFiles` (else untested code lands at 0%) fail the CLI; `removedFiles`
+ * and `improvements` are reported only.
  */
 export function compareScores(
   current,

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

@@ -1,28 +1,17 @@
-/**
- * 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.
- */
+/** Full-scope (default) capture path for `coverage-capture.js`. */
 import path from 'node:path';
 import { resolveChangedFilesRef } from './changed-files.js';
 import {
   anyChangedUnderTargets,
   describeFreshness,
+  reportCaptureFailure,
   stampCapturedTree,
 } 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.
- *
- * The skip check scores the ref `resolveChangedFilesRef` resolves — the rule,
- * and the same answer, incremental mode applies, so a fall-through from it
- * cannot change scope mid-run (Story #5365).
+ * Optional no-CRAP-files skip, freshness probe, then capture and stamp. The
+ * skip uses the same ref incremental mode resolves, so a fall-through from
+ * it cannot change scope mid-run.
  *
  * @param {{
  *   crap: object,
@@ -35,9 +24,9 @@ import {
  *   writeCaptureStampImpl: Function,
  *   logger: { info: Function, warn: Function, error: Function },
  * }} opts
- * @returns {number} process exit code
+ * @returns {Promise<number>} process exit code
  */
-export function runFullScopeCapture({
+export async function runFullScopeCapture({
   crap,
   coverage,
   args,
@@ -56,8 +45,7 @@ export function runFullScopeCapture({
         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.
+      // A bad ref must not relax the gate; fall through to freshness.
       logger.warn(
         `[coverage-capture] ⚠ ${err?.message ?? err} — falling back to freshness check.`,
       );
@@ -86,17 +74,13 @@ export function runFullScopeCapture({
   logger.info(
     `[coverage-capture] Coverage at ${crap.coveragePath} is ${describeFreshness(freshness, crap.targetDirs)}; running npm run test:coverage…`,
   );
-  // Story #5278 — the digest of the tree the suite is about to measure, taken
-  // BEFORE the spawn. That is the value the stamp claims; see
-  // `stampCapturedTree`.
+  // Pre-spawn digest; see `stampCapturedTree`.
   const preDigest = computeContentDigestImpl(args.cwd, crap.targetDirs);
-  const code = runCaptureImpl({
+  const code = await runCaptureImpl({
     cwd: args.cwd,
     timeoutMs: coverage?.timeoutMs,
     log: (m) => logger.info(m),
-    // Story #5278 — consulted only if this capture had to queue behind
-    // another full suite on this host. Whoever we waited for may have just
-    // stamped this exact tree.
+    // After queueing behind another suite, which may have stamped this tree.
     recheckFresh: () =>
       isCoverageFreshImpl({
         coveragePath: crap.coveragePath,
@@ -104,17 +88,8 @@ export function runFullScopeCapture({
         cwd: args.cwd,
       }).fresh === true,
   });
-  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;
-  }
+  if (code !== 0) return reportCaptureFailure(code, logger);
 
-  // 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.
   stampCapturedTree({
     preDigest,
     cwd: args.cwd,

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

@@ -1,40 +1,14 @@
-/**
- * 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).
- */
+/** Incremental-mode capture path for `coverage-capture.js`. */
 import path from 'node:path';
 import { resolveChangedFilesRef } from './changed-files.js';
-import { stampCapturedTree } from './coverage-capture.js';
+import { reportCaptureFailure, stampCapturedTree } from './coverage-capture.js';
 
 /**
- * Run the skip-aware capture path when
- * `delivery.quality.gates.crap.incrementalCoverage.skipWhenUnchanged` is true
- * (the default since Story #5173).
- *
- * **This does not shorten the capture run.** The changed-file set decides
- * *whether* to capture, never *what* the capture executes: when nothing under
- * `crap.targetDirs` changed there is no capture at all, and otherwise the
- * ordinary full `npm run test:coverage` runs. The saving that makes the mode
- * worth having is the skip.
- *
- * Gated by `skipWhenUnchanged` alone (Story #5173). It MUST NOT consult
- * `baselineJoin`: that switch governs the CRAP join
- * (`crap-baseline-join.js`), which resolves methods in untouched files from
- * the committed baseline row instead of demanding fresh coverage for them —
- * a gate loosening, where the skip is a pure saving. The two are defaulted
- * differently for exactly that reason, so neither may read the other.
- *
- * 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).
+ * Under `skipWhenUnchanged`: the changed-file set decides whether to capture,
+ * never what runs (a capture is always the full suite). Must not read
+ * `baselineJoin` — that loosens the gate, while the skip is a pure saving.
+ * Returns `null` to fall through to full scope, including when the ref
+ * cannot be resolved (never silently relax the gate).
  *
  * @param {{
  *   crap: object,
@@ -48,9 +22,9 @@ import { stampCapturedTree } from './coverage-capture.js';
  *   writeCaptureStampImpl: Function,
  *   logger: { info: Function, warn: Function, error: Function },
  * }} opts
- * @returns {number | null}
+ * @returns {Promise<number | null>}
  */
-export function tryIncrementalCapture({
+export async function tryIncrementalCapture({
   crap,
   coverage,
   args,
@@ -99,9 +73,9 @@ export function tryIncrementalCapture({
   logger.info(
     `[coverage-capture] Incremental mode: ${scopedFiles.length} changed file(s) under [${crap.targetDirs.join(', ')}] — capturing…`,
   );
-  // Story #5278 — pre-spawn digest; see `stampCapturedTree`.
+  // Pre-spawn digest; see `stampCapturedTree`.
   const preDigest = computeContentDigestImpl(args.cwd, crap.targetDirs);
-  const code = runCaptureImpl({
+  const code = await runCaptureImpl({
     cwd: args.cwd,
     timeoutMs: coverage?.timeoutMs,
     log: (m) => logger.info(m),
@@ -113,12 +87,7 @@ export function tryIncrementalCapture({
         requireScope: 'incremental',
       }).fresh === true,
   });
-  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;
-  }
+  if (code !== 0) return reportCaptureFailure(code, logger);
 
   stampCapturedTree({
     preDigest,

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

@@ -1,27 +1,12 @@
 /**
- * coverage-capture-usage.js — the `--help` spec for `coverage-capture.js`
- * (Story #5063).
- *
- * The delivery workflow invokes `coverage-capture.js` by name
- * (`helpers/deliver-story-reference.md` § Step 1), which brings it under the
- * workflow-invoked self-description contract enforced by
- * `tests/enforcement/workflow-script-help.test.js`. It failed that contract:
- * `--help` fell through to the capture path and spawned the whole coverage
- * suite instead of describing the script.
- *
- * The spec lives here rather than inline for the same reason
- * `coverage-capture-incremental.js` does — a same-file expansion of the CLI
- * shell costs maintainability index on a file already near its floor, and a
- * usage table is data, not decision logic.
+ * `--help` spec for `coverage-capture.js`, which must answer `--help` without
+ * spawning the suite.
  */
 
 import { respondToHelp } from './cli-usage.js';
 
 /**
- * Usage spec consumed by `cli-usage.js#respondToHelp`. `coverage-capture.js`
- * does not route through `runAsCli` (its synchronous main returns an exit
- * code that `process.exit` forwards), so the help short-circuit is wired by
- * hand rather than declared on a `runAsCli` call.
+ * Wired by hand: `coverage-capture.js` does not route through `runAsCli`.
  *
  * @type {{ invocation: string, summary: string, flags: Array<[string, string]> }}
  */
@@ -37,7 +22,7 @@ const COVERAGE_CAPTURE_USAGE = {
     ],
     [
       '--require-credited',
-      'Refuse (exit 1) instead of spawning when no credited capture stamp covers this tree. Passed by the close gate when delivery.execution.requireCreditedCapture is set; a bare invocation always runs, so the deposit path stays open.',
+      'Refuse (exit 1) instead of spawning when no credited capture stamp covers this tree. An operator opt-in for one invocation; a bare invocation always runs, so the deposit path stays open.',
     ],
     [
       '--ref <git-ref>',
@@ -48,11 +33,6 @@ const COVERAGE_CAPTURE_USAGE = {
 };
 
 /**
- * Answer `--help` / `-h` on stdout, returning whether the caller should stop.
- * Takes the full `process.argv`-shaped array so the CLI shell hands over its
- * own argv unchanged and the index arithmetic lives here rather than at the
- * call site.
- *
  * @param {string[]} argv Full `process.argv`-shaped array.
  * @param {{ write: (s: string) => void }} [out] Defaults to `process.stdout`.
  * @returns {boolean} `true` when help was printed and the run must not proceed.