mandrel 2.24.0 → 2.26.0

package/.agents/scripts/check-arch-cycles.js

@@ -37,16 +37,19 @@ import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import { runAsCli } from './lib/cli-utils.js';
+import {
+  buildGraph,
+  collectJsFiles,
+  DEFAULT_ROOTS,
+  parseRelativeImports,
+} from './lib/import-graph.js';
 
-/**
- * Default scan roots making up the project's distributed surface — the
- * directories published to npm via `package.json` `files[]`. Resolving
- * them into one graph (relativized against the repo root) means a cycle
- * crossing two roots is visible to `findCycles`.
- *
- * @type {string[]}
- */
-export const DEFAULT_ROOTS = [path.join('.agents', 'scripts'), 'bin', 'lib'];
+// The import-graph builder itself lives in `lib/import-graph.js` (Story
+// #4902) so `audit-baselines.js` can rank hotspots by import in-degree
+// against the same graph this ratchet detects cycles in. Re-exported here
+// because this module's named exports are its unit-test surface and its
+// documented contract; the behaviour is unchanged by the move.
+export { buildGraph, collectJsFiles, DEFAULT_ROOTS, parseRelativeImports };
 
 /**
  * Parse argv for `--baseline <path>`, `--root <path>`, and `--json`.
@@ -80,90 +83,6 @@ export function parseArgv(argv = []) {
   return { baselinePath, rootPath, json };
 }
 
-/**
- * Recursively collect `.js` files under `rootDir`, skipping
- * `node_modules`. Returns absolute paths, sorted for determinism.
- *
- * @param {string} rootDir
- * @returns {string[]}
- */
-export function collectJsFiles(rootDir) {
-  const out = [];
-  const walk = (dir) => {
-    let entries;
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      if (entry.name === 'node_modules') continue;
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        walk(full);
-      } else if (entry.isFile() && entry.name.endsWith('.js')) {
-        out.push(full);
-      }
-    }
-  };
-  walk(rootDir);
-  return out.sort();
-}
-
-const IMPORT_RE = /from\s+['"](\.\.?\/[^'"]+\.js)['"]/g;
-
-/**
- * Pure helper: extract relative static-import specifiers from source text.
- *
- * @param {string} source
- * @returns {string[]}
- */
-export function parseRelativeImports(source) {
-  const specs = [];
-  for (const m of source.matchAll(IMPORT_RE)) {
-    specs.push(m[1]);
-  }
-  return specs;
-}
-
-/**
- * Build a directed import graph over the given files. Node identity is the
- * file path relative to `rootDir`, posix-separated, so the graph (and any
- * cycles found in it) serializes identically across platforms. Edges that
- * resolve outside the scanned file set are dropped.
- *
- * @param {string[]} files absolute paths
- * @param {string} rootDir
- * @param {{ readFile?: (p: string) => string }} [opts]
- * @returns {Map<string, string[]>}
- */
-export function buildGraph(files, rootDir, { readFile } = {}) {
-  const read = readFile ?? ((p) => fs.readFileSync(p, 'utf-8'));
-  const toId = (abs) => path.relative(rootDir, abs).split(path.sep).join('/');
-  const idSet = new Set(files.map(toId));
-  const graph = new Map();
-  for (const file of files) {
-    const id = toId(file);
-    let source;
-    try {
-      source = read(file);
-    } catch {
-      graph.set(id, []);
-      continue;
-    }
-    const edges = [];
-    for (const spec of parseRelativeImports(source)) {
-      const target = path
-        .relative(rootDir, path.resolve(path.dirname(file), spec))
-        .split(path.sep)
-        .join('/');
-      if (idSet.has(target) && target !== id) edges.push(target);
-    }
-    graph.set(id, [...new Set(edges)].sort());
-  }
-  return graph;
-}
-
 /**
  * Pure helper: rotate a cycle (array of module ids, no repeated terminal
  * element) so it starts at its lexicographically-smallest member. The same

package/.agents/scripts/check-baseline-drift.js

@@ -118,21 +118,34 @@ export async function runCheckBaselineDrift({
   return { exitCode: run.ok ? 0 : 1, output };
 }
 
+/**
+ * Run the drift check and *return* its exit code rather than calling
+ * `process.exit()` — this CLI prints one row per drifted baseline entry
+ * full-scope, so its report is exactly the kind of payload that outgrows the
+ * 64 KiB pipe buffer under a `| tee`. `process.exit()` terminates before a
+ * queued async pipe write drains, silently truncating it (Story #4783, the
+ * same defect `check-baselines.js` carried). Handing the code back lets
+ * `runAsCli`'s `propagateExitCode` path settle it through
+ * `settleCli`/`flushStdio` instead. The 0/1/2 contract documented at the top
+ * of this file is unchanged — only *when* the process leaves is.
+ *
+ * @returns {Promise<number>} 0 no drift, 1 drift detected, 2 could not run.
+ */
 async function main() {
   let result;
   try {
     result = await runCheckBaselineDrift({ argv: process.argv.slice(2) });
   } catch (err) {
     process.stdout.write(`${err?.message ?? String(err)}\n`);
-    process.exit(2);
-    return;
+    return 2;
   }
   process.stdout.write(`${result.output}\n`);
-  process.exit(result.exitCode);
+  return result.exitCode;
 }
 
 runAsCli(import.meta.url, main, {
   source: 'check-baseline-drift',
   usage: HELP_TEXT,
   exitCode: 2,
+  propagateExitCode: true,
 });

