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

package/dist/extension/pipeline/verify.d.ts

@@ -0,0 +1,277 @@
+/**
+ * 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 type { Finding } from "./types.js";
+/** Total wall-clock budget for a single verify run before it is abandoned (fail-open). */
+export declare const VERIFY_TIMEOUT_MS: number;
+/** Per-PACKAGE wall-clock budget for the test half (spec §3d); overrun fails open. */
+export declare const VERIFY_TEST_TIMEOUT_MS: number;
+/** A resolved verify command plus how it was found. */
+export interface VerifyCommand {
+    /** Shell-free command + args, e.g. ["pnpm", "run", "typecheck"]. */
+    argv: string[];
+    /** Human label (the script name or override) for findings + the honest note. */
+    label: string;
+    source: "override" | "script";
+    /**
+     * The absolute dir to run the command IN: the changed package's dir for a
+     * scoped script, or the repo root for an override / repo-root fallback. This is
+     * what keeps the gate off the repo-root recursive runner in a monorepo.
+     */
+    cwd: string;
+}
+/** The outcome of one verify attempt. `ran: false` is the fail-open path. */
+export interface VerifyOutcome {
+    /** Did a command actually run to completion? false = no command / spawn failed / timed out. */
+    ran: boolean;
+    /** Did the change pass the gate? true when it ran clean OR when it could not run (fail-open). */
+    ok: boolean;
+    /** The command label, when one was resolved. */
+    command?: string;
+    /** Honest note when the gate did not produce a verdict (skipped / unrunnable / timed out). */
+    reason?: string;
+    /** Critical findings parsed from a failing run; empty otherwise. */
+    findings: Finding[];
+}
+/** Injectable fs seam so detection is unit-testable without a real repo. */
+export interface DetectOpts {
+    readFile?: (path: string) => string;
+    /** Allow a repo-local .yagni-code/verify override. Defaults false. */
+    allowRepoOverride?: boolean;
+    /**
+     * Absolute dirs of the package(s) the change touched (from
+     * {@link resolvePackageDirs}). When present, the first one with a usable,
+     * non-fanned-out script is selected and the gate is SCOPED to it; the repo-root
+     * fallback is only used when none qualify. Absent => repo-root fallback only.
+     */
+    changedDirs?: string[];
+}
+/**
+ * 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 declare function detectPackageManager(cwd: string, readFile: (p: string) => string): string;
+/**
+ * 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 declare function isFannedOutScript(body: string): boolean;
+/**
+ * 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 declare function parseChangedPaths(status: string): string[];
+/**
+ * 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 declare function resolvePackageDirs(repoRoot: string, relPaths: string[], readFile: (path: string) => string): string[];
+/**
+ * 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 declare function ownChangedDirs(repoRoot: string, status: string, baselinePaths: string[], readFile: (path: string) => string): string[];
+/**
+ * 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 declare function detectVerifyCommands(cwd: string, opts?: DetectOpts): VerifyCommand[];
+/** Back-compat singular: the first detected verify command, or null. */
+export declare function detectVerifyCommand(cwd: string, opts?: DetectOpts): VerifyCommand | 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 declare function detectVerifyTestCommands(cwd: string, opts?: DetectOpts): VerifyCommand[];
+/**
+ * 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 declare function classifyVerifyInfraFailure(output: string, exitCode: number): string | null;
+/** How the pure test classifier read one test run (spec §3d). */
+export type TestFailureClassification = {
+    kind: "clean";
+} | {
+    kind: "failures";
+    findings: Finding[];
+} | {
+    kind: "infra";
+    reason: string;
+} | {
+    kind: "uncertain";
+};
+/**
+ * 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 declare function classifyTestFailure(output: string, exitCode: number): TestFailureClassification;
+/**
+ * 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 declare function parseVerifyFailures(output: string, exitCode: number, label: string): Finding[];
+/** Result of actually executing the resolved command. */
+export interface VerifyExecResult {
+    code: number;
+    output: string;
+}
+/**
+ * The impure exec seam (default: execFile); injected in tests. The optional
+ * `env` is the §3d seam extension: absent (the typecheck half — byte-identical
+ * to the pre-test-half contract) the default exec applies the scrubbed
+ * {@link buildVerifyEnv}; the test half passes {@link buildTestEnv}'s user env.
+ * Existing 3-arg implementations remain assignable.
+ */
+export type VerifyExec = (argv: string[], cwd: string, signal: AbortSignal, env?: NodeJS.ProcessEnv) => Promise<VerifyExecResult>;
+/** Build the environment used for repo verify commands, intentionally excluding secrets and Node injection hooks. */
+export declare function buildVerifyEnv(source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * 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 declare function buildTestEnv(source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export interface MakeRunVerifyOpts {
+    detect?: (cwd: string, changedDirs: string[]) => VerifyCommand[];
+    /**
+     * Discover the changed package dir(s) the gate should scope to. Default: a real
+     * `git status` via {@link snapshotWorkspace} folded through the pure
+     * {@link parseChangedPaths} + {@link resolvePackageDirs}, MINUS the `baselinePaths`
+     * (the tree's pre-run dirt), so the scope is THIS run's own diff and an unrelated
+     * dirty package never retargets the gate. Injected in tests to stay hermetic.
+     * Recomputed each round so the scope follows the growing diff.
+     */
+    changedDirs?: (cwd: string, signal?: AbortSignal, baselinePaths?: string[]) => Promise<string[]>;
+    exec?: VerifyExec;
+    timeoutMs?: number;
+    /**
+     * Discover the TEST-half command(s) (spec §3d). Default: each changed
+     * package's own `test` script via {@link detectVerifyTestCommands}. Injected
+     * in tests. NOT consulted when the typecheck half resolved to a
+     * `.yagni-code/verify` override (the override covers the test half).
+     */
+    detectTests?: (cwd: string, changedDirs: string[]) => VerifyCommand[];
+    /** Per-package wall-clock cap for the test half (default VERIFY_TEST_TIMEOUT_MS). */
+    testTimeoutMs?: number;
+    /** Test-half env override for determinism in tests (default: buildTestEnv() per run). */
+    testEnv?: NodeJS.ProcessEnv;
+}
+/**
+ * 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 declare function makeRunVerify(opts?: MakeRunVerifyOpts): (cwd: string, signal?: AbortSignal, baselinePaths?: string[]) => Promise<VerifyOutcome>;
+//# sourceMappingURL=verify.d.ts.map