@vintasoftware/pr-review-canvas 0.3.0 → 0.5.0

package/src/review/carry-over.ts

@@ -0,0 +1,79 @@
+// A canvas carried over to a later head: the head's diff is identical to the diff the canvas was
+// generated from, so the canvas stands for it. The one place that reads the rule.
+import type { CarriedOverInfo } from '../contract/api.js'
+import type { Pr } from '../contract/review-artifact.js'
+import type { AppContext } from '../server/context.js'
+import type { CanvasLookup } from '../store/canvas-store.js'
+import type { Derived } from '../store/derived-store.js'
+
+/** A commit with the merge base its diff runs from; `Pr`, a prepared context, and a canvas manifest all provide it. */
+export interface DiffedCommit {
+  headSha: string
+  mergeBaseSha: string
+}
+
+/**
+ * True when `commit` stands for the head: it is the head, or the head's diff against its merge
+ * base is identical to `commit`'s diff against its own, file by file and byte for byte. Layers,
+ * hunk ids, folds, and attention points all assume the diff on screen is the one the canvas was
+ * generated from, and identity is what guarantees that; a base merge that only moves a hunk down
+ * already breaks it. How the head reached that diff does not matter. A diff missing on this
+ * machine, and a change set that is empty on both sides, keep the strict reading. Off when the
+ * project marks the canvas outdated on any commit.
+ */
+export async function standsForHead(
+  ctx: AppContext,
+  pr: DiffedCommit,
+  commit: DiffedCommit
+): Promise<boolean> {
+  if (commit.headSha === pr.headSha) {
+    return true
+  }
+  if (!ctx.projectConfig.config.canvas.keepForIdenticalDiff) {
+    return false
+  }
+  const [older, head] = await Promise.all([
+    ctx.derived.readOrBuild(commit.headSha, commit.mergeBaseSha),
+    ctx.derived.readOrBuild(pr.headSha, pr.mergeBaseSha),
+  ])
+  if (older === null || head === null) {
+    return false
+  }
+  // Two empty diffs are equal by having nothing to compare, which is no evidence that the canvas
+  // explains the head. An empty change set has nothing to review either way, so the strict
+  // reading costs the reviewer nothing here.
+  return Object.keys(head.patches).length > 0 && samePatches(older, head)
+}
+
+/**
+ * Whether two diffs change the same code: the same patch keys, each with the same patch body.
+ * The patches are the diff; the files array beside them only counts and flags what the patches
+ * already say, so comparing the patches is comparing the whole change.
+ */
+export function samePatches(a: Derived, b: Derived): boolean {
+  const keys = Object.keys(a.patches)
+  return keys.length === Object.keys(b.patches).length && keys.every(k => a.patches[k] === b.patches[k])
+}
+
+/**
+ * The canvas for this pull request: the store's answer, with a canvas of another commit read as
+ * ready when that commit stands for the head. A canvas has a manifest naming its merge base;
+ * one whose manifest is gone cannot be compared.
+ */
+export async function lookupCanvas(ctx: AppContext, number: number, pr: Pr): Promise<CanvasLookup> {
+  const found = await ctx.canvases.findForPr(number, pr.headSha)
+  if (found.status !== 'stale') {
+    return found
+  }
+  const manifest = await ctx.canvases.readManifest(found.headSha)
+  if (manifest !== null && (await standsForHead(ctx, pr, manifest))) {
+    const carriedOver: CarriedOverInfo = { canvasHeadSha: found.headSha, currentHeadSha: pr.headSha }
+    // How far the head moved, when the head was built on the canvas's commit. A head that
+    // reached the identical diff another way, by a rebase, is no distance from it at all.
+    if (found.relation === 'ancestor') {
+      carriedOver.commitsBehind = found.commitsBehind
+    }
+    return { status: 'ready', headSha: found.headSha, carriedOver }
+  }
+  return found
+}

package/src/review/doctor.ts

@@ -3,9 +3,11 @@
 import { randomBytes } from 'node:crypto'
 import { readFile, rm, writeFile } from 'node:fs/promises'
 import path from 'node:path'