package/.agents/scripts/check-baselines.js

@@ -65,6 +65,22 @@ export {
   selectEnabledGates,
 };
 
+/**
+ * Run the dispatcher and *return* its exit code rather than calling
+ * `process.exit()`.
+ *
+ * The return is load-bearing (Story #4783's defect, reintroduced here):
+ * `process.exit()` terminates before a queued async pipe write drains, so a
+ * full `--gate coverage` report — a quarter of a megabyte of JSON — arrived
+ * truncated at the 64 KiB pipe boundary under the `| tee` in CI's coverage
+ * step, while still exiting 0. Handing the code back to `runAsCli`'s
+ * `propagateExitCode` path settles it through `settleCli`/`flushStdio`
+ * instead, which assigns `process.exitCode` and lets Node terminate once
+ * stdout has drained. The 0/1/2/3/4 contract in `lib/baselines/exit-codes.js`
+ * is unchanged — only *when* the process leaves is.
+ *
+ * @returns {Promise<number>} An exit code from the `EXIT_*` contract.
+ */
 async function main() {
   let result;
   try {
@@ -74,14 +90,14 @@ async function main() {
     process.stdout.write(
       `${JSON.stringify({ schemaVersion: '1', error: message }, null, 2)}\n`,
     );
-    process.exit(EXIT_CONFIG);
-    return;
+    return EXIT_CONFIG;
   }
   process.stdout.write(`${result.output}\n`);
-  process.exit(result.exitCode);
+  return result.exitCode;
 }
 
 runAsCli(import.meta.url, main, {
   source: 'check-baselines',
   usage: HELP_TEXT,
+  propagateExitCode: true,
 });

package/.agents/scripts/check-context-budget.js

@@ -47,9 +47,18 @@
  * Ratchet semantics (mirroring the sibling ratchets):
  *   - A gated tier grows beyond `baseline.tiers.<tier>.totalBytes +
  *     baseline.toleranceBytes` → exit 1, naming the tier and its delta.
- *   - A gated tier shrinks below its baseline total → printed as a `-`
- *     (removal) note, warning the baseline can be refreshed downward.
- *     Shrink-only exits 0.
+ *   - A gated tier shrinks below its baseline total → exit 1 (Story #4872).
+ *     A ratchet that only tightens in one direction lets every measured
+ *     improvement evaporate: the recorded total keeps promising headroom the
+ *     tree no longer spends, so the next growth is absorbed by stale slack
+ *     instead of being reported. Shrinkage is therefore **actionable** —
+ *     refresh the baseline down and the gain is locked in. Unlike growth this
+ *     is deliberately **zero-tolerance**: `toleranceBytes` exists to keep a
+ *     trivial addition from churning the file, and applying it downward would
+ *     silently discard every sub-tolerance gain.
+ *   - A recorded row naming a path the measured tier no longer contains →
+ *     exit 1. The row describes a file that has been deleted or de-listed, so
+ *     the bytes it contributes to the recorded total are fiction.
  *   - Within tolerance / clean → exit 0.
  *   - Baseline file absent → warn + exit 0 (no-op; nothing to ratchet against).
  *
@@ -303,16 +312,45 @@ export function buildBaseline(tierMap, toleranceBytes) {
   };
 }
 
+/**
+ * Collect the recorded rows of one gated tier that name a path the measured
+ * tier no longer contains (Story #4872). A deleted file drops out of the
+ * resolved tier, and so does one that has been de-listed from the read set —
+ * either way the row's bytes are counted into a recorded total that no live
+ * file backs, so the row is drift and not a detail.
+ *
+ * @param {string} tier
+ * @param {Array<{ path: string, bytes: number }>} files live tier measurement
+ * @param {{ files?: Array<{ path: string, bytes?: number }> }} baseTier recorded tier
+ * @returns {Array<{ tier: string, path: string, bytes: number|null }>}
+ */
+function absentRows(tier, files, baseTier) {
+  const live = new Set(files.map((f) => f.path));
+  const out = [];
+  for (const row of baseTier?.files ?? []) {
+    if (typeof row?.path !== 'string' || live.has(row.path)) continue;
+    out.push({
+      tier,
+      path: row.path,
+      bytes: Number.isFinite(row.bytes) ? row.bytes : null,
+    });
+  }
+  return out;
+}
+
 /**
  * Pure diff: compare the current tier map against the committed baseline. A
  * gated tier with no current files is skipped; a tier absent from the baseline
- * is skipped. `grown` entries fail the gate; `shrunk` entries are informational.
+ * is skipped. `grown`, `shrunk` and `absent` entries all fail the gate — see
+ * the ratchet semantics in the module header for why shrinkage is actionable
+ * rather than informational (Story #4872).
  *
  * @param {{ tiers: Record<string, Array<{ path: string, bytes: number }>> }} tierMap
  * @param {{ toleranceBytes?: number, tiers?: Record<string, { totalBytes: number }> }} baseline
  * @returns {{
  *   grown: Array<{ tier: string, current: number, baseline: number, tolerance: number, delta: number }>,
- *   shrunk: Array<{ tier: string, current: number, baseline: number }>,
+ *   shrunk: Array<{ tier: string, current: number, baseline: number, delta: number }>,
+ *   absent: Array<{ tier: string, path: string, bytes: number|null }>,
  *   skipped: string[],
  * }}
  */
@@ -322,6 +360,7 @@ export function diffBudget(tierMap, baseline) {
     : 0;
   const grown = [];
   const shrunk = [];
+  const absent = [];
   const skipped = [];
   for (const tier of GATED_TIERS) {
     const files = tierMap.tiers[tier] ?? [];
@@ -345,16 +384,42 @@ export function diffBudget(tierMap, baseline) {
         delta: current - baselineBytes,
       });
     } else if (current < baselineBytes) {
-      shrunk.push({ tier, current, baseline: baselineBytes });
+      // Deliberately zero-tolerance: `tolerance` guards against churn from a
+      // trivial *addition*; mirroring it downward would discard every gain
+      // smaller than the tolerance, which is the leak this branch closes.
+      shrunk.push({
+        tier,
+        current,
+        baseline: baselineBytes,
+        delta: baselineBytes - current,
+      });
     }
+    absent.push(...absentRows(tier, files, baseTier));
   }
