mandrel 2.56.0 → 2.58.0

package/.agents/scripts/lib/test-isolate/render-report.js

@@ -0,0 +1,97 @@
+/**
+ * lib/test-isolate/render-report.js — the human-readable `test-isolate` report.
+ *
+ * Story #5316: extracted verbatim from `.agents/scripts/test-isolate.js`,
+ * where no test could reach it (CRAP 72 at cyclomatic 8, 0% coverage). Pure
+ * string building — no I/O, no clock — so the whole surface is assertable.
+ *
+ * The three sections it renders are split into helpers so each is
+ * independently readable and none of them alone approaches the cyclomatic
+ * ceiling; `renderReport` is left as the composition.
+ */
+
+/**
+ * The flipper section: files that passed alone and failed in the suite, plus
+ * the bisection suspects for each.
+ *
+ * @param {string[]} lines Accumulator, appended in place.
+ * @param {import('./runner.js').IsolateReport} report
+ */
+function pushFlipperSection(lines, report) {
+  if (report.flippers.length === 0) {
+    lines.push('✓ No flippers detected — every file that passed alone');
+    lines.push('  also passed in the full suite run.');
+    return;
+  }
+  lines.push(`✗ ${report.flippers.length} flipper(s) detected:`);
+  for (const f of report.flippers) lines.push(`  - ${f}`);
+  lines.push('');
+  if (report.bisections.length === 0) return;
+  lines.push('Likely polluters (bisection suspects):');
+  for (const b of report.bisections) {
+    const tag = b.inconclusive ? ' [inconclusive]' : '';
+    lines.push(`  ${b.file}${tag}`);
+    for (const s of b.suspects) lines.push(`    ← ${s}`);
+  }
+}
+
+/**
+ * One env-mutating file's added/removed/changed summary. Empty parts are
+ * omitted, so a file that only added a var reads as `added=[...]` alone.
+ *
+ * @param {{added: string[], removed: string[], changed: string[]}} envDiff
+ * @returns {string}
+ */
+function formatEnvDiff(envDiff) {
+  const parts = [];
+  if (envDiff.added.length > 0)
+    parts.push(`added=[${envDiff.added.join(', ')}]`);
+  if (envDiff.removed.length > 0) {
+    parts.push(`removed=[${envDiff.removed.join(', ')}]`);
+  }
+  if (envDiff.changed.length > 0) {
+    parts.push(`changed=[${envDiff.changed.join(', ')}]`);
+  }
+  return parts.join(' ');
+}
+
+/**
+ * The env-leak section: files whose process exited with `process.env` still
+ * mutated, called out even when no failure cascade has manifested yet.
+ *
+ * @param {string[]} lines Accumulator, appended in place.
+ * @param {import('./runner.js').IsolateReport} report
+ */
+function pushEnvSection(lines, report) {
+  if (report.envMutators.length === 0) {
+    lines.push('✓ No env-var leaks detected across isolated runs.');
+    return;
+  }
+  lines.push(
+    `⚠ ${report.envMutators.length} file(s) left process.env mutated:`,
+  );
+  for (const m of report.envMutators) {
+    lines.push(`  ${m.file}`);
+    lines.push(`    ${formatEnvDiff(m.envDiff)}`);
+  }
+}
+
+/**
+ * Render the diagnostic report as text.
+ *
+ * @param {import('./runner.js').IsolateReport} report
+ * @returns {string}
+ */
+export function renderReport(report) {
+  const lines = [];
+  lines.push('');
+  lines.push('=== test-isolate diagnostic report ===');
+  lines.push(`Files scanned:  ${report.files.length}`);
+  lines.push(`Wall duration:  ${(report.durationMs / 1000).toFixed(1)}s`);
+  lines.push('');
+  pushFlipperSection(lines, report);
+  lines.push('');
+  pushEnvSection(lines, report);
+  lines.push('');
+  return lines.join('\n');
+}

package/.agents/scripts/lib/test-isolate/run-isolate.js

