@nanonets/graft 0.16.0 → 0.18.0

package/README.md

@@ -17,7 +17,7 @@
   <img src="https://img.shields.io/badge/License-MIT-20C997?style=for-the-badge" />
   <a href="TELEMETRY.md"><img src="https://img.shields.io/badge/telemetry-anonymous%2C%20opt--out-546FFF?style=for-the-badge" /></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/NanoNets/Graft"><img src="https://img.shields.io/ossf-scorecard/github.com/NanoNets/Graft?style=for-the-badge&label=openssf%20scorecard" /></a>
-  <a href="https://github.com/apps/trailhq-graft"><img src="https://img.shields.io/badge/PR%20reviews-install%20GitHub%20App-546FFF?style=for-the-badge&logo=github&logoColor=white" /></a>
+  <a href="https://app.trailhq.com/get-started?step=pick"><img src="https://img.shields.io/badge/Trail%20Brain-try%20it-E5484D?style=for-the-badge&logoColor=white" /></a>
 </p>
 
 ### Up to **4× cheaper** and **3× faster**, with better or no loss of correctness.
@@ -31,7 +31,14 @@
 
 </div>
 
-<p align="center"><b>Reviewing pull requests?</b> <a href="https://github.com/apps/trailhq-graft">Add the graft GitHub App</a> to get an automatic blast-radius review on every PR.</p>
+<p align="center">
+  <b>This works beyond code too.</b><br/>
+  A living skill file that learns from every task and gets sharper the more your team works.
+</p>
+
+<p align="center">
+  <a href="https://app.trailhq.com/get-started?step=pick"><img src="https://img.shields.io/badge/Try%20Trail%20Brain%20%E2%86%92-E5484D?style=for-the-badge" alt="Try Trail Brain" height="34"/></a>
+</p>
 
 <p align="center">
   <img src="assets/graft-comparison-demo.gif" alt="Side-by-side comparison of a coding agent working with and without graft" width="820"/>

package/dist/app/brain-build.d.ts

@@ -0,0 +1,66 @@
+import { type AppCredentials, type Fetch, type RepoAccessGap } from "./identity.js";
+import { type RepoDigest } from "./history.js";
+/** One request to build a repository into a brain. */
+export interface BrainBuildJob {
+    owner: string;
+    repo: string;
+    /** Branch to read; empty means the repository's default. */
+    ref?: string;
+    /**
+     * The brain the rules land in, and the workspace key to write it with.
+     *
+     * Both optional, and omitting them changes the mode: with them, the digest is
+     * posted straight to the brain and only a job id comes back; without them the
+     * digest is RETURNED and the caller ingests it itself.
+     *
+     * The second mode is what the platform's own proxy uses. It already holds the
+     * user's session and can write to the brain directly, so handing graft a
+     * workspace key just to have it call back would mean minting a credential per
+     * build for no gain.
+     */
+    brainId?: string;
+    brainToken?: string;
+    /** Platform base URL. Defaults to production. */
+    brainBaseUrl?: string;
+    /** File the rules as approved rather than as drafts. Onboarding sets it:
+     * a brain whose every rule is an invisible draft answers nothing. */
+    autoApprove?: boolean;
+}
+export interface BrainBuildResult {
+    /** Set only when the digest was posted; empty in return-the-digest mode. */
+    jobId: string;
+    headSha: string;
+    commits: number;
+    threads: number;
+    symbols: number;
+    sources: number;
+    /** Set only in return-the-digest mode. */
+    digest?: RepoDigest;
+}
+export interface BrainBuildDeps {
+    creds: AppCredentials;
+    fetch: Fetch;
+    api?: string;
+    githubHost?: string;
+    log?: (msg: string) => void;
+    now?: () => number;
+}
+/** Raised when the App cannot see the repository. Distinct because the caller
+ * turns it into a specific answer — "install the app, or run it locally" — and
+ * not into a 500. */
+export declare class RepoNotAccessibleError extends Error {
+    /** Which gap it is, so the caller can send the user to the right place. */
+    readonly gap: RepoAccessGap;
+    constructor(message: string, 
+    /** Which gap it is, so the caller can send the user to the right place. */
+    gap?: RepoAccessGap);
+}
+/**
+ * Read the repository and hand its history to the brain.
+ *
+ * Public repositories still go through the installation lookup, because the App
+ * needs a token to clone at any useful rate limit, and a repository the App is
+ * not installed on is exactly the case the UI has to distinguish.
+ */
+export declare function buildRepoIntoBrain(job: BrainBuildJob, deps: BrainBuildDeps): Promise<BrainBuildResult>;
+//# sourceMappingURL=brain-build.d.ts.map

