@vintasoftware/pr-review-canvas 0.3.0 → 0.4.0

package/src/server/routes/review-routes.ts

@@ -4,14 +4,19 @@ import { z } from 'zod'
 import type { ReviewBodyResponse, StateResponse } from '../../contract/api.js'
 import { PostCommentInputSchema, type PostCommentResult } from '../../contract/comments.js'
 import type { Pr, ReviewArtifact } from '../../contract/review-artifact.js'
-import { checkInlineTarget, postComment } from '../../github/post-comment.js'
-import { PostReviewInputSchema, postReview } from '../../github/post-review.js'
-import { buildReviewBody, stateForHead, unreviewedLayers } from '../../github/review-body.js'
+import type { PrState } from '../../contract/state.js'
+import { checkInlineTarget } from '../../git/patch-lines.js'
+import { PostReviewInputSchema } from '../../contract/reviews.js'
+import { lookupCanvas } from '../../review/carry-over.js'
+import { buildReviewBody, stateForCanvas, unreviewedLayers } from '../../review/review-body.js'
+import { isLocalKey, keyLabel, type ReviewKey } from '../../contract/review-key.js'
+import { canvasBelongsTo } from '../../store/canvas-store.js'
 import { isReviewedId } from '../../store/state-store.js'
-import type { PrLoader } from '../bundle.js'
+import type { Derived } from '../../store/derived-store.js'
+import { LOCAL_CAPABILITIES, type PrLoader } from '../bundle.js'
 import type { AppContext } from '../context.js'
 import { AppError } from '../errors.js'
