mandrel 2.25.0 → 2.27.0

package/.agents/scripts/lib/cyclomatic-ceiling.js

@@ -0,0 +1,265 @@
+/**
+ * cyclomatic-ceiling.js — the enforcing core behind
+ * `delivery.quality.codingGuardrails.cyclomaticMustFix` (Story #4923).
+ *
+ * The two `codingGuardrails` cyclomatic knobs shipped schema-validated,
+ * bootstrap-defaulted and resolver-resolved, and were then read by nothing:
+ * `cyclomaticMustFix` had no consumer at all, and `cyclomaticFlag` was
+ * shadowed by a hardcoded `8` in a `quality-preview` display column. A ceiling
+ * nothing enforces is worse than no ceiling, because the workflow docs promise
+ * the merge will be refused.
+ *
+ * This module is that enforcement, shaped as a **ratchet** rather than a
+ * cliff. The repository already carries dozens of functions above the
+ * must-fix ceiling; failing every one of them at once would have made the
+ * gate un-landable and it would have been disabled the same day. So the
+ * committed `baselines/cyclomatic.json` records the existing breaches per
+ * file, and the gate fails only when a change **adds** an over-ceiling
+ * function to a file that had none, adds one **beyond** that file's recorded
+ * count, or pushes a file's worst function **higher** than recorded. Burning
+ * the recorded breaches down is a separate, always-permitted motion — a
+ * shrinking baseline is the success signal.
+ *
+ * Scope: the module walks the `maintainability` gate's `targetDirs` /
+ * `ignoreGlobs`. Both instruments read the same coverage-free escomplex
+ * surface, so re-declaring the scope under `codingGuardrails` would have
+ * added two config keys whose only correct value is "whatever maintainability
+ * says".
+ *
+ * @module lib/cyclomatic-ceiling
+ */
+
+import path from 'node:path';
+import { calculateReportForFile } from './maintainability-engine.js';
+import { isIgnoredByGlobs, scanDirectory } from './maintainability-utils.js';
+
+/** Default location of the committed breach baseline. */
+export const DEFAULT_CYCLOMATIC_BASELINE = 'baselines/cyclomatic.json';
+
+/** Baseline `$schema` marker, matching the sibling ratchet baselines. */
+const CYCLOMATIC_BASELINE_SCHEMA =
+  'https://mandrel.dev/baselines/cyclomatic.schema.json';
+
+/**
+ * Resolve the enforcement policy from a resolved `delivery.quality` block.
+ *
+ * `mustFix` and `flag` come straight from `resolveCodingGuardrails`, so a
+ * consumer that tunes either knob tunes this gate — which is the whole point
+ * of the Story. `targetDirs` / `ignoreGlobs` are borrowed from the
+ * maintainability gate (see the module note).
+ *
+ * @param {object | null | undefined} quality resolved `delivery.quality`
+ * @returns {{ mustFix: number, flag: number, targetDirs: string[], ignoreGlobs: string[] }}
+ */
+export function resolveCyclomaticPolicy(quality) {
+  const guardrails = quality?.codingGuardrails ?? {};
+  const mi = quality?.maintainability ?? {};
+  return {
+    mustFix: Number(guardrails.cyclomaticMustFix ?? 12),
+    flag: Number(guardrails.cyclomaticFlag ?? 8),
+    targetDirs: Array.isArray(mi.targetDirs) ? mi.targetDirs : [],
+    ignoreGlobs: Array.isArray(mi.ignoreGlobs) ? mi.ignoreGlobs : [],
+  };
+}
+
+/**
+ * Reduce one file's escomplex method list to a breach row, or `null` when the
+ * file carries no function above `ceiling`.
+ *
+ * Pure. Module-private: tests reach it through `scanCyclomatic`'s `scoreFile`
+ * seam, which keeps the row math exercised without adding an export whose only
+ * importer is a test (the `--production` dead-export pass discounts those).
+ *
+ * @param {string} file repo-relative POSIX path
+ * @param {Array<{ cyclomatic?: number }>} methods
+ * @param {number} ceiling
+ * @returns {{ file: string, methodsAboveCeiling: number, maxCyclomatic: number } | null}
+ */
+function breachRowFor(file, methods, ceiling) {
+  let count = 0;
+  let max = 0;
+  for (const method of methods ?? []) {
+    const c = Number(method?.cyclomatic ?? 0);
+    if (!Number.isFinite(c)) continue;
+    if (c > ceiling) count += 1;
+    if (c > max) max = c;
+  }
+  return count === 0
+    ? null
+    : { file, methodsAboveCeiling: count, maxCyclomatic: max };
+}
+
+/**
+ * Walk the configured scope and score every file, returning the breach rows
+ * sorted by path.
+ *
+ * `scoreFile` is a seam so tests can drive the reduction without the kernel;
+ * production callers omit it.
+ *
+ * @param {{
+ *   targetDirs: string[],
+ *   ignoreGlobs?: string[],
+ *   ceiling: number,
+ *   cwd?: string,
+ *   scoreFile?: (absPath: string) => { methods?: Array<{ cyclomatic?: number }>, parseError?: boolean },
+ * }} args
+ * @returns {{ rows: Array<object>, scannedFiles: number, parseErrors: number }}
+ */
+export function scanCyclomatic({
+  targetDirs,
+  ignoreGlobs = [],
+  ceiling,
+  cwd = process.cwd(),
+  scoreFile = calculateReportForFile,
+}) {
+  const files = [];
+  for (const dir of targetDirs ?? []) {
+    const abs = path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
+    scanDirectory(abs, files, { cwd, ignoreGlobs });
+  }
+  files.sort();
+  const rows = [];
+  let parseErrors = 0;
+  for (const abs of files) {
+    if (isIgnoredByGlobs(abs, ignoreGlobs, cwd)) continue;
+    const report = scoreFile(abs);
+    if (!report || report.parseError) {
+      parseErrors += 1;
+      continue;
+    }
+    const rel = path.relative(cwd, abs).split(path.sep).join('/');
+    const row = breachRowFor(rel, report.methods, ceiling);
+    if (row) rows.push(row);
+  }
+  rows.sort((a, b) => a.file.localeCompare(b.file));
+  return { rows, scannedFiles: files.length, parseErrors };
+}
+
+/**
+ * Diff current breach rows against the committed baseline.
+ *
+ * Four buckets, only the first two of which fail the gate:
+ *
+ *   - `added`    — a file whose over-ceiling function count rose (including
+ *                  0 → 1, i.e. a brand-new breach in new or changed code).
+ *   - `worsened` — a file whose worst function got worse than recorded.
+ *   - `removed`  — a file that no longer breaches at all.
+ *   - `improved` — a file that breaches less than recorded.
+ *
+ * Pure; identity is the repo-relative file path.
+ *
+ * @param {Array<{file: string, methodsAboveCeiling: number, maxCyclomatic: number}>} baselineRows
+ * @param {Array<{file: string, methodsAboveCeiling: number, maxCyclomatic: number}>} currentRows
+ * @returns {{ added: Array<object>, worsened: Array<object>, removed: Array<object>, improved: Array<object> }}
+ */
+export function diffCyclomaticRows(baselineRows, currentRows) {
+  const base = new Map(
+    (baselineRows ?? [])
+      .filter((r) => typeof r?.file === 'string')
+      .map((r) => [r.file, r]),
+  );
+  const added = [];
+  const worsened = [];
+  const improved = [];
+  const seen = new Set();
+  for (const row of currentRows ?? []) {
+    if (typeof row?.file !== 'string') continue;
+    seen.add(row.file);
+    const prior = base.get(row.file);
+    const priorCount = Number(prior?.methodsAboveCeiling ?? 0);
+    const priorMax = Number(prior?.maxCyclomatic ?? 0);
+    if (row.methodsAboveCeiling > priorCount) {
+      added.push({ ...row, baselineCount: priorCount });
+      continue;
+    }
+    if (row.maxCyclomatic > priorMax) {
+      worsened.push({ ...row, baselineMax: priorMax });
+      continue;
+    }
+    if (row.methodsAboveCeiling < priorCount || row.maxCyclomatic < priorMax) {
+      improved.push({
+        ...row,
+        baselineCount: priorCount,
+        baselineMax: priorMax,
+      });
+    }
+  }
+  const removed = (baselineRows ?? []).filter(
+    (r) => typeof r?.file === 'string' && !seen.has(r.file),
+  );
+  const byFile = (a, b) => a.file.localeCompare(b.file);
+  return {
+    added: added.sort(byFile),
+    worsened: worsened.sort(byFile),
+    removed: removed.sort(byFile),
+    improved: improved.sort(byFile),
+  };
+}
+
+/**
+ * Assemble the committed baseline envelope. The rollup is deliberately
+ * derived, never hand-written: a zero-row baseline here reports zero breaches
+ * because the repository has none, not because nobody produced it.
+ *
+ * @param {{ rows: Array<object>, ceiling: number, generatedAt?: string }} args
+ * @returns {object}
+ */
+export function buildCyclomaticEnvelope({ rows, ceiling, generatedAt }) {
+  const safeRows = rows ?? [];
+  let methods = 0;
+  let max = 0;
+  for (const row of safeRows) {
+    methods += Number(row.methodsAboveCeiling ?? 0);
+    if (Number(row.maxCyclomatic ?? 0) > max) max = Number(row.maxCyclomatic);
+  }
+  return {
+    $schema: CYCLOMATIC_BASELINE_SCHEMA,
+    generatedAt: generatedAt ?? new Date().toISOString(),
+    ceiling,
+    rollup: {
+      '*': {
+        filesAboveCeiling: safeRows.length,
+        methodsAboveCeiling: methods,
+        maxCyclomatic: max,
+      },
+    },
+    rows: safeRows,
+  };
+}
+
+/**
+ * Render the human-readable diff. Emits a summary line even on a clean run so
+ * operators see the "no drift" signal rather than silence.
+ *
+ * @param {{ added: Array, worsened: Array, removed: Array, improved: Array }} diff
+ * @param {number} ceiling
+ * @returns {string}
+ */
+export function renderCyclomaticDiff(diff, ceiling) {
+  const lines = [];
+  for (const r of diff.added) {
+    lines.push(
+      `+ ${r.file}: ${r.methodsAboveCeiling} function(s) over c=${ceiling} (recorded ${r.baselineCount}), worst c=${r.maxCyclomatic}`,
+    );
+  }
+  for (const r of diff.worsened) {
+    lines.push(
+      `! ${r.file}: worst function c=${r.maxCyclomatic} (recorded ${r.baselineMax})`,
+    );
+  }
+  for (const r of diff.improved) {
+    lines.push(
+      `~ ${r.file}: ${r.methodsAboveCeiling} over c=${ceiling} (recorded ${r.baselineCount}), worst c=${r.maxCyclomatic} (recorded ${r.baselineMax})`,
+    );
+  }
+  for (const r of diff.removed) {
+    lines.push(`- ${r.file}: no longer over c=${ceiling}`);
+  }
+  const failing = diff.added.length + diff.worsened.length;
+  lines.push(
+    `[cyclomatic] ceiling=${ceiling} added=${diff.added.length} worsened=${diff.worsened.length} improved=${diff.improved.length} removed=${diff.removed.length} ${
+      failing > 0 ? '(gate fail)' : '(ok)'
+    }`,
+  );
+  return lines.join('\n');
+}