@@ -0,0 +1,87 @@
+/**
+ * lib/test-isolate/run-isolate.js — the `test-isolate` orchestration.
+ *
+ * Story #5316: moved out of `.agents/scripts/test-isolate.js` (CRAP 56 at
+ * cyclomatic 7, 0% coverage) so it can be driven from a test. The CLI shell
+ * that remains does nothing but call this and translate the exit code.
+ *
+ * `resolveFiles` and `diagnose` are named seams defaulting to the real
+ * implementations, per [`rules/test-seams.md`](../../../rules/test-seams.md):
+ * a unit test substitutes them rather than running real suites in child
+ * processes, and the production caller passes neither.
+ */
+
+import { parseIsolateArgv } from './cli-options.js';
+import { resolveTestFiles as defaultResolveTestFiles } from './list-files.js';
+import { createProgressLogger } from './progress-log.js';
+import { renderReport } from './render-report.js';
+import { diagnoseIsolation as defaultDiagnoseIsolation } from './runner.js';
+
+/**
+ * The report shape returned when no file matched the pattern — a real report
+ * with nothing in it, so callers never branch on null.
+ *
+ * @returns {import('./runner.js').IsolateReport}
+ */
+function emptyReport() {
+  return {
+    pattern: null,
+    files: [],
+    isolated: [],
+    suite: [],
+    flippers: [],
+    bisections: [],
+    envMutators: [],
+    durationMs: 0,
+  };
+}
+
+/**
+ * Run the isolation diagnosis end to end.
+ *
+ * Exit code is 1 when the run found anything worth an operator's attention —
+ * a flipper OR an env mutator — and 0 otherwise. An empty match set is not a
+ * failure: nothing was asked of the suite, so nothing can be wrong with it.
+ *
+ * @param {object} [opts]
+ * @param {string[]} [opts.argv]
+ * @param {string} [opts.repoRoot]
+ * @param {(line: string) => void} [opts.onLog]
+ * @param {(args: {pattern: string|undefined, repoRoot: string}) => string[]} [opts.resolveFiles]
+ * @param {(args: object) => Promise<import('./runner.js').IsolateReport>} [opts.diagnose]
+ * @returns {Promise<{ exitCode: number, report: import('./runner.js').IsolateReport }>}
+ */
+export async function runTestIsolate({
+  argv = [],
+  repoRoot,
+  onLog = (s) => process.stdout.write(`${s}\n`),
+  resolveFiles = defaultResolveTestFiles,
+  diagnose = defaultDiagnoseIsolation,
+} = {}) {
+  const options = parseIsolateArgv(argv);
+  const files = resolveFiles({ pattern: options.pattern, repoRoot });
+  if (files.length === 0) {
+    onLog(
+      `[test-isolate] no test files matched pattern: ${options.pattern ?? '<default>'}`,
+    );
+    return { exitCode: 0, report: emptyReport() };
+  }
+
+  if (!options.quiet) {
+    onLog(`[test-isolate] scanning ${files.length} file(s)...`);
+  }
+  const report = await diagnose({
+    repoRoot,
+    files,
+    workers: options.workers,
+    suiteConcurrency: options.suiteConcurrency,
+    maxBisectDepth: options.maxBisectDepth,
+    maxBisectTargets: options.maxBisectTargets,
+    onProgress: options.quiet ? undefined : createProgressLogger(onLog),
+  });
+
+  onLog(options.json ? JSON.stringify(report, null, 2) : renderReport(report));
+
+  const clean = report.flippers.length === 0 && report.envMutators.length === 0;
+  return { exitCode: clean ? 0 : 1, report };
+}

package/.agents/scripts/lib/test-run-credit.js

