Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
38.9 KB
Raw Blame
#!/usr/bin/env bun
/**
 * scripts/contributor-audit.ts — mechanical audit of contributor merges and open PRs.
 *
 *   bun run audit:contributors <base>..<head> [--prs <manifest>] [--json]
 *
 * For every first-parent commit in <base>..<head> (each merged PR) and every PR
 * head named in the --prs manifest (trial-merged onto <head>), the driver asks
 * one question: do the tests that change brought fail when its product code is
 * taken away? In an isolated checkout of <head> (or of the trial merge) it:
 *
 *   1. runs the change's test files and requires a green baseline;
 *   2. reverses exactly that change's product hunks (non-test, non-doc):
 *      `git diff --binary M^1 M -- <product files> | git apply -R`, so later
 *      fixes to the same files stay in place (no whole-file revert);
 *   3. re-runs the tests and classifies the run;
 *   4. re-applies the hunks, checks the tree is byte-identical, and re-verifies
 *      green.
 *
 * When the hunks no longer apply at <head> (later commits rewrote them), the
 * merge is audited at its own merge commit instead and the row says so.
 *
 * Results reuse the vocabulary of scripts/check-test-discriminates.sh plus
 * three of their own:
 *   discriminates          tests fail with the product hunks reversed
 *   does_not_discriminate  tests pass with the product hunks reversed
 *   vacuous_failure        non-zero exit but no executed test failed (crash, timeout)
 *   setup_failed           baseline red, install failed, hunks would not reverse,
 *                          or the restored tree did not go green again
 *   conflict               the PR head does not merge cleanly onto <head>
 *   not_audited            nothing to prove (no product change, no tests, none ran)
 * Mechanical results never overwrite human verdicts; those live in a separate
 * verdicts file (accept | rework | reject | not_yet_proven) and print in their
 * own column.
 *
 * Untrusted code (bun install, the tests) runs under `env -i` with an
 * allowlist: a temporary HOME and GBRAIN_HOME, no credential files, and both
 * DATABASE_URL and GBRAIN_DATABASE_URL cleared unless --postgres names a
 * test-shaped database. Lifecycle scripts are skipped (`--ignore-scripts`).
 *
 * Global checks run from THIS checkout (never the audited tree's copy):
 * scripts/wave-security-scan.sh over the range and each PR, and
 * scripts/check-postgres-lane-coverage.ts over <head> and each trial merge.
 *
 * Exit codes:
 *   0    every change discriminates (or changes no product code) and every check passed
 *   1    at least one change or check needs a human look
 *   2    usage or preflight refusal (an agent-contract error envelope)
 *   130  interrupted; finished cases are saved, rerun with --resume
 *
 * Docs: docs/TESTING.md ("Contributor audit"), docs/RELEASING.md (community PR wave).
 */
import { spawn, spawnSync } from 'node:child_process';
import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, writeSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join, resolve } from 'node:path';
import type { Action } from '../src/core/agent-output.ts';
import { renderCliError } from '../src/core/agent-output.ts';
import { parseReleasePackage } from '../src/core/bun-floor.ts';
import { opError } from '../src/core/ops/contract.ts';
import { assertSafeE2eDatabaseUrl } from '../test/helpers/db-guard.ts';

const TOOL_ROOT = join(import.meta.dir, '..');
const COMMAND = 'audit:contributors';
const DOCS = 'docs/TESTING.md#contributor-audit';
const STATE_VERSION = 1;

export type Mechanical = 'discriminates' | 'does_not_discriminate' | 'vacuous_failure' | 'setup_failed' | 'conflict' | 'not_audited';
export type HumanVerdict = 'accept' | 'rework' | 'reject' | 'not_yet_proven';
const HUMAN_VERDICTS: readonly HumanVerdict[] = ['accept', 'rework', 'reject', 'not_yet_proven'];

export interface Options {
  range: string; prs?: string; json: boolean; postgres?: string; resume: boolean; runDir?: string;
  stepTimeoutSec: number; verdicts?: string; skipSecurity: boolean; skipLanes: boolean; keepWorktrees: boolean; help: boolean;
}
export interface RunCounts { exit: number; pass: number; fail: number; timedOut: boolean }
export interface CaseResult {
  id: string; kind: 'merge' | 'pr'; sha: string; parent: string; pr?: number; author: string; subject: string;
  result: Mechanical; reason?: string; audited_at?: string; tests: string[]; product_files: number;
  runs: { baseline?: RunCounts; reversed?: RunCounts; restored?: RunCounts };
  lanes?: CheckResult; security?: CheckResult; seconds: number;
}
export interface CheckResult { status: 'pass' | 'review' | 'skipped'; detail: string }
interface PinnedPr { number?: number; head: string; ref?: string }
interface State {
  version: number; base: string; head: string; prs: PinnedPr[];
  cases: Record<string, CaseResult>; checks: { security?: CheckResult; lanes?: CheckResult };
}

const action = (argv: string[], why: string, extra: Partial<Action> = {}): Action =>
  ({ argv, consent: [], actor: 'agent', why, requires_exclusive: false, ...extra });
const helpFix = () => action(['bun', 'run', COMMAND, '--help'], 'Prints every flag, the range form and the exit codes.');

// ── pure helpers (exported for tests) ──────────────────────────────────────

