@yagni-app/code-staging 0.0.0 → 0.1.0-staging.1002.1

package/dist/extension/pipeline/verify.js

@@ -0,0 +1,758 @@
+/**
+ * P4 - the deterministic, non-LLM verify gate so "clean" means "builds".
+ *
+ * The /go review half is judgment (LLM lenses). Judgment can like a change that
+ * does not compile: the recorded false-clean defect. This module runs each changed
+ * package's own secret-independent build check (`typecheck`/`lint`) via `execFile`
+ * and turns a non-zero exit into `critical` Findings that flow through the SAME
+ * review -> fix loop, so the loop cannot stop `clean` while the build is broken and
+ * the fix stage gets the real errors.
+ *
+ * `detectVerifyCommands`, `detectVerifyTestCommands`, `parseVerifyFailures`,
+ * `classifyTestFailure`, `isFannedOutScript`, `parseChangedPaths` and
+ * `resolvePackageDirs` are PURE (unit-tested directly). `makeRunVerify` is the
+ * thin impure runner; it shells out (pi's ExtensionContext exposes no exec,
+ * mirroring workspace.ts) and is wrapped with R1's timeout composition
+ * (`composeAbortSignal`) so a slow or flaky suite is bounded.
+ *
+ * Scoped-by-default: in a monorepo the gate runs EVERY changed package's own
+ * check in that package's dir, never the repo-root recursive runner (`pnpm -r
+ * test`, `turbo`, an e2e suite). The changed packages are found by reusing
+ * workspace.ts's git seam MINUS the tree's pre-run dirt, so judgment stays
+ * scoped to THIS run's real diff and an unrelated dirty package never retargets
+ * the gate.
+ *
+ * TWO HALVES (spec §3d). The TYPECHECK half runs each changed package's
+ * secret-independent build check (`typecheck`/`lint`, never `test`) under the
+ * scrubbed {@link buildVerifyEnv}; its behavior is frozen (invariant §0.2). The
+ * TEST half then runs each changed package's own `test` script under the user's
+ * real environment MINUS every `YAGNI_*` var and NODE_OPTIONS
+ * ({@link buildTestEnv}) — tests legitimately need the user's DB / local infra,
+ * but repo-defined commands never see YAGNI tokens (§0.9). Test output is
+ * classified by the pure {@link classifyTestFailure}: parseable test failures
+ * become `critical` findings through the same review->fix loop; infra/env
+ * failures (connection refused, missing env, DB/auth, command not found) and
+ * anything UNCERTAIN fail OPEN with an honest note, never a never-clearable
+ * critical.
+ *
+ * Safe-by-default and FAIL-OPEN: if no scoped, non-fanned-out command is
+ * detectable, or the command cannot be spawned, or it times out, the gate
+ * produces no findings and records an honest note rather than blocking a real
+ * change on its own inability to run. Repo-local `.yagni-code/verify` overrides
+ * are opt-in only and, when active, ARE the whole gate (they cover the test half
+ * too — no detected `test` script runs alongside an override). All captured
+ * command output passes through {@link scrubSecrets} before it can enter
+ * findings, handoffs, or run records (§0.9).
+ */
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { composeAbortSignal } from "./resilience.js";
+import { scrubSecrets } from "./scrubSecrets.js";
+import { snapshotWorkspace } from "./workspace.js";
+/** Total wall-clock budget for a single verify run before it is abandoned (fail-open). */
+export const VERIFY_TIMEOUT_MS = 10 * 60_000;
+/** Per-PACKAGE wall-clock budget for the test half (spec §3d); overrun fails open. */
+export const VERIFY_TEST_TIMEOUT_MS = 10 * 60_000;
+/** Cap on located findings parsed from one failing run, and on the opaque-tail message. */
+const MAX_LOCATED_FINDINGS = 25;
+const MAX_TAIL_CHARS = 1000;
+/** The verify lens reuses `does_it_hold` (does the change build/test) to avoid widening ReviewLens. */
+const VERIFY_LENS = "does_it_hold";
+/**
+ * The priority order of package.json scripts we treat as a verify command.
+ * Deliberately a SECRET-INDEPENDENT build check (`typecheck`/`lint`), NEVER the
+ * package `test`. The verify env is scrubbed of secrets (see {@link buildVerifyEnv}),
+ * so a package whose tests need infra (a DB, an e2e secret) can never exit 0 under
+ * it: selecting `test` would reintroduce the deterministic, never-clearable
+ * `critical` that forces round_cap on every run (the exact defect this gate exists
+ * to avoid). The gate's job is "the change compiles"; the worker stages and CI run
+ * the tests. `build` is also excluded (it writes dist/.next/ artifacts into the
+ * tree). A repo that wants a different check opts in via `.yagni-code/verify`.
+ */
+const SCRIPT_PRIORITY = ["verify", "typecheck", "lint"];
+function tryRead(readFile, path) {
+    try {
+        return readFile(path);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Detect the package manager from a lockfile (default npm). Exported for the
+ * worktree bootstrap (spec §3b), which must install with the same pm the verify
+ * gate will later run scripts through.
+ */
+export function detectPackageManager(cwd, readFile) {
+    if (tryRead(readFile, join(cwd, "pnpm-lock.yaml")) != null)
+        return "pnpm";
+    if (tryRead(readFile, join(cwd, "yarn.lock")) != null)
+        return "yarn";
+    return "npm";
+}
+/**
+ * True for a script body that fans out across packages or shells a secret-gated
+ * e2e runner: `pnpm` with `-r`/`--recursive`/`--filter`, or `turbo` / `lerna` /
+ * `nx run-many` / `playwright`. Such a script can never exit 0 from a
+ * single-package change under the scrubbed verify env (it drags in unrelated
+ * packages and missing secrets), so it must NEVER be chosen as the gate command:
+ * choosing it is the deterministic false-`critical` this gate exists to avoid.
+ * Applied to BOTH the scoped package script and the repo-root fallback. The `-r`
+ * flag is matched at a flag boundary so it never hits an innocent substring.
+ */
+export function isFannedOutScript(body) {
+    if (/\bpnpm\b/.test(body) && /(?:^|\s)(?:-r|--recursive|--filter)(?:[\s=]|$)/.test(body))
+        return true;
+    if (/\b(?:turbo|lerna)\b/.test(body))
+        return true;
+    if (/\bnx\s+run-many\b/.test(body))
+        return true;
+    if (/\bplaywright\b/.test(body))
+        return true;
+    return false;
+}
+/**
+ * Parse `git status --porcelain` into repo-relative changed paths. Each line is
+ * `XY <path>`; we drop the 2-char XY status + its separating space, and for a
+ * rename/copy (`R  old -> new`) take the destination. Pure; the impure git
+ * shell-out is {@link snapshotWorkspace}.
+ */
+export function parseChangedPaths(status) {
+    const paths = [];
+    for (const raw of status.split("\n")) {
+        if (raw.length < 4)
+            continue; // need at least "XY p"
+        const entry = raw.slice(3); // drop the 2-char XY status + its separating space
+        const arrow = entry.indexOf(" -> ");
+        const path = (arrow >= 0 ? entry.slice(arrow + 4) : entry).trim();
+        if (path)
+            paths.push(path);
+    }
+    return paths;
+}
+/** Walk up from a changed path's dir to repoRoot; return the nearest dir holding a package.json (or null). */
+function nearestPackageDir(repoRoot, rel, readFile) {
+    let dir = dirname(join(repoRoot, rel));
+    while (true) {
+        if (tryRead(readFile, join(dir, "package.json")) != null)
+            return dir;
+        if (dir === repoRoot)
+            return null;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null; // reached the filesystem root without a package.json
+        dir = parent;
+    }
+}
+/**
+ * Map each repo-relative changed path to its nearest enclosing package dir (the
+ * one with a package.json, repoRoot inclusive), deduped + deterministically
+ * sorted. `readFile` is injected so this stays pure. Used to SCOPE the verify gate
+ * to the package(s) a change actually touched instead of the whole monorepo.
+ */
+export function resolvePackageDirs(repoRoot, relPaths, readFile) {
+    const dirs = new Set();
+    for (const rel of relPaths) {
+        const dir = nearestPackageDir(repoRoot, rel, readFile);
+        if (dir)
+            dirs.add(dir);
+    }
+    return [...dirs].sort();
+}
+/**
+ * This run's OWN changed package dirs: the porcelain `status`'s packages MINUS the
+ * packages touched only by `baselinePaths` (the tree's pre-run dirt). A package with
+ * a NEW change stays in scope even if it also had pre-run dirt; a package whose every
+ * changed path predates the run drops out. Pure (the `readFile` seam keeps it so), so
+ * an unrelated dirty package can never retarget the gate off this run's real diff.
+ */
+export function ownChangedDirs(repoRoot, status, baselinePaths, readFile) {
+    const baseline = new Set(baselinePaths);
+    const own = parseChangedPaths(status).filter((p) => !baseline.has(p));
+    return resolvePackageDirs(repoRoot, own, readFile);
+}
+/**
+ * The highest-priority package.json script at `pkgDir` that is a string AND not a
+ * fanned-out/e2e runner, as a {@link VerifyCommand} that runs IN `pkgDir`. `pm` is
+ * the repo's package manager (detected once at the repo root, since a monorepo's
+ * lockfile lives there, not in each package). Null when the dir has no usable
+ * script, so the caller tries the next scope or fails open.
+ */
+function pickScript(pkgDir, readFile, pm) {
+    const pkgRaw = tryRead(readFile, join(pkgDir, "package.json"));
+    if (!pkgRaw)
+        return null;
+    let scripts = {};
+    try {
+        scripts = JSON.parse(pkgRaw).scripts ?? {};
+    }
+    catch {
+        scripts = {};
+    }
+    for (const name of SCRIPT_PRIORITY) {
+        const body = scripts[name];
+        if (typeof body === "string" && !isFannedOutScript(body)) {
+            return { argv: [pm, "run", name], label: name, source: "script", cwd: pkgDir };
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the verify command(s) for a repo. An explicitly allowed `.yagni-code/verify`
+ * override wins (first non-comment, non-empty line, whitespace-split into argv; run
+ * at the repo root) as a single command. Otherwise the gate is SCOPED to the change:
+ * EVERY changed package's highest-priority, non-fanned-out script is returned (each
+ * run in its own package), falling back to the repo-root script (still rejecting
+ * fanned-out runners). Covering all changed packages (not just the first) stops the
+ * gate giving false confidence by checking the wrong package. Returns [] when nothing
+ * is usable, so the caller fails open rather than running the repo-root recursive
+ * runner and emitting a false `critical`.
+ */
+export function detectVerifyCommands(cwd, opts = {}) {
+    const readFile = opts.readFile ?? ((p) => readFileSync(p, "utf8"));
+    const override = opts.allowRepoOverride ? tryRead(readFile, join(cwd, ".yagni-code", "verify")) : null;
+    if (override) {
+        for (const raw of override.split("\n")) {
+            const line = raw.trim();
+            if (!line || line.startsWith("#"))
+                continue;
+            const argv = line.split(/\s+/);
+            if (argv.length > 0)
+                return [{ argv, label: line, source: "override", cwd }];
+        }
+    }
+    // Detect the package manager ONCE at the repo root: a monorepo keeps a single
+    // lockfile there, so detecting it inside a changed package dir would mis-fall to npm.
+    const pm = detectPackageManager(cwd, readFile);
+    // Scope to the change: run the build check of EVERY changed package (deterministic
+    // order from resolvePackageDirs), each in its own dir. This stays off the repo-root
+    // recursive runner AND never silently checks only the first (lexicographically
+    // smallest) package while leaving the package the run actually targeted unverified.
+    const commands = [];
+    const seen = new Set();
+    for (const dir of opts.changedDirs ?? []) {
+        if (seen.has(dir))
+            continue;
+        seen.add(dir);
+        const scoped = pickScript(dir, readFile, pm);
+        if (scoped)
+            commands.push(scoped);
+    }
+    if (commands.length > 0)
+        return commands;
+    // Fallback: the repo-root script, still rejecting fanned-out runners so a
+    // recursive `pnpm -r test` is never selected anywhere. Empty => fail open.
+    const root = pickScript(cwd, readFile, pm);
+    return root ? [root] : [];
+}
+/** Back-compat singular: the first detected verify command, or null. */
+export function detectVerifyCommand(cwd, opts = {}) {
+    return detectVerifyCommands(cwd, opts)[0] ?? null;
+}
+/** The package.json `test` script at `pkgDir` as a VerifyCommand, when usable. */
+function pickTestScript(pkgDir, readFile, pm) {
+    const pkgRaw = tryRead(readFile, join(pkgDir, "package.json"));
+    if (!pkgRaw)
+        return null;
+    let scripts = {};
+    try {
+        scripts = JSON.parse(pkgRaw).scripts ?? {};
+    }
+    catch {
+        scripts = {};
+    }
+    const body = scripts.test;
+    if (typeof body === "string" && !isFannedOutScript(body)) {
+        return { argv: [pm, "run", "test"], label: "test", source: "script", cwd: pkgDir };
+    }
+    return null;
+}
+/**
+ * Resolve the TEST-half command(s) (spec §3d): every changed package's own
+ * `test` script (each run in its own dir), falling back to the repo-root `test`
+ * script; a fanned-out script (`pnpm -r test`, turbo, playwright) is rejected
+ * everywhere (the same false-critical guard as the typecheck half). Returns []
+ * when nothing is usable so the caller fails open. The `.yagni-code/verify`
+ * override is deliberately NOT consulted here: an active override IS the whole
+ * gate and the caller skips the test half entirely.
+ */
+export function detectVerifyTestCommands(cwd, opts = {}) {
+    const readFile = opts.readFile ?? ((p) => readFileSync(p, "utf8"));
+    const pm = detectPackageManager(cwd, readFile);
+    const commands = [];
+    const seen = new Set();
+    for (const dir of opts.changedDirs ?? []) {
+        if (seen.has(dir))
+            continue;
+        seen.add(dir);
+        const scoped = pickTestScript(dir, readFile, pm);
+        if (scoped)
+            commands.push(scoped);
+    }
+    if (commands.length > 0)
+        return commands;
+    const root = pickTestScript(cwd, readFile, pm);
+    return root ? [root] : [];
+}
+/**
+ * Infra/environment failure classification for the typecheck half (spec §3b,
+ * invariant §0.2). A fresh run worktree has no node_modules until the bootstrap
+ * finishes (or when it fail-opened), so a verify command can exit non-zero not
+ * because the CHANGE is broken but because the ENVIRONMENT is: `tsc: command
+ * not found` (exit 127), a Node loader `ERR_MODULE_NOT_FOUND`, or a spawn-shaped
+ * ENOENT surfaced through the runner's own output. Those must become an honest
+ * fail-open `verifyNote` ("verify could not run"), NEVER critical findings — a
+ * finding the fix stage can't clear would force round_cap on every run.
+ *
+ * Deliberately conservative (when uncertain, treat it as a REAL failure and let
+ * {@link parseVerifyFailures} report it): tsc's own `error TS2307: Cannot find
+ * module` is a legitimate compile diagnostic a change can cause, so a bare
+ * "Cannot find module" only classifies as infra when it carries the Node
+ * loader's `Require stack`/`ERR_MODULE_NOT_FOUND` signature, not the TS code.
+ * Returns a short human cause for the note, or null when it looks like a real
+ * verify failure.
+ */
+export function classifyVerifyInfraFailure(output, exitCode) {
+    if (exitCode === 127)
+        return "command not found (exit 127; missing node_modules?)";
+    if (/command not found/i.test(output))
+        return "command not found (missing node_modules?)";
+    if (/not recognized as an internal or external command/i.test(output)) {
+        return "command not found (missing node_modules?)";
+    }
+    if (/\bERR_MODULE_NOT_FOUND\b/.test(output))
+        return "module resolution failed (ERR_MODULE_NOT_FOUND)";
+    if (/Cannot find module/.test(output) && /Require stack:/.test(output)) {
+        return "module resolution failed (Cannot find module)";
+    }
+    if (/\bspawn(?:Sync)?\b.*\bENOENT\b/.test(output))
+        return "spawn failed (ENOENT)";
+    return null;
+}
+/**
+ * Test-half infra/environment patterns (spec §3d): failure shapes that mean the
+ * ENVIRONMENT could not run the suite — a DB that is not up, a missing env var,
+ * auth against local infra, a connect timeout — not that the CHANGE broke a
+ * test. Each is deliberately specific (a bare "timed out" or "401" would eat
+ * real assertion failures); when none match, classification falls through to
+ * the failure parsers and, past those, to fail-open UNCERTAIN.
+ */
+const TEST_INFRA_PATTERNS = [
+    [/\bECONNREFUSED\b|\bconnection refused\b/i, "connection refused (is the test's DB/service running?)"],
+    [/\bECONNRESET\b/, "connection reset by the test's DB/service"],
+    [/\bENOTFOUND\b|\bEAI_AGAIN\b/, "DNS/host resolution failed for a test dependency"],
+    [/\bEADDRINUSE\b/, "a port the tests need is already in use"],
+    [/\bETIMEDOUT\b|\bconnect(?:ion)? timed out\b/i, "connection to a test dependency timed out"],
+    [/\bmissing (?:required )?env(?:ironment)? (?:var(?:iable)?s?)\b/i, "missing environment variable"],
+    [/\benvironment variable\b[^\n]{0,80}\b(?:is )?(?:not set|missing|required|must be set)\b/i, "missing environment variable"],
+    [/\bprocess\.env\.[A-Z0-9_]+ is (?:undefined|not set)\b/, "missing environment variable"],
+    [/\bSASL\b|\bSCRAM-SERVER\b/, "database auth failed (missing DB credentials?)"],
+    [/\bpassword authentication failed\b/i, "database auth failed"],
+    [/\brole "[^"]*" does not exist\b/i, "database role does not exist"],
+    [/\bdatabase "[^"]*" does not exist\b/i, "database does not exist"],
+    [/\brelation "[^"]*" does not exist\b/i, "database schema missing (migrations not run?)"],
+    [/\bauthentication (?:failed|error)\b/i, "authentication against a test dependency failed"],
+    [/\b401 Unauthorized\b|\b403 Forbidden\b/i, "authorization against a test dependency failed"],
+];
+/** Strip a trailing `(4 ms)` / `(0.82ms)` duration off a failing-test name. */
+function stripDuration(name) {
+    return name.replace(/\s*\(\d+(?:\.\d+)?\s*m?s\)\s*$/, "").trim();
+}
+/** A failing-test bullet: jest `✕ name`, vitest `×/✗ name`, node spec `✖ name`. */
+const FAIL_BULLET = /^[✕✖✗×]\s+(.+)$/;
+/** node:test spec-reporter location line printed right above the footer's ✖ line. */
+const NODE_TEST_AT = /^test at (\S+?):(\d+)(?::\d+)?$/;
+/** TAP failing line (node:test tap reporter): `not ok 1 - name`. */
+const TAP_NOT_OK = /^not ok\s+\d+\s+-\s+(.+)$/;
+/** vitest per-test failure header: ` FAIL  file > suite > name` (jest's has no `>`). */
+const RUNNER_FAIL = /^FAIL\s+(\S+)(?:\s+>\s+(.+))?/;
+/** Evidence that a test RUN happened and failed, even when no per-test line parsed. */
+const FAILURE_SUMMARY = [
+    /(?:^|\n)\s*# fail\s+[1-9]\d*\b/, // node:test TAP footer
+    /\bTests:\s+(?:\d+\s+\w+,\s*)*[1-9]\d*\s+failed\b/, // jest: "Tests:  1 failed, 3 passed, 4 total"
+    /\bTests\s+[1-9]\d*\s+failed\b/, // vitest: "Tests  2 failed | 30 passed (32)"
+    /\b[1-9]\d*\s+failing\b/, // mocha / node:test "N failing"
+    /[✕✖✗×]\s+failing tests:/u, // node:test spec footer header
+];
+/**
+ * PURE classification of one test-script run (spec §3d, invariant §0.2).
+ * Deliberately asymmetric with {@link parseVerifyFailures} (which always emits
+ * a finding on non-zero exit): a test suite fails for environmental reasons far
+ * more often than a typecheck does, and a finding the fix stage cannot clear
+ * forces round_cap on every run. So:
+ *
+ *  - exit 0 → `clean`.
+ *  - infra/env shapes (command not found, module resolution, connection
+ *    refused, missing env var, DB/auth, connect timeout) → `infra` with a short
+ *    cause; checked FIRST so a suite whose assertions failed only because its
+ *    DB was down fails open rather than blocking.
+ *  - recognisable failing-test lines (pnpm-wrapped vitest / jest / node:test
+ *    TAP + spec reporters) → `failures` with located `critical` findings
+ *    (capped at 25, deduped, locations attached when the runner printed them).
+ *  - a failure summary with no parseable per-test lines → one capped tail
+ *    finding (still real evidence tests ran and failed).
+ *  - anything else → `uncertain`, and the CALLER FAILS OPEN (an honest note,
+ *    never a guessed finding).
+ *
+ * Callers scrub the output through {@link scrubSecrets} BEFORE classification
+ * so findings/notes never carry secrets (§0.9).
+ */
+export function classifyTestFailure(output, exitCode) {
+    if (exitCode === 0)
+        return { kind: "clean" };
+    const spawnInfra = classifyVerifyInfraFailure(output, exitCode);
+    if (spawnInfra)
+        return { kind: "infra", reason: spawnInfra };
+    for (const [re, reason] of TEST_INFRA_PATTERNS) {
+        if (re.test(output))
+            return { kind: "infra", reason };
+    }
+    // Per-test failure lines, deduped by test name; a later duplicate that DOES
+    // carry a location upgrades the located-less first sighting (node:test prints
+    // the body ✖ first and the located footer ✖ later). `pendingLocation` is the
+    // one-shot `test at file:line` node:test prints directly above a footer ✖;
+    // `currentFile` is jest's sticky `FAIL <file>` header covering its ✕ bullets.
+    const byMessage = new Map();
+    let pendingLocation;
+    let currentFile;
+    for (const raw of output.split("\n")) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        const at = line.match(NODE_TEST_AT);
+        if (at) {
+            pendingLocation = { file: at[1], line: Number(at[2]) };
+            continue;
+        }
+        let parsed;
+        const bullet = line.match(FAIL_BULLET) ?? line.match(TAP_NOT_OK);
+        if (bullet) {
+            const name = stripDuration(bullet[1]);
+            if (name && name.length <= 200 && !/^failing tests:?$/i.test(name)) {
+                parsed = { message: name };
+                if (pendingLocation) {
+                    parsed.file = pendingLocation.file;
+                    parsed.line = pendingLocation.line;
+                }
+                else if (currentFile) {
+                    parsed.file = currentFile;
+                }
+            }
+        }
+        else {
+            const fail = line.match(RUNNER_FAIL);
+            if (fail && /\.[cm]?[jt]sx?$/.test(fail[1])) {
+                // vitest's `FAIL file > suite > name` is a test failure in itself; jest's
+                // bare `FAIL file` only names the file — its ✕ bullets that follow are
+                // located against it via currentFile.
+                if (fail[2])
+                    parsed = { message: stripDuration(fail[2]), file: fail[1] };
+                else
+                    currentFile = fail[1];
+            }
+        }
+        if (!parsed)
+            continue;
+        pendingLocation = undefined;
+        const existing = byMessage.get(parsed.message);
+        if (!existing)
+            byMessage.set(parsed.message, parsed);
+        else if (!existing.file && parsed.file)
+            byMessage.set(parsed.message, parsed);
+    }
+    const failures = [...byMessage.values()].slice(0, MAX_LOCATED_FINDINGS);
+    if (failures.length > 0) {
+        return {
+            kind: "failures",
+            findings: failures.map((f) => {
+                const finding = { severity: "critical", lens: VERIFY_LENS, message: `verify: test failed: ${f.message}` };
+                if (f.file)
+                    finding.file = f.file;
+                if (f.line)
+                    finding.line = f.line;
+                return finding;
+            }),
+        };
+    }
+    if (FAILURE_SUMMARY.some((re) => re.test(output))) {
+        const tail = output.length > MAX_TAIL_CHARS ? output.slice(output.length - MAX_TAIL_CHARS) : output;
+        return {
+            kind: "failures",
+            findings: [
+                {
+                    severity: "critical",
+                    lens: VERIFY_LENS,
+                    message: `verify (test) failed (exit ${exitCode}). Output tail:\n${tail.trim()}`,
+                },
+            ],
+        };
+    }
+    return { kind: "uncertain" };
+}
+/** Match a TypeScript diagnostic line: `path(line,col): error TSxxxx: message`. */
+const TS_DIAGNOSTIC = /^(.+?)\((\d+),\d+\):\s*error\s+TS\d+:\s*(.+)$/;
+/** Match a generic `path:line:col: error message` (eslint/tsc-pretty-ish). */
+const GENERIC_DIAGNOSTIC = /^(.+?):(\d+):\d+:?\s*(?:error\b[:\s]*)?(.+)$/;
+/**
+ * Turn a failing verify run into `critical` Findings. A clean (exit 0) run yields
+ * none. Located diagnostics (TypeScript first, then a generic file:line form) are
+ * parsed into per-error findings; if none parse, a single capped finding carries
+ * the tail of the output so the fix stage still gets actionable signal. Never
+ * throws; always emits at least one finding on a non-zero exit.
+ */
+export function parseVerifyFailures(output, exitCode, label) {
+    if (exitCode === 0)
+        return [];
+    const located = [];
+    const seen = new Set();
+    for (const raw of output.split("\n")) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        const m = line.match(TS_DIAGNOSTIC) ?? line.match(GENERIC_DIAGNOSTIC);
+        if (!m)
+            continue;
+        const file = m[1].trim();
+        const lineNo = Number(m[2]);
+        const message = m[3].trim();
+        // Guard the generic matcher against noise: require a plausible file token.
+        if (!file || /\s/.test(file) || !Number.isFinite(lineNo))
+            continue;
+        const key = `${file}:${lineNo}:${message}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        located.push({ severity: "critical", lens: VERIFY_LENS, message: `verify: ${message}`, file, line: lineNo });
+        if (located.length >= MAX_LOCATED_FINDINGS)
+            break;
+    }
+    if (located.length > 0)
+        return located;
+    const tail = output.length > MAX_TAIL_CHARS ? output.slice(output.length - MAX_TAIL_CHARS) : output;
+    return [
+        {
+            severity: "critical",
+            lens: VERIFY_LENS,
+            message: `verify (${label}) failed (exit ${exitCode}). Output tail:\n${tail.trim()}`,
+        },
+    ];
+}
+const SAFE_ENV_KEYS = [
+    "PATH",
+    "HOME",
+    "USER",
+    "USERNAME",
+    "SHELL",
+    "TMPDIR",
+    "TMP",
+    "TEMP",
+    "SystemRoot",
+    "WINDIR",
+    "PNPM_HOME",
+    "COREPACK_HOME",
+];
+/** Build the environment used for repo verify commands, intentionally excluding secrets and Node injection hooks. */
+export function buildVerifyEnv(source = process.env) {
+    const env = { CI: "true" };
+    for (const key of SAFE_ENV_KEYS) {
+        const value = source[key];
+        if (value !== undefined)
+            env[key] = value;
+    }
+    return env;
+}
+/**
+ * The TEST-half environment (spec §3d): the user's FULL environment — tests
+ * legitimately need the local DB url, service creds, PATH extensions — MINUS
+ * every `YAGNI_*` var (repo-defined commands never inherit YAGNI tokens, §0.9)
+ * and MINUS NODE_OPTIONS (the same injection-hook stripping as the typecheck
+ * half). CI is forced on so a bare `vitest`/`jest --watch` test script runs
+ * once instead of parking in watch mode until the 10-min cap kills it.
+ */
+export function buildTestEnv(source = process.env) {
+    const env = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (value === undefined)
+            continue;
+        if (key.startsWith("YAGNI_"))
+            continue;
+        if (key === "NODE_OPTIONS")
+            continue;
+        env[key] = value;
+    }
+    env.CI = "true";
+    return env;
+}
+// `signal` is deliberately NOT passed into execFile: Node's built-in abort
+// handling kills via the child's pid, and when the spawn itself failed (missing
+// command, missing cwd) an abort landing in the same tick resolves that to pid 0
+// — signalling the WHOLE process group and killing the parent. Abort is wired
+// manually with an explicit pid guard; a killed child reaches the callback with
+// a code-less error, which stays the same fail-open rejection as before.
+const defaultExec = (argv, cwd, signal, env) => new Promise((resolve, reject) => {
+    if (signal.aborted)
+        return reject(new Error("verify aborted before start"));
+    const child = execFile(argv[0], argv.slice(1), { cwd, env: env ?? buildVerifyEnv(), maxBuffer: 32 * 1024 * 1024 }, (err, stdout, stderr) => {
+        signal.removeEventListener("abort", onAbort);
+        const output = `${stdout ?? ""}${stderr ?? ""}`;
+        if (err) {
+            // A non-zero EXIT is a verify failure (carries a numeric code); a spawn
+            // error (ENOENT) or an abort has no numeric code and is a fail-open.
+            const code = err.code;
+            if (typeof code === "number")
+                return resolve({ code, output });
+            return reject(err);
+        }
+        resolve({ code: 0, output });
+    });
+    const onAbort = () => {
+        try {
+            if (child.pid)
+                child.kill("SIGTERM");
+        }
+        catch {
+            /* ignore */
+        }
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+});
+/**
+ * Build the runVerify function injected into the orchestrator. It discovers the
+ * changed package(s) (scoped to this run's diff via `baselinePaths`), detects a
+ * build check for EACH, runs them (in their package dirs) under a composed (caller +
+ * timeout) abort signal, then runs each changed package's own `test` script (the
+ * §3d test half), and unions everything onto a single {@link VerifyOutcome}.
+ * Fail-open on every path it cannot turn into a clean verdict, so the gate never
+ * blocks a real change on its own failure.
+ */
+export function makeRunVerify(opts = {}) {
+    const detect = opts.detect ??
+        ((cwd, changedDirs) => detectVerifyCommands(cwd, {
+            allowRepoOverride: process.env.YAGNI_CODE_ALLOW_VERIFY_OVERRIDE === "1",
+            changedDirs,
+        }));
+    const detectTests = opts.detectTests ?? ((cwd, changedDirs) => detectVerifyTestCommands(cwd, { changedDirs }));
+    const changedDirs = opts.changedDirs ??
+        (async (cwd, signal, baselinePaths) => {
+            const snapshot = await snapshotWorkspace(cwd, signal);
+            if (!snapshot.tracked)
+                return [];
+            // This run's OWN changed packages = the current diff minus the pre-run dirt, so
+            // a stray pre-existing file (or an unrelated dirty package) never pulls its dir
+            // into scope and the gate verifies what THIS run actually touched.
+            return ownChangedDirs(cwd, snapshot.status, baselinePaths ?? [], (p) => readFileSync(p, "utf8"));
+        });
+    const exec = opts.exec ?? defaultExec;
+    const timeoutMs = opts.timeoutMs ?? VERIFY_TIMEOUT_MS;
+    const testTimeoutMs = opts.testTimeoutMs ?? VERIFY_TEST_TIMEOUT_MS;
+    return async function runVerify(cwd, signal, baselinePaths) {
+        const dirs = await changedDirs(cwd, signal, baselinePaths);
+        const commands = detect(cwd, dirs);
+        // An explicitly-allowed .yagni-code/verify override IS the whole gate (spec
+        // §3d: it "covers the test half too"), so no detected test script runs
+        // alongside it — the repo already told us exactly how to verify.
+        const overridden = commands.some((c) => c.source === "override");
+        const testCommands = overridden ? [] : detectTests(cwd, dirs);
+        if (commands.length === 0 && testCommands.length === 0) {
+            return { ran: false, ok: true, reason: "verify skipped: no verify command detected", findings: [] };
+        }
+        const findings = [];
+        const reasons = [];
+        let anyRan = false;
+        // TYPECHECK HALF (frozen behavior, §0.2): run every changed package's build
+        // check; union the findings. One package that cannot spawn fails OPEN (a
+        // recorded reason, no finding) without sinking the verdict for the packages
+        // that did run. Output is scrubbed before it can enter a finding (§0.9).
+        const typecheckLabels = [];
+        for (const command of commands) {
+            const composed = composeAbortSignal(signal, AbortSignal.timeout(timeoutMs));
+            try {
+                const { code, output: rawOutput } = await exec(command.argv, command.cwd, composed);
+                const output = scrubSecrets(rawOutput);
+                if (code !== 0) {
+                    // Infra/env failure (command not found in a fresh worktree, Node loader
+                    // resolution): the ENVIRONMENT could not run the check, so it is the same
+                    // fail-open as a spawn error — an honest reason, never a critical finding
+                    // the fix stage can't clear (invariant §0.2).
+                    const infra = classifyVerifyInfraFailure(output, code);
+                    if (infra) {
+                        reasons.push(`verify (${command.label}) could not run: ${infra}`);
+                        continue;
+                    }
+                }
+                anyRan = true;
+                typecheckLabels.push(command.label);
+                if (code !== 0)
+                    findings.push(...parseVerifyFailures(output, code, command.label));
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                reasons.push(`verify (${command.label}) could not run: ${scrubSecrets(msg)}`);
+            }
+        }
+        // TEST HALF (spec §3d): each changed package's own `test` script, run AFTER
+        // the typecheck half under the user's env minus YAGNI_*/NODE_OPTIONS. When
+        // the typecheck half already produced findings the tests are skipped with an
+        // honest note — a tree that doesn't compile fails its suite for the same
+        // root cause, and the loop must fix the compile errors first anyway; the
+        // round where typecheck goes green runs the tests, so `clean` is never
+        // reached without the tests having run (or their absence honestly noted).
+        const testLabels = [];
+        if (testCommands.length > 0) {
+            if (findings.length > 0) {
+                reasons.push("tests skipped: the typecheck half failed; 'clean' still requires a later round's tests");
+            }
+            else {
+                const testEnv = opts.testEnv ?? buildTestEnv();
+                let testFindingCount = 0;
+                for (const command of testCommands) {
+                    const where = basename(command.cwd) || command.cwd;
+                    const composed = composeAbortSignal(signal, AbortSignal.timeout(testTimeoutMs));
+                    try {
+                        const { code, output: rawOutput } = await exec(command.argv, command.cwd, composed, testEnv);
+                        const output = scrubSecrets(rawOutput);
+                        const cls = classifyTestFailure(output, code);
+                        if (cls.kind === "infra") {
+                            reasons.push(`tests (${where}) could not run: ${cls.reason}; 'clean' reflects typecheck + review only`);
+                            continue;
+                        }
+                        if (cls.kind === "uncertain") {
+                            // Failing OPEN on an uninterpretable failure (§3d): an honest note,
+                            // never a guessed finding the fix stage cannot clear.
+                            reasons.push(`tests (${where}) exited ${code} but the output was not interpretable as test failures; failing open. 'clean' reflects typecheck + review only`);
+                            continue;
+                        }
+                        anyRan = true;
+                        testLabels.push(command.label);
+                        if (cls.kind === "failures") {
+                            const room = Math.max(0, MAX_LOCATED_FINDINGS - testFindingCount);
+                            const take = cls.findings.slice(0, room);
+                            testFindingCount += take.length;
+                            findings.push(...take);
+                        }
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        reasons.push(`tests (${where}) could not run: ${scrubSecrets(msg)}`);
+                    }
+                }
+            }
+        }
+        // The command labels list only what produced a verdict — on BOTH the
+        // typecheck and test halves — so the FINISH trailer's `passed (<cmds>)`
+        // never claims a check that was infra-skipped or threw (invariant §0.1).
+        const command = [...new Set(typecheckLabels), ...new Set(testLabels)].join(", ");
+        if (!anyRan) {
+            return { ran: false, ok: true, command, reason: reasons.join("; ") || "verify skipped", findings: [] };
+        }
+        return {
+            ran: true,
+            ok: findings.length === 0,
+            command,
+            findings,
+            ...(reasons.length ? { reason: reasons.join("; ") } : {}),
+        };
+    };
+}
+//# sourceMappingURL=verify.js.map