mandrel 2.31.0 → 2.32.0

package/.agents/scripts/lib/baselines/kinds/_crap-read.js

@@ -0,0 +1,150 @@
+/**
+ * _crap-read.js — the CRAP baseline read path (Story #5002).
+ *
+ * Underscore-prefixed like `_shared-metric.js`: a helper for the per-kind
+ * modules in this directory, not a kind of its own. `kinds/crap.js` re-exports
+ * `loadCrapBaseline` so existing importers keep one door.
+ *
+ * **This module is the whole read path, and there is only one.** `crap-utils.js`
+ * used to carry a second one — `projectCrapEnvelopeToLegacy` plus its
+ * `COMPAT_STAMP_*` allow-lists — so `check-baselines` (through
+ * `baselines/reader.js`) and the `quality-preview` pre-commit arm (through that
+ * projection) fed the same compat axes from two hand-maintained field lists. A
+ * stamp added to one and not the other yielded two opposite verdicts on one
+ * envelope, three times over: Story #4866 (`scoringSemantics`,
+ * `tsTranspilerVersion`), #4969 (`rows[].anonymous`), #4986
+ * (`provenanceStamped`). Every one of those axes keys on a POSITIVE marker, so
+ * a dropped field read `undefined` and failed the baseline closed with a remedy
+ * that could not work — re-deriving it wrote the stamp the read path then
+ * discarded. With one reader that drift class is structurally impossible, so no
+ * allow-list needs maintaining.
+ */
+
+import path from 'node:path';
+import { readBaselineAtRef } from '../../baseline-loader.js';
+import { resolveEscomplexVersion } from '../../crap-utils.js';
+import { loadBaseline } from '../../gates/baseline-store.js';
+import {
+  loadFile as loadBaselineFile,
+  load as loadBaselineKind,
+} from '../reader.js';
+
+/**
+ * Read the committed CRAP baseline off the working tree through
+ * `baselines/reader.js` and project it onto the `file`-keyed shape the
+ * comparator and the compat axes consume.
+ *
+ * `baselinePath` selects the explicit-path reader variant (the worktree /
+ * epic-ref callers always know their own path); without one the reader
+ * resolves the configured location for the `crap` kind itself.
+ *
+ * `escomplexVersion` is back-filled from the running scorer exactly as the
+ * deleted projection stamped it — the v2 envelope does not carry the field, and
+ * `escomplex-mismatch` is a fatal axis, so omitting it would fail every
+ * baseline closed on a value that was never on disk.
+ *
+ * Returns `null` on any read/parse/schema failure; the preview gate maps that
+ * to "no baseline" and fails open, as it always did.
+ *
+ * Deliberately module-local: `loadCrapBaseline`'s `readFromTree` default is the
+ * single production door to it, and tests inject their own loader.
+ *
+ * @param {{baselinePath?: string, projectRoot?: string}} [opts]
+ * @returns {object|null}
+ */
+function readCrapBaselineFromTree({ baselinePath, projectRoot } = {}) {
+  const cwd = projectRoot ?? process.cwd();
+  let envelope;
+  try {
+    envelope = baselinePath
+      ? loadBaselineFile(
+          path.isAbsolute(baselinePath)
+            ? baselinePath
+            : path.resolve(cwd, baselinePath),
+          { kind: 'crap' },
+        )
+      : loadBaselineKind('crap', { cwd });
+  } catch {
+    return null;
+  }
+  return {
+    kernelVersion: envelope.kernelVersion,
+    escomplexVersion: resolveEscomplexVersion(),
+    scoringSemantics: envelope.scoringSemantics ?? null,
+    tsTranspilerVersion:
+      typeof envelope.tsTranspilerVersion === 'string'
+        ? envelope.tsTranspilerVersion
+        : null,
+    provenanceStamped: envelope.provenanceStamped,
+    rows: (envelope.rows ?? []).map(projectBaselineRow),
+  };
+}
+
+/**
+ * Re-key one on-disk row (`path`) onto the `file` field `compareCrap` matches
+ * on, carrying the two write-only-when-non-default row markers verbatim.
+ *
+ * Both markers are BASELINE facts. Dropping `anonymous` would leave every
+ * re-keyed row looking like an unmarked anonymous one — precisely the shape the
+ * `anon-identity-unstamped` axis fails closed (Story #4969) — and dropping
+ * `coordinateSystem` would let the comparator drift-resolve across two
+ * coordinate systems (Story #4866).
+ *
+ * @param {{path: string, method: string, startLine: number, crap: number,
+ *   coordinateSystem?: string, anonymous?: boolean}} row
+ * @returns {object}
+ */
+function projectBaselineRow(row) {
+  return {
+    crap: row.crap,
+    file: row.path,
+    method: row.method,
+    startLine: row.startLine,
+    ...(row.coordinateSystem === undefined
+      ? {}
+      : { coordinateSystem: row.coordinateSystem }),
+    ...(row.anonymous === undefined ? {} : { anonymous: row.anonymous }),
+  };
+}
+
+/**
+ * Pure helper: resolve the CRAP baseline either from the working tree (via
+ * `readCrapBaselineFromTree`) or, when `epicRef` is supplied, from
+ * `git show <epicRef>:<baselinePath>` via `readBaselineAtRef`.
+ *
+ * Story #1120 threads `epic/<id>` into close-validation so the comparison runs
+ * against the Epic-branch HEAD's committed baseline. This helper delegates the
+ * read to baseline-store and applies the CRAP shape-check +
+ * `tsTranspilerVersion` back-fill on top.
+ */
+export function loadCrapBaseline({
+  baselinePath,
+  epicRef,
+  readAtRef = readBaselineAtRef,
+  readFromTree = readCrapBaselineFromTree,
+  logger = console,
+}) {
+  const parsed = loadBaseline({
+    baselinePath,
+    epicRef,
+    readAtRef,
+    readFromTree,
+    logger,
+    label: 'CRAP',
+  });
+  // No-epicRef path delegates to readFromTree which already applies the
+  // shape-check + tsTranspilerVersion back-fill, so a tree read returns either
+  // a valid envelope or null. Epic-ref path bypasses that helper — shape-check
+  // + back-fill happens here.
+  if (!epicRef) return parsed;
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return null;
+  }
+  if (typeof parsed.kernelVersion !== 'string') return null;
+  if (typeof parsed.escomplexVersion !== 'string') return null;
+  if (!Array.isArray(parsed.rows)) return null;
+  if (typeof parsed.tsTranspilerVersion !== 'string') {
+    parsed.tsTranspilerVersion = '0.0.0';
+  }
+  return parsed;
+}