const TEST_PATH = /(^|\/)(test|tests|__tests__)\/|\.(test|spec)\.[cm]?[jt]sx?$/;
const DOC_PATH = /(^|\/)docs\/|\.(md|mdx)$|^llms(-full)?\.txt$/i;
const RUNNABLE_TEST = /\.test\.[cm]?[jt]sx?$/;

export function classifyPath(path: string): 'test' | 'doc' | 'product' {
  if (TEST_PATH.test(path)) return 'test';
  if (DOC_PATH.test(path)) return 'doc';
  return 'product';
}

export function parseCounts(output: string): { pass: number; fail: number } {
  const last = (re: RegExp) => { const all = [...output.matchAll(re)]; return all.length ? Number(all[all.length - 1][1]) : 0; };
  return { pass: last(/^\s*(\d+) pass\b/gm), fail: last(/^\s*(\d+) fail\b/gm) };
}

/** The discrimination verdict for the run with the product hunks reversed. */
export function classifyReversed(run: RunCounts): { result: Mechanical; reason?: string } {
  if (run.timedOut) return { result: 'vacuous_failure', reason: 'timeout' };
  if (run.exit === 0) return { result: 'does_not_discriminate' };
  if (run.fail === 0) return { result: 'vacuous_failure', reason: 'no_test_failed' };
  return { result: 'discriminates' };
}

export function isTestShapedDatabaseUrl(url: string): boolean {
  try { assertSafeE2eDatabaseUrl(url, {}); return true; } catch { return false; }
}

/** The complete environment untrusted code sees. Nothing from the caller's environment passes through. */
export function sandboxEnv(o: { home: string; bunPath: string; cacheDir: string; postgresUrl?: string }): Record<string, string> {
  return {
    PATH: [dirname(o.bunPath), '/usr/local/bin', '/usr/bin', '/bin'].join(':'),
    HOME: o.home,
    GBRAIN_HOME: join(o.home, '.gbrain'),
    TMPDIR: join(o.home, 'tmp'),
    LANG: 'C.UTF-8',
    LC_ALL: 'C.UTF-8',
    TERM: 'dumb',
    NO_COLOR: '1',
    CI: '1',
    GIT_CONFIG_NOSYSTEM: '1',
    GIT_CONFIG_GLOBAL: '/dev/null',
    GIT_TERMINAL_PROMPT: '0',
    BUN_INSTALL_CACHE_DIR: o.cacheDir,
    DATABASE_URL: o.postgresUrl ?? '',
    GBRAIN_DATABASE_URL: '',
    ...(o.postgresUrl ? { GBRAIN_TEST_ALLOW_DATABASE_URL: '1' } : {}),
  };
}

export function prNumberFromSubject(subject: string): number | undefined {
  const m = /^Merge pull request #(\d+)\b/.exec(subject) ?? /\(#(\d+)\)\s*$/.exec(subject);
  return m ? Number(m[1]) : undefined;
}

const short = (sha: string) => sha.slice(0, 9);
const cell = (s: string) => s.replace(/\|/g, '\\|').replace(/\n/g, ' ');

