@vintasoftware/pr-review-canvas 0.3.0 → 0.5.0

package/src/contract/review-key.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod'
+
+/**
+ * The two reviews of work that has no pull request yet. They are separate targets, so reviewing a
+ * branch does not disturb the review of what is not committed, and each keeps its own progress
+ * marks and chat threads.
+ */
+export const LOCAL_KEYS = ['branch', 'uncommitted'] as const
+
+/**
+ * Which local review: `branch` is the current branch against the base it will be opened against,
+ * uncommitted edits left out; `uncommitted` is that branch with the working tree on top.
+ */
+export type LocalKey = (typeof LOCAL_KEYS)[number]
+
+/**
+ * What a canvas, its review state, and its chat threads are filed under: a pull request or merge
+ * request number, or one of the local reviews. It is also what the URLs carry, so `/review/12`
+ * and `/review/uncommitted` are the same page over different targets.
+ */
+export type ReviewKey = number | LocalKey
+
+export const LocalKeySchema = z.enum(LOCAL_KEYS)
+export const ReviewKeySchema = z.union([LocalKeySchema, z.number().int().positive()])
+
+export function isLocalKey(key: ReviewKey): key is LocalKey {
+  return LOCAL_KEYS.some(local => local === key)
+}
+
+/** The key as it appears in a URL segment and as a directory name. */
+export function keyToString(key: ReviewKey): string {
+  return String(key)
+}
+
+/** What the page calls the target, for a title or a heading. */
+export function keyLabel(key: ReviewKey): string {
+  if (key === 'branch') {
+    return 'Branch review'
+  }
+  return key === 'uncommitted' ? 'Uncommitted work' : `#${String(key)}`
+}
+
+/** The key a URL segment names, or null when it names none of them. */
+export function parseReviewKey(raw: string): ReviewKey | null {
+  const local = LocalKeySchema.safeParse(raw)
+  if (local.success) {
+    return local.data
+  }
+  const n = Number(raw)
+  return Number.isInteger(n) && n > 0 ? n : null
+}

package/src/contract/reviews.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod'
+
+/**
+ * `COMMENT` leaves a review with no verdict, the way a thread-level review does: the body and the
+ * comments land, and nothing is approved or rejected.
+ */
+export const REVIEW_EVENTS = ['COMMENT', 'APPROVE', 'REQUEST_CHANGES'] as const
+export const ReviewEventSchema = z.enum(REVIEW_EVENTS)
+export type ReviewEvent = (typeof REVIEW_EVENTS)[number]
+
+export const PostReviewInputSchema = z.object({
+  event: ReviewEventSchema,
+  /** The dialog sends the body the user read, edited or not. */
+  body: z.string().min(1).max(65536).optional(),
+  /**
+   * Whether the pending comments go out with this review. True unless the page says otherwise, so
+   * a reviewer who wrote drafts never submits a review that silently leaves them behind.
+   */
+  includePending: z.boolean().default(true),
+  /** The commit the dialog named. The server refuses the review when the head moved on. */
+  headSha: z
+    .string()
+    .regex(/^[0-9a-f]{40}$/)
+    .optional(),
+})
+export type PostReviewInput = z.infer<typeof PostReviewInputSchema>

package/src/contract/settings.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { DEFAULT_FOLD_LEVEL, FOLD_LEVELS } from '../../static/js/fold-levels.js'
 import { DEFAULT_SKIN, isSkin, SKINS, type Skin } from '../../static/js/skin.js'
 import { DEFAULT_THEME, isTheme, THEMES, type Theme } from '../../static/js/theme.js'
 