-  return { grown, shrunk, skipped };
+  return { grown, shrunk, absent, skipped };
+}
+
+/**
+ * Count the drift entries that fail the gate. Every direction is actionable
+ * (Story #4872), so this is the one place the failure set is defined and both
+ * the summary tag and the exit code read it.
+ *
+ * @param {ReturnType<typeof diffBudget>} diff
+ * @returns {number}
+ */
+export function budgetFailureCount(diff) {
+  return (
+    (diff?.grown?.length ?? 0) +
+    (diff?.shrunk?.length ?? 0) +
+    (diff?.absent?.length ?? 0)
+  );
 }
 
 /**
  * Render the human-readable diff. `+` lines are tiers that grew beyond
- * tolerance (gate fail); `-` lines are tiers that shrank (refreshable
- * baseline). A one-line summary always follows.
+ * tolerance; `-` lines are tiers that shrank below their recorded total or
+ * rows naming a path the tree no longer carries. All three fail the gate. A
+ * one-line summary always follows.
  *
  * @param {ReturnType<typeof diffBudget>} diff
  * @returns {string}
@@ -368,12 +433,17 @@ export function renderDiff(diff) {
   }
   for (const s of diff.shrunk) {
     lines.push(
-      `- ${s.tier}: ${s.current} bytes below baseline ${s.baseline} — refresh baselines/context-budget.json`,
+      `- ${s.tier}: ${s.current} bytes is under the recorded ${s.baseline} (delta -${s.delta}) — the ratchet is holding slack the tree no longer spends; refresh baselines/context-budget.json`,
+    );
+  }
+  for (const a of diff.absent ?? []) {
+    lines.push(
+      `- ${a.tier}: recorded row ${a.path} names a path the measured tier no longer contains — refresh baselines/context-budget.json`,
     );
   }
-  const tag = diff.grown.length > 0 ? '(gate fail)' : '(ok)';
+  const tag = budgetFailureCount(diff) > 0 ? '(gate fail)' : '(ok)';
   lines.push(
-    `[context-budget] grown=${diff.grown.length} shrunk=${diff.shrunk.length} skipped=${diff.skipped.length} ${tag}`,
+    `[context-budget] grown=${diff.grown.length} shrunk=${diff.shrunk.length} absent=${diff.absent?.length ?? 0} skipped=${diff.skipped.length} ${tag}`,
   );
   return lines.join('\n');
 }
@@ -454,7 +524,7 @@ export async function runCli({
   if (!baseline) {
     if (json) {
       stdout.write(
-        `${JSON.stringify({ kind: 'context-budget-report', baselinePath: resolvedBaselinePath, tiers: tierMap.tiers, grown: [], shrunk: [], skipped: GATED_TIERS, exitCode: 0, noBaseline: true }, null, 2)}\n`,
+        `${JSON.stringify({ kind: 'context-budget-report', baselinePath: resolvedBaselinePath, tiers: tierMap.tiers, grown: [], shrunk: [], absent: [], skipped: GATED_TIERS, exitCode: 0, noBaseline: true }, null, 2)}\n`,
       );
     } else {
       stderr.write(
@@ -472,7 +542,7 @@ export async function runCli({
   const bootDrift = agentBootDrift(tierMap, baseline, ceiling);
   const permissiveDrift = bootDrift.filter((d) => d.direction === 'permissive');
   const exitCode =
-    diff.grown.length > 0 ||
+    budgetFailureCount(diff) > 0 ||
     bootOverflow.length > 0 ||
     permissiveDrift.length > 0
       ? 1
@@ -490,6 +560,7 @@ export async function runCli({
       ),
       grown: diff.grown,
       shrunk: diff.shrunk,
+      absent: diff.absent,
       skipped: diff.skipped,
       agentBootCeilingBytes: ceiling,
       agentBootOverflow: bootOverflow,
@@ -527,6 +598,16 @@ export async function runCli({
           `[context-budget] ❌ a documentation tier grew beyond tolerance — refresh the budget consciously with \`node .agents/scripts/check-context-budget.js --update\` once the growth is intentional\n`,
         );
       }
+      if (diff.shrunk.length > 0) {
+        stderr.write(
+          `[context-budget] ❌ a documentation tier came in under its recorded total — the ratchet is holding slack the tree no longer spends, so the next growth would be absorbed silently. Lock the gain in with \`node .agents/scripts/check-context-budget.js --update\`\n`,
+        );
+      }
+      if (diff.absent.length > 0) {
+        stderr.write(
+          `[context-budget] ❌ a recorded row names a path the measured tier no longer contains — its bytes inflate the recorded total against nothing. Refresh with \`node .agents/scripts/check-context-budget.js --update\`\n`,
+        );
+      }
     }
   }
 

package/.agents/scripts/check-cyclomatic.js

@@ -0,0 +1,214 @@
+/**
+ * CLI: ratchet on cyclomatic complexity against
+ * `delivery.quality.codingGuardrails.cyclomaticMustFix` (Story #4923).
+ *
+ * The must-fix ceiling was documented as blocking (`code-quality-guardrails.md`
+ * promises "the close-validation chain refuses the merge") while being read by
+ * nothing. This is the consumer that makes the promise true. It joins the
+ * standalone-ratchet family — `check-arch-cycles.js`, `check-dead-exports.js`,
+ * `check-context-budget.js` — which the CI `baselines` job runs as a required
+ * check, and it follows their contract exactly:
+ *
+ *   - Reads the committed breach baseline at `baselines/cyclomatic.json`
+ *     (override with `--baseline <path>`).
+ *   - Walks the maintainability gate's `targetDirs` / `ignoreGlobs` and scores
+ *     every function with the in-repo escomplex kernel — no coverage artifact
+ *     required, so the verdict is available on a cold checkout.
+ *   - Exit 0 when clean, improved, or shrinking; exit 1 when a file gains an
+ *     over-ceiling function or its worst function gets worse.
+ *
+ * `--update` rewrites the baseline from the current tree. That is the
+ * sanctioned motion after a deliberate refactor lands, and the only way the
+ * recorded breach count is allowed to rise.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { runAsCli } from './lib/cli-utils.js';
+import { getQuality, resolveConfig } from './lib/config-resolver.js';
+import {
+  buildCyclomaticEnvelope,
+  DEFAULT_CYCLOMATIC_BASELINE,
+  diffCyclomaticRows,
+  renderCyclomaticDiff,
+  resolveCyclomaticPolicy,
+  scanCyclomatic,
+} from './lib/cyclomatic-ceiling.js';
+
+/**
+ * Parse `--baseline <path>`, `--json`, and `--update`.
+ *
+ * @param {string[]} argv
+ * @returns {{ baselinePath: string | null, json: boolean, update: boolean }}
+ */
+function parseArgv(argv = []) {
+  let baselinePath = null;
+  let json = false;
+  let update = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--baseline') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        baselinePath = next;
+        i += 1;
+      }
+    } else if (a === '--json') {
+      json = true;
+    } else if (a === '--update') {
+      update = true;
+    }
+  }
+  return { baselinePath, json, update };
+}
+
+/**
+ * Read a breach baseline envelope from disk. Returns `null` when the file is
+ * missing or unparseable — the caller treats that as an empty baseline, which
+ * makes the very first run report every existing breach as `added` rather than
+ * silently passing.
+ *
+ * @param {string} baselinePath
+ * @returns {{ ceiling?: number, rows?: Array<object> } | null}
+ */
+function loadCyclomaticBaseline(baselinePath) {
+  try {
+    if (!fs.existsSync(baselinePath)) return null;
+    const parsed = JSON.parse(fs.readFileSync(baselinePath, 'utf-8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Top-level CLI entry. Exported so tests can drive the whole pipeline through
+ * the injected seams below without spawning a process.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ *   resolveConfigImpl?: typeof resolveConfig,
+ *   scanImpl?: typeof scanCyclomatic,
+ *   loadBaselineImpl?: typeof loadCyclomaticBaseline,
+ *   writeFileImpl?: (p: string, data: string) => void,
+ * }} [opts]
+ * @returns {Promise<number>} 0 = clean / improved; 1 = ratchet breached
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+  resolveConfigImpl = resolveConfig,
+  scanImpl = scanCyclomatic,
+  loadBaselineImpl = loadCyclomaticBaseline,
+  writeFileImpl = (p, data) => fs.writeFileSync(p, data),
+} = {}) {
+  const { baselinePath, json, update } = parseArgv(argv);
+  const quality = getQuality(resolveConfigImpl({ cwd }));
+  const policy = resolveCyclomaticPolicy(quality);
+  const resolvedBaselinePath = path.resolve(
+    cwd,
+    baselinePath ?? DEFAULT_CYCLOMATIC_BASELINE,
+  );
+
+  const scan = scanImpl({
+    targetDirs: policy.targetDirs,
+    ignoreGlobs: policy.ignoreGlobs,
+    ceiling: policy.mustFix,
+    cwd,
+  });
+
+  if (update) {
+    const envelope = buildCyclomaticEnvelope({
+      rows: scan.rows,
+      ceiling: policy.mustFix,
+    });
+    writeFileImpl(
+      resolvedBaselinePath,
+      `${JSON.stringify(envelope, null, 2)}\n`,
+    );
+    stdout.write(
+      `[cyclomatic] wrote ${scan.rows.length} breach row(s) at ceiling c=${policy.mustFix} to ${resolvedBaselinePath}\n`,
+    );
+    return 0;
+  }
+
+  const baseline = loadBaselineImpl(resolvedBaselinePath);
+  const baselineRows = Array.isArray(baseline?.rows) ? baseline.rows : [];
+  const diff = diffCyclomaticRows(baselineRows, scan.rows);
+  const exitCode = diff.added.length + diff.worsened.length > 0 ? 1 : 0;
+
+  if (json) {
+    stdout.write(
+      `${JSON.stringify(
+        {
+          kind: 'cyclomatic-report',
+          ceiling: policy.mustFix,
+          flag: policy.flag,
+          baselinePath: resolvedBaselinePath,
+          baselineCeiling: baseline?.ceiling ?? null,
+          scannedFiles: scan.scannedFiles,
+          parseErrors: scan.parseErrors,
+          baselineRows,
+          currentRows: scan.rows,
+          ...diff,
+          exitCode,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    return exitCode;
+  }
+
+  if (!baseline) {
+    stderr.write(
+      `[cyclomatic] ⚠ baseline not found at ${resolvedBaselinePath} — treating as empty\n`,
+    );
+  } else if (
+    typeof baseline.ceiling === 'number' &&
+    baseline.ceiling !== policy.mustFix
+  ) {
+    stderr.write(
+      `[cyclomatic] ⚠ baseline was recorded at ceiling c=${baseline.ceiling} but the configured cyclomaticMustFix is c=${policy.mustFix} — re-run with --update\n`,
+    );
+  }
+  stdout.write('\n--- cyclomatic preview ---\n');
+  stdout.write(`${renderCyclomaticDiff(diff, policy.mustFix)}\n`);
+  return exitCode;
+}
+
+async function main() {
+  return runCli();
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'cyclomatic',
+  propagateExitCode: true,
+  errorPrefix: '[cyclomatic] ❌ Fatal error',
+  usage: {
+    invocation:
+      'node .agents/scripts/check-cyclomatic.js [--baseline <path>] [--update] [--json]',
+    summary:
+      'Ratchet on cyclomatic complexity: fail when a file gains a function above `delivery.quality.codingGuardrails.cyclomaticMustFix`, or when its worst function gets worse than the recorded baseline.',
+    flags: [
+      [
+        '--baseline <path>',
+        'Baseline file (default: baselines/cyclomatic.json).',
+      ],
+      [
+        '--update',
+        'Rewrite the baseline from the current tree (the post-refactor motion).',
+      ],
+      ['--json', 'Emit the comparison envelope as JSON.'],
+    ],
+    notes: [
+      'Exit codes:\n  0  clean, improved, or shrinking\n  1  a new or worsened over-ceiling function',
+    ],
+  },
+});