export function renderMarkdown(state: State, verdicts: Record<string, { verdict?: string; note?: string }>): string {
  const counts = (r?: RunCounts) => r ? `${r.pass}✓/${r.fail}✗${r.timedOut ? ' (timeout)' : ''}` : '–';
  const lines = [
    `## Contributor audit \`${short(state.base)}..${short(state.head)}\``,
    '',
    '| Case | PR | Author | Mechanical | Detail | Baseline → reversed → restored | Lanes | Security | Human verdict |',
    '|---|---|---|---|---|---|---|---|---|',
  ];
  for (const c of Object.values(state.cases)) {
    const detail = [c.reason, c.audited_at ? `audited at ${short(c.audited_at)}` : '', c.tests.length ? `${c.tests.length} test file(s)` : ''].filter(Boolean).join('; ');
    const human = verdicts[c.id] ? `${verdicts[c.id].verdict}${verdicts[c.id].note ? `: ${verdicts[c.id].note}` : ''}` : 'pending';
    lines.push(`| ${c.kind} \`${short(c.sha)}\` ${cell(c.subject.slice(0, 60))} | ${c.pr ? `#${c.pr}` : '–'} | ${cell(c.author)} | **${c.result}** | ${cell(detail || '–')} | ${counts(c.runs.baseline)} → ${counts(c.runs.reversed)} → ${counts(c.runs.restored)} | ${c.lanes?.status ?? '–'} | ${c.security?.status ?? '–'} | ${cell(human)} |`);
  }
  const check = (name: string, r?: CheckResult) => `- ${name}: **${r?.status ?? 'not run'}**${r?.detail ? ` (${cell(r.detail)})` : ''}`;
  lines.push('', check('wave-security-scan over the range', state.checks.security), check('check:postgres-lanes at head', state.checks.lanes), '',
    'Mechanical results come from the driver; human verdicts come only from the verdicts file. A green mechanical row is evidence, not acceptance.');
  return lines.join('\n') + '\n';
}

export function exitCodeFor(state: State): 0 | 1 {
  const clean = (c: CaseResult) => c.result === 'discriminates' || (c.result === 'not_audited' && c.reason === 'no_product_change');
  const checkOk = (r?: CheckResult) => !r || r.status !== 'review';
  const casesOk = Object.values(state.cases).every(c => clean(c) && checkOk(c.lanes) && checkOk(c.security));
  return casesOk && checkOk(state.checks.security) && checkOk(state.checks.lanes) ? 0 : 1;
}

const USAGE = `usage: bun run ${COMMAND} <base>..<head> [flags]

Audits every first-parent commit in <base>..<head>, plus each PR head in --prs
trial-merged onto <head>: green baseline, reverse the change's product hunks,
classify, restore, re-verify green.

  --prs <manifest>     JSON {"prs":[{"number":N}|{"head":"<sha>"}|{"ref":"<ref>"}]}; heads are
                       pinned into <run-dir>/prs.pinned.json — pass that file on reruns
  --json               print the report as JSON instead of the Markdown table
  --postgres <url>     run tests with DATABASE_URL=<url>; the database name must be test-shaped
  --resume             keep finished cases from <run-dir>/state.json (same refs and pins only)
  --run-dir <dir>      state, logs and pinned manifest (default: <git-dir>/contributor-audit/<base>-<head>)
  --verdicts <file>    human verdicts {"<case id>":{"verdict":"accept|rework|reject|not_yet_proven","note":"…"}}
                       (default: <run-dir>/verdicts.json when present)
  --step-timeout <s>   per-step timeout in seconds (default 900)
  --skip-security      opt out of wave-security-scan (and the gitleaks preflight)
  --skip-lanes         opt out of check:postgres-lanes
  --keep-worktrees     leave the isolated checkouts on disk for inspection

Exit: 0 clean, 1 needs a human look, 2 usage/preflight refusal, 130 interrupted (rerun with --resume).
Docs: ${DOCS}
`;

export function parseArgs(argv: string[]): Options {
  const o: Options = { range: '', json: false, resume: false, stepTimeoutSec: 900, skipSecurity: false, skipLanes: false, keepWorktrees: false, help: false };
  const value = (i: number, flag: string): string => {
    const v = argv[i + 1];
    if (v === undefined || v.startsWith('--')) {
      throw opError('invalid_params', `${flag} needs a value`, `Pass ${flag} followed by its value.`, { why: `${flag} was the last argument or was followed by another flag.`, fix: helpFix() });
    }
    return v;
  };
  for (let i = 0; i < argv.length; i++) {
    const a = argv[i];
    switch (a) {
      case '--help': case '-h': o.help = true; break;
      case '--json': o.json = true; break;
      case '--resume': o.resume = true; break;
      case '--skip-security': o.skipSecurity = true; break;
      case '--skip-lanes': o.skipLanes = true; break;
      case '--keep-worktrees': o.keepWorktrees = true; break;
      case '--prs': o.prs = value(i, a); i++; break;
      case '--postgres': o.postgres = value(i, a); i++; break;
      case '--run-dir': o.runDir = value(i, a); i++; break;
      case '--verdicts': o.verdicts = value(i, a); i++; break;
      case '--step-timeout': {
        const n = Number(value(i, a)); i++;
        if (!Number.isInteger(n) || n <= 0) throw opError('invalid_params', `--step-timeout must be a positive whole number of seconds`, 'Pass --step-timeout 900 (or another positive integer).', { why: `Got "${argv[i]}".`, fix: helpFix() });
        o.stepTimeoutSec = n; break;
      }
      default:
        if (a.startsWith('-')) throw opError('unknown_flag', `${COMMAND} does not accept ${a}`, `Drop ${a}; run with --help for the accepted flags.`, { why: 'Unknown flags are refused rather than ignored so a typo never changes what gets audited.', fix: helpFix() });
        if (o.range) throw opError('invalid_params', `only one range is accepted (got "${o.range}" and "${a}")`, 'Pass a single <base>..<head> range.', { why: 'The audit compares one base against one head.', fix: helpFix() });
        o.range = a;
    }
  }
  if (!o.help && !/^[^.\s]+\.\.[^.\s]+$/.test(o.range)) {
    throw opError('invalid_params', o.range ? `range must be <base>..<head> (got "${o.range}")` : 'a <base>..<head> range is required',
      'Pass the range of merges to audit, e.g. the commit before the merge train and origin/master.', {
        why: 'The audit needs both ends of the range to list the merges it re-tests.',
        fix: action(['bun', 'run', COMMAND, '<base>..<head>'], 'Audits every merge between the two refs.', { inputs: [{ name: 'base>..<head', how: 'base = the last commit before the merges to audit; head = usually origin/master' }] }),
      });
  }
  if (o.postgres && !isTestShapedDatabaseUrl(o.postgres)) {
    throw opError('invalid_params', '--postgres must name a test-shaped database', 'Point --postgres at a throwaway database whose name has "test" as a segment (e.g. gbrain_test).', {
      why: 'The audited tests are untrusted and run destructive SQL against whatever database they are given.',
      fix: action(['docker', 'run', '-d', '--name', 'gbrain-audit-pg', '-p', '127.0.0.1:5435:5432', '-e', 'POSTGRES_PASSWORD=postgres', '-e', 'POSTGRES_DB=gbrain_test', 'pgvector/pgvector:pg16'], 'Starts a disposable test-shaped database at postgres://postgres:postgres@localhost:5435/gbrain_test.', { consent: ['persistent_install'] }),
    });
  }
  return o;
}

// ── process + git plumbing ─────────────────────────────────────────────────

class Interrupted extends Error {}
let interrupted = false;
let activeChild: number | undefined;

function git(args: string[], cwd: string, allowFail = false): { ok: boolean; out: string; raw: string; err: string } {
  const r = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
  const ok = r.status === 0;
  if (!ok && !allowFail) throw new Error(`git ${args.join(' ')} failed (exit ${r.status}): ${(r.stderr || '').trim()}`);
  return { ok, out: (r.stdout || '').trim(), raw: r.stdout || '', err: (r.stderr || '').trim() };
}

/** Runs one step in its own process group with output to a log file; kills the group on timeout. */
async function runStep(cmd: string[], o: { cwd: string; env?: Record<string, string>; log: string; timeoutMs: number }): Promise<{ exit: number; timedOut: boolean; output: string }> {
  mkdirSync(dirname(o.log), { recursive: true });
  const fd = openSync(o.log, 'w');
  writeSync(fd, `$ ${o.env ? 'env -i <allowlist> ' : ''}${cmd.join(' ')}\n`);
  const argv = o.env ? ['env', '-i', ...Object.entries(o.env).map(([k, v]) => `${k}=${v}`), ...cmd] : cmd;
  const child = spawn(argv[0], argv.slice(1), { cwd: o.cwd, stdio: ['ignore', fd, fd], detached: true });
  activeChild = child.pid;
  let timedOut = false;
  const kill = () => { try { process.kill(-child.pid!, 'SIGKILL'); } catch { /* already gone */ } };
  const timer = setTimeout(() => { timedOut = true; kill(); }, o.timeoutMs);
  const exit = await new Promise<number>(res => {
    child.on('exit', (code, signal) => res(code ?? (signal ? 128 : 1)));
    child.on('error', () => res(127));
  });
  clearTimeout(timer);
  kill();
  activeChild = undefined;
  closeSync(fd);
  if (interrupted) throw new Interrupted();
  return { exit, timedOut, output: readFileSync(o.log, 'utf8') };
}

const progress = (msg: string) => process.stderr.write(`[audit] ${msg}\n`);

function refuse(e: unknown, json: boolean): number {
  const r = renderCliError(e, { json, command: COMMAND, tty: false });
  if (r.stdout) process.stdout.write(r.stdout);
  if (r.stderr) process.stderr.write(r.stderr);
  return 2;
}

function semverAtLeast(have: string, floor: string): boolean {
  const a = have.split('.').map(Number), b = floor.split('.').map(Number);
  for (let i = 0; i < 3; i++) { if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0); }
  return true;
}