package/dist/app/brain-build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-build.d.ts","sourceRoot":"","sources":["../../src/app/brain-build.ts"],"names":[],"mappings":"AAiBA,OAAO,EAA0C,KAAK,cAAc,EAAE,KAAK,KAAK,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAC5H,OAAO,EAAkE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAc/G,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;yEACqE;IACrE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;qBAEqB;AACrB,qBAAa,sBAAuB,SAAQ,KAAK;IAG7C,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,aAAa;gBAF3B,OAAO,EAAE,MAAM;IACf,2EAA2E;IAClE,GAAG,GAAE,aAAgF;CAIjG;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,gBAAgB,CAAC,CA4H3B"}

package/dist/app/brain-build.js

@@ -0,0 +1,169 @@
+/**
+ * Building one repository into a brain, on demand.
+ *
+ * The whole point of the onboarding flow this serves: someone pastes a
+ * repository URL, and a minute later they are looking at rules mined from their
+ * own history. Nothing is installed and nobody has signed up yet, so this has to
+ * work from the repository name alone.
+ *
+ * Runs in the app rather than in the platform because only the app has the
+ * GitHub App credentials, only it can clone, and only graft can build a symbol
+ * graph. What crosses back to the platform is a digest of messages and symbol
+ * ids — never source.
+ */
+import { buildGraph } from "../graph/build.js";
+import { contextDirFor } from "../context/node-file.js";
+import { loadGraphCached } from "../graph/load.js";
+import { checkoutRepository } from "./checkout.js";
+import { appJwt, installationFor, repoAccessGap } from "./identity.js";
+import { buildDigest, postDigest, readCommits, readSymbols, readThreads } from "./history.js";
+import { budgetSources, readAgentInstructions, readBranchProtection, readCodeowners, readCodifiedRules, readDecisionDocs, readDeclinedIssues, readReverts, readTestNames, } from "./sources.js";
+/** Raised when the App cannot see the repository. Distinct because the caller
+ * turns it into a specific answer — "install the app, or run it locally" — and
+ * not into a 500. */
+export class RepoNotAccessibleError extends Error {
+    gap;
+    constructor(message, 
+    /** Which gap it is, so the caller can send the user to the right place. */
+    gap = { reason: "not_installed", ownerId: null, installationId: null }) {
+        super(message);
+        this.gap = gap;
+    }
+}
+/**
+ * Read the repository and hand its history to the brain.
+ *
+ * Public repositories still go through the installation lookup, because the App
+ * needs a token to clone at any useful rate limit, and a repository the App is
+ * not installed on is exactly the case the UI has to distinguish.
+ */
+export async function buildRepoIntoBrain(job, deps) {
+    const log = deps.log ?? (() => { });
+    const api = deps.api ?? "https://api.github.com";
+    const tag = `${job.owner}/${job.repo}`;
+    const installationId = await installationFor(deps.creds, job.owner, job.repo, deps.fetch, (deps.now ?? Date.now)(), api);
+    if (installationId === null) {
+        // Which of the two gaps it is decides what the UI can offer, so it is
+        // resolved here rather than guessed there.
+        const gap = await repoAccessGap(deps.creds, job.owner, deps.fetch, (deps.now ?? Date.now)(), api);
+        throw new RepoNotAccessibleError(gap.reason === "repo_not_selected"
+            ? `graft is installed on ${job.owner} but ${tag} is not in the list of repositories it can see`
+            : `graft is not installed on ${job.owner}`, gap);
+    }
+    const tokenRes = await deps.fetch(`${api}/app/installations/${installationId}/access_tokens`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${appJwt(deps.creds, (deps.now ?? Date.now)())}`,
+            accept: "application/vnd.github+json",
+            "user-agent": "graft-app",
+        },
+    });
+    if (!tokenRes.ok) {
+        throw new Error(`installation token for ${tag} failed: ${tokenRes.status}`);
+    }
+    const token = JSON.parse(await tokenRes.text()).token;
+    // Whether the repository is private decides what the UI may show before
+    // signup, and the default branch is not discoverable from a shallow
+    // single-ref fetch (there is no origin/HEAD to resolve), so both are read from
+    // the API in one call rather than guessed.
+    const meta = await repoMeta(job.owner, job.repo, token, deps.fetch, api);
+    const checkout = checkoutRepository({
+        owner: job.owner,
+        repo: job.repo,
+        ref: job.ref || meta.defaultBranch,
+        token,
+        api: deps.githubHost,
+        log,
+    });
+    try {
+        // `graphOnly`: the symbol ids and their hashes are all the digest needs, and
+        // the markdown projections cost real time on a large repo.
+        await buildGraph(checkout.dir, { graphOnly: true });
+        const graph = loadGraphCached(contextDirFor(checkout.dir));
+        const commits = readCommits(checkout.dir);
+        const symbols = readSymbols(graph);
+        // The threads are the slow part (two API calls per pull request), and the
+        // one most likely to fail on a rate limit. A failure here degrades to a
+        // commits-only ingest rather than losing the whole build.
+        let threads = [];
+        try {
+            threads = await readThreads(job.owner, job.repo, token, deps.fetch, api);
+        }
+        catch (e) {
+            log(`${tag}: pull-request discussion unavailable (${e instanceof Error ? e.message : e}); mining commits only`);
+        }
+        // Everything the repo already states as a rule. All best-effort: the file
+        // readers cannot fail the build, and the two API readers swallow their own
+        // errors, so a repo with none of this still gets a brain from its history.
+        const sources = budgetSources([
+            ...readAgentInstructions(checkout.dir),
+            ...readDecisionDocs(checkout.dir),
+            ...readCodeowners(checkout.dir),
+            ...readCodifiedRules(checkout.dir),
+            ...readReverts(checkout.dir),
+            ...readTestNames(symbols.map((s) => ({ name: s.name, path: s.path }))),
+            ...(await readBranchProtection(job.owner, job.repo, meta.defaultBranch, token, deps.fetch, api)),
+            ...(await readDeclinedIssues(job.owner, job.repo, token, deps.fetch, api)),
+        ]);
+        log(`${tag}: read ${commits.length} commits, ${threads.length} threads, ${symbols.length} symbols, ${sources.length} stated sources`);
+        const digest = buildDigest({
+            owner: job.owner,
+            name: job.repo,
+            headSha: checkout.headSha,
+            defaultBranch: job.ref || meta.defaultBranch,
+            isPrivate: meta.isPrivate,
+            commits,
+            threads,
+            symbols,
+            sources,
+            autoApprove: job.autoApprove ?? false,
+        });
+        const counts = {
+            headSha: checkout.headSha,
+            commits: commits.length,
+            threads: threads.length,
+            symbols: symbols.length,
+            sources: sources.length,
+        };
+        if (!job.brainId || !job.brainToken) {
+            return { jobId: "", ...counts, digest };
+        }
+        const { jobId } = await postDigest(job.brainBaseUrl ?? "https://agents.nanonets.com", job.brainId, job.brainToken, digest, deps.fetch);
+        return { jobId, ...counts };
+    }
+    finally {
+        // Always: the clone was made with an installation token and is not something
+        // to leave in /tmp.
+        checkout.cleanup();
+    }
+}
+/**
+ * The repository's visibility and default branch, in one call.
+ *
+ * Unknown counts as private: saying a repo is public when it is not would leak
+ * its name into a pre-signup screen. An unknown default branch is left empty,
+ * and the checkout then falls back to whatever the remote's HEAD points at,
+ * which is the same thing by another route.
+ */
+async function repoMeta(owner, repo, token, fetchImpl, api) {
+    try {
+        const res = await fetchImpl(`${api}/repos/${owner}/${repo}`, {
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: "application/vnd.github+json",
+                "user-agent": "graft-app",
+            },
+        });
+        if (!res.ok)
+            return { isPrivate: true, defaultBranch: "" };
+        const parsed = JSON.parse(await res.text());
+        return {
+            isPrivate: parsed.private !== false,
+            defaultBranch: (parsed.default_branch ?? "").trim(),
+        };
+    }
+    catch {
+        return { isPrivate: true, defaultBranch: "" };
+    }
+}
+//# sourceMappingURL=brain-build.js.map

package/dist/app/brain-build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-build.js","sourceRoot":"","sources":["../../src/app/brain-build.ts"],"names":[],"mappings":"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"}

package/dist/app/checkout.d.ts

@@ -5,24 +5,74 @@ export interface CheckoutRequest {
     baseRef: string;
     token: string;
     api?: string;
+    /** Where to say which of GitHub's two PR refs the review is actually using —
+     * the App's own log callback, so the two cases are told apart in the container
+     * logs rather than guessed at from the comment. */
+    log?: (msg: string) => void;
 }
 export interface Checkout {
-    /** Working tree at the pull request's merge commit. */
+    /** Working tree at the pull request's merge commit, or at its head commit when
+     * the merge ref is gone (see {@link ref}). */
     dir: string;
     /** What `blast --base` should diff against. */
     base: string;
+    /** Which ref the tree came from. `merge` is the normal case; `head` means the
+     * pull request is closed and GitHub has deleted its merge preview. */
+    ref: "merge" | "head";
     /** Removes the tree. Always call it — the token's clone is not something to
      * leave in /tmp. */
     cleanup: () => void;
 }
 /**
- * Fetch the PR's merge ref and its base, shallow.
+ * Fetch the PR's code and its base, shallow, and land on it.
  *
  * `refs/pull/N/merge` is GitHub's own merge of the PR into its base — the same
  * thing the checks see, and the right thing to review: it is what will land, not
- * what the contributor's branch says in isolation.
+ * what the contributor's branch says in isolation. It is preferred whenever it
+ * exists.
+ *
+ * But GitHub DELETES that ref the moment a pull request is closed or merged: it
+ * is only a preview of a merge, and there is nothing left to preview afterwards.
+ * Re-reviewing any merged PR therefore died at the fetch with `couldn't find
+ * remote ref refs/pull/N/merge` — 16 in a row on one installation — which is why
+ * `refs/pull/N/head` (the branch tip as the author pushed it, kept indefinitely
+ * in the BASE repository, so it survives even the fork being deleted) is fetched
+ * as a fallback. What changes with it is the diff basis, which
+ * {@link headDiffBase} is entirely about.
  */
 export declare function checkoutPullRequest(req: CheckoutRequest): Checkout;
+/** What a plain-repository checkout needs: no pull request, just a ref. */
+export interface RepoCheckoutRequest {
+    owner: string;
+    repo: string;
+    /** Branch to read. Empty means "whatever HEAD points at" (the default branch). */
+    ref?: string;
+    token: string;
+    /** How much history to fetch. The default is deeper than a PR review needs
+     * because commit MESSAGES are the payload here, not a diff — 50 commits is a
+     * fortnight on an active repo and would mine almost nothing. */
+    depth?: number;
+    api?: string;
+    log?: (msg: string) => void;
+}
+/** A plain checkout: the tree, the commit it landed on, and the cleanup. */
+export interface RepoCheckout {
+    dir: string;
+    headSha: string;
+    /** The branch actually checked out, resolved when the caller named none. */
+    branch: string;
+    cleanup: () => void;
+}
+/**
+ * Clone one repository at a ref, shallow, for reading rather than reviewing.
+ *
+ * Separate from {@link checkoutPullRequest} rather than a flag on it: that
+ * function's whole shape — two refspecs, the merge/head fallback, the diff-base
+ * resolution — exists to answer "what does this pull request change", and none
+ * of it applies to "read this repository's history". Sharing the hardened `git`
+ * runner is the part worth reusing.
+ */
+export declare function checkoutRepository(req: RepoCheckoutRequest): RepoCheckout;
 /** Never let a token reach a log line, even inside git's own error text. */
 export declare function redact(text: string, token: string): string;
 //# sourceMappingURL=checkout.d.ts.map

package/dist/app/checkout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../../src/app/checkout.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,QAAQ;IACvB,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb;wBACoB;IACpB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAkCD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,QAAQ,CAoClE;AAED,4EAA4E;AAC5E,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI1D"}
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../../src/app/checkout.ts"],"names":[],"mappings":"AAoCA,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;uDAEmD;IACnD,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,QAAQ;IACvB;kDAC8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb;0EACsE;IACtE,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC;IACtB;wBACoB;IACpB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AA+CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,QAAQ,CA2DlE;AAED,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd;;oEAEgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,YAAY,CAqCzE;AAyED,4EAA4E;AAC5E,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI1D"}

package/dist/app/checkout.js

@@ -21,6 +21,16 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 /** Enough history for a merge base against the pull request's base branch. */
 const FETCH_DEPTH = 50;
+/**
+ * One extra reach back, used only on the `/head` fallback below.
+ *
+ * An open PR's base tip is a commit or two from the merge base, so 50 is plenty.
+ * A pull request being re-reviewed weeks after it merged is the opposite case:
+ * the base branch has moved on by however many commits the repo lands in that
+ * time, and the commit the branch was actually merged on top of sits behind all
+ * of them. Deepening once is cheaper than raising `FETCH_DEPTH` for every review.
+ */
+const DEEPEN_DEPTH = 500;
 const GIT_TIMEOUT_MS = 120_000;
 /** A git invocation with the dangerous parts of the environment removed. */
 function git(dir, args, token) {
@@ -47,48 +57,206 @@ function git(dir, args, token) {
             HOME: dir,
         },
     });
-    return { ok: res.status === 0, err: `${res.stderr ?? ""}${res.error ? ` ${res.error.message}` : ""}`.trim() };
+    return {
+        ok: res.status === 0,
+        out: res.stdout ?? "",
+        err: `${res.stderr ?? ""}${res.error ? ` ${res.error.message}` : ""}`.trim(),
+    };
 }
+/** First line of a git command's output, or null when it said nothing useful. */
+function line(dir, args) {
+    const { ok, out } = git(dir, args);
+    const first = out.split("\n")[0]?.trim() ?? "";
+    return ok && first !== "" ? first : null;
+}
+const short = (sha) => sha.slice(0, 7);
 /**
- * Fetch the PR's merge ref and its base, shallow.
+ * Fetch the PR's code and its base, shallow, and land on it.
  *
  * `refs/pull/N/merge` is GitHub's own merge of the PR into its base — the same
  * thing the checks see, and the right thing to review: it is what will land, not
- * what the contributor's branch says in isolation.
+ * what the contributor's branch says in isolation. It is preferred whenever it
+ * exists.
+ *
+ * But GitHub DELETES that ref the moment a pull request is closed or merged: it
+ * is only a preview of a merge, and there is nothing left to preview afterwards.
+ * Re-reviewing any merged PR therefore died at the fetch with `couldn't find
+ * remote ref refs/pull/N/merge` — 16 in a row on one installation — which is why
+ * `refs/pull/N/head` (the branch tip as the author pushed it, kept indefinitely
+ * in the BASE repository, so it survives even the fork being deleted) is fetched
+ * as a fallback. What changes with it is the diff basis, which
+ * {@link headDiffBase} is entirely about.
  */
 export function checkoutPullRequest(req) {
     const host = (req.api ?? "https://github.com").replace(/\/$/, "");
     const dir = mkdtempSync(join(tmpdir(), `graft-app-${req.owner}-${req.repo}-`));
     const cleanup = () => rmSync(dir, { recursive: true, force: true });
-    const steps = [
+    const log = req.log ?? (() => { });
+    const tag = `${req.owner}/${req.repo}#${req.number}`;
+    const fail = (step, err) => {
+        cleanup();
+        // A merge ref is absent while GitHub is still computing mergeability, and
+        // present-but-stale right after a push — worth saying which step failed so
+        // that case is distinguishable from a permissions problem.
+        throw new Error(`checkout ${tag} failed at ${step}: ${redact(err, req.token)}`);
+    };
+    const setup = [
         ["init", ["init", "--quiet", "-b", "__graft_base"]],
         ["remote", ["remote", "add", "origin", `${host}/${req.owner}/${req.repo}.git`]],
-        // Both refs in one fetch: the merge ref to review, the base to diff against.
-        [
-            "fetch",
-            [
-                "fetch",
-                "--quiet",
-                `--depth=${FETCH_DEPTH}`,
-                "--no-recurse-submodules",
-                "origin",
-                `+refs/pull/${req.number}/merge:refs/graft/merge`,
-                `+refs/heads/${req.baseRef}:refs/graft/base`,
-            ],
-        ],
-        ["checkout", ["checkout", "--quiet", "--detach", "refs/graft/merge"]],
     ];
-    for (const [name, args] of steps) {
-        const { ok, err } = git(dir, args, name === "fetch" ? req.token : undefined);
-        if (!ok) {
-            cleanup();
-            // A merge ref is absent while GitHub is still computing mergeability, and
-            // present-but-stale right after a push — worth saying which step failed so
-            // that case is distinguishable from a permissions problem.
-            throw new Error(`checkout ${req.owner}/${req.repo}#${req.number} failed at ${name}: ${redact(err, req.token)}`);
+    for (const [name, args] of setup) {
+        const { ok, err } = git(dir, args);
+        if (!ok)
+            fail(name, err);
+    }
+    // Both refs in one fetch: the ref to review, the base to diff against.
+    const merge = git(dir, fetchArgs(req, "merge"), req.token);
+    const ref = merge.ok ? "merge" : "head";
+    if (!merge.ok) {
+        const head = git(dir, fetchArgs(req, "head"), req.token);
+        // Neither ref: a base branch that has since been deleted, an installation
+        // that lost access, a repository that is gone. Both errors go out, because a
+        // bare "couldn't find refs/pull/N/merge" now means only "this PR is closed"
+        // and says nothing about why the fallback did not save it either.
+        if (!head.ok) {
+            fail("fetch", `${merge.err} | falling back to refs/pull/${req.number}/head: ${head.err}`);
         }
     }
-    return { dir, base: "refs/graft/base", cleanup };
+    const co = git(dir, ["checkout", "--quiet", "--detach", `refs/graft/${ref}`]);
+    if (!co.ok)
+        fail("checkout", co.err);
+    if (ref === "merge") {
+        log(`${tag}: reviewing refs/pull/${req.number}/merge against ${req.baseRef}`);
+        return { dir, base: "refs/graft/base", ref, cleanup };
+    }
+    const against = headDiffBase(dir, req);
+    if (against === null) {
+        fail("diff base", `refs/pull/${req.number}/merge is gone and refs/pull/${req.number}/head gives no diff against ` +
+            `${req.baseRef}: within ${FETCH_DEPTH + DEEPEN_DEPTH} commits they share no history, or the branch ` +
+            `is already in ${req.baseRef} with no merge commit to diff against (a fast-forward merge)`);
+    }
+    // Not "the PR is closed": that is only the usual reason the merge ref is
+    // missing, and stating it as fact would send an operator chasing the wrong
+    // thing when the fetch failed for some other reason.
+    log(`${tag}: no refs/pull/${req.number}/merge (GitHub deletes it when a pull request closes), reviewing refs/pull/${req.number}/head against ${against}`);
+    return { dir, base: "refs/graft/base", ref, cleanup };
+}
+/**
+ * Clone one repository at a ref, shallow, for reading rather than reviewing.
+ *
+ * Separate from {@link checkoutPullRequest} rather than a flag on it: that
+ * function's whole shape — two refspecs, the merge/head fallback, the diff-base
+ * resolution — exists to answer "what does this pull request change", and none
+ * of it applies to "read this repository's history". Sharing the hardened `git`
+ * runner is the part worth reusing.
+ */
+export function checkoutRepository(req) {
+    const host = (req.api ?? "https://github.com").replace(/\/$/, "");
+    const dir = mkdtempSync(join(tmpdir(), `graft-repo-${req.owner}-${req.repo}-`));
+    const cleanup = () => rmSync(dir, { recursive: true, force: true });
+    const log = req.log ?? (() => { });
+    const tag = `${req.owner}/${req.repo}`;
+    const fail = (step, err) => {
+        cleanup();
+        throw new Error(`${tag}: ${step} failed: ${redact(err, req.token)}`);
+    };
+    const init = git(dir, ["init", "--quiet", "--initial-branch=graft-tmp"]);
+    if (!init.ok)
+        fail("init", init.err);
+    const remote = git(dir, ["remote", "add", "origin", `${host}/${req.owner}/${req.repo}.git`]);
+    if (!remote.ok)
+        fail("remote", remote.err);
+    const depth = req.depth ?? REPO_FETCH_DEPTH;
+    // A named branch is fetched by name; with none, `HEAD` resolves to whatever
+    // the remote's default branch is, which is what the caller means by "the
+    // repository" and saves an API round trip to look the name up.
+    const refspec = req.ref
+        ? `+refs/heads/${req.ref}:refs/graft/head`
+        : `+HEAD:refs/graft/head`;
+    const fetched = git(dir, ["fetch", "--quiet", `--depth=${depth}`, "--no-recurse-submodules", "origin", refspec], req.token);
+    if (!fetched.ok)
+        fail("fetch", fetched.err);
+    const co = git(dir, ["checkout", "--quiet", "--detach", "refs/graft/head"]);
+    if (!co.ok)
+        fail("checkout", co.err);
+    const headSha = line(dir, ["rev-parse", "HEAD"]) ?? "";
+    const branch = req.ref ?? line(dir, ["rev-parse", "--abbrev-ref", "origin/HEAD"]) ?? "";
+    log(`${tag}: read ${req.ref || "HEAD"} at ${short(headSha)} (${depth} commits deep)`);
+    return { dir, headSha, branch: branch.replace(/^origin\//, ""), cleanup };
+}
+/** Default history depth for a repository read. See RepoCheckoutRequest.depth. */
+const REPO_FETCH_DEPTH = 500;
+/** The one fetch each attempt makes: the PR ref to review plus the base branch. */
+function fetchArgs(req, pull, deepen = false) {
+    return [
+        "fetch",
+        "--quiet",
+        deepen ? `--deepen=${DEEPEN_DEPTH}` : `--depth=${FETCH_DEPTH}`,
+        "--no-recurse-submodules",
+        "origin",
+        `+refs/pull/${req.number}/${pull}:refs/graft/${pull}`,
+        `+refs/heads/${req.baseRef}:refs/graft/base`,
+    ];
+}
+/**
+ * Point `refs/graft/base` at the commit the head ref should be diffed against,
+ * and describe it for the log — or null when this history cannot answer.
+ *
+ * The two refs do NOT give the same diff, and the difference is not a detail:
+ *
+ *  - `/merge` is a commit whose parents are the base tip and the head, so
+ *    `refs/graft/base...HEAD` resolves its merge base to the base tip and the
+ *    diff is exactly the pull request.
+ *  - `/head` is the author's branch tip. While the branch is *not* in the base
+ *    branch's history — an open PR, a closed-unmerged one, and also a squash or
+ *    rebase merge, which land new commits with new shas — the three-dot diff
+ *    still resolves to the fork point and still reports exactly the author's
+ *    changes (that is what three dots is for; see `rangeArgs` in blast/diff.ts).
+ *  - After a MERGE COMMIT, though, the head commit is an ancestor of the base
+ *    branch, so the merge base of the two IS the head commit and
+ *    `refs/graft/base...HEAD` reports that nothing changed. An empty blast
+ *    radius posted with total confidence is worse than the fetch error it
+ *    replaced, so that case is detected and given the basis `/merge` would have
+ *    had: the first parent of the merge commit that brought the branch in, which
+ *    is the base branch as it stood at the merge.
+ */
+function headDiffBase(dir, req) {
+    for (const deepen of [false, true]) {
+        // The shallow window is measured from each tip, so a base branch that moved
+        // on since the merge can leave the shared history out of it entirely: git
+        // then has no merge base at all and `git diff a...b` fails outright. One
+        // deepening is the difference between reviewing a months-old PR and not.
+        if (deepen && !git(dir, fetchArgs(req, "head", true), req.token).ok)
+            return null;
+        const against = resolveHeadBase(dir, req);
+        if (against !== null)
+            return against;
+    }
+    return null;
+}
+function resolveHeadBase(dir, req) {
+    const head = line(dir, ["rev-parse", "refs/graft/head"]);
+    const shared = line(dir, ["merge-base", "refs/graft/base", "refs/graft/head"]);
+    if (head === null || shared === null)
+        return null;
+    if (shared !== head)
+        return `${req.baseRef} (merge base ${short(shared)})`;
+    // The head commit is in the base branch: find the merge that put it there. The
+    // EARLIEST merge on the ancestry path is the one — a later one is some other
+    // branch's merge that happens to sit above it.
+    const merge = line(dir, ["rev-list", "--reverse", "--ancestry-path", "--merges", "refs/graft/head..refs/graft/base"]);
+    if (merge === null)
+        return null;
+    const parent = line(dir, ["rev-parse", `${merge}^1`]);
+    if (parent === null)
+        return null;
+    // Only worth using if it is diffable: a shallow boundary can hold the merge
+    // commit while leaving the fork point below it out of the repository.
+    if (line(dir, ["merge-base", parent, "refs/graft/head"]) === null)
+        return null;
+    if (!git(dir, ["update-ref", "refs/graft/base", parent]).ok)
+        return null;
+    return `${req.baseRef} as it stood at the merge (${short(parent)})`;
 }
 /** Never let a token reach a log line, even inside git's own error text. */
 export function redact(text, token) {