mandrel 1.58.0 → 1.59.0

package/.agents/scripts/lib/close-validation/commands.js

@@ -0,0 +1,188 @@
+/**
+ * close-validation/commands.js — Command resolution + formatter file policy.
+ *
+ * Owns the `project.commands.*` resolution helpers used by the close-
+ * validation gates (typecheck / formatCheck / formatWrite), the Story-diff
+ * changed-file listing for the format gate, and the formatter
+ * file-eligibility policy (Story #3410).
+ */
+
+import { execFileSync } from 'node:child_process';
+import { diffNameOnly } from '../changed-files.js';
+import { getCommands } from '../config/commands.js';
+
+/**
+ * Fallback typecheck command — the gate is mandatory by design (Epic-branch
+ * type regressions surface in the next Story's pre-push otherwise).
+ */
+const TYPECHECK_FALLBACK = 'npm run typecheck';
+
+/** Default formatter command when `project.commands.formatCheck` is unset. */
+export const FORMAT_CHECK_FALLBACK = 'npx biome format .';
+
+/** Default formatter command in write mode. */
+const FORMAT_WRITE_FALLBACK = 'npx biome format --write .';
+
+/**
+ * Build the format-gate hint dynamically from the resolved write command so
+ * a Prettier-only repo gets `prettier --write` in its hint, not biome.
+ */
+export function buildFormatHint(writeCmd) {
+  const cmd =
+    writeCmd && writeCmd.trim().length > 0 ? writeCmd : FORMAT_WRITE_FALLBACK;
+  return `Run \`${cmd}\` to auto-fix formatting drift.`;
+}
+
+/**
+ * Resolve a string `project.commands.<key>` with a fallback when the
+ * value is missing, empty, or the resolver throws on malformed config.
+ * Shared engine behind the three resolveX command helpers.
+ *
+ * @param {{ project?: { commands?: object } } | null | undefined} config
+ *   Canonical resolved config (or a bare `{ project: { commands } }` bag).
+ * @param {string} key
+ * @param {string} fallback
+ * @returns {string}
+ */
+function resolveCommandWithFallback(config, key, fallback) {
+  try {
+    // `getCommands` reads `config.project.commands` from the canonical
+    // resolved config.
+    const cmds = getCommands(config);
+    const value = cmds[key];
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return value.trim();
+    }
+  } catch {
+    // Malformed config — fall through to the framework default.
+  }
+  return fallback;
+}
+
+/**
+ * Resolve the typecheck command. Reads `project.commands.typecheck`;
+ * falls back to `npm run typecheck`. The framework-wide
+ * `COMMANDS_DEFAULTS.typecheck` is `null` but this gate is mandatory, so
+ * we apply the fallback here. Exported for testing.
+ *
+ * @param {{ project?: { commands?: object } } | null | undefined} config
+ * @returns {string}
+ */
+export function resolveTypecheckCommand(config) {
+  return resolveCommandWithFallback(config, 'typecheck', TYPECHECK_FALLBACK);
+}
+
+/**
+ * Resolve the format-check command. Reads `project.commands.formatCheck`;
+ * falls back to `npx biome format .` so existing repos keep working byte-
+ * for-byte. Exported for testing.
+ *
+ * @param {{ project?: { commands?: object } } | null | undefined} config
+ * @returns {string}
+ */
+export function resolveFormatCheckCommand(config) {
+  return resolveCommandWithFallback(
+    config,
+    'formatCheck',
+    FORMAT_CHECK_FALLBACK,
+  );
+}
+
+/**
+ * Resolve the format-write command used by story-close format-autofix (and
+ * surfaced in the format-gate hint). Reads `project.commands.formatWrite`;
+ * falls back to `npx biome format --write .`. Exported for testing.
+ *
+ * @param {{ project?: { commands?: object } } | null | undefined} config
+ * @returns {string}
+ */
+export function resolveFormatWriteCommand(config) {
+  return resolveCommandWithFallback(
+    config,
+    'formatWrite',
+    FORMAT_WRITE_FALLBACK,
+  );
+}
+
+/**
+ * Compute the Story-diff file scope for formatter gates. The default Biome
+ * formatter used to run against `.` from inside `.worktrees/story-*`, which
+ * lets consumer ignore globs that exclude `.worktrees` self-exclude the whole
+ * run. Scoping to changed paths keeps verification real without depending on
+ * how consumers spell root ignore patterns.
+ *
+ * @param {{ cwd: string, baseRef: string }} opts
+ * @returns {string[]}
+ */
+export function listChangedFilesForFormatGate({ cwd, baseRef }) {
+  if (!cwd) throw new Error('listChangedFilesForFormatGate: cwd is required');
+  if (!baseRef)
+    throw new Error('listChangedFilesForFormatGate: baseRef is required');
+  // Bridge execFileSync into the gitSpawn(cwd, ...args) contract so
+  // diffNameOnly owns the stdout → path-list conversion.
+  const gitSpawn = (_cwd, ...args) => {
+    try {
+      const stdout = execFileSync('git', args, {
+        cwd: _cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      return { status: 0, stdout, stderr: '' };
+    } catch (err) {
+      return {
+        status: err.status ?? 1,
+        stdout: err.stdout ?? '',
+        stderr: err.stderr ?? err.message,
+      };
+    }
+  };
+  return diffNameOnly({ baseRef, cwd, gitSpawn });
+}
+
+/**
+ * File extensions Biome's formatter can process. Used to filter the
+ * changed-file scope down to the formatter-eligible subset (Story #3410):
+ * passing only ineligible paths (e.g. a docs-only Story whose diff is all
+ * markdown) makes `biome format <files>` report "No files were processed"
+ * and exit 1, failing the gate for a Story that has nothing to format.
+ *
+ * The set mirrors Biome's handled languages (JS/TS family + JSON + CSS).
+ * Markdown, YAML, and other unhandled types are intentionally absent — the
+ * default formatter is biome, so the scope is keyed to what biome formats.
+ * Consumers who swap the formatter via `project.commands.formatCheck`
+ * do not get `changedFileScope` at all (see `buildDefaultGates`), so this
+ * filter only ever runs against the default biome command.
+ */
+const FORMATTER_ELIGIBLE_EXTENSIONS = new Set([
+  'ts',
+  'tsx',
+  'js',
+  'jsx',
+  'mjs',
+  'cjs',
+  'json',
+  'jsonc',
+  'css',
+]);
+
+/**
+ * Whether a changed path is eligible for the default (biome) formatter,
+ * decided purely by file extension. Pure function — no I/O. Exported for
+ * unit coverage (Story #3410).
+ *
+ * @param {string} filePath - A repo-relative path (forward-slash normalized).
+ * @returns {boolean}
+ */
+export function isFormatterEligible(filePath) {
+  if (typeof filePath !== 'string') return false;
+  const lastSlash = Math.max(
+    filePath.lastIndexOf('/'),
+    filePath.lastIndexOf('\\'),
+  );
+  const base = filePath.slice(lastSlash + 1);
+  const dot = base.lastIndexOf('.');
+  // No extension (dotfile-only or extensionless) → not formatter-eligible.
+  if (dot <= 0) return false;
+  const ext = base.slice(dot + 1).toLowerCase();
+  return FORMATTER_ELIGIBLE_EXTENSIONS.has(ext);
+}

package/.agents/scripts/lib/close-validation/gates.js

@@ -0,0 +1,235 @@
+/**
+ * close-validation/gates.js — Gate construction and partitioning.
+ *
+ * Owns the canonical close-validation gate list (`buildDefaultGates` /
+ * `DEFAULT_GATES`) and the parallel-vs-serial partitioning used by the
+ * runner (`INDEPENDENT_GATE_NAMES` / `partitionGates`).
+ */
+
+import {
+  buildFormatHint,
+  FORMAT_CHECK_FALLBACK,
+  resolveFormatCheckCommand,
+  resolveFormatWriteCommand,
+  resolveTypecheckCommand,
+} from './commands.js';
+
+/**
+ * @typedef {Object} Gate
+ * @property {string}   name  - Short label used in progress logs.
+ * @property {string}   cmd   - Executable to run.
+ * @property {string[]} args  - Arguments passed to `cmd`.
+ * @property {string}   [hint] - Remediation hint shown on failure.
+ * @property {{ baseRef: string }} [changedFileScope] - Optional Story-diff scope.
+ * @property {Record<string, string>} [env] - Optional per-gate environment
+ *   overlay. Merged over `process.env` for this gate's spawned child only.
+ *   Used to thread the epic baseRef into the `check-baselines` gate via
+ *   `BASELINE_REF` (Story #3890) so baseline regressions compare against the
+ *   epic integration branch rather than `origin/main`.
+ * @property {(cmd: string, args: string[], opts: { cwd: string, gateName?: string, log?: (m: string) => void, signal?: AbortSignal, env?: Record<string, string> }) => Promise<{ status: number }> | { status: number }} [run]
+ *   - Optional in-process runner. Story #1973: when present, the gate
+ *     executes via this callable instead of spawning `cmd`/`args` through
+ *     the default runner — used for per-kind baseline gates that import
+ *     `compare(head, base)` directly.
+ */
+
+const TYPECHECK_HINT =
+  'TypeScript regression — fix type errors on the Story branch before retrying close. If the failure is a stale generated type (e.g. wrangler types), regenerate locally and commit before the close.';
+
+function buildChangedFileScope(baseRef) {
+  if (!baseRef) return null;
+  return { baseRef };
+}
+
+/**
+ * Derive the per-gate `env` overlay that pins the `check-baselines`
+ * regression-compare base to the close run's integration branch
+ * (Story #3890).
+ *
+ * The baselines gate resolves its compare ref through `resolveScope`,
+ * whose environment layer reads `BASELINE_REF`. Threading
+ * `origin/<epicBranch>` here makes the gate diff head against the epic
+ * integration branch instead of the framework-default `origin/main`, so
+ * drift that already landed on `main` but is outside the Story's own diff
+ * does not surface as a phantom regression. The same convention
+ * (`origin/<epicBranch>`) is used by the baseline-attribution and
+ * auto-refresh paths, keeping read/compare bases aligned.
+ *
+ * Returns `null` when no integration branch is supplied (the gate then
+ * keeps its existing default-ref / consumer-config behaviour untouched).
+ *
+ * @param {string|undefined|null} epicBranch
+ * @returns {{ BASELINE_REF: string } | null}
+ */
+function buildBaselinesGateEnv(epicBranch) {
+  if (typeof epicBranch !== 'string' || epicBranch.length === 0) return null;
+  return { BASELINE_REF: `origin/${epicBranch}` };
+}
+
+/**
+ * Resolve whether the CRAP gate is enabled. When enabled, the close-
+ * validation graph drops the standalone `test` gate because coverage-
+ * capture already runs the suite under c8 instrumentation (Story #1798).
+ *
+ * Reads the single canonical shape `delivery.quality.gates.crap.enabled`
+ * from the resolved config. Defaults to `true` so an omitted setting
+ * matches `CRAP_GATE_DEFAULTS.enabled`. We deliberately do NOT round-trip
+ * through `getQuality()` here because that resolver expects the unresolved
+ * `gates.crap.*` shape.
+ *
+ * @param {object|undefined|null} config - Canonical resolved config.
+ * @returns {boolean}
+ */
+function isCrapGateEnabled(config) {
+  if (!config || typeof config !== 'object') return true;
+  const enabled = config?.delivery?.quality?.gates?.crap?.enabled;
+  return typeof enabled === 'boolean' ? enabled : true;
+}
+
+/**
+ * Conditionally produce the standalone `test` gate entry. Returns an empty
+ * array when the CRAP gate is enabled (Story #1798: coverage-capture is the
+ * canonical test runner in that mode); returns the legacy single-entry
+ * gate otherwise. Splitting this out keeps `buildDefaultGates` flat for
+ * the CRAP-cyclomatic gate.
+ *
+ * @param {object|undefined|null} config - Canonical resolved config.
+ * @returns {Gate[]}
+ */
+function buildTestGateEntry(config) {
+  if (isCrapGateEnabled(config)) return [];
+  return [{ name: 'test', cmd: 'npm', args: ['test'] }];
+}
+
+/**
+ * Build the canonical close-validation gate list.
+ *
+ * Ordering (cheapest fast-fail first): typecheck → lint → [test] →
+ * format → coverage-capture → check-baselines. The standalone `test`
+ * gate is dropped when `crap.enabled === true` (Story #1798) because
+ * coverage-capture carries test-failure signalling under c8 in that
+ * mode.
+ *
+ * `typecheck` is mandatory; consumers may customise the command via
+ * `project.commands.typecheck` (default `npm run typecheck`).
+ *
+ * Story #2210 retired the legacy per-kind in-process regression gates
+ * (`check-maintainability`, `check-crap`, `check-mutation`) and their
+ * shared in-process runner. The unified `check-baselines` gate is now the
+ * single source of truth for per-kind regression enforcement
+ * (attribution-wired floor + tolerance + schema).
+ * The `epicBranch` parameter threads the close run's integration branch
+ * into two gates: the `format` gate's `changedFileScope` (existing) and —
+ * since Story #3890 — the `check-baselines` gate's `BASELINE_REF` env, so
+ * the baselines regression compare diffs head against the epic integration
+ * branch (`origin/<epicBranch>`) rather than the framework-default
+ * `origin/main`. Without this, every child Story on an `epic/<id>` branch
+ * re-discovered inherited main-vs-epic drift in untouched files as phantom
+ * regressions and worked around it by hand-setting `BASELINE_REF`.
+ *
+ * @param {{ config?: object, epicBranch?: string }} [opts] - `config` is the
+ *   canonical resolved config (`{ project, delivery, ... }`); gate commands
+ *   resolve from `project.commands` and the CRAP toggle from
+ *   `delivery.quality.gates.crap.enabled`. `epicBranch` is the close run's
+ *   integration branch (`epic/<id>` for Epic-attached Stories, the base
+ *   branch for standalone Stories).
+ * @returns {Gate[]}
+ */
+export function buildDefaultGates({ config, epicBranch } = {}) {
+  const typecheckCmdString = resolveTypecheckCommand(config);
+  const [typecheckCmd, ...typecheckArgs] = typecheckCmdString
+    .split(/\s+/)
+    .filter(Boolean);
+  const formatCheckString = resolveFormatCheckCommand(config);
+  const [formatCmd, ...formatArgs] = formatCheckString
+    .split(/\s+/)
+    .filter(Boolean);
+  const formatWriteString = resolveFormatWriteCommand(config);
+  const formatChangedFileScope =
+    formatCheckString === FORMAT_CHECK_FALLBACK
+      ? buildChangedFileScope(epicBranch)
+      : null;
+  const baselinesGateEnv = buildBaselinesGateEnv(epicBranch);
+  return [
+    {
+      name: 'typecheck',
+      cmd: typecheckCmd,
+      args: typecheckArgs,
+      hint: TYPECHECK_HINT,
+    },
+    { name: 'lint', cmd: 'npm', args: ['run', 'lint'] },
+    ...buildTestGateEntry(config),
+    {
+      // Gate name kept generic ("format") so the close-orchestrator log line
+      // and the per-gate phase-timer key don't shift when a repo swaps biome
+      // for Prettier / dprint via `project.commands.formatCheck`. The
+      // actual command and the remediation hint resolve from config.
+      name: 'format',
+      cmd: formatCmd,
+      args: formatArgs,
+      hint: buildFormatHint(formatWriteString),
+      ...(formatChangedFileScope
+        ? { changedFileScope: formatChangedFileScope }
+        : {}),
+    },
+    {
+      name: 'coverage-capture',
+      cmd: 'node',
+      args: ['.agents/scripts/coverage-capture.js'],
+      hint: 'Coverage capture failed — `npm run test:coverage` exited non-zero. Fix failing tests or coverage-threshold breaches, then re-run close.',
+    },
+    {
+      // Story #2210 — unified `check-baselines` gate is the only path for
+      // per-kind regression enforcement. The legacy per-kind in-process
+      // gates were retired because their regression-compare semantics are
+      // fully subsumed by this gate's attribution-wired floor + tolerance +
+      // schema enforcement, and running both paths in series was redundant
+      // and conflict-prone.
+      //
+      // `check-baselines.js` self-skips per-kind gates whose
+      // `enabled === false` is configured, so registering it
+      // unconditionally is safe.
+      name: 'check-baselines',
+      cmd: 'node',
+      args: ['.agents/scripts/check-baselines.js', '--format', 'text'],
+      hint: 'Unified baselines gate breached. Inspect the JSON report (`node .agents/scripts/check-baselines.js`) to see which kind/component/axis fell below floor; remediate the underlying file(s) or — when the regression is intentional — refresh the relevant baseline through its per-kind update script and commit with a `baseline-refresh:` tagged subject.',
+      ...(baselinesGateEnv ? { env: baselinesGateEnv } : {}),
+    },
+  ];
+}
+
+/**
+ * Default gate list resolved with no consumer config — uses the
+ * `npm run typecheck` fallback for the typecheck gate. Call sites that have a
+ * resolved config object in scope (e.g. `story-close.js`) should
+ * prefer `buildDefaultGates({ config })` so a configured
+ * `project.commands.typecheck` is honoured.
+ *
+ * @type {Gate[]}
+ */
+export const DEFAULT_GATES = buildDefaultGates();
+
+/**
+ * Gates whose I/O is read-only against the working tree (no shared mutable
+ * state, no overlapping ports/sockets). Safe to run concurrently — see
+ * `runCloseValidation` for the Promise.all + AbortController plumbing.
+ */
+export const INDEPENDENT_GATE_NAMES = new Set(['lint', 'format', 'typecheck']);
+
+/**
+ * Partition a gate list into the parallel-safe set and the order-sensitive
+ * remainder. Order is preserved within each bucket so the serial walk stays
+ * cheapest-fast-fail-first (test → coverage-capture → check-baselines).
+ *
+ * @param {Gate[]} gates
+ * @returns {{ independent: Gate[], serial: Gate[] }}
+ */
+export function partitionGates(gates) {
+  const independent = [];
+  const serial = [];
+  for (const gate of gates) {
+    if (INDEPENDENT_GATE_NAMES.has(gate.name)) independent.push(gate);
+    else serial.push(gate);
+  }
+  return { independent, serial };
+}

package/.agents/scripts/lib/close-validation/process.js

@@ -0,0 +1,101 @@
+/**
+ * close-validation/process.js — Child-process lifecycle plumbing for gates.
+ *
+ * Owns the default async gate runner (spawn + line-prefixed stdio piping)
+ * and the AbortSignal / exit-code helpers it composes.
+ */
+
+import { spawn } from 'node:child_process';
+
+/**
+ * Pipe a child stream's output line-by-line through `emit`, prepending
+ * `prefix` to each line. Tail bytes without a trailing newline flush on
+ * `end` so the operator never loses the last line of a gate's output.
+ */
+function pipePrefixed(stream, prefix, emit) {
+  let buf = '';
+  stream.setEncoding('utf8');
+  stream.on('data', (chunk) => {
+    buf += chunk;
+    while (true) {
+      const nl = buf.indexOf('\n');
+      if (nl === -1) break;
+      emit(prefix + buf.slice(0, nl));
+      buf = buf.slice(nl + 1);
+    }
+  });
+  stream.on('end', () => {
+    if (buf.length > 0) emit(prefix + buf);
+  });
+}
+
+/** Wire the AbortSignal so an abort kills the child. Returns the cleanup fn. */
+export function attachGateAbortHandler(child, signal) {
+  if (!signal) return () => {};
+  const killChild = () => {
+    try {
+      child.kill('SIGTERM');
+    } catch {
+      /* race: already exited */
+    }
+  };
+  if (signal.aborted) {
+    killChild();
+    return () => {};
+  }
+  signal.addEventListener('abort', killChild, { once: true });
+  return () => signal.removeEventListener('abort', killChild);
+}
+
+/** SIGTERM (no exit code) on abort → non-zero so the gate counts as failed. */
+export function gateExitCode(code, sig) {
+  if (typeof code === 'number') return code;
+  return sig ? 143 : 1;
+}
+
+/**
+ * Default async gate runner — used by `runCloseValidation` when no `runner`
+ * is injected. Spawns the gate via `child_process.spawn`, prefixes every
+ * stdout/stderr line with `[gate-name] ` (so concurrent gates don't bleed
+ * into each other in the operator's terminal), and resolves only when the
+ * child exits.
+ *
+ * Honours `opts.signal`: a TERM is delivered to the child the moment the
+ * signal fires, so a sibling gate's failure aborts the rest of the wave
+ * promptly. The promise still resolves (rather than rejecting) on abort —
+ * `runCloseValidation` sees a non-zero status and folds it into the
+ * already-recorded first-failure.
+ *
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{ cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void, env?: Record<string, string> }} opts
+ * @returns {Promise<{ status: number }>}
+ */
+export function defaultGateRunner(cmd, args, opts = {}) {
+  const { cwd, signal, gateName, log, env } = opts;
+  const child = spawn(cmd, args, {
+    cwd,
+    shell: process.platform === 'win32',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    // Per-gate env overlay (Story #3890): merged over the inherited
+    // environment so a gate-scoped `BASELINE_REF` reaches the spawned
+    // `check-baselines` child without mutating the parent process env.
+    ...(env ? { env: { ...process.env, ...env } } : {}),
+  });
+  const prefix = gateName ? `[${gateName}] ` : '';
+  const emit =
+    typeof log === 'function' ? log : (m) => process.stdout.write(`${m}\n`);
+  pipePrefixed(child.stdout, prefix, emit);
+  pipePrefixed(child.stderr, prefix, emit);
+  const detach = attachGateAbortHandler(child, signal);
+  return new Promise((resolve) => {
+    child.on('exit', (code, sig) => {
+      detach();
+      resolve({ status: gateExitCode(code, sig) });
+    });
+    child.on('error', () => {
+      detach();
+      resolve({ status: 1 });
+    });
+  });
+}

package/.agents/scripts/lib/close-validation/projections/maintainability.js

@@ -15,11 +15,11 @@
  * pre-push time.
  */
 
+import { getBaseline } from '../../baselines/maintainability-baseline-io.js';
 import { diffNameOnly } from '../../changed-files.js';
 import { cachedGitFetchSync } from '../../git/cached-fetch.js';
 import { gitSpawn as defaultGitSpawn } from '../../git-utils.js';
 import { calculateForSource } from '../../maintainability-engine.js';
-import { getBaseline } from '../../maintainability-utils.js';
 import { MISSING_ARG_REASONS, validateProjectionInputs } from './inputs.js';
 
 /**