function writeJson(path: string, value: unknown): void {
  mkdirSync(dirname(path), { recursive: true });
  writeFileSync(`${path}.tmp`, JSON.stringify(value, null, 2) + '\n');
  renameSync(`${path}.tmp`, path);
}

// ── preflight ──────────────────────────────────────────────────────────────

async function preflight(o: Options, repo: string): Promise<{ base: string; head: string; runDir: string; prs: PinnedPr[] }> {
  const resolveRef = (ref: string) => git(['rev-parse', '--verify', '-q', `${ref}^{commit}`], repo, true);
  const [baseRef, headRef] = o.range.split('..');
  for (const ref of [baseRef, headRef]) {
    if (!resolveRef(ref).ok) throw opError('invalid_params', `cannot resolve "${ref}" to a commit`, `Fetch the ref first, then rerun.`, { why: `"${ref}" is not a commit in ${repo}.`, fix: action(['git', 'fetch', 'origin'], 'Brings remote branches and tags into this clone.', { verify: { argv: ['git', 'rev-parse', '--verify', `${ref}^{commit}`] } }) });
  }
  const base = resolveRef(baseRef).out, head = resolveRef(headRef).out;
  if (!git(['merge-base', '--is-ancestor', base, head], repo, true).ok) {
    throw opError('invalid_params', `${baseRef} is not an ancestor of ${headRef}`, 'Swap the ends or pick a base that the head contains.', { why: 'The audit walks the first-parent history from base to head.', fix: helpFix() });
  }
  const pkg = git(['show', `${head}:package.json`], repo, true);
  const floor = pkg.ok ? parseReleasePackage(pkg.out).floor : null;
  if (floor && !semverAtLeast(Bun.version, floor)) {
    throw opError('config_error', `Bun ${Bun.version} is older than the audited tree's floor ${floor}`, 'Upgrade Bun, then rerun.', { why: 'Tests run under an older Bun fail for reasons unrelated to the change and would read as setup failures.', fix: action(['bun', 'upgrade'], 'Installs a Bun that meets engines.bun.', { actor: 'user', consent: ['persistent_install'], verify: { argv: ['bun', '--version'] } }) });
  }
  if (!o.skipSecurity) {
    for (const tool of ['gitleaks', 'python3']) {
      if (spawnSync(tool, ['--version'], { stdio: 'ignore' }).error) {
        throw opError('config_error', `${tool} is not installed; the security scan cannot run`, `Install ${tool}, or rerun with --skip-security to audit without the security scan.`, {
          why: tool === 'gitleaks' ? 'wave-security-scan fails closed without its secrets lane.' : 'wave-security-scan does its pattern checks in python3.',
          fix: action(['brew', 'install', tool], `Installs ${tool} for the wave-security-scan lane.`, { actor: 'user', consent: ['persistent_install'], verify: { argv: [tool, '--version'] } }),
        });
      }
    }
  }
  if (o.postgres) {
    const { default: postgres } = await import('#postgres');
    const sql = postgres(o.postgres, { max: 1, connect_timeout: 5, onnotice: () => {} });
    try { await sql`select 1`; } catch (e) {
      throw opError('config_error', 'the --postgres database is unreachable', 'Start the test database (or fix the URL), then rerun.', { why: `Connecting failed: ${(e instanceof Error ? e.message || (e as { code?: string }).code || e.name : String(e)).replace(/postgres(ql)?:\/\/\S+/g, '<url>')}.`, fix: action(['docker', 'ps'], 'Shows whether the test database container is running.') });
    } finally { await sql.end({ timeout: 1 }); }
  }
  const gitDir = resolve(repo, git(['rev-parse', '--git-common-dir'], repo).out);
  const runDir = resolve(o.runDir ?? join(gitDir, 'contributor-audit', `${short(base)}-${short(head)}`));
  mkdirSync(runDir, { recursive: true });

  const prs: PinnedPr[] = [];
  if (o.prs) {
    let manifest: { prs?: Array<{ number?: number; head?: string; ref?: string }> };
    try { manifest = JSON.parse(readFileSync(o.prs, 'utf8')); } catch (e) {
      throw opError('invalid_params', `cannot read the --prs manifest ${o.prs}`, 'Pass a JSON file shaped {"prs":[{"number":123}]}.', { why: e instanceof Error ? e.message : String(e), fix: helpFix() });
    }
    for (const entry of manifest.prs ?? []) {
      let sha: string | undefined;
      if (entry.head) {
        if (!resolveRef(entry.head).ok && entry.number) git(['fetch', '--no-tags', 'origin', `refs/pull/${entry.number}/head`], repo, true);
        sha = resolveRef(entry.head).ok ? resolveRef(entry.head).out : undefined;
      } else if (entry.ref) {
        sha = resolveRef(entry.ref).ok ? resolveRef(entry.ref).out : undefined;
      } else if (entry.number) {
        progress(`fetching refs/pull/${entry.number}/head`);
        const f = git(['fetch', '--no-tags', 'origin', `refs/pull/${entry.number}/head`], repo, true);
        sha = f.ok ? git(['rev-parse', 'FETCH_HEAD'], repo).out : undefined;
      }
      if (!sha) {
        throw opError('invalid_params', `cannot pin PR entry ${JSON.stringify(entry)}`, 'Check the PR number, ref or head SHA, and that origin is reachable.', { why: 'Every trial merge is pinned to an exact commit so reruns test the same code.', fix: action(['git', 'fetch', 'origin'], 'Brings remote refs into this clone.') });
      }
      prs.push({ ...(entry.number ? { number: entry.number } : {}), ...(entry.ref ? { ref: entry.ref } : {}), head: sha });
    }
    const pinned = join(runDir, 'prs.pinned.json');
    writeJson(pinned, { base, head, prs });
    progress(`pinned ${prs.length} PR head(s) → ${pinned} (pass it as --prs on reruns)`);
  }
  return { base, head, runDir, prs };
}