-import { parseGithubRemote } from '../config.js'
+import { ORIGIN_HINT } from '../config.js'
 import type { Git } from '../git/git.js'
-import type { GitHubClient } from '../github/gh.js'
+import { CLI_INFO, type HostClient } from '../host/client.js'
+import { GITHUB_HOST, type Host } from '../host/host.js'
+import { parseOriginRemote } from '../host/remote.js'
 import { ensureDataDir, resolveDataDir } from '../store/data-dir.js'
 import { CLAUDE_SKILLS_DIR, CODEX_SKILLS_DIR, SKILL_NAME, SKILL_SOURCE_DIR } from './install-skill.js'
 import { skillContent } from './skill-content.js'
@@ -27,12 +29,15 @@ export interface DoctorReport {
 
 export interface DoctorDeps {
   git: Git
-  gh: GitHubClient
+  /** Where `PR_REVIEW_HOST` is read from. */
+  env: NodeJS.ProcessEnv
+  /** The CLI client for the host origin names; without a usable origin, GitHub's is checked. */
+  client: (host: Host) => HostClient
   version: string
   acpxVersion: () => Promise<string | null>
   /** `--data-dir` or `PR_REVIEW_DATA_DIR`; without it the dir sits next to the git common dir. */
   dataDirOverride?: string | undefined
-  readSkill?: (file: string) => Promise<string | null>
+  readSkill?: ReadSkill
 }
 
 function message(err: unknown): string {
@@ -55,57 +60,91 @@ async function checkDataDir(dir: string): Promise<DoctorCheck> {
   }
 }
 
+export type ReadSkill = (file: string) => Promise<string | null>
+
+const readSkillFile: ReadSkill = file => readFile(file, 'utf8')
+
+/** One copy of the skill in the repository, next to how it compares with the bundled one. */
+export interface SkillCopy {
+  kind: 'claude' | 'codex'
+  /** The skills directory the copy sits in, absolute. */
+  dir: string
+  /** `<dir>/pr-review-canvas`, relative to the repository. */
+  path: string
+  /** True when the copy's body or recorded hash differs from the bundled skill, or it cannot be read. */
+  stale: boolean
+  /** Why the copy could not be read, when it could not. */
+  error?: string
+}
+
+/**
+ * The copies of the skill in `.claude/skills` and `.agents/skills`. A directory without one is
+ * left out. Throws when the bundled skill itself cannot be read.
+ */
+export async function findSkillCopies(
+  repoRoot: string,
+  readSkill: ReadSkill = readSkillFile
+): Promise<SkillCopy[]> {
+  const expected = skillContent(await readFile(path.join(SKILL_SOURCE_DIR, 'SKILL.md'), 'utf8')).hash
+  const copies: SkillCopy[] = []
+  for (const [kind, skillsDir] of [
+    ['claude', CLAUDE_SKILLS_DIR],
+    ['codex', CODEX_SKILLS_DIR],
+  ] as const) {
+    const dir = path.join(repoRoot, skillsDir)
+    const target = path.join(dir, SKILL_NAME)
+    const rel = path.relative(repoRoot, target)
+    try {
+      const text = await readSkill(path.join(target, 'SKILL.md'))
+      if (text === null) continue
+      const { hash, frontmatter } = skillContent(text)
+      const matches = hash === expected && frontmatter.getIn(['metadata', 'body-sha256']) === expected
+      copies.push({ kind, dir, path: rel, stale: !matches })
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+        copies.push({ kind, dir, path: rel, stale: true, error: message(err) })
+      }
+    }
+  }
+  return copies
+}
+
 /** The skill the generation flow needs, in either harness's directory. */
 export async function checkSkill(
   repoRoot: string | null,
-  readSkill: NonNullable<DoctorDeps['readSkill']> = file => readFile(file, 'utf8')
+  readSkill: ReadSkill = readSkillFile
 ): Promise<DoctorCheck> {
   if (repoRoot === null) {
     return { ok: false, detail: 'no repository, so no skill directory to look in', hint: 'run from a clone' }
   }
-  const targets = [CLAUDE_SKILLS_DIR, CODEX_SKILLS_DIR].map(dir => path.join(repoRoot, dir, SKILL_NAME))
-  const found: string[] = []
-  const stale: string[] = []
-  let expected: string
+  let copies: SkillCopy[]
   try {
-    expected = skillContent(await readFile(path.join(SKILL_SOURCE_DIR, 'SKILL.md'), 'utf8')).hash
+    copies = await findSkillCopies(repoRoot, readSkill)
   } catch (err) {
     return { ok: false, detail: message(err), hint: 'reinstall the pr-review package' }
   }
-  for (const target of targets) {
-    try {
-      const text = await readSkill(path.join(target, 'SKILL.md'))
-      if (text === null) continue
-      found.push(path.relative(repoRoot, target))
-      const { hash, frontmatter } = skillContent(text)
-      if (hash !== expected || frontmatter.getIn(['metadata', 'body-sha256']) !== expected) {
-        stale.push(path.relative(repoRoot, target))
-      }
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
-        stale.push(`${path.relative(repoRoot, target)}: ${message(err)}`)
-      }
-    }
-  }
+  const stale = copies.flatMap(copy =>
+    copy.stale ? [copy.error === undefined ? copy.path : `${copy.path}: ${copy.error}`] : []
+  )
   if (stale.length > 0) {
     return {
       ok: false,
       detail: `outdated or modified skill: ${stale.join(', ')}`,
-      hint: 'run `pr-review install-skill`',
+      hint: 'run `pr-review upgrade` or `pr-review install-skill`',
     }
   }