package/.agents/scripts/lib/baselines/kinds/crap.js

@@ -13,15 +13,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { readBaselineAtRef } from '../../baseline-loader.js';
 import {
   COORDINATE_ORIGINAL,
   COORDINATE_TRANSPILED,
   deriveFixGuidance,
 } from '../../crap-engine.js';
 import { isAnonymousMethodLabel } from '../../crap-method-identity.js';
-import { getCrapBaseline } from '../../crap-utils.js';
-import { loadBaseline } from '../../gates/baseline-store.js';
 import { Logger } from '../../Logger.js';
 import { resolveTsTranspilerVersion } from '../../transpile.js';
 import {
@@ -31,6 +28,12 @@ import {
 } from '../envelope.js';
 import { canonicalise } from '../path-canon.js';
 import { mergeRowsByScope } from '../scope.js';
+import {
+  buildNewViolation,
+  deriveUncoveredFiles,
+  formatNewViolationMeasure,
+  newMethodGateScore,
+} from './_crap-new-method-gate.js';
 import {
   makeAggregate,
   makeCompare,
@@ -42,6 +45,11 @@ import {
 export const name = 'crap';
 export const keyField = 'path';
 
+// The CRAP baseline read path (Story #5002) lives in `_crap-read.js` — the ONE
+// door, re-exported here so `preview-gates.js` and every existing importer keep
+// reaching it through this module.
+export { loadCrapBaseline } from './_crap-read.js';
+
 const __filename = fileURLToPath(import.meta.url);
 
 /**
@@ -245,18 +253,12 @@ function crapRowKey(row) {
   return `${row.path}::${row.method}@${row.startLine}`;
 }
 
-// `methodIdentityKey` / `indexBaselineRowsByFile` (Story #4981) live in
-// crap-baseline-index.js, not here — `crap-utils.js#scanAndScore` needs them
-// to build the incremental join's per-file baseline lookup, and crap-utils.js
-// already imports `getCrapBaseline` FROM this module. Defining them here and
-// importing them into crap-utils.js would close that edge into a cycle
-// (kinds/crap.js → crap-utils.js → kinds/crap.js). Re-exported here so
-// existing importers of this module keep a single door to the identity key
-// `crapRowKey` composes with the file path.
-export {
-  indexBaselineRowsByFile,
-  methodIdentityKey,
-} from '../../crap-baseline-index.js';
+// `methodIdentityKey` / `indexBaselineRowsByFile` (Story #4981) are now
+// module-local to `crap-baseline-join.js` (Story #5002): after that module
+// absorbed the per-file queue wiring, both callers are inside it, so the
+// exports — and the re-export that used to live here — were reachable from
+// tests alone. `resolveIncrementalContext` is the production door to the
+// index; `crapRowKey` above is the composite key it halves.
 
 /**
  * Pure stabilizer for s-stability-epsilon (Story #1964). CRAP rows match
@@ -395,6 +397,9 @@ export function checkCrapRegression(row, baseline, tolerance, kind) {
  * (`crap: null` / `coverage: null`, or an explicit `unscorable: true`) carries
  * no measurement to compare. It is bucketed and counted, and it is excluded
  * from `comparable` so it cannot dilute any ratio derived from this result.
+ *
+ * **A new method in a wholly-uncovered file is gated on complexity alone**
+ * (Story #5002) — see `newMethodGateScore`.
  */
 export function compareCrap({
   currentRows,
@@ -402,6 +407,7 @@ export function compareCrap({
   newMethodCeiling,
   tolerance,
 }) {
+  const uncoveredFiles = deriveUncoveredFiles(currentRows);
   const exactIndex = new Map();
   const methodIndex = new Map();
   for (const b of baselineRows ?? []) {
@@ -475,14 +481,10 @@ export function compareCrap({
       continue;
     }
 
-    if (row.crap > newMethodCeiling + tolerance) {
+    const gateScore = newMethodGateScore(row, uncoveredFiles);
+    if (gateScore > newMethodCeiling + tolerance) {
       newViolations += 1;
-      violations.push({
-        ...row,
-        kind: 'new',
-        baseline: null,
-        ceiling: newMethodCeiling,
-      });
+      violations.push(buildNewViolation(row, newMethodCeiling, gateScore));
     }
   }
 
@@ -892,48 +894,6 @@ export function assertBaselineCompatible(baseline, ctx = {}) {
   return null;
 }
 
-/**
- * Pure helper: resolve the CRAP baseline either from the working tree
- * (via `getCrapBaseline`) or, when `epicRef` is supplied, from
- * `git show <epicRef>:<baselinePath>` via `readBaselineAtRef`.
- *
- * Story #1120 threads `epic/<id>` into close-validation so the
- * comparison runs against the Epic-branch HEAD's committed baseline.
- * This helper delegates the read to baseline-store and applies the CRAP
- * shape-check + `tsTranspilerVersion` back-fill on top.
- */
-export function loadCrapBaseline({
-  baselinePath,
-  epicRef,
-  readAtRef = readBaselineAtRef,
-  readFromTree = getCrapBaseline,
-  logger = console,
-}) {
-  const parsed = loadBaseline({
-    baselinePath,
-    epicRef,
-    readAtRef,
-    readFromTree,
-    logger,
-    label: 'CRAP',
-  });
-  // No-epicRef path delegates to readFromTree which already applies the
-  // shape-check + tsTranspilerVersion back-fill, so a tree read returns
-  // either a valid envelope or null. Epic-ref path bypasses that helper
-  // — shape-check + back-fill happens here.
-  if (!epicRef) return parsed;
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    return null;
-  }
-  if (typeof parsed.kernelVersion !== 'string') return null;
-  if (typeof parsed.escomplexVersion !== 'string') return null;
-  if (!Array.isArray(parsed.rows)) return null;
-  if (typeof parsed.tsTranspilerVersion !== 'string') {
-    parsed.tsTranspilerVersion = '0.0.0';
-  }
-  return parsed;
-}
-
 /**
  * Build the structured `--json` report envelope.
  *
@@ -1061,7 +1021,7 @@ export function printViolation(v) {
       `[CRAP] ❌ NEW-METHOD over ceiling: ${v.file}::${v.method} (line ${v.startLine})`,
     );
     Logger.error(
-      `       crap=${v.crap.toFixed(2)} > ceiling=${v.ceiling} (c=${v.cyclomatic}, cov=${v.coverage.toFixed(2)})`,
+      `       ${formatNewViolationMeasure(v)} > ceiling=${v.ceiling} (c=${v.cyclomatic}, cov=${v.coverage.toFixed(2)})`,
     );
     return;
   }

package/.agents/scripts/lib/baselines/orphan-pruner.js

@@ -0,0 +1,233 @@
+// .agents/scripts/lib/baselines/orphan-pruner.js
+//
+// Story #5012 — the measurement-free remedy that makes hard-failing on a stale
+// baseline row defensible.
+//
+// The scope gate (`check-baseline-scope.js`) blocks a PR that leaves a row
+// pointing at a file it deleted. A hard gate is only fair while its remedy is
+// cheap, and the existing remedy — re-run the scorer, re-derive the baseline —
+// costs a full coverage run or a full-tree MI re-score for what is arithmetic
+// on a row set. This pruner is that arithmetic.
+//
+// ## Measurement-free by contract
+//
+// Three prohibitions, each guarding a way the file could start lying:
+//
+//   1. **Never add a row.** Adding one means claiming a measurement nobody
+//      took. Producing rows stays the producers' exclusive job.
+//   2. **Never restamp `generatedAt`.** A fresh stamp over rows nobody
+//      re-measured is precisely the failure an age check exists to catch — the
+//      envelope would claim to describe today's tree on the strength of a
+//      deletion. The pruner carries the original stamp through untouched.
+//   3. **Never delete a row it cannot prove inert.** Only two classes qualify:
+//      the file is absent from disk, or the file is no longer matched by the
+//      gate's own `targetDirs` / `ignoreGlobs`. Everything else survives.
+//
+// ## Degrade, never guess
+//
+// A degraded inventory (`files: null` — unreadable `.c8rc.cjs`, absent
+// `targetDirs`) means scope is unknown, not empty. Treating it as empty would
+// make every row look out-of-scope and hand the pruner the whole baseline. So
+// an unreadable scope config falls back to **orphan-only** pruning: the
+// absent-from-disk class still resolves off the filesystem and is still safe,
+// while the out-of-scope class is suspended until scope can be read again.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { getKindModule } from './kernel.js';
+import { _internals as readerInternals } from './reader.js';
+import { EXTRA_REASONS } from './scope-assert.js';
+import {
+  buildScopeInventory,
+  isFileKeyed,
+  SCOPE_KINDS,
+} from './scope-inventory.js';
+import { writeFile } from './writer.js';
+
+/** Every kind whose rows key on a repo-relative file path. */
+export const PRUNABLE_KINDS = Object.freeze(SCOPE_KINDS.filter(isFileKeyed));
+
+/**
+ * Partition a row set into the rows to keep and the rows to drop.
+ *
+ * Pure given its injected `existsOnDisk` predicate. `inScope` of `null` is the
+ * degraded case: only the absent-from-disk class is prunable.
+ *
+ * @param {{
+ *   rows: Array<Record<string, unknown>>,
+ *   inScope: Set<string> | null,
+ *   existsOnDisk: (relPath: string) => boolean,
+ * }} params
+ * @returns {{ keep: Array<object>, removed: Array<{ path: string, reason: string }> }}
+ */
+export function planPrune({ rows, inScope, existsOnDisk } = {}) {
+  const keep = [];
+  const removed = [];
+  for (const row of Array.isArray(rows) ? rows : []) {
+    const key = row?.path;
+    if (typeof key !== 'string' || key.length === 0) {
+      keep.push(row);
+      continue;
+    }
+    if (!existsOnDisk(key)) {
+      removed.push({ path: key, reason: EXTRA_REASONS.ABSENT });
+      continue;
+    }
+    if (inScope !== null && !inScope.has(key)) {
+      removed.push({ path: key, reason: EXTRA_REASONS.OUT_OF_SCOPE });
+      continue;
+    }
+    keep.push(row);
+  }
+  return { keep, removed };
+}
+
+/**
+ * Prune one parsed envelope and recompute its `rollup` through the kind's own
+ * arithmetic (`kinds/<kind>.js#rollup`), so the pruned file stays internally
+ * consistent and still validates against its schema. Recomputing by a private
+ * formula here would let the rollup and the rows describe different trees.
+ *
+ * A rollup carrying component buckets beyond `*` is refused rather than
+ * recomputed: the component globs that produced those buckets live in gate
+ * config this module is not handed, and emitting a `*`-only rollup would
+ * silently delete them.
+ *
+ * @param {{
+ *   kind: string,
+ *   envelope: object,
+ *   inventory: { files: string[] | null },
+ *   existsOnDisk?: (relPath: string) => boolean,
+ * }} params
+ * @returns {{
+ *   envelope: object | null,
+ *   removed: Array<{ path: string, reason: string }>,
+ *   skipped: boolean,
+ *   reason: string | null,
+ * }}
+ */
+export function pruneEnvelope({
+  kind,
+  envelope,
+  inventory,
+  existsOnDisk,
+} = {}) {
+  const rollupKeys = Object.keys(envelope?.rollup ?? {});
+  if (rollupKeys.some((key) => key !== '*')) {
+    return {
+      envelope: null,
+      removed: [],
+      skipped: true,
+      reason: `rollup carries component buckets (${rollupKeys.join(', ')}); prune them with the producer`,
+    };
+  }
+  const inScope = inventory?.files === null ? null : new Set(inventory.files);
+  const { keep, removed } = planPrune({
+    rows: envelope?.rows ?? [],
+    inScope,
+    existsOnDisk: existsOnDisk ?? (() => true),
+  });
+  if (removed.length === 0) {
+    return { envelope: null, removed: [], skipped: false, reason: null };
+  }
+  return {
+    envelope: {
+      ...envelope,
+      // `generatedAt` is carried by the spread, deliberately unmodified.
+      rollup: getKindModule(kind).rollup(keep, []),
+      rows: keep,
+    },
+    removed,
+    skipped: false,
+    reason: null,
+  };
+}
+
+/**
+ * Read and JSON-parse a baseline file. Returns `null` when the file is absent
+ * (a kind this repository does not use) and throws only on malformed JSON,
+ * which is a real defect the caller should surface rather than swallow.
+ *
+ * @param {string} absPath
+ * @param {typeof fs} fsImpl
+ * @returns {object | null}
+ */
+function readEnvelope(absPath, fsImpl) {
+  let raw;
+  try {
+    raw = fsImpl.readFileSync(absPath, 'utf8');
+  } catch {
+    return null;
+  }
+  return JSON.parse(raw);
+}
+
+/**
+ * Prune one kind end to end: resolve its baseline path, read it, build the
+ * scope inventory, plan, and (unless `check`) write.
+ *
+ * @param {object} params
+ * @returns {object} One entry of the report's `kinds` array.
+ */
+function pruneKind({ kind, cwd, quality, check, fsImpl, requireFn }) {
+  const absPath = readerInternals.resolveBaselinePath(kind, { cwd });
+  const relPath = path.relative(cwd, absPath).split(path.sep).join('/');
+  const envelope = readEnvelope(absPath, fsImpl);
+  if (envelope === null) {
+    return { kind, path: relPath, present: false, removed: [], written: false };
+  }
+  const inventory = buildScopeInventory({ kind, cwd, quality, requireFn });
+  const result = pruneEnvelope({
+    kind,
+    envelope,
+    inventory,
+    existsOnDisk: (rel) => fsImpl.existsSync(path.resolve(cwd, rel)),
+  });
+  const base = {
+    kind,
+    path: relPath,
+    present: true,
+    degraded: inventory.degraded,
+    degradedReason: inventory.degraded ? inventory.reason : null,
+    skipped: result.skipped,
+    skipReason: result.reason,
+    removed: result.removed,
+    written: false,
+  };
+  if (result.envelope === null || check) return base;
+  writeFile(absPath, result.envelope, { fsImpl });
+  return { ...base, written: true };
+}
+
+/**
+ * Prune every file-keyed baseline under `cwd`.
+ *
+ * @param {{
+ *   cwd?: string,
+ *   kinds?: string[],
+ *   check?: boolean,
+ *   quality?: object,
+ *   fsImpl?: typeof fs,
+ *   requireFn?: (id: string) => object,
+ * }} params
+ * @returns {{ kinds: Array<object>, removedCount: number, writtenCount: number, check: boolean }}
+ */
+export function runPrune({
+  cwd = process.cwd(),
+  kinds = PRUNABLE_KINDS,
+  check = false,
+  quality,
+  fsImpl = fs,
+  requireFn,
+} = {}) {
+  const results = kinds.map((kind) =>
+    pruneKind({ kind, cwd, quality, check, fsImpl, requireFn }),
+  );
+  return {
+    check,
+    kinds: results,
+    removedCount: results.reduce((sum, r) => sum + r.removed.length, 0),
+    writtenCount: results.filter((r) => r.written).length,
+  };
+}

package/.agents/scripts/lib/baselines/refresh-service.js

@@ -76,11 +76,10 @@
  * @module .agents/scripts/lib/baselines/refresh-service
  */
 
-import { execFile as nodeExecFile } from 'node:child_process';
 import nodeFs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { promisify } from 'node:util';
+import { execFileCaptureAsync } from '../child-exec.js';
 import { getQuality, resolveConfig } from '../config-resolver.js';
 import {
   buildScopePredicate,
@@ -107,8 +106,6 @@ import {
 
 const nodeRequire = createRequire(import.meta.url);
 
-const execFileAsync = promisify(nodeExecFile);
-
 /**
  * Kinds the refresh service knows how to dispatch. Stays in lockstep with
  * the per-kind modules under `.agents/scripts/lib/baselines/kinds/`.
@@ -574,8 +571,9 @@ function assertRequiredScopeRows({
 }
 
 /**
- * Default git-diff derivation for the diff-scope path. Uses `execFile`
- * (no shell) and only the canonical two-dot range `baseRef..headRef` —
+ * Default git-diff derivation for the diff-scope path. Runs through the shared
+ * child-process surface ([`child-exec.js`](../child-exec.js)) — `execFile`,
+ * never a shell — and only the canonical two-dot range `baseRef..headRef`:
  * triple-dot is intentionally avoided so the result reflects exactly the
  * files that differ between the two refs at the time of the call.
  *
@@ -585,10 +583,10 @@ function assertRequiredScopeRows({
 async function defaultGitDiff({ baseRef, headRef, cwd }) {
   const range = `${baseRef}..${headRef}`;
   try {
-    const { stdout } = await execFileAsync(
+    const { stdout } = await execFileCaptureAsync(
       'git',
       ['diff', '--name-only', range],
-      { cwd, maxBuffer: 16 * 1024 * 1024 },
+      { cwd },
     );
     return stdout
       .split(/\r?\n/)