// ── the driver ─────────────────────────────────────────────────────────────

interface Ctx { o: Options; repo: string; runDir: string; scratch: string; cacheDir: string; head: string; timeoutMs: number }

/** One fresh Bun process per test file (as the unit loop runs them), each in its own throwaway HOME. */
async function runTests(ctx: Ctx, wt: string, tests: string[], log: string): Promise<RunCounts> {
  const total: RunCounts = { exit: 0, pass: 0, fail: 0, timedOut: false };
  for (const [i, test] of tests.entries()) {
    const home = mkdtempSync(join(ctx.scratch, 'home-'));
    mkdirSync(join(home, 'tmp'));
    const env = sandboxEnv({ home, bunPath: process.execPath, cacheDir: ctx.cacheDir, postgresUrl: ctx.o.postgres });
    const fileLog = tests.length === 1 ? log : log.replace(/\.log$/, `.${i + 1}.log`);
    const r = await runStep([process.execPath, '--no-env-file', 'test', '--timeout=60000', `./${test}`], { cwd: wt, env, log: fileLog, timeoutMs: ctx.timeoutMs });
    rmSync(home, { recursive: true, force: true });
    const counts = parseCounts(r.output);
    total.pass += counts.pass;
    total.fail += counts.fail;
    total.timedOut ||= r.timedOut;
    if (total.exit === 0) total.exit = r.exit;
  }
  return total;
}

async function install(ctx: Ctx, wt: string, log: string): Promise<boolean> {
  if (!existsSync(join(wt, 'package.json'))) return true;
  const home = mkdtempSync(join(ctx.scratch, 'home-'));
  mkdirSync(join(home, 'tmp'));
  const env = sandboxEnv({ home, bunPath: process.execPath, cacheDir: ctx.cacheDir });
  const lock = existsSync(join(wt, 'bun.lock')) || existsSync(join(wt, 'bun.lockb'));
  const r = await runStep([process.execPath, 'install', ...(lock ? ['--frozen-lockfile'] : []), '--ignore-scripts'], { cwd: wt, env, log, timeoutMs: ctx.timeoutMs });
  rmSync(home, { recursive: true, force: true });
  return r.exit === 0 && !r.timedOut;
}

function addWorktree(ctx: Ctx, sha: string, name: string): string {
  const wt = join(ctx.scratch, name);
  git(['worktree', 'add', '--detach', '--force', wt, sha], ctx.repo);
  return wt;
}

function removeWorktree(ctx: Ctx, wt: string): void {
  if (ctx.o.keepWorktrees) { progress(`kept worktree ${wt}`); return; }
  git(['worktree', 'remove', '--force', wt], ctx.repo, true);
  rmSync(wt, { recursive: true, force: true });
}