-  if (found.length === 0) {
+  if (copies.length === 0) {
     return {
       ok: false,
       detail: `${SKILL_NAME} is in neither ${CLAUDE_SKILLS_DIR} nor ${CODEX_SKILLS_DIR}`,
       hint: 'run `pr-review install-skill`',
     }
   }
-  return { ok: true, detail: found.join(', ') }
+  return { ok: true, detail: copies.map(copy => copy.path).join(', ') }
 }
 
 async function checkAcpx(deps: DoctorDeps): Promise<DoctorCheck> {
-  const hint = 'install with `npm install -g acpx` and check `acpx --version`'
+  const hint = 'install with `npm install -g acpx@latest` and check `acpx --version`'
   try {
     const version = (await deps.acpxVersion())?.trim()
     return version
@@ -130,25 +169,30 @@ export async function runDoctorChecks(
     git = { ok: false, detail: message(err), hint: 'run from a clone or pass --repo <dir>' }
   }
 
+  let host = GITHUB_HOST
   let origin: DoctorCheck
   try {
     const url = await deps.git.remoteUrl('origin')
-    const repo = url === null ? null : parseGithubRemote(url)
-    origin =
-      repo === null
-        ? { ok: false, detail: url ?? 'no origin remote', hint: 'add a github.com origin' }
-        : { ok: true, detail: `${repo.owner}/${repo.name}` }
+    const parsed = url === null ? null : parseOriginRemote(url, deps.env)
+    if (parsed === null) {
+      origin = { ok: false, detail: url ?? 'no origin remote', hint: ORIGIN_HINT }
+    } else {
+      host = parsed.host
+      origin = { ok: true, detail: `${parsed.repo.owner}/${parsed.repo.name} (${host.label})` }
+    }
   } catch (err) {
-    origin = { ok: false, detail: message(err), hint: 'add a github.com origin' }
+    origin = { ok: false, detail: message(err), hint: ORIGIN_HINT }
   }
 
-  const status = await deps.gh.authStatus()
+  // The `gh` keys are the report's public names; for a GitLab origin they describe glab.
+  const status = await deps.client(host).authStatus()
+  const cli = CLI_INFO[host.cli.cli]
   const gh: DoctorCheck = status.installed
     ? { ok: true, detail: status.detail }
-    : { ok: false, detail: status.detail, hint: 'install it from https://cli.github.com' }
+    : { ok: false, detail: status.detail, hint: `install it from ${cli.installUrl}` }
   const ghAuth: DoctorCheck = status.authenticated
     ? { ok: true, detail: status.detail }
-    : { ok: false, detail: status.detail, hint: 'run `gh auth login`' }
+    : { ok: false, detail: status.detail, hint: `run \`${cli.loginCommand}\`` }
 
   let dataDir: DoctorCheck
   try {

package/src/review/incremental.ts

@@ -0,0 +1,107 @@
+// Incremental generation: the basis canvas an update starts from, the per-file delta between that
+// canvas's diff and the head's, and the split of the basis into content the head leaves untouched
+// and content the generator has to decide anew. Everything here is a function of two diffs and one
+// stored canvas, so `prepare` states the split instead of asking the generator to work it out.
+import type {
+  BasisSplit,
+  BasisSplitLayer,
+  BasisSplitPoint,
+  FileDelta,
+} from '../contract/generation-context.js'
+import type { ReviewArtifact } from '../contract/review-artifact.js'
+import type { Git } from '../git/git.js'
+import type { CanvasStore } from '../store/canvas-store.js'
+import type { Derived } from '../store/derived-store.js'
+
+/**
+ * Which files the head changes relative to the basis canvas's diff. A file is unchanged only when
+ * its whole patch is byte-identical: line numbers, context, and all. Anything less would let a
+ * fold or an annotation of the basis land on a line it was never written for. Renames arrive as a
+ * removal and an addition, since a file's key follows its path.
+ *
+ * The two sides are matched by path, and each side's patch is read through its own key. A key is
+ * the sanitized path, and two paths can sanitize to the same key (`a-b.ts` and `a_b.ts`), which
+ * `uniqueKey` then separates by the order the files appear in that one diff. The same key can
+ * therefore name different files in two diffs; the path cannot.
+ */
+export function fileDelta(basis: Derived, head: Derived): FileDelta {
+  const keysByPath = (d: Derived): Map<string, string> => new Map(d.files.map(f => [f.path, f.key]))
+  const basisKeys = keysByPath(basis)
+  const headKeys = keysByPath(head)
+  const delta: FileDelta = { unchanged: [], changed: [], added: [], removed: [] }
+  for (const [path, headKey] of headKeys) {
+    const basisKey = basisKeys.get(path)
+    if (basisKey === undefined) {
+      delta.added.push(path)
+    } else if (basis.patches[basisKey] === head.patches[headKey]) {
+      delta.unchanged.push(path)
+    } else {
+      delta.changed.push(path)
+    }
+  }
+  for (const path of basisKeys.keys()) {
+    if (!headKeys.has(path)) {
+      delta.removed.push(path)
+    }
+  }
+  for (const list of Object.values(delta)) {
+    list.sort()
+  }
+  return delta
+}
+
+/**
+ * The basis canvas divided in two. A layer is carried whole when the head touches none of its
+ * files; otherwise the layer is re-judged, and only the files the head leaves alone keep their
+ * note, folds, and annotations. A point is carried when the file it sits in is untouched, which
+ * keeps its title and so its fingerprint, and with it any dismissal the reviewer made.
+ */
+export function splitBasis(
+  artifact: ReviewArtifact,
+  delta: FileDelta
+): Omit<BasisSplit, 'canvasSha' | 'reviewJsonPath' | 'files'> {
+  const unchanged = new Set(delta.unchanged)
+  const layers: BasisSplitLayer[] = artifact.layers.map(layer => {
+    const carriedFiles = layer.files.filter(f => unchanged.has(f.path)).map(f => f.path)
+    const reJudgedFiles = layer.files.filter(f => !unchanged.has(f.path)).map(f => f.path)
+    return {
+      key: layer.key,
+      title: layer.title,
+      status: reJudgedFiles.length === 0 ? 'carried' : 're-judged',
+      carriedFiles,
+      reJudgedFiles,
+    }
+  })
+  const points: BasisSplitPoint[] = artifact.points.map(point => ({
+    kind: point.kind,
+    path: point.path,
+    title: point.title,
+    status: unchanged.has(point.path) ? 'carried' : 're-judged',
+  }))
+  return { layers, points }
+}
+
+/**
+ * The canvas an incremental run builds on: the newest one generated for a commit this head was
+ * built on. A canvas of a line of work the head no longer contains describes code that was
+ * abandoned, so it is never a basis, however recent it is.
+ */
+export async function findBasisCanvas(
+  canvases: CanvasStore,
+  git: Git,
+  prNumber: number | undefined,
+  headSha: string
+): Promise<string | null> {
+  const index = await canvases.readIndex()
+  const candidates = Object.entries(index.canvases)
+    .filter(
+      ([sha, entry]) => sha !== headSha && (entry.prNumber === undefined || entry.prNumber === prNumber)
+    )
+    .sort(([, a], [, b]) => (a.generatedAt < b.generatedAt ? 1 : a.generatedAt > b.generatedAt ? -1 : 0))
+  for (const [sha] of candidates) {
+    if (await git.isAncestor(sha, headSha)) {
+      return sha
+    }
+  }
+  return null
+}

package/src/review/normalize.ts

@@ -29,6 +29,8 @@ export interface NormalizeInput {
   caps: TextCaps
   generatedAt: string
   generator: Generator
+  /** The canvas this one was generated from, when the run was incremental. */
+  basisCanvasSha?: string | undefined
   /** The globs that make a file a test; the project config's list, or the built-in one. */
   testPatterns?: readonly string[] | undefined
 }
@@ -76,16 +78,20 @@ function unionRisk(layers: readonly Layer[]): RiskTag[] {
   return out
 }
 
+/**
+ * A layer's id is its own key, which the validator has already checked is unique here. A reviewed
+ * mark is keyed by it, so a regenerated canvas that reorders or renames its layers keeps the
+ * reviewer's progress pointing at the same concern; a position could not.
+ */
 function toLayer(
   layer: ModelLayer,
-  index: number,
   highRisk: readonly HighRiskRule[],
   testPatterns: readonly string[]
 ): Layer {
   const { risk: _modelRisk, files, ...rest } = layer
   return {
     ...rest,
-    id: `layer-${index + 1}`,
+    id: layer.key,
     risk: layerRisk(layer, highRisk),
     files: files.map(f => ({ ...f, isTest: isTestPath(f.path, testPatterns) })),
   }
@@ -167,12 +173,12 @@ function sortPoints(points: Unassigned[]): Point[] {
 
 export function normalize(output: ModelOutput, input: NormalizeInput): ReviewArtifact {
   const testPatterns = input.testPatterns ?? DEFAULT_TEST_PATTERNS
-  const layers = output.layers.map((l, i) => toLayer(l, i, input.highRisk, testPatterns))
+  const layers = output.layers.map(l => toLayer(l, input.highRisk, testPatterns))
   const points = [
     ...output.points.map(p => modelPoint(p, layers, input.files)),
     ...layers.flatMap(l => testPoints(l, input.files, input.caps.pointTitle)),
   ]
-  return {
+  const artifact: ReviewArtifact = {
     version: 1,
     pr: input.pr,
     files: [...input.files],
@@ -184,6 +190,10 @@ export function normalize(output: ModelOutput, input: NormalizeInput): ReviewArt
     generator: input.generator,
     source: 'local',
   }
+  if (input.basisCanvasSha !== undefined) {
+    artifact.basisCanvasSha = input.basisCanvasSha
+  }
+  return artifact
 }
 
 /**

package/src/review/prepare.ts

@@ -2,16 +2,28 @@
 // the canvas directory. The agent reads those two files; publish reads context.json back.
 import { appendFile, readdir, rm } from 'node:fs/promises'
 import path from 'node:path'
-import { type GenerationContext, isLargePr, type PrepareTarget } from '../contract/generation-context.js'
+import {
+  type BasisSplit,
+  type GenerationContext,
+  isLargePr,
+  type PrepareTarget,
+  type PrepareTargetInput,
+} from '../contract/generation-context.js'
 import { effectiveCaps, LIMITS, type Pr } from '../contract/review-artifact.js'
-import { fetchPrMeta, fetchPrRefs, toPr } from '../github/pr.js'
+import type { LocalKey } from '../contract/review-key.js'
+import { describeLocalWork, resolveLocalBase, UNCOMMITTED_STATE } from '../git/local-target.js'
+import { fetchPrRefs } from '../git/pr-refs.js'
+
+import { toPr } from '../host/pr.js'
 import type { AppContext } from '../server/context.js'
 import { readText, writeJsonAtomic, writeTextAtomic } from '../store/atomic-json.js'
+import type { Derived } from '../store/derived-store.js'
+import { fileDelta, findBasisCanvas, splitBasis } from './incremental.js'
 import { loadPromptSources, type PromptSources, renderPrompt } from './prompt.js'
 
 export interface PrepareOptions {
   force: boolean
-  /** Progress lines: `fetch-pr`, `fetch-refs`, `collect-diffs`, `prompt`. */
+  /** Progress lines: `fetch-pr`, `fetch-refs`, `snapshot`, `collect-diffs`, `prompt`. */
   log: (phase: string) => void
   promptSources?: PromptSources
 }
@@ -23,16 +35,40 @@ export interface PrepareResult {
   promptPath: string
   contextPath: string
   status: 'prepared' | 'exists'
+  /** Local targets only: which review it is, the base resolved for it, and what its head holds. */
+  local?: { review: LocalKey; base: string; headRef: string; uncommitted: boolean }
 }
 
 /** The PR meta, live from GitHub, with the head and base refs fetched into the local clone. */
 async function resolvePr(ctx: AppContext, number: number, log: PrepareOptions['log']): Promise<Pr> {
   log('fetch-pr')
-  const meta = await fetchPrMeta(ctx.gh, ctx.config.repo, number)
+  const meta = await ctx.config.host.fetchPrMeta(ctx.gh, ctx.config.repo, number)
   log('fetch-refs')
-  const shas = await fetchPrRefs(ctx.git, meta)
+  const shas = await fetchPrRefs(ctx.git, ctx.config.host, meta)
   const pr = toPr(meta, ctx.config.repo, shas)
-  await ctx.prs.writePr(pr)
+  await ctx.prs.writePr(number, pr)
+  return pr
+}
+
+/**
+ * The work in this clone that has no pull request yet: the current branch, or a snapshot commit
+ * of the working tree when it carries edits. The meta is cached under `prs/<branch|uncommitted>/`,
+ * which is what the matching page reads.
+ */
+async function resolveLocal(
+  ctx: AppContext,
+  target: Extract<PrepareTarget, { kind: 'local' }>,
+  log: PrepareOptions['log']
+): Promise<Pr> {
+  log('snapshot')
+  const pr = await describeLocalWork(ctx.git, {
+    base: target.base,
+    source: target.source,
+    repo: ctx.config.repo,
+    now: ctx.now,
+  })
+  await ctx.prs.writePr(target.source, pr)
+  await ctx.prs.writeLocalTarget(target.source, target)
   return pr
 }
 
@@ -53,7 +89,7 @@ async function resolveRefs(
     title: head,
     body: '',
     author,
-    url: `https://github.com/${repo.owner}/${repo.name}/compare/${base}...${head}`,
+    url: ctx.config.host.compareUrl(repo, base, head),
     state: 'pre-pr',
     draft: false,
     updatedAt: ctx.now().toISOString(),
@@ -98,25 +134,83 @@ async function clearCanvasDir(canvasDir: string): Promise<void> {
   }
 }
 
-export async function prepare(
+/**
+ * The basis canvas of this run, split into what carries and what is re-judged, or null when the
+ * canvas is generated from a blank page: `--force`, `canvas.incremental: false`, no canvas of an
+ * ancestor commit, or a basis whose canvas or diff this machine can no longer read.
+ *
+ * Only a pull request's canvases are owned by a number; a refs or local run considers the canvases
+ * that carry no number, the same ownership rule the store's own lookup uses.
+ */
+async function resolveBasis(
   ctx: AppContext,
   target: PrepareTarget,
+  pr: Pr,
+  head: Derived
+): Promise<BasisSplit | null> {
+  const prNumber = target.kind === 'pr' ? target.number : undefined
+  const sha = await findBasisCanvas(ctx.canvases, ctx.git, prNumber, pr.headSha)
+  if (sha === null) {
+    return null
+  }
+  const [artifact, manifest] = await Promise.all([
+    ctx.canvases.readArtifact(sha),
+    ctx.canvases.readManifest(sha),
+  ])
+  if (artifact === null || manifest === null) {
+    return null
+  }
+  const basis = await ctx.derived.readOrBuild(sha, manifest.mergeBaseSha)
+  if (basis === null) {
+    return null
+  }
+  const files = fileDelta(basis, head)
+  return {
+    canvasSha: sha,
+    reviewJsonPath: path.join(ctx.canvases.canvasDir(sha), 'review.json'),
+    files,
+    ...splitBasis(artifact, files),
+  }
+}
+
+/** The target with its base resolved, which is the form `context.json` records. */
+async function resolveTarget(ctx: AppContext, input: PrepareTargetInput): Promise<PrepareTarget> {
+  if (input.kind !== 'local') {
+    return input
+  }
+  return { kind: 'local', source: input.source, base: await resolveLocalBase(ctx.git, input.base) }
+}
+
+export async function prepare(
+  ctx: AppContext,
+  input: PrepareTargetInput,
   opts: PrepareOptions
 ): Promise<PrepareResult> {
+  const target = await resolveTarget(ctx, input)
   const pr =
     target.kind === 'pr'
       ? await resolvePr(ctx, target.number, opts.log)
-      : await resolveRefs(ctx, target.base, target.head, opts.log)
+      : target.kind === 'local'
+        ? await resolveLocal(ctx, target, opts.log)
+        : await resolveRefs(ctx, target.base, target.head, opts.log)
   const canvasDir = ctx.canvases.canvasDir(pr.headSha)
   const promptPath = path.join(canvasDir, 'prompt.md')
   const contextPath = path.join(canvasDir, 'context.json')
-  const result = {
+  const result: Omit<PrepareResult, 'status'> = {
     canvasDir,
     headSha: pr.headSha,
     mergeBaseSha: pr.mergeBaseSha,
     promptPath,
     contextPath,
   }
+  if (target.kind === 'local') {
+    result.local = {
+      review: target.source,
+      base: target.base,
+      headRef: pr.headRef,
+      uncommitted: pr.state === UNCOMMITTED_STATE,
+    }
+  }
   if (!opts.force && (await ctx.canvases.exists(pr.headSha))) {
     return { ...result, status: 'exists' }
   }
@@ -125,6 +219,8 @@ export async function prepare(
   const derived = await ctx.derived.ensure(pr.headSha, pr.mergeBaseSha)
   const additions = derived.files.reduce((n, f) => n + f.additions, 0)
   const deletions = derived.files.reduce((n, f) => n + f.deletions, 0)
+  // A pull request's counts are the forge's; anything else is counted from the diff itself. The
+  // page derives its own from the files it shows, so this is only what the canvas records.
   const fullPr: Pr =
     target.kind === 'pr' ? pr : { ...pr, additions, deletions, changedFiles: derived.files.length }
   const derivedDir = ctx.derived.derivedDir(pr.headSha)
@@ -162,6 +258,11 @@ export async function prepare(
     largePr: isLargePr({ files: derived.files.length, additions, deletions }),
     preparedAt: ctx.now().toISOString(),
   }
+  // `--force` means start over, so it never reads a basis, whatever the project config says.
+  const basis = opts.force || !config.canvas.incremental ? null : await resolveBasis(ctx, target, pr, derived)
+  if (basis !== null) {
+    context.basis = basis
+  }
   const sources =
     opts.promptSources ??
     (await loadPromptSources(undefined, {