mandrel 1.57.0

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

@@ -0,0 +1,352 @@
+/**
+ * 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.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import picomatch from 'picomatch';
+import { write, writeFile } from './baselines/writer.js';
+
+export 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.
+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.
+export 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).
+ */
+export function buildScopePredicate({ include = [], exclude = [] } = {}) {
+  const inc =
+    include.length === 0 ? () => true : picomatch(include, { dot: true });
+  const exc =
+    exclude.length === 0 ? () => false : picomatch(exclude, { dot: true });
+  return (relPath) => {
+    const norm = toForwardSlash(relPath);
+    return inc(norm) && !exc(norm);
+  };
+}
+
+/**
+ * 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.
+ */
+export function scoreEntry(entry) {
+  const sMap = entry?.s ?? {};
+  const bMap = entry?.b ?? {};
+  const fMap = entry?.f ?? {};
+
+  let lT = 0;
+  let lC = 0;
+  for (const v of Object.values(sMap)) {
+    lT += 1;
+    if (v > 0) lC += 1;
+  }
+  let bT = 0;
+  let bC = 0;
+  for (const arr of Object.values(bMap)) {
+    if (!Array.isArray(arr)) continue;
+    for (const v of arr) {
+      bT += 1;
+      if (v > 0) bC += 1;
+    }
+  }
+  let fT = 0;
+  let fC = 0;
+  for (const v of Object.values(fMap)) {
+    fT += 1;
+    if (v > 0) fC += 1;
+  }
+  const pct = (c, t) => (t === 0 ? null : Number(((100 * c) / t).toFixed(2)));
+  return {
+    lines: pct(lC, lT),
+    branches: pct(bC, bT),
+    functions: pct(fC, fT),
+    denominators: { lines: lT, branches: bT, functions: fT },
+  };
+}
+
+/**
+ * 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.
+ */
+export function scoreCoverageFinal({ raw, cwd, scope }) {
+  const inScope = scope ?? buildScopePredicate({});
+  const out = {};
+  for (const [absPath, entry] of Object.entries(raw ?? {})) {
+    const rel = toForwardSlash(path.relative(cwd, absPath));
+    if (!inScope(rel)) continue;
+    out[rel] = scoreEntry(entry);
+  }
+  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.
+ */
+export function readCoverageFinal(cwd, opts = {}, fsImpl) {
+  const resolvedFs = fsImpl ?? fs;
+  const coveragePath =
+    typeof opts === 'string'
+      ? opts
+      : (opts?.coveragePath ?? COVERAGE_FINAL_PATH);
+  const abs = path.isAbsolute(coveragePath)
+    ? coveragePath
+    : path.resolve(cwd, coveragePath);
+  if (!resolvedFs.existsSync(abs)) {
+    throw new Error(
+      `coverage-final.json not found at ${abs}. Run \`npm run test:coverage\` first.`,
+    );
+  }
+  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 &&
+    typeof parsed === 'object' &&
+    !Array.isArray(parsed) &&
+    Array.isArray(parsed.rows) &&
+    typeof parsed.$schema === 'string'
+  );
+}
+
+function projectEnvelopeToFlat(envelope) {
+  const out = {};
+  for (const row of envelope.rows) {
+    if (!row || typeof row.path !== 'string') continue;
+    out[row.path] = {
+      lines: row.lines,
+      branches: row.branches,
+      functions: row.functions,
+    };
+  }
+  return out;
+}
+
+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).
+  return isEnvelopeShape(parsed) ? projectEnvelopeToFlat(parsed) : parsed;
+}
+
+export function readBaseline(cwd, fsImpl = fs) {
+  const abs = path.resolve(cwd, COVERAGE_BASELINE_PATH);
+  if (!fsImpl.existsSync(abs)) return null;
+  return normaliseParsedBaseline(JSON.parse(fsImpl.readFileSync(abs, 'utf8')));
+}
+
+function projectFlatToRows(baseline) {
+  return Object.entries(baseline ?? {}).map(([file, scores]) => {
+    const { denominators: _ignored, ...rest } = scores ?? {};
+    return {
+      path: file,
+      lines: rest.lines ?? 0,
+      branches: rest.branches ?? 0,
+      functions: rest.functions ?? 0,
+    };
+  });
+}
+
+function writeEnvelopeViaFsImpl(abs, envelope, fsImpl) {
+  fsImpl.mkdirSync(path.dirname(abs), { recursive: true });
+  const canonical = {
+    $schema: envelope.$schema,
+    kernelVersion: envelope.kernelVersion,
+    generatedAt: envelope.generatedAt,
+    rollup: envelope.rollup,
+    rows: envelope.rows,
+  };
+  fsImpl.writeFileSync(abs, `${JSON.stringify(canonical, null, 2)}\n`);
+}
+
+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).
+function readPriorRows(abs, fsImpl) {
+  try {
+    const parsed = JSON.parse(fsImpl.readFileSync(abs, 'utf8'));
+    return Array.isArray(parsed?.rows) ? parsed.rows : null;
+  } catch {
+    return null;
+  }
+}
+
+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({
+    kind: 'coverage',
+    rows: projectFlatToRows(baseline),
+    prior: prior ?? undefined,
+    epsilon: prior && opts.epsilon !== undefined ? opts.epsilon : undefined,
+    scope: opts.scope,
+  });
+  dispatchEnvelopeWrite(abs, envelope, fsImpl);
+  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.
+ */
+export function axisToleranceFor(
+  denominator,
+  baseTolerance = COVERAGE_TOLERANCE,
+) {
+  if (!Number.isFinite(denominator) || denominator <= 0) return baseTolerance;
+  const eventResolution = 100 / denominator;
+  return Math.max(baseTolerance, eventResolution * NOISE_EVENT_HEADROOM);
+}
+
+/**
+ * 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.
+ */
+export function compareScores(
+  current,
+  baseline,
+  tolerance = COVERAGE_TOLERANCE,
+) {
+  const regressions = [];
+  const newFiles = [];
+  const improvements = [];
+  const removedFiles = [];
+
+  for (const [file, scores] of Object.entries(current)) {
+    const base = baseline[file];
+    if (base === undefined) {
+      newFiles.push({ file, current: scores });
+      continue;
+    }
+    const drops = [];
+    let anyImprovement = false;
+    const denominators = scores?.denominators ?? {};
+    for (const axis of /** @type {const} */ ([
+      'lines',
+      'branches',
+      'functions',
+    ])) {
+      const c = scores[axis];
+      const b = base[axis];
+      if (c === null || c === undefined) continue;
+      if (b === null || b === undefined) continue;
+      const axisTol = axisToleranceFor(denominators[axis], tolerance);
+      if (c < b - axisTol)
+        drops.push({
+          axis,
+          current: c,
+          baseline: b,
+          drop: b - c,
+          tolerance: axisTol,
+        });
+      else if (c > b + axisTol) anyImprovement = true;
+    }
+    if (drops.length > 0) {
+      regressions.push({ file, drops });
+    } else if (anyImprovement) {
+      improvements.push({ file });
+    }
+  }
+  for (const file of Object.keys(baseline)) {
+    if (current[file] === undefined) removedFiles.push({ file });
+  }
+
+  return { regressions, newFiles, improvements, removedFiles };
+}

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