@@ -24,6 +25,8 @@ export const SettingsSchema = z.object({
   version: z.literal(1),
   skin: z.enum(SKINS),
   theme: z.enum(THEMES),
+  /** The reading level every review opens at; the control on the page changes it for one page. */
+  foldLevel: z.enum(FOLD_LEVELS),
   agent: z.enum(CHAT_AGENTS),
   model: z.string().min(1).nullable(),
   chatTimeoutSec: z.number().int().min(CHAT_TIMEOUT_MIN_SEC).max(CHAT_TIMEOUT_MAX_SEC),
@@ -35,6 +38,7 @@ export const DEFAULT_SETTINGS: Settings = {
   version: 1,
   skin: DEFAULT_SKIN,
   theme: DEFAULT_THEME,
+  foldLevel: DEFAULT_FOLD_LEVEL,
   agent: 'claude',
   model: null,
   chatTimeoutSec: 600,
@@ -45,6 +49,7 @@ export const DEFAULT_SETTINGS: Settings = {
 export const SettingsInputSchema = z.object({
   skin: z.enum(SKINS).optional(),
   theme: z.enum(THEMES).optional(),
+  foldLevel: z.enum(FOLD_LEVELS).optional(),
   agent: z.enum(CHAT_AGENTS).optional(),
   model: z.string().max(200).nullable().optional(),
   chatTimeoutSec: z.number().int().min(CHAT_TIMEOUT_MIN_SEC).max(CHAT_TIMEOUT_MAX_SEC).optional(),
@@ -107,6 +112,8 @@ export interface SettingsResponse {
     maxRepairRounds: number
     inlineDiffMaxLines: number
     smallPrHunks: number
+    /** Whether a canvas still stands for a later head with an identical diff. */
+    keepForIdenticalDiff: boolean
     layers: number
     highRisk: number
   }

package/src/contract/state.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { PendingCommentSchema } from './pending.js'
 
 export const ChatThreadSchema = z.object({
   name: z.string(),
@@ -11,37 +12,67 @@ export const ChatThreadSchema = z.object({
 
 export type ChatThread = z.infer<typeof ChatThreadSchema>
 
-export const PrStateSchema = z.object({
-  version: z.literal(1),
-  /**
-   * Counts the writes to this file. The page uses it to tell a newer answer from an older one
-   * when two of its requests overlap. Absent in state files of older tool versions.
-   */
-  rev: z.number().int().nonnegative().optional(),
-  reviewed: z.record(z.string(), z.literal(true)),
-  /**
-   * The commit the reviewed marks describe. A canvas for another commit describes other code,
-   * so the marks start again when the head moves. Absent in state files of older tool versions.
-   */
-  reviewedHeadSha: z.string().optional(),
-  hiddenThreads: z.record(z.string(), z.object({ at: z.string() })),
-  posted: z.array(
-    z.object({ commentId: z.number().int(), pointFingerprint: z.string().optional(), at: z.string() })
-  ),
-  dismissed: z.record(z.string(), z.object({ at: z.string(), reason: z.string().optional() })),
-  chat: z.object({ threads: z.array(ChatThreadSchema), activeThread: z.string().optional() }),
-  updatedAt: z.string(),
-})
+/**
+ * Version 1 keyed a reviewed mark by the layer's position in the canvas (`layer:layer-2`). Marks
+ * are keyed by the layer's own key now, so a regenerated canvas that reorders its layers keeps
+ * them straight, and the old positional marks cannot be translated without the canvas they were
+ * made on. They are dropped; the rest of the file (dismissals, posted comments, chat threads)
+ * carries over untouched.
+ */
+const dropPositionalMarks = (raw: unknown): unknown => {
+  if (raw === null || typeof raw !== 'object') {
+    return raw
+  }
+  const { reviewedHeadSha: _reviewedHeadSha, ...rest } = raw as Record<string, unknown>
+  if (rest['version'] !== 1) {
+    return rest
+  }
+  return { ...rest, version: 2, reviewed: {}, reviewedCanvasSha: undefined }
+}
+
+export const PrStateSchema = z.preprocess(
+  dropPositionalMarks,
+  z.object({
+    version: z.literal(2),
+    /**
+     * Counts the writes to this file. The page uses it to tell a newer answer from an older one
+     * when two of its requests overlap. Absent in state files of older tool versions.
+     */
+    rev: z.number().int().nonnegative().optional(),
+    reviewed: z.record(z.string(), z.literal(true)),
+    /**
+     * The commit of the canvas the reviewed marks were made on: the head, or the commit a carried-over
+     * canvas was generated for. A canvas for another commit describes other code, so the marks start
+     * again with it, unless that canvas names this one as its basis and the code behind a mark is
+     * untouched. Absent in state files of older tool versions.
+     */
+    reviewedCanvasSha: z.string().optional(),
+    hiddenThreads: z.record(z.string(), z.object({ at: z.string() })),
+    posted: z.array(
+      z.object({ commentId: z.number().int(), pointFingerprint: z.string().optional(), at: z.string() })
+    ),
+    dismissed: z.record(z.string(), z.object({ at: z.string(), reason: z.string().optional() })),
+    /**
+     * The comments of the review being written, in the order they were added. They live here and
+     * nowhere else until the review is submitted, so a reload does not lose a draft. A state file
+     * of an older tool version has none, which reads as an empty list.
+     */
+    pending: z.array(PendingCommentSchema).default([]),
+    chat: z.object({ threads: z.array(ChatThreadSchema), activeThread: z.string().optional() }),
+    updatedAt: z.string(),
+  })
+)
 export type PrState = z.infer<typeof PrStateSchema>
 
 export function emptyState(updatedAt: string): PrState {
   return {
-    version: 1,
+    version: 2,
     rev: 0,
     reviewed: {},
     hiddenThreads: {},
     posted: [],
     dismissed: {},
+    pending: [],
     chat: { threads: [] },
     updatedAt,
   }

package/src/contract/validation.ts

@@ -15,6 +15,7 @@ export const VALIDATION_CODES = [
   'RISK_IN_OTHER',
   'ANNOTATION_OUTSIDE_HUNK',
   'FOLD_INVALID',
+  'FOLD_MISSING',
   'POINT_OUTSIDE_DIFF',
   'TOO_MANY_POINTS',
   'TEST_PATH_UNKNOWN',

package/src/git/environment.mjs

@@ -0,0 +1,27 @@
+// Remove hook repository pointers so cwd selects the repository. Keep configuration,
+// credentials, and discovery limits: callers may rely on relocated config files, inline
+// config, SSH agents, proxies, or filesystem discovery fences.
+export const REPO_ENV_VARS = [
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_COMMON_DIR',
+  'GIT_INDEX_FILE',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_NAMESPACE',
+  'GIT_PREFIX',
+]
+
+/**
+ * `env` without those variables. Everything else is kept, so ssh agents, credential helpers,
+ * proxies, and PATH still reach `fetch`.
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {NodeJS.ProcessEnv}
+ */
+export function envWithoutRepo(env = process.env) {
+  const clean = { ...env }
+  for (const name of REPO_ENV_VARS) {
+    delete clean[name]
+  }
+  return clean
+}

package/src/git/git.ts

@@ -1,4 +1,6 @@
 import { execFile } from 'node:child_process'
+import path from 'node:path'
+import { envWithoutRepo } from './environment.mjs'
 
 /**
  * The git operations the tool needs. Routes, stores, and the CLI receive an implementation
@@ -26,8 +28,56 @@ export interface Git {
   topLevel(): Promise<string>
   commonDir(): Promise<string>
   remoteUrl(name: string): Promise<string | null>
+  /** The checked-out branch, or null on a detached HEAD. */
+  currentBranch(): Promise<string | null>
+  /** The first of `refs` that resolves, or null when none of them do. */
+  firstExistingRef(refs: readonly string[]): Promise<string | null>
+  /** What a symbolic ref points at, in its short form; null when it is not one. */
+  symbolicRef(name: string): Promise<string | null>
+  /** `git config user.name`, the person this clone commits as; null when it is unset. */
+  configuredUser(): Promise<string | null>
+  /**
+   * A commit that holds the working tree as it is right now, or null when it matches HEAD.
+   * Nothing the user staged is touched: the snapshot is built in an index of this tool's own.
+   */
+  snapshotWorktree(): Promise<string | null>
+  /** Keeps `sha` reachable for good, whatever the working tree does next. */
+  anchorCommit(sha: string): Promise<void>
 }
 
+/**
+ * The index `snapshotWorktree` stages into, inside this worktree's own git directory rather than
+ * the one every worktree shares. It is kept between runs so git's stat cache spares a rehash of
+ * the whole tree, and `git worktree remove` takes it away with the worktree it belongs to.
+ */
+export const SNAPSHOT_INDEX = 'pr-review-canvas.index'
+
+/**
+ * Where the newest snapshot commit is anchored, so `git gc` cannot collect it between `prepare`
+ * and `publish`. `refs/worktree/` is git's own per-worktree namespace: two worktrees of one clone
+ * each keep their own snapshot instead of overwriting the single ref they would otherwise share.
+ *
+ * It moves with the working tree, so it protects one commit only. A canvas outlives the tree it
+ * was drawn from, and `anchorCommit` gives each published one an anchor of its own.
+ */
+export const SNAPSHOT_REF = 'refs/worktree/pr-review-snapshot'
+
+/** One ref per published snapshot canvas, under the same per-worktree namespace. */
+export const CANVAS_ANCHOR_PREFIX = 'refs/worktree/pr-review-canvas'
+
+/**
+ * A fixed identity and time, so the same working tree always hashes to the same commit: preparing
+ * twice without an edit lands on the canvas that already exists instead of making a second one.
+ */
+const SNAPSHOT_ENV = {
+  GIT_AUTHOR_NAME: 'pr-review',
+  GIT_AUTHOR_EMAIL: 'pr-review@localhost',
+  GIT_AUTHOR_DATE: '1970-01-01T00:00:00+0000',
+  GIT_COMMITTER_NAME: 'pr-review',
+  GIT_COMMITTER_EMAIL: 'pr-review@localhost',
+  GIT_COMMITTER_DATE: '1970-01-01T00:00:00+0000',
+} as const
+
 export const STDERR_MESSAGE_MAX = 300
 
 /**
@@ -59,13 +109,18 @@ interface ExecResult {
   code: number
 }
 
-/** Runs git with an argument array; never a shell. */
-export function execGit(cwd: string, args: string[]): Promise<ExecResult> {
+/** Runs git with an argument array; never a shell. `extra` puts back the few repo variables a
+ * command needs, such as the snapshot index. */
+export function execGit(
+  cwd: string,
+  args: string[],
+  extra: Readonly<Record<string, string>> = {}
+): Promise<ExecResult> {
   return new Promise(resolve => {
     execFile(
       'git',
       args,
-      { cwd, encoding: 'buffer', maxBuffer: 256 * 1024 * 1024 },
+      { cwd, env: { ...envWithoutRepo(), ...extra }, encoding: 'buffer', maxBuffer: 256 * 1024 * 1024 },
       (error, stdout, stderr) => {
         const code = error && typeof error.code === 'number' ? error.code : error ? 1 : 0
         resolve({ stdout, stderr: stderr.toString('utf8'), code })
@@ -77,8 +132,8 @@ export function execGit(cwd: string, args: string[]): Promise<ExecResult> {
 export type GitExec = typeof execGit
 
 export function createGit(cwd: string, exec: GitExec = execGit): Git {
-  async function run(args: string[]): Promise<string> {
-    const r = await exec(cwd, args)
+  async function run(args: string[], env: Readonly<Record<string, string>> = {}): Promise<string> {
+    const r = await exec(cwd, args, env)
     if (r.code !== 0) {
       throw new GitError(args, r.stderr, r.code)
     }
@@ -101,12 +156,12 @@ export function createGit(cwd: string, exec: GitExec = execGit): Git {
     fetch: async (remote, refspecs) => {
       await run(['fetch', '--no-tags', '--quiet', remote, ...refspecs])
     },
-    show: async (ref, path) => {
-      const r = await exec(cwd, ['show', `${ref}:${path}`])
+    show: async (ref, file) => {
+      const r = await exec(cwd, ['show', `${ref}:${file}`])
       return r.code === 0 ? r.stdout : null
     },
-    blobSize: async (ref, path) => {
-      const r = await exec(cwd, ['cat-file', '-s', `${ref}:${path}`])
+    blobSize: async (ref, file) => {
+      const r = await exec(cwd, ['cat-file', '-s', `${ref}:${file}`])
       return r.code === 0 ? Number(r.stdout.toString('utf8').trim()) : null
     },
     commitAuthor: ref => run(['log', '-1', '--format=%an', ref]),
@@ -116,5 +171,50 @@ export function createGit(cwd: string, exec: GitExec = execGit): Git {
       const r = await exec(cwd, ['remote', 'get-url', name])
       return r.code === 0 ? r.stdout.toString('utf8').trim() : null
     },
+    currentBranch: async () => {
+      const r = await exec(cwd, ['symbolic-ref', '--quiet', '--short', 'HEAD'])
+      return r.code === 0 ? r.stdout.toString('utf8').trim() : null
+    },
+    symbolicRef: async name => {
+      const r = await exec(cwd, ['symbolic-ref', '--quiet', '--short', name])
+      return r.code === 0 ? r.stdout.toString('utf8').trim() : null
+    },
+    configuredUser: async () => {
+      const r = await exec(cwd, ['config', '--get', 'user.name'])
+      const value = r.code === 0 ? r.stdout.toString('utf8').trim() : ''
+      return value === '' ? null : value
+    },
+    firstExistingRef: async refs => {
+      for (const ref of refs) {
+        const r = await exec(cwd, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])
+        if (r.code === 0) {
+          return ref
+        }
+      }
+      return null
+    },
+    snapshotWorktree: async () => {
+      const indexEnv = {
+        GIT_INDEX_FILE: path.join(
+          await run(['rev-parse', '--path-format=absolute', '--git-dir']),
+          SNAPSHOT_INDEX
+        ),
+      }
+      // `:/` stages the whole repository whatever the cwd is; ignored files stay out of it.
+      await run(['add', '-A', '--', ':/'], indexEnv)
+      const tree = await run(['write-tree'], indexEnv)
+      if (tree === (await run(['rev-parse', 'HEAD^{tree}']))) {
+        return null
+      }
+      const sha = await run(
+        ['commit-tree', tree, '-p', 'HEAD', '-m', 'pr-review: working tree snapshot'],
+        SNAPSHOT_ENV
+      )
+      await run(['update-ref', SNAPSHOT_REF, sha])
+      return sha
+    },
+    anchorCommit: async sha => {
+      await run(['update-ref', `${CANVAS_ANCHOR_PREFIX}/${sha}`, sha])
+    },
   }
 }

package/src/git/local-target.ts

@@ -0,0 +1,138 @@
+// Where a review of work that has no pull request yet takes its two commits from: the branch the
+// change will be opened against, and either the tip of the current branch or a snapshot of the
+// working tree as it stands.
+import type { Pr, Repo } from '../contract/review-artifact.js'
+import type { LocalKey } from '../contract/review-key.js'
+import { type Git, GitError } from './git.js'
+
+/** Tried in order when the user names no base: the remote's default branch first. */
+export const BASE_CANDIDATES = ['origin/HEAD', 'origin/main', 'origin/master', 'main', 'master'] as const
+
+/** `origin/HEAD` is a pointer, and a canvas that says `origin/main` reads better than one that
+ * says the pointer's name. */
+const ORIGIN_HEAD = 'origin/HEAD'
+
+export class LocalTargetError extends Error {
+  readonly hint: string
+
+  constructor(message: string, hint: string) {
+    super(message)
+    this.name = 'LocalTargetError'
+    this.hint = hint
+  }
+}
+
+/**
+ * The branch the current work will be opened against. `origin/HEAD` is the remote's own answer,
+ * so it is preferred over guessing at names; a repository that never fetched it falls back to the
+ * two usual ones.
+ */
+export async function resolveLocalBase(git: Git, override?: string | undefined): Promise<string> {
+  if (override !== undefined && override !== '') {
+    return override
+  }
+  const found = await git.firstExistingRef(BASE_CANDIDATES)
+  if (found === null) {
+    throw new LocalTargetError(
+      'no default branch to compare against',
+      'pass --base <ref>, or fetch origin so origin/HEAD resolves'
+    )
+  }
+  if (found !== ORIGIN_HEAD) {
+    return found
+  }
+  return (await git.symbolicRef(`refs/remotes/${ORIGIN_HEAD}`)) ?? ORIGIN_HEAD
+}
+
+export interface LocalHead {
+  headSha: string
+  /** The checked-out branch, or null on a detached HEAD. */
+  branch: string | null
+  /** True when the head is a snapshot of the working tree rather than a commit on the branch. */
+  uncommitted: boolean
+}
+
+/**
+ * Who the local work belongs to. Uncommitted edits are nobody's commit yet, so the name this
+ * clone commits as says more than the author of whatever HEAD happens to be.
+ */
+export async function localAuthor(git: Git, uncommitted: boolean): Promise<string> {
+  if (uncommitted) {
+    const configured = await git.configuredUser()
+    if (configured !== null) {
+      return configured
+    }
+  }
+  return git.commitAuthor('HEAD')
+}
+
+export interface DescribeLocalOptions {
+  base: string
+  source: LocalKey
+  repo: Repo
+  now: () => Date
+}
+
+/**
+ * The local work in the shape the rest of the tool reads a pull request in. `prepare` writes it to
+ * `prs/<branch|uncommitted>/pr.json` and the page resolves it again on a refresh, so both have to
+ * agree on the head, the title, and the words the header shows; they are decided here, once.
+ *
+ * The line counts are left at zero: only the collected diff knows them, and `prepare` fills them
+ * in once it has one.
+ */
+export async function describeLocalWork(git: Git, opts: DescribeLocalOptions): Promise<Pr> {
+  const head = await resolveLocalHead(git, opts.source)
+  const branch = head.branch ?? 'HEAD'
+  return {
+    number: null,
+    title: head.uncommitted ? `Uncommitted work on ${branch}` : branch,
+    body: '',
+    author: await localAuthor(git, head.uncommitted),
+    // Nothing is pushed yet, so there is no page on the forge to link to.
+    url: '',
+    state: head.uncommitted ? UNCOMMITTED_STATE : BRANCH_STATE,
+    draft: false,
+    updatedAt: opts.now().toISOString(),
+    baseRef: opts.base,
+    headRef: branch,
+    headSha: head.headSha,
+    mergeBaseSha: await git.mergeBase(opts.base, head.headSha),
+    additions: 0,
+    deletions: 0,
+    changedFiles: 0,
+    repo: opts.repo,
+  }
+}
+
+/** What `pr.state` reads for each local review. One word, because the header paints it as a pill. */
+export const BRANCH_STATE = 'branch'
+export const UNCOMMITTED_STATE = 'uncommitted'
+
+/**
+ * The commit a local review describes. The `uncommitted` review snapshots the edits and the
+ * untracked files into a commit of their own; when there are none, and for the `branch` review
+ * always, that is the tip of the current branch.
+ */
+export async function resolveLocalHead(git: Git, source: LocalKey): Promise<LocalHead> {
+  const branch = await git.currentBranch()
+  let head: string
+  try {
+    head = await git.revParse('HEAD')
+  } catch (err) {
+    if (err instanceof GitError) {
+      throw new LocalTargetError(
+        'this branch has no commits yet, so there is nothing to compare against',
+        'make one commit first, then run the review again'
+      )
+    }
+    throw err
+  }
+  if (source === 'branch') {
+    return { headSha: head, branch, uncommitted: false }
+  }
+  const snapshot = await git.snapshotWorktree()
+  return snapshot === null
+    ? { headSha: head, branch, uncommitted: false }
+    : { headSha: snapshot, branch, uncommitted: true }
+}

package/src/git/patch-lines.ts

@@ -1,8 +1,8 @@
 // The header parser and the line lookup live in static/js/hunks.js so the browser can load them
 // without a bundler; the server imports the same code here.
-import { parseHunkHeader } from '../../static/js/hunks.js'
+import { hunkForLine, parseHunkHeader } from '../../static/js/hunks.js'
 import { hunkId } from '../contract/keys.js'
-import type { Hunk } from '../contract/review-artifact.js'
+import type { FileEntry, Hunk, Side } from '../contract/review-artifact.js'
 
 export { hunkForLine, hunkLineRanges, parseHunkHeader } from '../../static/js/hunks.js'
 
@@ -58,3 +58,35 @@ export function labelPatch(key: string, patch: string): string {
     .map((h, i) => [`### hunk ${hunkId(key, i + 1)}`, h.header, ...h.lines].join('\n'))
     .join('\n')
 }
+
+export interface InlineTarget {
+  path: string
+  line: number
+  side: Side
+  startLine?: number | undefined
+}
+
+/**
+ * Whether a comment targets lines in the local diff: the file is in the diff, and the whole
+ * range sits inside one hunk on that side. Returns the reason when it will not, so the route can
+ * refuse before the request leaves the machine.
+ */
+export function checkInlineTarget(files: ReadonlyArray<FileEntry>, target: InlineTarget): string | null {
+  const file = files.find(f => f.path === target.path)
+  if (file === undefined) {
+    return `${target.path} is not in the diff`
+  }
+  const hunk = hunkForLine(file.hunks, target.side, target.line)
+  if (hunk === null) {
+    return `${target.path}:${target.line} (${target.side}) is not in the diff`
+  }
+  if (target.startLine !== undefined) {
+    if (target.startLine > target.line) {
+      return `the first line of the range must come before ${target.line}`
+    }
+    if (hunkForLine(file.hunks, target.side, target.startLine) !== hunk) {
+      return `${target.path}:${target.startLine}-${target.line} (${target.side}) spans more than one chunk`
+    }
+  }
+  return null
+}

package/src/git/pr-refs.ts

@@ -0,0 +1,36 @@
+import type { Git } from './git.js'
+import type { Host } from '../host/host.js'
+import type { PrMeta } from '../host/pr.js'
+
+export function prHeadRef(number: number): string {
+  return `refs/pr/${number}/head`
+}
+
+export function prBaseRef(number: number): string {
+  return `refs/pr/${number}/base`
+}
+
+/**
+ * Fetches the review's head and base into local refs and resolves the two commits the diff needs.
+ * The local refs are the ones the prior-art skill used, so an existing clone keeps working, and
+ * they are the same for both hosts; only the remote ref that holds the head differs.
+ *
+ * A merged PR is diffed against the base as it was at merge time: the merge commit's first
+ * parent (a merge commit, a squash, or the last rebased commit all sit on the base branch, so
+ * it is local once the base was fetched). Today's base tip would contain the PR and give an
+ * empty diff.
+ */
+export async function fetchPrRefs(
+  git: Git,
+  host: Host,
+  meta: PrMeta
+): Promise<{ headSha: string; mergeBaseSha: string }> {
+  await git.fetch('origin', [
+    `+${host.remoteHeadRef(meta.number)}:${prHeadRef(meta.number)}`,
+    `+refs/heads/${meta.baseRef}:${prBaseRef(meta.number)}`,
+  ])
+  const headSha = await git.revParse(prHeadRef(meta.number))
+  const base = meta.mergeCommitSha === null ? prBaseRef(meta.number) : `${meta.mergeCommitSha}^1`
+  const mergeBaseSha = await git.mergeBase(base, headSha)
+  return { headSha, mergeBaseSha }
+}