/** Steps 1–4 on a prepared tree; `patchFrom` renders the change's diff limited to the given paths. */
async function discriminate(ctx: Ctx, wt: string, c: CaseResult, files: string[], patchFrom: (paths: string[]) => string, logs: string, step: (s: string) => void): Promise<'reverse_failed' | void> {
  const products = files.filter(f => classifyPath(f) === 'product');
  c.product_files = products.length;
  c.tests = files.filter(f => classifyPath(f) === 'test' && RUNNABLE_TEST.test(f) && !f.includes('fixtures/') && existsSync(join(wt, f)));
  if (!products.length) { c.result = 'not_audited'; c.reason = 'no_product_change'; return; }
  if (!c.tests.length) { c.result = 'not_audited'; c.reason = 'no_tests'; return; }
  const patch = join(logs, 'product.patch');
  writeFileSync(patch, patchFrom(products));
  const lockTouched = products.some(f => /(^|\/)(package\.json|bun\.lockb?)$/.test(f));

  step(`baseline (${c.tests.length} test file(s))`);
  c.runs.baseline = await runTests(ctx, wt, c.tests, join(logs, 'baseline.log'));
  if (c.runs.baseline.exit !== 0 || c.runs.baseline.timedOut) { c.result = 'setup_failed'; c.reason = c.runs.baseline.timedOut ? 'baseline_timeout' : 'baseline_red'; return; }
  if (c.runs.baseline.pass === 0) { c.result = 'not_audited'; c.reason = 'no_tests_ran'; return; }

  step(`reverse ${products.length} product file(s)`);
  if (!git(['apply', '-R', '--binary', patch], wt, true).ok) return 'reverse_failed';
  if (lockTouched && !(await install(ctx, wt, join(logs, 'install-reversed.log')))) { c.result = 'setup_failed'; c.reason = 'install_failed_reversed'; }
  else {
    step('tests with the change reversed');
    c.runs.reversed = await runTests(ctx, wt, c.tests, join(logs, 'reversed.log'));
    Object.assign(c, classifyReversed(c.runs.reversed));
  }

  step('restore and re-verify green');
  const restored = git(['apply', '--binary', patch], wt, true).ok && git(['diff', '--quiet'], wt, true).ok;
  if (!restored) { c.result = 'setup_failed'; c.reason = 'restore_mismatch'; return; }
  if (lockTouched && !(await install(ctx, wt, join(logs, 'install-restored.log')))) { c.result = 'setup_failed'; c.reason = 'install_failed_restored'; return; }
  c.runs.restored = await runTests(ctx, wt, c.tests, join(logs, 'restored.log'));
  if (c.runs.restored.exit !== 0) { c.reason = `restore_red (reversed run said ${c.result})`; c.result = 'setup_failed'; }
}

async function lanesCheck(ctx: Ctx, tree: string, log: string): Promise<CheckResult> {
  if (ctx.o.skipLanes) return { status: 'skipped', detail: '--skip-lanes' };
  const r = await runStep([process.execPath, join(TOOL_ROOT, 'scripts', 'check-postgres-lane-coverage.ts')], {
    cwd: tree, log, timeoutMs: ctx.timeoutMs, env: { ...sandboxEnv({ home: ctx.scratch, bunPath: process.execPath, cacheDir: ctx.cacheDir }), GBRAIN_GUARD_ROOT: tree },
  });
  const summary = r.output.trim().split('\n').filter(l => !l.startsWith('$ ') && /postgres-lane|FAIL/.test(l)).slice(-3).join(' / ');
  return r.exit === 0 ? { status: 'pass', detail: summary } : { status: 'review', detail: `${summary || 'lane check failed'} (log: ${log})` };
}

async function securityCheck(ctx: Ctx, range: string, log: string): Promise<CheckResult> {
  if (ctx.o.skipSecurity) return { status: 'skipped', detail: '--skip-security' };
  const r = await runStep(['bash', join(TOOL_ROOT, 'scripts', 'wave-security-scan.sh'), '--json', range], { cwd: ctx.repo, log, timeoutMs: ctx.timeoutMs });
  const json = r.output.trim().split('\n').reverse().find(l => l.startsWith('{'));
  try {
    const s = JSON.parse(json ?? '') as { gate: string; alarm: number; gitleaks_hits: string; dependency_changed: boolean };
    const detail = `alarm=${s.alarm} gitleaks=${s.gitleaks_hits}${s.dependency_changed ? ' deps changed' : ''}`;
    return { status: s.gate === 'clean' ? 'pass' : 'review', detail };
  } catch { return { status: 'review', detail: `scan exited ${r.exit} without a report (log: ${log})` }; }
}

async function auditMerge(ctx: Ctx, c: CaseResult, headTree: string, logs: string, step: (s: string) => void): Promise<void> {
  const files = git(['diff', '--name-only', '--no-renames', c.parent, c.sha], ctx.repo).out.split('\n').filter(Boolean);
  const patchFrom = (paths: string[]) => git(['diff', '--binary', '--no-renames', c.parent, c.sha, '--', ...paths], ctx.repo).raw;
  c.audited_at = ctx.head;
  if (!git(['diff', '--quiet'], headTree, true).ok) git(['checkout', '--', '.'], headTree);
  if ((await discriminate(ctx, headTree, c, files, patchFrom, logs, step)) !== 'reverse_failed') return;
  step('hunks do not reverse at head; auditing at the merge commit');
  c.runs = {};
  const wt = addWorktree(ctx, c.sha, `at-${short(c.sha)}`);
  try {
    if (!(await install(ctx, wt, join(logs, 'install-at-merge.log')))) { c.result = 'setup_failed'; c.reason = 'install_failed'; return; }
    c.audited_at = c.sha;
    const r = await discriminate(ctx, wt, c, files, patchFrom, logs, step);
    if (r === 'reverse_failed') { c.result = 'setup_failed'; c.reason = 'reverse_failed'; }
  } finally { removeWorktree(ctx, wt); }
}