package/.agents/scripts/lib/feedback-loop/audit-results-graduator.js

@@ -333,5 +333,3 @@ export async function graduateAuditResults(opts = {}) {
     },
   });
 }
-
-export default graduateAuditResults;

package/.agents/scripts/lib/feedback-loop/prior-feedback-fetcher.js

@@ -307,5 +307,3 @@ export async function fetchPriorFeedback({
 
   return envelope;
 }
-
-export default fetchPriorFeedback;

package/.agents/scripts/lib/feedback-loop/retro-proposals-graduator.js

@@ -495,5 +495,3 @@ export async function fileRetroProposals({
   );
   return { routedProposals: enriched, summary };
 }
-
-export default graduateRetroProposals;

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

@@ -40,6 +40,23 @@ import { execFileSync, spawnSync } from 'node:child_process';
  * @property {string} stderr - Trimmed stderr.
  */
 
+/**
+ * Explicit stdout ceiling for every git invocation in this module.
+ *
+ * Both child-process runners default `maxBuffer` to 1 MB, at which point the
+ * child is killed and the call fails with `ENOBUFS` for a reason unrelated to
+ * git. The push path is the sharp edge: `git push` relays the whole `pre-push`
+ * hook output, which is unbounded by design — this repo's hook emits a full
+ * `check-baselines` envelope, measured at 2,166,643 bytes, so every Story
+ * close failed at `phase: push` once hooks became reachable inside worktrees.
+ *
+ * 64 MB is the bound Story #4914 already set on `baselines/git-base.js` for
+ * the identical failure, matching `run-test-profile.js`,
+ * `audit-baselines/trend.js` and `audit-baselines/weights.js`. This module was
+ * missed by that sweep.
+ */
+const MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+
 let _execFileSync = execFileSync;
 let _spawnSync = spawnSync;
 
@@ -108,38 +125,44 @@ export function __setGitRunners(exec, spawn) {
 }
 
 /**
- * Run a git command synchronously, returning trimmed stdout.
- * Throws an Error if the command exits with a non-zero code.
+ * The **single** throwing git runner. Both the module-level {@link gitSync} and
+ * the interface returned by {@link createGitInterface} route through this —
+ * they differ only in which `execFileSync` they hand it.
  *
- * @param {string}   cwd  - Working directory for the git process.
- * @param {...string} args - Git sub-command and arguments.
+ * @param {typeof execFileSync} exec
+ * @param {string} cwd
+ * @param {string[]} args
  * @returns {string} Trimmed stdout text.
  */
-export function gitSync(cwd, ...args) {
-  return _execFileSync('git', args, {
+function runGitSync(exec, cwd, args) {
+  return exec('git', args, {
     cwd,
     encoding: 'utf8',
     stdio: ['pipe', 'pipe', 'pipe'],
     shell: false,
     env: cleanGitEnv(),
+    maxBuffer: MAX_BUFFER_BYTES,
   }).trim();
 }
 
 /**
- * Run a git command synchronously, returning a result object.
- * Never throws — callers must inspect `status` to detect failure.
+ * The **single** non-throwing git runner — the `spawnSync` counterpart of
+ * {@link runGitSync}, normalising `status`/stdout/stderr into a
+ * {@link GitResult}.
  *
- * @param {string}   cwd  - Working directory for the git process.
- * @param {...string} args - Git sub-command and arguments.
+ * @param {typeof spawnSync} spawn
+ * @param {string} cwd
+ * @param {string[]} args
  * @returns {GitResult}
  */
-export function gitSpawn(cwd, ...args) {
-  const result = _spawnSync('git', args, {
+function runGitSpawn(spawn, cwd, args) {
+  const result = spawn('git', args, {
     cwd,
     stdio: 'pipe',
     encoding: 'utf-8',
     shell: false,
     env: cleanGitEnv(),
+    maxBuffer: MAX_BUFFER_BYTES,
   });
   return {
     status: result.status ?? 1,
@@ -148,6 +171,30 @@ export function gitSpawn(cwd, ...args) {
   };
 }
 
+/**
+ * Run a git command synchronously, returning trimmed stdout.
+ * Throws an Error if the command exits with a non-zero code.
+ *
+ * @param {string}   cwd  - Working directory for the git process.
+ * @param {...string} args - Git sub-command and arguments.
+ * @returns {string} Trimmed stdout text.
+ */
+export function gitSync(cwd, ...args) {
+  return runGitSync(_execFileSync, cwd, args);
+}
+
+/**
+ * Run a git command synchronously, returning a result object.
+ * Never throws — callers must inspect `status` to detect failure.
+ *
+ * @param {string}   cwd  - Working directory for the git process.
+ * @param {...string} args - Git sub-command and arguments.
+ * @returns {GitResult}
+ */
+export function gitSpawn(cwd, ...args) {
+  return runGitSpawn(_spawnSync, cwd, args);
+}
+
 /**
  * Build a git interface closed over injected child-process runners. Preferred
  * seam for callers that want explicit injection without touching the
@@ -165,57 +212,25 @@ export function gitSpawn(cwd, ...args) {
 export function createGitInterface(deps = {}) {
   const exec = deps.exec ?? execFileSync;
   const spawn = deps.spawn ?? spawnSync;
-  const sleep =
-    deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const sleep = deps.sleep ?? defaultSleep;
   const jitterFactor = deps.jitter ?? 0.5;
 
-  const gitSync = (cwd, ...args) =>
-    exec('git', args, {
-      cwd,
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-      shell: false,
-      env: cleanGitEnv(),
-    }).trim();
-
-  const gitSpawn = (cwd, ...args) => {
-    const result = spawn('git', args, {
-      cwd,
-      stdio: 'pipe',
-      encoding: 'utf-8',
-      shell: false,
-      env: cleanGitEnv(),
-    });
-    return {
-      status: result.status ?? 1,
-      stdout: (result.stdout ?? '').trim(),
-      stderr: (result.stderr ?? '').trim(),
-    };
-  };
-
-  async function runWithRetry(leadingArgs, cwd, args) {
-    const backoff = [250, 500, 1000];
-    let attempt = 0;
-    let last;
-    for (;;) {
-      attempt++;
-      last = gitSpawn(cwd, ...leadingArgs, ...args);
-      if (last.status === 0) return { ...last, attempts: attempt };
-      if (!isPackedRefsContention(last.stderr))
-        return { ...last, attempts: attempt };
-      if (attempt > backoff.length) return { ...last, attempts: attempt };
-      const base = backoff[attempt - 1];
-      const jitter = Math.floor(Math.random() * base * jitterFactor);
-      await sleep(base + jitter);
-    }
-  }
+  const boundGitSpawn = (cwd, ...args) => runGitSpawn(spawn, cwd, args);
+  const withRetry =
+    (argvPrefix) =>
+    (cwd, ...args) =>
+      gitWithContentionRetry(
+        { spawnGit: boundGitSpawn, sleep, jitterFactor },
+        cwd,
+        argvPrefix,
+        args,
+      );
 
   return {
-    gitSync,
-    gitSpawn,
-    gitFetchWithRetry: (cwd, ...args) => runWithRetry(['fetch'], cwd, args),
-    gitPullWithRetry: (cwd, ...args) =>
-      runWithRetry(['pull', '--rebase'], cwd, args),
+    gitSync: (cwd, ...args) => runGitSync(exec, cwd, args),
+    gitSpawn: boundGitSpawn,
+    gitFetchWithRetry: withRetry(['fetch']),
+    gitPullWithRetry: withRetry(['pull', '--rebase']),
   };
 }
 
@@ -238,12 +253,21 @@ function isPackedRefsContention(stderr) {
 }
 
 /**
- * Sleep helper for retry backoff. Overridable via `__setSleep` so tests
- * can skip real wall-clock delays without relying on node:test timer mocks.
+ * Real wall-clock sleep — the default backoff delay for both the module-level
+ * retry helpers and {@link createGitInterface}.
  * @param {number} ms
  * @returns {Promise<void>}
  */
-let _sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Sleep helper for retry backoff. Overridable via `__setSleep` so tests
+ * can skip real wall-clock delays without relying on node:test timer mocks.
+ * @type {(ms: number) => Promise<void>}
+ */
+let _sleep = defaultSleep;
 let _jitterFactor = 0.5;
 
 /**
@@ -258,38 +282,65 @@ export function __setSleep(fn, opts = {}) {
 }
 
 /**
- * Shared bounded retry loop for git commands that can hit packed-refs lock
- * contention. Only contention signatures trigger a retry — non-contention
+ * Backoff schedule for {@link gitWithContentionRetry}: 250ms, 500ms, 1000ms
+ * (3 retries → 4 attempts total).
+ */
+const CONTENTION_BACKOFF_MS = Object.freeze([250, 500, 1000]);
+
+/**
+ * The **single** bounded retry loop for git commands that can hit packed-refs
+ * lock contention. Only contention signatures trigger a retry — non-contention
  * failures surface immediately, and success short-circuits the loop.
  *
- * Backoff schedule: 250ms, 500ms, 1000ms (3 retries → 4 attempts total).
  * Deliberately no global lock — a mutex would erase the parallelism the
- * worktree-isolation model is designed to enable. The schedule and the
- * jitter policy (`_sleep` / `_jitterFactor` seams) live only here so a
- * backoff tuning change has a single point of application.
+ * worktree-isolation model is designed to enable. The schedule and the jitter
+ * policy live only here, so a backoff tuning change has a single point of
+ * application: the module-level `gitFetchWithRetry` / `gitPullWithRetry` pass
+ * the `_sleep` / `_jitterFactor` seams, and {@link createGitInterface} passes
+ * its injected equivalents.
  *
+ * @param {{ spawnGit: (cwd: string, ...args: string[]) => GitResult,
+ *   sleep: (ms: number) => Promise<void>, jitterFactor: number }} runners
  * @param {string} cwd
  * @param {string[]} argvPrefix - Leading git argv (e.g. `['fetch']`).
  * @param {string[]} args - Trailing arguments (e.g. `['origin']`).
  * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
  */
-async function gitWithContentionRetry(cwd, argvPrefix, args) {
-  const backoff = [250, 500, 1000];
+async function gitWithContentionRetry(
+  { spawnGit, sleep, jitterFactor },
+  cwd,
+  argvPrefix,
+  args,
+) {
   let attempt = 0;
-  let last;
   for (;;) {
     attempt++;
-    last = gitSpawn(cwd, ...argvPrefix, ...args);
-    if (last.status === 0) return { ...last, attempts: attempt };
-    if (!isPackedRefsContention(last.stderr))
+    const last = spawnGit(cwd, ...argvPrefix, ...args);
+    const exhausted = attempt > CONTENTION_BACKOFF_MS.length;
+    if (
+      last.status === 0 ||
+      exhausted ||
+      !isPackedRefsContention(last.stderr)
+    ) {
       return { ...last, attempts: attempt };
-    if (attempt > backoff.length) return { ...last, attempts: attempt };
-    const base = backoff[attempt - 1];
-    const jitter = Math.floor(Math.random() * base * _jitterFactor);
-    await _sleep(base + jitter);
+    }
+    const base = CONTENTION_BACKOFF_MS[attempt - 1];
+    await sleep(base + Math.floor(Math.random() * base * jitterFactor));
   }
 }
 
+/**
+ * The module-level retry runners — the `__setSleep`-overridable seams bound to
+ * the module-global {@link gitSpawn}. Read lazily so `__setSleep` and
+ * `__setGitRunners` still take effect after import.
+ *
+ * @returns {{ spawnGit: typeof gitSpawn, sleep: (ms: number) => Promise<void>,
+ *   jitterFactor: number }}
+ */
+function moduleRetryRunners() {
+  return { spawnGit: gitSpawn, sleep: _sleep, jitterFactor: _jitterFactor };
+}
+
 /**
  * Run `git fetch …` with the bounded packed-refs-contention retry loop
  * (see `gitWithContentionRetry`).
@@ -299,7 +350,7 @@ async function gitWithContentionRetry(cwd, argvPrefix, args) {
  * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
  */
 export function gitFetchWithRetry(cwd, ...args) {
-  return gitWithContentionRetry(cwd, ['fetch'], args);
+  return gitWithContentionRetry(moduleRetryRunners(), cwd, ['fetch'], args);
 }
 
 /**
@@ -312,7 +363,12 @@ export function gitFetchWithRetry(cwd, ...args) {
  * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
  */
 export function gitPullWithRetry(cwd, ...args) {
-  return gitWithContentionRetry(cwd, ['pull', '--rebase'], args);
+  return gitWithContentionRetry(
+    moduleRetryRunners(),
+    cwd,
+    ['pull', '--rebase'],
+    args,
+  );
 }
 
 /**