-import { parsePrNumber } from './api.js'
+import { parseTargetKey, requirePrNumber } from './api.js'
 
 const ReviewedBodySchema = z.object({
   reviewed: z.boolean(),
@@ -20,6 +25,14 @@ const ReviewedBodySchema = z.object({
     .string()
     .regex(/^[0-9a-f]{40}$/)
     .optional(),
+  /**
+   * The commit of the canvas on the page, which the marks are keyed to. The head when absent. Any
+   * other value must be a canvas indexed for this pull request.
+   */
+  canvasSha: z
+    .string()
+    .regex(/^[0-9a-f]{40}$/)
+    .optional(),
 })
 const DismissedBodySchema = z.object({ dismissed: z.boolean(), reason: z.string().max(500).optional() })
 const HiddenBodySchema = z.object({ hidden: z.boolean() })
@@ -54,12 +67,34 @@ async function readBody<T>(request: Request, schema: z.ZodType<T>, expected: str
   return parsed.data
 }
 
-/** The canvas the reviewer is signing off on: the one written for the pull request's head. */
-async function artifactForHead(ctx: AppContext, number: number, pr: Pr): Promise<ReviewArtifact> {
+/** Refuses a commit that is not an indexed canvas of this target. */
+async function requireCanvasOf(ctx: AppContext, key: ReviewKey, canvasSha: string): Promise<void> {
+  const entry = (await ctx.canvases.readIndex()).canvases[canvasSha]
+  // The same rule the lookups use, so a mark can only be keyed to a canvas this target shows.
+  if (entry === undefined || !canvasBelongsTo(entry, key)) {
+    throw new AppError(
+      'CANVAS_NOT_FOUND',
+      `${canvasSha.slice(0, 7)} is not a canvas of ${keyLabel(key)}`,
+      404,
+      'reload the page'
+    )
+  }
+}
+
+/**
+ * The canvas the reviewer is signing off on, with the marks made on it: the canvas written for the
+ * pull request's head, or for another commit with an identical diff.
+ */
+async function canvasForSignOff(
+  ctx: AppContext,
+  number: number,
+  pr: Pr
+): Promise<{ artifact: ReviewArtifact; state: PrState }> {
+  const stored = await ctx.state.read(number)
   if (ctx.fixtureArtifact !== null) {
-    return { ...ctx.fixtureArtifact, pr }
+    return { artifact: { ...ctx.fixtureArtifact, pr }, state: stateForCanvas(stored, pr.headSha) }
   }
-  const found = await ctx.canvases.findForPr(number, pr.headSha)
+  const found = await lookupCanvas(ctx, number, pr)
   if (found.status !== 'ready') {
     throw new AppError(
       'SIGNOFF_INCOMPLETE',
@@ -72,7 +107,7 @@ async function artifactForHead(ctx: AppContext, number: number, pr: Pr): Promise
   if (artifact === null) {
     throw new AppError('CANVAS_NOT_FOUND', `no canvas for pull request ${number}`, 404, 'generate one first')
   }
-  return artifact
+  return { artifact, state: stateForCanvas(stored, found.headSha) }
 }
 
 export function reviewRoutes(ctx: AppContext, loader: PrLoader): Hono {
@@ -84,25 +119,25 @@ export function reviewRoutes(ctx: AppContext, loader: PrLoader): Hono {
     if (caps.canComment === false) {
       throw new AppError(
         'COMMENT_FORBIDDEN',
-        caps.reason ?? 'this GitHub login cannot post on this repository',
+        caps.reason ?? `this ${ctx.config.host.label} login cannot post on this repository`,
         403,
         caps.hint
       )
     }
   }
 
-  const stateBody = (number: number, state: StateResponse['state']): StateResponse => ({
-    prNumber: number,
+  const stateBody = (key: ReviewKey, state: StateResponse['state']): StateResponse => ({
+    prNumber: key,
     state,
   })
 
   api.get('/prs/:n/state', async c => {
-    const number = parsePrNumber(c.req.param('n'))
-    return c.json(stateBody(number, await ctx.state.read(number)))
+    const key = parseTargetKey(c.req.param('n'))
+    return c.json(stateBody(key, await ctx.state.read(key)))
   })
 
   api.put('/prs/:n/reviewed/:id{.+}', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const key = parseTargetKey(c.req.param('n'))
     const id = c.req.param('id')
     if (!isReviewedId(id)) {
       throw new AppError(
@@ -113,21 +148,31 @@ export function reviewRoutes(ctx: AppContext, loader: PrLoader): Hono {
       )
     }
     const body = await readBody(c.req.raw, ReviewedBodySchema, '{ "reviewed": true }')
-    const pr = await loader.currentPr(number)
-    requireSameHead(body.headSha, pr.headSha)
-    return c.json(stateBody(number, await ctx.state.setReviewed(number, id, body.reviewed, pr.headSha)))
+    // A mark is made against the canvas on screen, which for a local review is the snapshot the
+    // page was drawn from, not whatever the working tree holds a keystroke later.
+    const pr = await loader.currentTarget(key)
+    if (!isLocalKey(key)) {
+      requireSameHead(body.headSha, pr.headSha)
+    }
+    // The page sends back the canvas commit the bundle keyed its marks to, so a toggle costs no
+    // git work; the index, not git, says the commit is a canvas of this target.
+    const canvasSha = body.canvasSha ?? pr.headSha
+    if (canvasSha !== pr.headSha) {
+      await requireCanvasOf(ctx, key, canvasSha)
+    }
+    return c.json(stateBody(key, await ctx.state.setReviewed(key, id, body.reviewed, canvasSha)))
   })
 
   api.put('/prs/:n/points/:fingerprint/dismissed', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const key = parseTargetKey(c.req.param('n'))
     const fingerprint = c.req.param('fingerprint')
     const body = await readBody(c.req.raw, DismissedBodySchema, '{ "dismissed": true, "reason": "…" }')
-    const next = await ctx.state.setDismissed(number, fingerprint, body.dismissed, body.reason)
-    return c.json(stateBody(number, next))
+    const next = await ctx.state.setDismissed(key, fingerprint, body.dismissed, body.reason)
+    return c.json(stateBody(key, next))
   })
 
   api.put('/prs/:n/threads/:rootCommentId/hidden', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const number = requirePrNumber(parseTargetKey(c.req.param('n')), 'hiding a comment thread')
     const rootId = z.coerce.number().int().positive().safeParse(c.req.param('rootCommentId'))
     if (!rootId.success) {
       throw new AppError('BAD_REQUEST', 'the thread id is the numeric id of its first comment', 400)
@@ -137,16 +182,20 @@ export function reviewRoutes(ctx: AppContext, loader: PrLoader): Hono {
   })
 
   api.get('/prs/:n/capabilities', async c => {
-    parsePrNumber(c.req.param('n'))
+    const key = parseTargetKey(c.req.param('n'))
+    if (isLocalKey(key)) {
+      return c.json(LOCAL_CAPABILITIES)
+    }
     return c.json(await ctx.capabilities.get({ refresh: c.req.query('refresh') === '1' }))
   })
 
   api.post('/prs/:n/comments', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const number = requirePrNumber(parseTargetKey(c.req.param('n')), 'posting a comment')
     const input = await readBody(c.req.raw, PostCommentInputSchema, 'an inline, reply, or issue comment')
     await requirePosting()
     const pr = await loader.currentPr(number)
     requireSameHead(input.headSha, pr.headSha)
+    let diff: Derived = { files: [], patches: {} }
     if (input.kind === 'inline') {
       const derived = await ctx.derived.read(pr.headSha)
       if (derived === null) {
@@ -161,8 +210,9 @@ export function reviewRoutes(ctx: AppContext, loader: PrLoader): Hono {
       if (problem !== null) {
         throw new AppError('COMMENT_LINE_NOT_IN_DIFF', problem, 422, 'comment on a line the diff shows')
       }
+      diff = derived
     }
-    const posted = await postComment(ctx.gh, ctx.config.repo, number, pr.headSha, input)
+    const posted = await ctx.config.host.postComment(ctx.gh, ctx.config.repo, number, pr.headSha, input, diff)
     await appendComment(ctx, number, posted)
     const entry =
       input.kind === 'inline' && input.pointFingerprint !== undefined
@@ -173,10 +223,9 @@ export function reviewRoutes(ctx: AppContext, loader: PrLoader): Hono {
   })
 
   api.get('/prs/:n/review/body', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const number = requirePrNumber(parseTargetKey(c.req.param('n')), 'the sign-off summary')
     const pr = await loader.currentPr(number)
-    const artifact = await artifactForHead(ctx, number, pr)
-    const state = stateForHead(await ctx.state.read(number), pr.headSha)
+    const { artifact, state } = await canvasForSignOff(ctx, number, pr)
     const comments = (await ctx.prs.readComments(number)) ?? (await loader.refreshComments(number)).comments
     const body: ReviewBodyResponse = {
       headSha: pr.headSha,
@@ -187,13 +236,12 @@ export function reviewRoutes(ctx: AppContext, loader: PrLoader): Hono {
   })
 
   api.post('/prs/:n/review', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const number = requirePrNumber(parseTargetKey(c.req.param('n')), 'submitting a review')
     const input = await readBody(c.req.raw, PostReviewInputSchema, '{ "event": "APPROVE" }')
     await requirePosting()
     const pr = await loader.currentPr(number)
     requireSameHead(input.headSha, pr.headSha)
-    const artifact = await artifactForHead(ctx, number, pr)
-    const state = stateForHead(await ctx.state.read(number), pr.headSha)
+    const { artifact, state } = await canvasForSignOff(ctx, number, pr)
     if (input.event === 'APPROVE') {
       const missing = unreviewedLayers(artifact, state)
       if (missing.length > 0) {
@@ -207,7 +255,10 @@ export function reviewRoutes(ctx: AppContext, loader: PrLoader): Hono {
     }
     const comments = (await ctx.prs.readComments(number)) ?? (await loader.refreshComments(number)).comments
     const body = input.body ?? buildReviewBody({ artifact, state, comments, headSha: pr.headSha })
-    const review = await postReview(ctx.gh, ctx.config.repo, number, pr.headSha, { event: input.event, body })
+    const review = await ctx.config.host.postReview(ctx.gh, ctx.config.repo, number, pr.headSha, {
+      event: input.event,
+      body,
+    })
     return c.json({ review }, 201)
   })
 

package/src/store/canvas-store.ts

@@ -1,5 +1,5 @@
 import path from 'node:path'
-import type { CanvasRelation } from '../contract/api.js'
+import type { CarriedOverInfo } from '../contract/api.js'
 import {
   type CanvasIndex,
   CanvasIndexSchema,
@@ -7,13 +7,43 @@ import {
   CanvasManifestSchema,
 } from '../contract/canvas-manifest.js'
 import { type ReviewArtifact, ReviewArtifactSchema } from '../contract/review-artifact.js'
+import { isLocalKey, type LocalKey, type ReviewKey } from '../contract/review-key.js'
 import type { Git } from '../git/git.js'
 import { readJson, readText, writeJsonAtomic } from './atomic-json.js'
 
+/** A canvas of a commit the head was built on, and how many commits the head gained since. */
+export interface AncestorCanvas {
+  status: 'stale'
+  headSha: string
+  relation: 'ancestor'
+  commitsBehind: number
+}
+
 export type CanvasLookup =
-  | { status: 'ready'; headSha: string }
-  | { status: 'stale'; headSha: string; relation: CanvasRelation; commitsBehind?: number }
-  | { status: 'missing' }
+  /** `headSha` is the canvas's own commit: the head, or another commit with an identical diff. */
+  { status: 'ready'; headSha: string; carriedOver?: CarriedOverInfo } | StaleCanvas | { status: 'missing' }
+
+/** A canvas of another commit: one the head was built on, or one from a line the head no longer contains. */
+export type StaleCanvas = AncestorCanvas | { status: 'stale'; headSha: string; relation: 'unrelated' }
+
+/** One canvas as `index.json` lists it. */
+export type CanvasEntry = CanvasIndex['canvases'][string]
+
+/**
+ * Whether a canvas is one of this target's. A canvas belongs to a pull request when it was
+ * generated for it or before it existed; to a local review when it belongs to no pull request. A
+ * snapshot of uncommitted work sits on no branch, so only the `uncommitted` review claims it.
+ *
+ * Every consumer asks through here: the lookups that pick the canvas to show, and the routes that
+ * accept a canvas a mark was made on. Two answers to this question is how marks end up keyed to a
+ * canvas their review will never show.
+ */
+export function canvasBelongsTo(entry: CanvasEntry, key: ReviewKey): boolean {
+  if (isLocalKey(key)) {
+    return entry.prNumber === undefined && (key === 'uncommitted' || entry.worktree !== true)
+  }
+  return entry.worktree !== true && (entry.prNumber === undefined || entry.prNumber === key)
+}
 
 export interface CanvasStore {
   readonly root: string
@@ -24,12 +54,23 @@ export interface CanvasStore {
   readArtifact(headSha: string): Promise<ReviewArtifact | null>
   readManifest(headSha: string): Promise<CanvasManifest | null>
   /** Writes review.json + manifest.json atomically and records the canvas in index.json. */
-  write(headSha: string, artifact: ReviewArtifact, manifest: CanvasManifest, prNumber?: number): Promise<void>
+  write(
+    headSha: string,
+    artifact: ReviewArtifact,
+    manifest: CanvasManifest,
+    prNumber?: number,
+    flags?: { worktree?: boolean }
+  ): Promise<void>
   /**
    * The best canvas for this PR: the one written for its current head, else the newest one the
    * head was built on top of, else one from a branch the head no longer contains.
    */
   findForPr(prNumber: number, currentHeadSha: string): Promise<CanvasLookup>
+  /**
+   * The best canvas for a local review: the one for this head, else the newest canvas that belongs
+   * to no pull request. A snapshot of uncommitted work counts only for the `uncommitted` review.
+   */
+  findForLocal(key: LocalKey, currentHeadSha: string): Promise<CanvasLookup>
   /** Records the PR number on a canvas that was exported before the pull request existed. */
   attachPrNumber(headSha: string, prNumber: number): Promise<void>
 }
@@ -47,6 +88,43 @@ export function createCanvasStore(repoRoot: string, git: Git): CanvasStore {
   const readIndex = async (): Promise<CanvasIndex> =>
     (await readJson(indexFile, CanvasIndexSchema)) ?? { canvases: {} }
 
+  /**
+   * The canvas for this head, or the closest one `accept` allows. Commits the head was built on
+   * come first, newest wins inside a relation, and a canvas off a discarded branch is the last
+   * resort.
+   */
+  const rank = async (
+    currentHeadSha: string,
+    accept: (entry: CanvasEntry) => boolean
+  ): Promise<CanvasLookup> => {
+    const index = await readIndex()
+    if (index.canvases[currentHeadSha] !== undefined) {
+      return { status: 'ready', headSha: currentHeadSha }
+    }
+    const candidates = Object.entries(index.canvases).filter(
+      ([sha, entry]) => sha !== currentHeadSha && accept(entry)
+    )
+    const ranked: Array<{ generatedAt: string; found: StaleCanvas }> = []
+    for (const [sha, entry] of candidates) {
+      const found: StaleCanvas = (await git.isAncestor(sha, currentHeadSha))
+        ? {
+            status: 'stale',
+            headSha: sha,
+            relation: 'ancestor',
+            commitsBehind: await git.countCommitsBetween(sha, currentHeadSha),
+          }
+        : { status: 'stale', headSha: sha, relation: 'unrelated' }
+      ranked.push({ generatedAt: entry.generatedAt, found })
+    }
+    ranked.sort((a, b) => {
+      if (a.found.relation !== b.found.relation) {
+        return a.found.relation === 'ancestor' ? -1 : 1
+      }
+      return a.generatedAt < b.generatedAt ? 1 : a.generatedAt > b.generatedAt ? -1 : 0
+    })
+    return ranked[0]?.found ?? { status: 'missing' }
+  }
+
   return {
     root: repoRoot,
     canvasDir,
@@ -54,12 +132,12 @@ export function createCanvasStore(repoRoot: string, git: Git): CanvasStore {
     exists: async headSha => (await readText(path.join(canvasDir(headSha), 'review.json'))) !== null,
     readArtifact: headSha => readJson(path.join(canvasDir(headSha), 'review.json'), ReviewArtifactSchema),
     readManifest: headSha => readJson(path.join(canvasDir(headSha), 'manifest.json'), CanvasManifestSchema),
-    write: async (headSha, artifact, manifest, prNumber) => {
+    write: async (headSha, artifact, manifest, prNumber, flags) => {
       const dir = canvasDir(headSha)
       await writeJsonAtomic(path.join(dir, 'review.json'), artifact)
       await writeJsonAtomic(path.join(dir, 'manifest.json'), manifest)
       const index = await readIndex()
-      const entry: CanvasIndex['canvases'][string] = {
+      const entry: CanvasEntry = {
         generatedAt: artifact.generatedAt,
         source: artifact.source,
       }
@@ -70,57 +148,14 @@ export function createCanvasStore(repoRoot: string, git: Git): CanvasStore {
       if (artifact.importedAt !== undefined) {
         entry.importedAt = artifact.importedAt
       }
+      if (flags?.worktree === true) {
+        entry.worktree = true
+      }
       index.canvases[headSha] = entry
       await writeJsonAtomic(indexFile, index)
     },
-    findForPr: async (prNumber, currentHeadSha) => {
-      const index = await readIndex()
-      if (index.canvases[currentHeadSha] !== undefined) {
-        return { status: 'ready', headSha: currentHeadSha }
-      }
-      // A canvas belongs to this PR when it was exported for it, or before the PR existed.
-      const candidates = Object.entries(index.canvases).filter(
-        ([sha, entry]) =>
-          sha !== currentHeadSha && (entry.prNumber === undefined || entry.prNumber === prNumber)
-      )
-      const ranked: Array<{
-        headSha: string
-        generatedAt: string
-        relation: CanvasRelation
-        commitsBehind?: number
-      }> = []
-      for (const [sha, entry] of candidates) {
-        if (await git.isAncestor(sha, currentHeadSha)) {
-          ranked.push({
-            headSha: sha,
-            generatedAt: entry.generatedAt,
-            relation: 'ancestor',
-            commitsBehind: await git.countCommitsBetween(sha, currentHeadSha),
-          })
-        } else {
-          ranked.push({ headSha: sha, generatedAt: entry.generatedAt, relation: 'unrelated' })
-        }
-      }
-      // Commits the head was built on come first; a force-pushed-away canvas is the last resort.
-      ranked.sort((a, b) => {
-        if (a.relation !== b.relation) {
-          return a.relation === 'ancestor' ? -1 : 1
-        }
-        return a.generatedAt < b.generatedAt ? 1 : a.generatedAt > b.generatedAt ? -1 : 0
-      })
-      const best = ranked[0]
-      if (best === undefined) {
-        return { status: 'missing' }
-      }
-      return best.commitsBehind === undefined
-        ? { status: 'stale', headSha: best.headSha, relation: best.relation }
-        : {
-            status: 'stale',
-            headSha: best.headSha,
-            relation: best.relation,
-            commitsBehind: best.commitsBehind,
-          }
-    },
+    findForPr: (prNumber, currentHeadSha) => rank(currentHeadSha, entry => canvasBelongsTo(entry, prNumber)),
+    findForLocal: (key, currentHeadSha) => rank(currentHeadSha, entry => canvasBelongsTo(entry, key)),
     attachPrNumber: async (headSha, prNumber) => {
       const index = await readIndex()
       const entry = index.canvases[headSha]

package/src/store/data-dir.ts

@@ -25,5 +25,6 @@ export async function ensureDataDir(dataDir: string): Promise<void> {
 }
 
 export function repoDir(dataDir: string, repo: Repo): string {
-  return path.join(dataDir, 'repos', `${repo.owner}__${repo.name}`)
+  const owner = repo.owner.replaceAll('/', '__')
+  return path.join(dataDir, 'repos', `${owner}__${repo.name}`)
 }

package/src/store/derived-store.ts

@@ -24,6 +24,12 @@ export interface DerivedStore {
   /** Reads `derived/` when it matches the commits, otherwise rebuilds it from local git. */
   ensure(headSha: string, mergeBaseSha: string): Promise<Derived>
   read(headSha: string): Promise<Derived | null>
+  /**
+   * The diffs built from the clone when the merge base is known and both commits are local, so a
+   * base that advanced under the head is seen; else the stored copy, which is all an imported
+   * canvas has.
+   */
+  readOrBuild(headSha: string, mergeBaseSha: string | undefined): Promise<Derived | null>
   /** Lines `from..to` (1-based, inclusive) of a materialized file, or null when not materialized. */
   readLines(
     headSha: string,
@@ -47,36 +53,44 @@ export function createDerivedStore(canvases: CanvasStore, git: Git, now: () => D
     return { files, patches }
   }
 
+  const derivable = async (headSha: string, mergeBaseSha: string): Promise<boolean> =>
+    (await git.commitExists(headSha)) && (await git.commitExists(mergeBaseSha))
+
+  const ensure = async (headSha: string, mergeBaseSha: string): Promise<Derived> => {
+    const dir = derivedDir(headSha)
+    const meta = await readJson(path.join(dir, 'meta.json'), DerivedMetaSchema)
+    if (meta !== null && meta.mergeBaseSha === mergeBaseSha) {
+      const cached = await read(headSha)
+      if (cached !== null) {
+        return cached
+      }
+    }
+    const collected = await collectDiffs(git, mergeBaseSha, headSha)
+    const files = collected.map(toFileEntry)
+    const patches = toPatchMap(collected)
+    await writeJsonAtomic(path.join(dir, 'files.json'), files)
+    await writeJsonAtomic(path.join(dir, 'patches.json'), patches)
+    for (const f of collected) {
+      await writeTextAtomic(path.join(dir, 'patches', `${f.key}.diff`), `${labelPatch(f.key, f.patch)}\n`)
+    }
+    await materialize(git, { headSha, mergeBaseSha, files: collected, outDir: dir })
+    await writeJsonAtomic(path.join(dir, 'meta.json'), {
+      headSha,
+      mergeBaseSha,
+      builtAt: now().toISOString(),
+    })
+    return { files, patches }
+  }
+
   return {
     derivedDir,
-    derivable: async (headSha, mergeBaseSha) =>
-      (await git.commitExists(headSha)) && (await git.commitExists(mergeBaseSha)),
-    ensure: async (headSha, mergeBaseSha) => {
-      const dir = derivedDir(headSha)
-      const meta = await readJson(path.join(dir, 'meta.json'), DerivedMetaSchema)
-      if (meta !== null && meta.mergeBaseSha === mergeBaseSha) {
-        const cached = await read(headSha)
-        if (cached !== null) {
-          return cached
-        }
-      }
-      const collected = await collectDiffs(git, mergeBaseSha, headSha)
-      const files = collected.map(toFileEntry)
-      const patches = toPatchMap(collected)
-      await writeJsonAtomic(path.join(dir, 'files.json'), files)
-      await writeJsonAtomic(path.join(dir, 'patches.json'), patches)
-      for (const f of collected) {
-        await writeTextAtomic(path.join(dir, 'patches', `${f.key}.diff`), `${labelPatch(f.key, f.patch)}\n`)
-      }
-      await materialize(git, { headSha, mergeBaseSha, files: collected, outDir: dir })
-      await writeJsonAtomic(path.join(dir, 'meta.json'), {
-        headSha,
-        mergeBaseSha,
-        builtAt: now().toISOString(),
-      })
-      return { files, patches }
-    },
+    derivable,
+    ensure,
     read,
+    readOrBuild: async (headSha, mergeBaseSha) =>
+      mergeBaseSha !== undefined && (await derivable(headSha, mergeBaseSha))
+        ? ensure(headSha, mergeBaseSha)
+        : read(headSha),
     readLines: async (headSha, side, filePath, from, to) => {
       const root = path.join(derivedDir(headSha), side)
       const full = path.resolve(root, filePath)

package/src/store/pr-store.ts

@@ -2,39 +2,48 @@ import { readdir, stat } from 'node:fs/promises'
 import path from 'node:path'
 import { type CommentsPayload, CommentsPayloadSchema } from '../contract/comments.js'
 import { type DiscoveryCache, DiscoveryCacheSchema } from '../contract/discovery.js'
+import { type LocalPrepareTarget, LocalPrepareTargetSchema } from '../contract/generation-context.js'
+import { isLocalKey, keyToString, type LocalKey, type ReviewKey } from '../contract/review-key.js'
 import { type Pr, PrSchema } from '../contract/review-artifact.js'
 import { readJson, readJsonOrDefault, writeJsonAtomic } from './atomic-json.js'
 
-/** PR-keyed files: the cached PR meta and the last comments payload. */
+/** Target-keyed files: the cached PR meta and the last comments payload. */
 export interface PrStore {
-  prDir(number: number): string
-  readPr(number: number): Promise<Pr | null>
-  writePr(pr: Pr): Promise<void>
+  prDir(key: ReviewKey): string
+  readPr(key: ReviewKey): Promise<Pr | null>
+  /** The key is passed in, because the local review's meta carries no number of its own. */
+  writePr(key: ReviewKey, pr: Pr): Promise<void>
   readComments(number: number): Promise<CommentsPayload | null>
   writeComments(number: number, comments: CommentsPayload): Promise<void>
   /** The last attachment scan, so an unchanged PR is not scanned again. */
   readDiscovery(number: number): Promise<DiscoveryCache | null>
   writeDiscovery(number: number, discovery: DiscoveryCache): Promise<void>
-  /** PR numbers with a cached pr.json, newest first by file mtime. */
+  /** PR numbers with a cached pr.json, newest first by file mtime. Local reviews are not ones. */
   listRecent(limit: number): Promise<Array<{ number: number; title: string; updatedAt: string }>>
+  /** What this local review was last prepared for, so the page can resolve the same head again. */
+  readLocalTarget(key: LocalKey): Promise<LocalPrepareTarget | null>
+  writeLocalTarget(key: LocalKey, target: LocalPrepareTarget): Promise<void>
 }
 
 export function createPrStore(repoRoot: string): PrStore {
-  const prDir = (number: number): string => {
-    if (!Number.isInteger(number) || number <= 0) {
-      throw new Error(`not a pull request number: ${number}`)
+  const prDir = (key: ReviewKey): string => {
+    if (!isLocalKey(key) && (!Number.isInteger(key) || key <= 0)) {
+      throw new Error(`not a pull request number: ${String(key)}`)
     }
-    return path.join(repoRoot, 'prs', String(number))
+    return path.join(repoRoot, 'prs', keyToString(key))
   }
   return {
     prDir,
-    readPr: number => readJson(path.join(prDir(number), 'pr.json'), PrSchema),
-    writePr: async pr => {
-      if (pr.number === null) {
-        throw new Error('cannot cache a pre-PR change set under prs/')
+    readPr: key => readJson(path.join(prDir(key), 'pr.json'), PrSchema),
+    writePr: async (key, pr) => {
+      if (!isLocalKey(key) && pr.number !== key) {
+        throw new Error(`pull request ${String(key)} cannot hold the meta of ${String(pr.number)}`)
       }
-      await writeJsonAtomic(path.join(prDir(pr.number), 'pr.json'), pr)
+      await writeJsonAtomic(path.join(prDir(key), 'pr.json'), pr)
     },
+    readLocalTarget: key =>
+      readJsonOrDefault(path.join(prDir(key), 'target.json'), LocalPrepareTargetSchema, () => null),
+    writeLocalTarget: (key, target) => writeJsonAtomic(path.join(prDir(key), 'target.json'), target),
     readComments: number => readJson(path.join(prDir(number), 'comments.json'), CommentsPayloadSchema),
     writeComments: (number, comments) => writeJsonAtomic(path.join(prDir(number), 'comments.json'), comments),
     readDiscovery: number =>