async function auditPr(ctx: Ctx, c: CaseResult, logs: string, step: (s: string) => void): Promise<void> {
  const wt = addWorktree(ctx, ctx.head, `pr-${short(c.sha)}`);
  try {
    step('trial merge');
    c.audited_at = ctx.head;
    if (git(['merge-base', '--is-ancestor', c.sha, ctx.head], ctx.repo, true).ok) { c.result = 'not_audited'; c.reason = 'already_merged'; return; }
    const m = git(['merge', '--no-ff', '--no-commit', '--no-edit', c.sha], wt, true);
    if (!m.ok) {
      const conflicted = git(['diff', '--name-only', '--diff-filter=U'], wt, true).out.split('\n').filter(Boolean);
      c.result = 'conflict'; c.reason = conflicted.length ? `conflicts in ${conflicted.slice(0, 5).join(', ')}` : m.err.split('\n')[0];
      git(['merge', '--abort'], wt, true);
      return;
    }
    const files = git(['diff', '--cached', '--name-only', '--no-renames', ctx.head], wt).out.split('\n').filter(Boolean);
    if (!(await install(ctx, wt, join(logs, 'install.log')))) { c.result = 'setup_failed'; c.reason = 'install_failed'; return; }
    const patchFrom = (paths: string[]) => git(['diff', '--cached', '--binary', '--no-renames', ctx.head, '--', ...paths], wt).raw;
    if ((await discriminate(ctx, wt, c, files, patchFrom, logs, step)) === 'reverse_failed') { c.result = 'setup_failed'; c.reason = 'reverse_failed'; }
    step('lanes on the trial merge');
    c.lanes = await lanesCheck(ctx, wt, join(logs, 'lanes.log'));
  } finally { removeWorktree(ctx, wt); }
  const mergeBase = git(['merge-base', ctx.head, c.sha], ctx.repo).out;
  step('security scan of the PR commits');
  c.security = await securityCheck(ctx, `${mergeBase}..${c.sha}`, join(logs, 'security.log'));
}

function loadVerdicts(path: string | undefined): Record<string, { verdict?: string; note?: string }> {
  if (!path || !existsSync(path)) return {};
  let raw: Record<string, { verdict?: string; note?: string }>;
  try { raw = JSON.parse(readFileSync(path, 'utf8')); } catch (e) {
    throw opError('invalid_params', `cannot parse the verdicts file ${path}`, 'Fix the JSON: {"<case id>":{"verdict":"accept","note":"…"}}.', { why: e instanceof Error ? e.message : String(e), fix: helpFix() });
  }
  for (const [id, v] of Object.entries(raw)) {
    if (!HUMAN_VERDICTS.includes(v?.verdict as HumanVerdict)) {
      throw opError('invalid_params', `verdict for ${id} must be one of ${HUMAN_VERDICTS.join(', ')}`, `Set "verdict" for ${id} to accept, rework, reject or not_yet_proven.`, { why: `Got ${JSON.stringify(v?.verdict)}.`, fix: helpFix() });
    }
  }
  return raw;
}