@@ -0,0 +1,277 @@
+/**
+ * lib/test-run-credit.js — let a green `npm test` **that routes through
+ * mandrel's own runner** earn the credit close reads (Story #5313, scoped by
+ * Story #5324).
+ *
+ * This is a **bonus, not the contract.** The deposit every project can rely
+ * on is `evidence-gate.js --standalone --scope-id <id> --gate test --worktree
+ * <workCwd> -- npm test`: it spawns whatever `npm test` resolves to and
+ * stamps what it just ran, so it is honest on any runner. What this module
+ * adds is that a repo whose `test` script *is* `run-tests.js` need not type
+ * that wrapper — the runner already knows the tree it ran against, whether
+ * the run was green, and whether it ran the whole suite, so it deposits on
+ * the way out.
+ *
+ * The reach is therefore exactly one call site: `run-tests.js`. A consumer
+ * whose `npm test` is `vitest run` or `jest` never loads this module, so it
+ * deposits nothing **and prints nothing** — silence is not a signal, and no
+ * delivery surface may tell an agent to confirm credit by reading for the
+ * line below. `mandrel doctor`'s `test-credit-path` check reports which of
+ * the two shapes a project is and names the wrapper as the remedy.
+ *
+ * On a green **full-tier** run inside a `story-<id>` checkout the runner
+ * records the `test` gate's evidence in the same keyspace
+ * `close-validation/runner.js` consults — keyed on HEAD and the tree
+ * fingerprint, hashed on the exact `{ cmd: 'npm', args: ['test'], cwd }`
+ * close will spawn — so close's `test` gate short-circuits at unchanged HEAD.
+ * The freshness keying is untouched: a later commit voids the record exactly
+ * as it voids one `evidence-gate.js` wrote.
+ *
+ * What it deliberately does **not** do is write the coverage capture stamp:
+ * that stamp is a claim that `coverage/coverage-final.json` describes this
+ * tree, and a bare `npm test` produces no such artifact. The CRAP gate still
+ * runs `coverage-capture.js` when it needs one.
+ *
+ * Total: every failure — not a Story branch, no git, an unwritable evidence
+ * file — is reported by reason and never fails the test run that earned it.
+ *
+ * @module lib/test-run-credit
+ */
+
+import path from 'node:path';
+
+import { gitSpawn as defaultGitSpawn } from './git-utils.js';
+import {
+  recordPass as defaultRecordPass,
+  shouldSkip as defaultShouldSkip,
+  hashCommandConfig,
+  treeFingerprint,
+} from './validation-evidence.js';
+
+/** The gate name close's runner looks the record up under. */
+const GATE_NAME = 'test';
+
+/** The exact command close spawns for that gate — the hash must match it. */
+const GATE_COMMAND = Object.freeze({
+  cmd: 'npm',
+  args: Object.freeze(['test']),
+});
+
+/**
+ * Read one trimmed git stdout line, or `null` on any failure.
+ *
+ * @param {Function} gitSpawnFn
+ * @param {string} cwd
+ * @param {string[]} args
+ * @returns {string|null}
+ */
+function gitLine(gitSpawnFn, cwd, args) {
+  try {
+    const res = gitSpawnFn(cwd, ...args);
+    if (res?.status !== 0) return null;
+    const line = String(res.stdout ?? '').trim();
+    return line.length > 0 ? line : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The Story id a checkout's branch names, or `null` off a Story branch.
+ *
+ * @param {string|null} branch
+ * @returns {number|null}
+ */
+export function storyIdFromBranch(branch) {
+  const match = /^story-(\d+)$/.exec(branch ?? '');
+  if (!match) return null;
+  const id = Number.parseInt(match[1], 10);
+  return Number.isInteger(id) && id > 0 ? id : null;
+}
+
+/**
+ * The checkout whose temp tree holds the evidence keyspace: the **main**
+ * checkout, which is where close runs with `--cwd <main-repo>`. From a
+ * worktree `git rev-parse --git-common-dir` names the main `.git`; from the
+ * main checkout it names its own. Either way the parent is the checkout.
+ *
+ * @param {string} cwd
+ * @param {Function} gitSpawnFn
+ * @returns {string|null}
+ */
+export function resolveEvidenceRoot(cwd, gitSpawnFn) {
+  const common = gitLine(gitSpawnFn, cwd, ['rev-parse', '--git-common-dir']);
+  if (!common) return null;
+  const absolute = path.resolve(cwd, common);
+  return path.basename(absolute) === '.git' ? path.dirname(absolute) : null;
+}
+
+/**
+ * Deposit the `test` gate's evidence for a green full-suite run.
+ *
+ * @param {{
+ *   cwd: string,
+ *   tier?: string,
+ *   status?: number,
+ *   durationMs?: number|null,
+ *   gitSpawnFn?: typeof defaultGitSpawn,
+ *   recordPassFn?: typeof defaultRecordPass,
+ * }} args
+ * @returns {{ deposited: boolean, reason: string, storyId?: number, sha?: string }}
+ */
+export function depositTestRunCredit({
+  cwd,
+  tier = 'full',
+  status = 0,
+  durationMs = null,
+  gitSpawnFn = defaultGitSpawn,
+  recordPassFn = defaultRecordPass,
+} = {}) {
+  if (status !== 0) return { deposited: false, reason: 'run-not-green' };
+  if (tier !== 'full') return { deposited: false, reason: 'not-full-tier' };
+  const storyId = storyIdFromBranch(
+    gitLine(gitSpawnFn, cwd, ['rev-parse', '--abbrev-ref', 'HEAD']),
+  );
+  if (storyId === null)
+    return { deposited: false, reason: 'not-a-story-branch' };
+  const sha = gitLine(gitSpawnFn, cwd, ['rev-parse', 'HEAD']);
+  const evidenceRoot = resolveEvidenceRoot(cwd, gitSpawnFn);
+  if (!sha || !evidenceRoot) {
+    return { deposited: false, reason: 'tree-unreadable', storyId };
+  }
+  return writeRecord({
+    storyId,
+    sha,
+    cwd,
+    evidenceRoot,
+    durationMs,
+    gitSpawnFn,
+    recordPassFn,
+  });
+}
+
+/**
+ * Deposit and say so on stderr — the runner's one-line hook, printed only
+ * when this runner is the one running. It names the outcome by reason, so a
+ * green run that deposited nothing (wrong branch, partial tier) says so
+ * rather than passing silently; a project on another runner prints no line
+ * at all, which is why absence of this line is never evidence either way.
+ *
+ * @param {Parameters<typeof depositTestRunCredit>[0] & { log?: (line: string) => void }} args
+ * @returns {ReturnType<typeof depositTestRunCredit>}
+ */
+export function reportTestRunCredit({
+  log = (line) => process.stderr.write(`${line}\n`),
+  ...args
+} = {}) {
+  const credit = depositTestRunCredit(args);
+  log(
+    credit.deposited
+      ? `[run-tests] ✓ deposited the close test credit for story #${credit.storyId} at ${credit.sha.slice(0, 7)}`
+      : `[run-tests] no close test credit deposited (${credit.reason})`,
+  );
+  return credit;
+}
+
+/**
+ * Is the `test` gate already credited for this tree — did a green bare
+ * `npm test` in the Story worktree deposit its evidence? The read side of
+ * {@link depositTestRunCredit}, consulted by `close-validation/gates.js`.
+ *
+ * When it did, close registers the plain `test` gate beside the capture gate
+ * even though coverage-capture is the active test runner: the runner's
+ * evidence check then skips it as credited, so close REPORTS the suite the
+ * worker already ran instead of silently folding it into the capture. It is
+ * never a second spend — an uncredited tree resolves `false` and the
+ * pre-#5313 shape (capture alone runs the suite) is unchanged. Every
+ * uncertainty resolves `false`.
+ *
+ * @param {{
+ *   storyId?: number|null,
+ *   cwd?: string,
+ *   evidenceCwd?: string|null,
+ *   gitSpawnImpl?: typeof defaultGitSpawn,
+ *   shouldSkipImpl?: typeof defaultShouldSkip,
+ *   log?: (line: string) => void,
+ * }} opts
+ * @returns {boolean}
+ */
+export function predictsTestEvidenceCredit({
+  storyId,
+  cwd,
+  evidenceCwd,
+  gitSpawnImpl = defaultGitSpawn,
+  shouldSkipImpl = defaultShouldSkip,
+  log,
+} = {}) {
+  if (!Number.isInteger(storyId) || storyId <= 0) return false;
+  if (typeof cwd !== 'string' || cwd.length === 0) return false;
+  try {
+    const sha = gitLine(gitSpawnImpl, cwd, ['rev-parse', 'HEAD']);
+    if (!sha) return false;
+    const verdict = shouldSkipImpl(
+      {
+        storyId,
+        gateName: GATE_NAME,
+        currentSha: sha,
+        configHash: hashCommandConfig({
+          cmd: GATE_COMMAND.cmd,
+          args: [...GATE_COMMAND.args],
+          cwd: path.resolve(cwd),
+        }),
+        inputFingerprint: treeFingerprint(cwd, gitSpawnImpl),
+      },
+      { cwd: evidenceCwd ?? cwd, standalone: true },
+    );
+    if (verdict.skip !== true) return false;
+    log?.(
+      '[close-validation] a green `npm test` already deposited the test credit for this tree — registering the plain `test` gate so close reports it as credited.',
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The write itself, split out so the guard chain above stays flat.
+ *
+ * @param {{ storyId: number, sha: string, cwd: string, evidenceRoot: string, durationMs: number|null, gitSpawnFn: Function, recordPassFn: Function }} args
+ * @returns {{ deposited: boolean, reason: string, storyId: number, sha: string }}
+ */
+function writeRecord({
+  storyId,
+  sha,
+  cwd,
+  evidenceRoot,
+  durationMs,
+  gitSpawnFn,
+  recordPassFn,
+}) {
+  try {
+    recordPassFn(
+      {
+        storyId,
+        gateName: GATE_NAME,
+        sha,
+        configHash: hashCommandConfig({
+          cmd: GATE_COMMAND.cmd,
+          args: [...GATE_COMMAND.args],
+          cwd: path.resolve(cwd),
+        }),
+        exitCode: 0,
+        durationMs,
+        inputFingerprint: treeFingerprint(cwd, gitSpawnFn),
+      },
+      { cwd: evidenceRoot, standalone: true },
+    );
+    return { deposited: true, reason: 'recorded', storyId, sha };
+  } catch (err) {
+    return {
+      deposited: false,
+      reason: `record-failed: ${err?.message ?? err}`,
+      storyId,
+      sha,
+    };
+  }
+}