// @ref LLP 0008#the-reviewsource-contract — three-valued prepareReadRootAsync (handle/null/throw); memoizeSource shares one materialization across scopes import type { DiffEntry, ReviewMetadata } from "../core/schema.js"; /** * The paths-only manifest of the OPEN pull requests stacked on top of this PR * (they branch off its head). Fetched by a source, injected into the coordinator * so an absence-style finding a later PR already addresses can be requalified. * Everything in it is PR-author-controlled, so it is treated as untrusted data. */ // @ref LLP 0010#the-upstack-manifest [implements] — paths-only, author-controlled, fetched once per run export interface StackManifest { upstackPRs: Array<{ number: number; title: string; authorLogin: string; files: string[] }>; /** A per-PR file list hit its cap (maxFilesPerPr) — the manifest is a subset. */ truncated: boolean; } /** Bounds + gates for the upward stack walk. Resolved in the command layer from the * trusted-base stack config; never head-controlled. Presence of this option (not a * boolean) is what turns the walk on. */ // @ref LLP 0010#bounded-guarded-upward-walk [constrained-by] — every field is a hard bound the walk must never exceed export interface StackWalkOptions { maxDepth: number; maxPrs: number; maxFilesPerPr: number; requireSameAuthor: boolean; } /** Pick the walk bounds out of a resolved stack config (drops enable/v2 fields). */ export function stackWalkFromConfig(stack: StackWalkOptions): StackWalkOptions { return { maxDepth: stack.maxDepth, maxPrs: stack.maxPrs, maxFilesPerPr: stack.maxFilesPerPr, requireSameAuthor: stack.requireSameAuthor, }; } /** The v2 confirmation cap, or undefined when confirmWithPatch is off. Callers apply * the on/off gate (ci: trusted-base `enabled`; review: `--stack-aware`) around this. */ // @ref LLP 0010#patch-level-confirmation-v2 [constrained-by] — confirmWithPatch is the v2 gate; off (default) → grounding is the floor and no patch is ever fetched export function stackConfirmFromConfig(stack: { confirmWithPatch: boolean; maxConfirmations: number; }): { maxConfirmations: number } | undefined { return stack.confirmWithPatch ? { maxConfirmations: stack.maxConfirmations } : undefined; } /** * A Source is where the diff comes from. CI and local mode differ only in which * Source (and Reporter) is wired into the otherwise-identical review core. */ export interface ReviewSource { getMetadata(): Promise; /** Changed files as path + patch text per file. */ getChangedFiles(): Promise; /** * Optionally walk the OPEN PRs stacked on top of this one and return a paths-only * manifest. Any error, rate limit, non-stack PR, or empty result returns `null` * (fail-open — a broken walk never blocks or changes a review). Omitted entirely * by sources with no concept of a stack (LocalGitSource) → a structural no-op. */ // @ref LLP 0010#the-upstack-manifest [constrained-by] — fail-open: any failure returns null, never throws, so a broken walk leaves the review exactly as if the feature were off getStackContextAsync?(options: StackWalkOptions): Promise; /** * Optionally fetch just the unified-diff patch a stacked child PR applied to ONE * file (v2 patch confirmation). Returns `null` when the file isn't in that PR or on * any error — fail-open, exactly like getStackContextAsync, so the caller strips the * requalification (finding stays blocking). Omitted by sources with no stack concept. */ // @ref LLP 0010#patch-level-confirmation-v2 [constrained-by] — fail-open null: a fetch failure strips the requalification rather than believing it getStackFilePatchAsync?(prNumber: number, file: string): Promise; /** * Optionally materialize the exact tree the review should READ from and return its * directory + a cleanup. The review core chdirs into it while running the agents * and the verifier, so their read/grep tools see the right versions of files. * * This matters for a GitHub PR: the diff is authoritative from the API, but the * agents also read surrounding source and the verifier re-reads cited files — and * those must be the PR-HEAD versions, not whatever happens to be checked out. * Return `null` (or omit the method) to just review the current working directory. * * Contract: `null` means "no tree to materialize" (a deliberate, safe * fall-through to the current checkout). A materialization FAILURE throws — * the review core fails closed on it in CI mode and falls back softly only in * local mode, where the user's own checkout is an acceptable read root. */ // @ref LLP 0008#the-reviewsource-contract [constrained-by] — null and throw are not interchangeable: null is safe fall-through, throw is real failure the caller must interpret per mode prepareReadRootAsync?(): Promise; } export interface PreparedReadRoot { /** Directory the review should read from (chdir target). */ dir: string; /** Remove the materialized tree; always called in a finally. */ cleanup: () => Promise; } /** * Wrap a source so getMetadata/getChangedFiles/prepareReadRootAsync each run once * and are shared across N sequential runReview calls (one `gh pr diff`, one * PR-head worktree for the whole fan-out — rate-limit hygiene, risk 6). The wrapped * prepareReadRootAsync hands each run a handle whose cleanup() is a no-op; the real * cleanup is deferred to dispose(), which must be called once after the last scope. */ // @ref LLP 0008#the-reviewsource-contract [implements] — one fetch/worktree shared across N scope runs; dispose() must run once, after the last scope, not per call export function memoizeSource(source: ReviewSource): ReviewSource & { dispose(): Promise } { let metadataPromise: Promise | undefined; let changedPromise: Promise | undefined; let readRootPromise: Promise | undefined; let stackPromise: Promise | undefined; let realHandle: PreparedReadRoot | null = null; const stackFn = source.getStackContextAsync; const patchFn = source.getStackFilePatchAsync; return { getMetadata: () => (metadataPromise ??= source.getMetadata()), getChangedFiles: () => (changedPromise ??= source.getChangedFiles()), // One PR has one stack: fetch it once and share it across every scope's run // (like getMetadata). Only exposed when the wrapped source can walk a stack, so // an optional-chained call on a stack-less source stays a structural no-op. ...(stackFn ? { getStackContextAsync: (options: StackWalkOptions) => (stackPromise ??= stackFn.call(source, options)), } : {}), // Passed straight through: v2 confirmation dedupes by (prNumber, file) within a run // and the fetch is cheap, so it needs no cross-scope memo — only the conditional // exposure that keeps a stack-less source a structural no-op. ...(patchFn ? { getStackFilePatchAsync: (prNumber: number, file: string) => patchFn.call(source, prNumber, file), } : {}), prepareReadRootAsync: async () => { readRootPromise ??= source.prepareReadRootAsync ? source.prepareReadRootAsync() : Promise.resolve(null); realHandle = await readRootPromise; if (!realHandle) { return null; } // No-op cleanup per run; the real teardown happens once in dispose(). return { dir: realHandle.dir, cleanup: async () => {} }; }, dispose: async () => { if (realHandle) { const handle = realHandle; realHandle = null; await handle.cleanup(); } }, }; }