@@ -0,0 +1,195 @@
+/**
+ * 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`.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Walk a directory tree and return the newest mtime (ms since epoch) seen
+ * across `.js` and `.mjs` files. Symlinks, missing dirs, and unreadable nodes
+ * resolve to 0 so the caller treats "no sources" the same as "ancient sources"
+ * — both mean "any existing coverage is fresh enough".
+ *
+ * Exported for unit testing.
+ *
+ * @param {string} cwd Absolute repo root.
+ * @param {string[]} targetDirs Repo-relative directories to scan.
+ * @param {{ statSync?: typeof fs.statSync, readdirSync?: typeof fs.readdirSync }} [io]
+ * @returns {number} Newest mtime in ms, or 0 when no source files exist.
+ */
+export function newestSourceMtime(cwd, targetDirs, io = {}) {
+  const statSync = io.statSync ?? fs.statSync;
+  const readdirSync = io.readdirSync ?? fs.readdirSync;
+  let newest = 0;
+
+  const visit = (abs) => {
+    let entries;
+    try {
+      entries = readdirSync(abs, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      const childAbs = path.join(abs, entry.name);
+      if (entry.isDirectory()) {
+        visit(childAbs);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (!entry.name.endsWith('.js') && !entry.name.endsWith('.mjs')) continue;
+      try {
+        const m = statSync(childAbs).mtimeMs;
+        if (m > newest) newest = m;
+      } catch {
+        // ignore unreadable file
+      }
+    }
+  };
+
+  for (const dir of targetDirs) {
+    if (!dir) continue;
+    visit(path.resolve(cwd, dir));
+  }
+  return newest;
+}
+
+/**
+ * Decide whether the existing coverage artifact is "fresh" — present and 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.
+ *
+ * @param {{
+ *   coveragePath: string,
+ *   targetDirs: string[],
+ *   cwd: string,
+ *   statSync?: typeof fs.statSync,
+ *   readdirSync?: typeof fs.readdirSync,
+ *   existsSync?: typeof fs.existsSync,
+ * }} opts
+ * @returns {{ fresh: boolean, reason: 'missing' | 'stale' | 'fresh' | 'no-sources' }}
+ */
+export function isCoverageFresh({
+  coveragePath,
+  targetDirs,
+  cwd,
+  statSync = fs.statSync,
+  readdirSync = fs.readdirSync,
+  existsSync = fs.existsSync,
+}) {
+  const absCoverage = path.resolve(cwd, coveragePath);
+  if (!existsSync(absCoverage)) return { fresh: false, reason: 'missing' };
+
+  let coverageMtime;
+  try {
+    coverageMtime = statSync(absCoverage).mtimeMs;
+  } catch {
+    return { fresh: false, reason: 'missing' };
+  }
+
+  const newestSrc = newestSourceMtime(cwd, targetDirs, {
+    statSync,
+    readdirSync,
+  });
+  if (newestSrc === 0) return { fresh: true, reason: 'no-sources' };
+  return coverageMtime >= newestSrc
+    ? { fresh: true, reason: 'fresh' }
+    : { fresh: false, reason: 'stale' };
+}
+
+/**
+ * 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`.
+ *
+ * @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}/`));
+  });
+}
+
+/**
+ * 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;
+
+/**
+ * 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.
+ *
+ * @param {{
+ *   cwd: string,
+ *   timeoutMs?: number,
+ *   runner?: typeof spawnSync,
+ *   log?: (m: string) => void,
+ * }} opts
+ * @returns {number}
+ */
+export function runCapture({
+  cwd,
+  timeoutMs,
+  runner = spawnSync,
+  log = () => {},
+} = {}) {
+  log('[coverage-capture] ▶ npm run test:coverage');
+  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', ['run', 'test:coverage'], 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 COVERAGE_TIMEOUT_EXIT_CODE;
+  }
+  return res.status ?? 1;
+}