export async function main(argv: string[]): Promise<number> {
  const json = argv.includes('--json');
  let o: Options;
  try { o = parseArgs(argv); } catch (e) { return refuse(e, json); }
  if (o.help) { process.stdout.write(USAGE); return 0; }
  const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
  if (top.status !== 0) return refuse(opError('config_error', 'not inside a git repository', 'Run the audit from the repository whose merges it audits.', { why: 'The range is resolved against the current directory\'s repository.', fix: action(['git', 'rev-parse', '--show-toplevel'], 'Shows which repository the current directory belongs to.') }), json);
  const repo = top.stdout.trim();

  let pre: Awaited<ReturnType<typeof preflight>>;
  let verdicts: Record<string, { verdict?: string; note?: string }>;
  let state: State;
  try {
    pre = await preflight(o, repo);
    const statePath = join(pre.runDir, 'state.json');
    const fresh: State = { version: STATE_VERSION, base: pre.base, head: pre.head, prs: pre.prs, cases: {}, checks: {} };
    state = fresh;
    if (o.resume && existsSync(statePath)) {
      const prev = JSON.parse(readFileSync(statePath, 'utf8')) as State;
      if (prev.version !== STATE_VERSION || prev.base !== pre.base || prev.head !== pre.head || JSON.stringify(prev.prs) !== JSON.stringify(pre.prs)) {
        throw opError('preview_changed', 'the saved run audited different refs or PR pins', 'Rerun with the pinned manifest from the saved run, or drop --resume to start over.', {
          why: `Saved run: ${short(prev.base)}..${short(prev.head)} with ${prev.prs.length} PR(s); this run: ${short(pre.base)}..${short(pre.head)} with ${pre.prs.length}. Mixing them would report results for code that was not tested.`,
          fix: action(['bun', 'run', COMMAND, o.range, '--prs', join(pre.runDir, 'prs.pinned.json'), '--resume'], 'Resumes against the exact PR heads the saved run pinned.'),
        });
      }
      state = prev;
      progress(`resuming: ${Object.keys(prev.cases).length} case(s) already done`);
    } else if (existsSync(statePath)) {
      progress(`starting over; the previous results in ${statePath} are replaced (pass --resume to keep them)`);
    }
    verdicts = loadVerdicts(o.verdicts ?? join(pre.runDir, 'verdicts.json'));
  } catch (e) { return refuse(e, json); }

  const statePath = join(pre.runDir, 'state.json');
  const scratch = mkdtempSync(join(tmpdir(), 'gbrain-contributor-audit-'));
  const ctx: Ctx = { o, repo, runDir: pre.runDir, scratch, cacheDir: join(pre.runDir, 'bun-cache'), head: pre.head, timeoutMs: o.stepTimeoutSec * 1000 };
  const onSigint = () => { interrupted = true; if (activeChild) { try { process.kill(-activeChild, 'SIGKILL'); } catch { /* gone */ } } };
  process.on('SIGINT', onSigint);
  const commits = git(['rev-list', '--first-parent', '--reverse', `${pre.base}..${pre.head}`], repo).out.split('\n').filter(Boolean);
  const total = commits.length + pre.prs.length;
  let headTree: string | undefined;
  let n = 0;
  try {
    for (const sha of commits) {
      n++;
      const id = `merge-${short(sha)}`;
      if (state.cases[id]) continue;
      const subject = git(['log', '-1', '--format=%s', sha], repo).out;
      const c: CaseResult = { id, kind: 'merge', sha, parent: git(['rev-parse', `${sha}^1`], repo).out, pr: prNumberFromSubject(subject), author: git(['log', '-1', '--format=%an', git(['rev-parse', '-q', '--verify', `${sha}^2`], repo, true).out || sha], repo).out, subject, result: 'not_audited', tests: [], product_files: 0, runs: {}, seconds: 0 };
      const started = Date.now();
      const step = (s: string) => progress(`(${n}/${total}) ${id}${c.pr ? ` #${c.pr}` : ''}: ${s}`);
      const logs = join(pre.runDir, 'logs', id);
      mkdirSync(logs, { recursive: true });
      if (!headTree) {
        step('preparing the head checkout');
        headTree = addWorktree(ctx, pre.head, 'head');
        if (!(await install(ctx, headTree, join(pre.runDir, 'logs', 'install-head.log')))) {
          c.result = 'setup_failed'; c.reason = 'install_failed_at_head';
        }
      }
      if (c.reason !== 'install_failed_at_head') await auditMerge(ctx, c, headTree, logs, step);
      c.seconds = Math.round((Date.now() - started) / 1000);
      step(`${c.result}${c.reason ? ` (${c.reason})` : ''} in ${c.seconds}s`);
      state.cases[id] = c;
      writeJson(statePath, state);
    }
    for (const pr of pre.prs) {
      n++;
      const id = `pr-${pr.number ?? short(pr.head)}`;
      if (state.cases[id]) continue;
      const subject = git(['log', '-1', '--format=%s', pr.head], repo).out;
      const c: CaseResult = { id, kind: 'pr', sha: pr.head, parent: pre.head, pr: pr.number, author: git(['log', '-1', '--format=%an', pr.head], repo).out, subject, result: 'not_audited', tests: [], product_files: 0, runs: {}, seconds: 0 };
      const started = Date.now();
      const step = (s: string) => progress(`(${n}/${total}) ${id}: ${s}`);
      const logs = join(pre.runDir, 'logs', id);
      mkdirSync(logs, { recursive: true });
      await auditPr(ctx, c, logs, step);
      c.seconds = Math.round((Date.now() - started) / 1000);
      step(`${c.result}${c.reason ? ` (${c.reason})` : ''} in ${c.seconds}s`);
      state.cases[id] = c;
      writeJson(statePath, state);
    }
    if (commits.length && !state.checks.security) {
      progress('wave-security-scan over the range');
      state.checks.security = await securityCheck(ctx, `${pre.base}..${pre.head}`, join(pre.runDir, 'logs', 'security-range.log'));
      writeJson(statePath, state);
    }
    if (!state.checks.lanes) {
      progress('check:postgres-lanes at head');
      headTree ??= addWorktree(ctx, pre.head, 'head');
      state.checks.lanes = await lanesCheck(ctx, headTree, join(pre.runDir, 'logs', 'lanes-head.log'));
      writeJson(statePath, state);
    }
  } catch (e) {
    if (!(e instanceof Interrupted)) throw e;
    progress(`interrupted; ${Object.keys(state.cases).length} finished case(s) saved in ${statePath}. Rerun with --resume.`);
    return 130;
  } finally {
    process.off('SIGINT', onSigint);
    if (headTree) removeWorktree(ctx, headTree);
    git(['worktree', 'prune'], repo, true);
    if (!o.keepWorktrees) rmSync(scratch, { recursive: true, force: true });
  }

  if (o.json) process.stdout.write(JSON.stringify({ ...state, verdicts, run_dir: pre.runDir, exit_code: exitCodeFor(state) }, null, 2) + '\n');
  else process.stdout.write(renderMarkdown(state, verdicts));
  progress(`report: ${statePath}; logs: ${join(pre.runDir, 'logs')}`);
  return exitCodeFor(state);
}

if (import.meta.main) process.exit(await main(process.argv.slice(2)));