mandrel 2.30.0 → 2.32.0

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,
+  };
+}

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

@@ -0,0 +1,314 @@
+// .agents/scripts/lib/baselines/scope-inventory.js
+//
+// Story #5012 — the ONE in-scope file inventory the honesty surface reads.
+//
+// A ratchet gate can be green while measuring almost nothing: nothing checks
+// that a committed baseline's row set still describes the tree it claims to
+// describe. Both instruments that now do — `check-baseline-scope.js` (assert)
+// and `prune-baseline-orphans.js` (remedy) — resolve "which files is this kind
+// supposed to have rows for?" through this module, so the gate and the pruner
+// cannot disagree about scope and start fighting each other.
+//
+// ## Recompute from the gate's own config, never from a second walker
+//
+// The inventory is derived from **the same configuration the kind's refresh
+// scorer reads**, through the same helpers:
+//
+//   - `coverage` — `.c8rc.cjs` `include` / `exclude`, applied with
+//     `coverage-baseline.js#buildScopePredicate`, exactly as
+//     `refresh-service.js#buildDefaultCoverageScorer` does.
+//   - every other file-keyed kind — `delivery.quality.gates.<kind>.targetDirs`
+//     / `.ignoreGlobs`, walked with `maintainability-utils.js#scanDirectory`,
+//     exactly as `refresh-service.js#buildDefaultMaintainabilityScorer` does.
+//
+// A second walker written here would report the two implementations
+// disagreeing as divergence — the same failure mode
+// `check-baseline-drift.js` avoids by re-scoring through
+// `resolveDefaultScorer` rather than a private scorer.
+//
+// ## Measurement-free by contract
+//
+// Nothing in this module runs a scorer, reads `coverage/coverage-final.json`,
+// or needs a test run to have happened. It walks directories and matches
+// globs. That is what makes the gate runnable on any checkout, which is in
+// turn what makes hard-failing on a stale row defensible.
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { buildScopePredicate } from '../coverage-baseline.js';
+import { scanDirectory } from '../maintainability-utils.js';
+
+/**
+ * Per-kind classification of which divergence directions may be asserted.
+ *
+ * **Only a kind whose producer emits one row per in-scope file may assert the
+ * MISSING direction.** This is not a conservatism knob — it is arithmetic.
+ * Measured against this repository on 2026-08-05, asserting MISSING densely
+ * yields 128 phantom rows for `crap` (rows are per-method and coverage-gated,
+ * so a file with no scorable method legitimately has none) and 510 for
+ * `duplication` (a row exists only where a clone was found). A gate that
+ * reports 638 phantom findings on a healthy tree is a gate nobody reads.
+ *
+ * `lint` and `mutation` are sparse for the same reason — a clean file has no
+ * lint row, an untested file has no mutation row. `lighthouse` (keyed on
+ * `route`) and `bundle-size` (keyed on `bundle`) are not file-keyed at all, so
+ * neither direction is meaningful: their keys name artefacts, not paths on
+ * disk, and a directory walk can say nothing about them.
+ *
+ * @type {Readonly<Record<string, { keyField: string, directions: readonly string[] }>>}
+ */
+export const KIND_SCOPE_POLICY = Object.freeze({
+  coverage: Object.freeze({
+    keyField: 'path',
+    directions: Object.freeze(['missing', 'extra']),
+  }),
+  maintainability: Object.freeze({
+    keyField: 'path',
+    directions: Object.freeze(['missing', 'extra']),
+  }),
+  crap: Object.freeze({
+    keyField: 'path',
+    directions: Object.freeze(['extra']),
+  }),
+  duplication: Object.freeze({
+    keyField: 'path',
+    directions: Object.freeze(['extra']),
+  }),
+  lint: Object.freeze({
+    keyField: 'path',
+    directions: Object.freeze(['extra']),
+  }),
+  mutation: Object.freeze({
+    keyField: 'path',
+    directions: Object.freeze(['extra']),
+  }),
+  lighthouse: Object.freeze({
+    keyField: 'route',
+    directions: Object.freeze([]),
+  }),
+  'bundle-size': Object.freeze({
+    keyField: 'bundle',
+    directions: Object.freeze([]),
+  }),
+});
+
+/** Every kind the honesty surface knows about, in report order. */
+export const SCOPE_KINDS = Object.freeze(Object.keys(KIND_SCOPE_POLICY));
+
+/**
+ * The directions `kind` may assert. Unknown kinds assert nothing — a kind this
+ * module has never heard of has no scope model, and inventing one would be the
+ * phantom-row failure above with extra steps.
+ *
+ * @param {string} kind
+ * @returns {readonly string[]}
+ */
+export function directionsFor(kind) {
+  return KIND_SCOPE_POLICY[kind]?.directions ?? [];
+}
+
+/**
+ * The row field `kind` keys on — `path` for the file-keyed kinds, `route` for
+ * lighthouse, `bundle` for bundle-size. Mirrors `kinds/<kind>.js#keyField`;
+ * kept here so a caller can classify without importing the kernel.
+ *
+ * @param {string} kind
+ * @returns {string}
+ */
+export function keyFieldFor(kind) {
+  return KIND_SCOPE_POLICY[kind]?.keyField ?? 'path';
+}
+
+/**
+ * True when `kind` keys its rows on a repo-relative file path, so a directory
+ * walk can be compared against its row set at all.
+ *
+ * @param {string} kind
+ * @returns {boolean}
+ */
+export function isFileKeyed(kind) {
+  return keyFieldFor(kind) === 'path' && Object.hasOwn(KIND_SCOPE_POLICY, kind);
+}
+
+/** Glob metacharacters that end a pattern's literal prefix. */
+const GLOB_META = /[*?[\]{}!+@()]/;
+
+/**
+ * Derive directory roots to walk from a list of include globs, by taking each
+ * pattern's literal leading path segments.
+ *
+ * The coverage gate's schema is closed and declares no `targetDirs` — its
+ * scope lives entirely in `.c8rc.cjs`. Without this derivation the coverage
+ * walk has no root to start from, so there is nothing to compare the row set
+ * against and the whole MISSING direction goes silently inert for the one kind
+ * whose producer is densest.
+ *
+ * `'.agents/scripts/**'` yields `.agents/scripts`; a pattern that is glob from
+ * its first segment (`'**​/*.js'`) yields `.`, the repo root.
+ *
+ * @param {string[]} globs
+ * @returns {string[]} De-duplicated roots, repo-relative POSIX.
+ */
+export function deriveWalkRoots(globs) {
+  const roots = new Set();
+  for (const glob of Array.isArray(globs) ? globs : []) {
+    if (typeof glob !== 'string' || glob.length === 0) continue;
+    const literal = [];
+    for (const segment of glob.split('/')) {
+      if (GLOB_META.test(segment)) break;
+      literal.push(segment);
+    }
+    roots.add(literal.join('/') || '.');
+  }
+  return [...roots];
+}
+
+/**
+ * Walk `roots` under `cwd` and return canonical repo-relative POSIX paths.
+ *
+ * Delegates to `scanDirectory`, which already owns the supported-extension set
+ * and the ignored-directory set (`node_modules`, `.git`, `temp`, `.worktrees`,
+ * …) that every scorer walks with. Passing `ignoreGlobs` straight through
+ * means an ignored file is dropped by the identical matcher the scorer uses.
+ *
+ * @param {{ cwd: string, roots: string[], ignoreGlobs?: string[] }} params
+ * @returns {string[]}
+ */
+function walkRoots({ cwd, roots, ignoreGlobs = [] }) {
+  const absolute = [];
+  for (const root of roots) {
+    const abs = path.isAbsolute(root) ? root : path.resolve(cwd, root);
+    scanDirectory(abs, absolute, { cwd, ignoreGlobs });
+  }
+  return absolute.map((abs) =>
+    path.relative(cwd, abs).split(path.sep).join('/'),
+  );
+}
+
+/**
+ * Build the coverage inventory from `.c8rc.cjs`.
+ *
+ * Roots come from the literal prefixes of `include`; the walked set is then
+ * filtered through the same `buildScopePredicate` the coverage scorer applies,
+ * so `exclude` is honoured by one implementation rather than two.
+ *
+ * @param {{ cwd: string, requireFn?: (id: string) => object }} params
+ * @returns {{ files: string[] | null, roots: string[], degraded: boolean, reason: string | null }}
+ */
+function coverageInventory({ cwd, requireFn }) {
+  const load = requireFn ?? createRequire(path.join(cwd, 'noop.cjs'));
+  let config;
+  try {
+    config = load(path.resolve(cwd, '.c8rc.cjs'));
+  } catch (err) {
+    return {
+      files: null,
+      roots: [],
+      degraded: true,
+      reason: `.c8rc.cjs unreadable: ${err?.message ?? err}`,
+    };
+  }
+  const include = Array.isArray(config?.include) ? config.include : [];
+  const exclude = Array.isArray(config?.exclude) ? config.exclude : [];
+  if (include.length === 0) {
+    return {
+      files: null,
+      roots: [],
+      degraded: true,
+      reason: '.c8rc.cjs declares no include globs',
+    };
+  }
+  const roots = deriveWalkRoots(include);
+  const inScope = buildScopePredicate({ include, exclude });
+  return {
+    files: walkRoots({ cwd, roots }).filter(inScope),
+    roots,
+    degraded: false,
+    reason: null,
+  };
+}
+
+/**
+ * Build the inventory for a `targetDirs`-configured kind (everything except
+ * coverage). Reads the gate's own `targetDirs` / `ignoreGlobs` off the
+ * normalized quality block — the same two keys its refresh scorer reads.
+ *
+ * @param {{ kind: string, cwd: string, gate: object }} params
+ * @returns {{ files: string[] | null, roots: string[], degraded: boolean, reason: string | null }}
+ */
+function targetDirsInventory({ kind, cwd, gate }) {
+  const roots = Array.isArray(gate?.targetDirs) ? gate.targetDirs : [];
+  const ignoreGlobs = Array.isArray(gate?.ignoreGlobs) ? gate.ignoreGlobs : [];
+  if (roots.length === 0) {
+    return {
+      files: null,
+      roots: [],
+      degraded: true,
+      reason: `delivery.quality.gates.${kind}.targetDirs is empty or unset`,
+    };
+  }
+  return {
+    files: walkRoots({ cwd, roots, ignoreGlobs }),
+    roots,
+    degraded: false,
+    reason: null,
+  };
+}
+
+/**
+ * Resolve the set of files `kind` is configured to have rows for.
+ *
+ * Never throws: an unreadable or absent scope config degrades to
+ * `{ files: null, degraded: true, reason }`. Callers treat a degraded
+ * inventory as "scope unknown" — the gate reports it and skips that kind's
+ * scope directions, the pruner falls back to orphan-only pruning. Neither may
+ * infer emptiness from it: a `files: []` inventory would make every committed
+ * row look out-of-scope and hand the pruner a licence to delete the baseline.
+ *
+ * @param {{
+ *   kind: string,
+ *   cwd?: string,
+ *   quality?: object,
+ *   requireFn?: (id: string) => object,
+ * }} params
+ * @returns {{
+ *   kind: string,
+ *   keyField: string,
+ *   directions: readonly string[],
+ *   files: string[] | null,
+ *   roots: string[],
+ *   degraded: boolean,
+ *   reason: string | null,
+ * }}
+ */
+export function buildScopeInventory({
+  kind,
+  cwd = process.cwd(),
+  quality,
+  requireFn,
+} = {}) {
+  const base = {
+    kind,
+    keyField: keyFieldFor(kind),
+    directions: directionsFor(kind),
+  };
+  if (!isFileKeyed(kind)) {
+    return {
+      ...base,
+      files: null,
+      roots: [],
+      degraded: false,
+      reason: `${kind} is not file-keyed (rows key on "${base.keyField}")`,
+    };
+  }
+  const resolved =
+    kind === 'coverage'
+      ? coverageInventory({ cwd, requireFn })
+      : targetDirsInventory({
+          kind,
+          cwd,
+          gate: quality?.gates?.[kind] ?? {},
+        });
+  return { ...base, ...resolved };
+}