mandrel 2.31.0 → 2.33.0

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/)

package/.agents/scripts/lib/baselines/scope-assert.js

@@ -0,0 +1,223 @@
+// .agents/scripts/lib/baselines/scope-assert.js
+//
+// Story #5012 — the pure both-directions row-set assertion, plus the
+// merge-base attribution that decides which half of a divergence is this
+// change set's fault.
+//
+// `check-baselines.js` answers "did a measured value regress?". Nothing
+// answered "does this baseline still describe the tree?" — so a row could
+// point at a file deleted six months ago, or an in-scope file could carry no
+// row at all, and every gate stayed green. Both directions are checked here:
+//
+//   - **missing** — an in-scope file with no row. Only asserted for kinds
+//     whose producer emits one row per in-scope file
+//     (`scope-inventory.js#KIND_SCOPE_POLICY`).
+//   - **extra** — a row whose file is gone from disk (`absent`) or no longer
+//     matched by the gate's own `targetDirs` / `ignoreGlobs` (`out-of-scope`).
+//
+// ## Why attribution exists
+//
+// Whole-tree equality on the PR path is unusable: the moment anyone lands an
+// in-scope file, every open PR reds on divergence its author did not create
+// and cannot fix from their branch. So the gate blocks only on divergence
+// attributable to `merge-base(base, HEAD)..HEAD`, and reports the inherited
+// remainder as a warning that costs nothing to carry.
+//
+// Attribution can be wrong in one safe direction only, so the resolution
+// **fails towards strict**: no resolvable base, a HEAD not ahead of its base,
+// or a change set that edits a baseline or the config defining its scope all
+// promote every finding to fatal. The last case is the load-bearing one — once
+// a branch has rewritten the scope rules themselves, "which side of the
+// merge-base introduced this row" is no longer a question the diff can answer.
+//
+// Pure module: no filesystem, no git, no config resolution. Every input is
+// handed in already resolved, which is what lets the whole attribution matrix
+// be unit-tested without a fixture repository.
+
+/** A row whose keyed file no longer exists on disk. */
+const REASON_ABSENT = 'absent';
+/** A row whose file exists but is no longer inside the gate's scope. */
+const REASON_OUT_OF_SCOPE = 'out-of-scope';
+
+export const EXTRA_REASONS = Object.freeze({
+  ABSENT: REASON_ABSENT,
+  OUT_OF_SCOPE: REASON_OUT_OF_SCOPE,
+});
+
+/**
+ * Strictness reasons, in resolution order. Exported so the CLI can render the
+ * cause without restating the strings.
+ */
+export const STRICT_REASONS = Object.freeze({
+  NO_BASE: 'no-resolvable-base',
+  NOT_AHEAD: 'head-not-ahead-of-base',
+  BASELINE_EDITED: 'change-set-edits-a-baseline',
+  SCOPE_CONFIG_EDITED: 'change-set-edits-a-scope-config',
+  ATTRIBUTABLE: 'attributable-to-merge-base-range',
+});
+
+/**
+ * Collect the distinct key values a row set carries, skipping malformed rows.
+ *
+ * @param {Array<Record<string, unknown>>} rows
+ * @param {string} keyField
+ * @returns {Set<string>}
+ */
+function rowKeys(rows, keyField) {
+  const keys = new Set();
+  for (const row of Array.isArray(rows) ? rows : []) {
+    const value = row?.[keyField];
+    if (typeof value === 'string' && value.length > 0) keys.add(value);
+  }
+  return keys;
+}
+
+/**
+ * Compare a baseline's row set against its in-scope inventory.
+ *
+ * Direction gating is the inventory's call, not this function's: a kind whose
+ * policy omits `missing` produces no missing findings even when its row set is
+ * far sparser than the tree, because for that kind sparseness is correct.
+ *
+ * @param {{
+ *   inventory: { kind: string, keyField: string, directions: readonly string[],
+ *     files: string[] | null, degraded: boolean, reason: string | null },
+ *   rows: Array<Record<string, unknown>>,
+ *   existsOnDisk?: (relPath: string) => boolean,
+ * }} params
+ * @returns {{
+ *   kind: string,
+ *   skipped: boolean,
+ *   reason: string | null,
+ *   missing: string[],
+ *   extra: Array<{ path: string, reason: string }>,
+ * }}
+ */
+export function assertScope({ inventory, rows, existsOnDisk } = {}) {
+  const kind = inventory?.kind ?? 'unknown';
+  const directions = inventory?.directions ?? [];
+  if (directions.length === 0 || inventory?.files === null) {
+    return {
+      kind,
+      skipped: true,
+      reason: inventory?.reason ?? `${kind} declares no assertable direction`,
+      missing: [],
+      extra: [],
+    };
+  }
+
+  const keyField = inventory.keyField;
+  const inScope = new Set(inventory.files);
+  const keyed = rowKeys(rows, keyField);
+  const onDisk = typeof existsOnDisk === 'function' ? existsOnDisk : () => true;
+
+  const missing = directions.includes('missing')
+    ? inventory.files.filter((file) => !keyed.has(file)).sort()
+    : [];
+
+  const extra = [];
+  if (directions.includes('extra')) {
+    for (const key of [...keyed].sort()) {
+      if (inScope.has(key)) continue;
+      extra.push({
+        path: key,
+        reason: onDisk(key) ? REASON_OUT_OF_SCOPE : REASON_ABSENT,
+      });
+    }
+  }
+
+  return { kind, skipped: false, reason: null, missing, extra };
+}
+
+/**
+ * Decide whether this run blocks on every finding or only on the attributable
+ * ones. Fails towards strict — each early return below is a case where the
+ * merge-base range cannot be trusted to explain the divergence.
+ *
+ * @param {{
+ *   base?: string | null,
+ *   aheadOfBase?: boolean,
+ *   changedFiles?: string[],
+ *   baselinePaths?: string[],
+ *   scopeConfigPaths?: string[],
+ * }} params
+ * @returns {{ strict: boolean, reason: string }}
+ */
+export function resolveStrictness({
+  base,
+  aheadOfBase,
+  changedFiles = [],
+  baselinePaths = [],
+  scopeConfigPaths = [],
+} = {}) {
+  if (typeof base !== 'string' || base.length === 0) {
+    return { strict: true, reason: STRICT_REASONS.NO_BASE };
+  }
+  if (aheadOfBase !== true) {
+    return { strict: true, reason: STRICT_REASONS.NOT_AHEAD };
+  }
+  const changed = new Set(changedFiles);
+  if (baselinePaths.some((file) => changed.has(file))) {
+    return { strict: true, reason: STRICT_REASONS.BASELINE_EDITED };
+  }
+  if (scopeConfigPaths.some((file) => changed.has(file))) {
+    return { strict: true, reason: STRICT_REASONS.SCOPE_CONFIG_EDITED };
+  }
+  return { strict: false, reason: STRICT_REASONS.ATTRIBUTABLE };
+}
+
+/**
+ * Split a kind's findings into the fatal set and the warning set.
+ *
+ * Under `strict`, everything is fatal. Otherwise a finding is fatal only when
+ * this change set created it:
+ *
+ *   - a **missing** row for a file the range ADDED — the branch introduced an
+ *     in-scope file and left it unmeasured;
+ *   - an **extra** row for a file the range DELETED or renamed away — the
+ *     branch removed the file and left its row behind.
+ *
+ * Everything else is inherited: real, worth reporting, and not this author's
+ * to fix from this branch.
+ *
+ * @param {{
+ *   missing?: string[],
+ *   extra?: Array<{ path: string, reason: string }>,
+ *   added?: string[],
+ *   removed?: string[],
+ *   strict?: boolean,
+ * }} params
+ * @returns {{
+ *   fatal: { missing: string[], extra: Array<{ path: string, reason: string }> },
+ *   warning: { missing: string[], extra: Array<{ path: string, reason: string }> },
+ *   fatalCount: number,
+ *   warningCount: number,
+ * }}
+ */
+export function attributeDivergence({
+  missing = [],
+  extra = [],
+  added = [],
+  removed = [],
+  strict = false,
+} = {}) {
+  const addedSet = new Set(added);
+  const removedSet = new Set(removed);
+  const isFatalMissing = (file) => strict || addedSet.has(file);
+  const isFatalExtra = (finding) => strict || removedSet.has(finding.path);
+
+  const fatal = {
+    missing: missing.filter(isFatalMissing),
+    extra: extra.filter(isFatalExtra),
+  };
+  const warning = {
+    missing: missing.filter((file) => !isFatalMissing(file)),
+    extra: extra.filter((finding) => !isFatalExtra(finding)),
+  };
+  return {
+    fatal,
+    warning,
+    fatalCount: fatal.missing.length + fatal.extra.length,
+    warningCount: warning.missing.length + warning.extra.length,
+  };
+}