@vintasoftware/pr-review-canvas 0.3.0 → 0.5.0

package/src/host/client.ts

@@ -0,0 +1,246 @@
+import { execFile } from 'node:child_process'
+import { z } from 'zod'
+
+/**
+ * The forge operations the tool needs, all through the host's own CLI (`gh` or `glab`) so the
+ * user's login is used and no token is ever read by this code. The two CLIs share one command
+ * grammar, so one client serves both; the spec names the binary and the instance. Routes receive
+ * an implementation through AppContext; tests use an in-memory fake.
+ */
+export interface HostClient {
+  /** `<cli> api --method GET <path>` with optional query params; returns the parsed JSON body. */
+  api(path: string, params?: Record<string, string>): Promise<unknown>
+  /** `<cli> api -i --method GET <path>`: the response headers as well as the body. */
+  apiWithHeaders(path: string): Promise<CliResponse>
+  /** Send JSON over stdin. Defaults to POST; comment edits use PATCH or PUT. */
+  post(path: string, body: unknown, method?: 'POST' | 'PATCH' | 'PUT' | 'DELETE'): Promise<unknown>
+  /** `<cli> api graphql`; returns the parsed `data` object. */
+  graphql(query: string, variables: Record<string, string | number>): Promise<unknown>
+  /** `<cli> auth status`: is the CLI installed and logged in? */
+  authStatus(): Promise<{ installed: boolean; authenticated: boolean; detail: string }>
+  /**
+   * The token of the current login, or null when there is none. Callers keep it in a local
+   * variable for the length of one request; it is never logged or written to disk.
+   */
+  authToken(): Promise<string | null>
+}
+
+export type HostCli = 'gh' | 'glab'
+
+/** What differs between the two CLIs. Everything else is the same argument list. */
+export interface HostCliSpec {
+  cli: HostCli
+  /** Variables the child gets on top of the process environment; `glab` learns its instance here. */
+  env: Record<string, string>
+  /** The command that prints the current login's token. */
+  tokenArgs: string[]
+}
+
+/** The words the doctor and error hints use for each CLI. */
+export const CLI_INFO: Record<HostCli, { label: string; installUrl: string; loginCommand: string }> = {
+  gh: { label: 'GitHub CLI (gh)', installUrl: 'https://cli.github.com', loginCommand: 'gh auth login' },
+  glab: {
+    label: 'GitLab CLI (glab)',
+    installUrl: 'https://gitlab.com/gitlab-org/cli',
+    loginCommand: 'glab auth login',
+  },
+}
+
+/** One HTTP answer from `<cli> api -i`: the status, the header names in lower case, and the body. */
+export interface CliResponse {
+  status: number
+  headers: Record<string, string>
+  body: unknown
+}
+
+/**
+ * Splits the output of `<cli> api -i` into the last header block and the body. A redirect prints
+ * one block per hop, and only the final one describes the answer.
+ */
+export function parseIncludedResponse(stdout: string): CliResponse {
+  const normalized = stdout.replace(/\r\n/g, '\n')
+  const parts = normalized.split('\n\n')
+  let body: unknown = null
+  const headerBlocks: string[] = []
+  for (const [i, part] of parts.entries()) {
+    if (/^HTTP\/[\d.]+ \d{3}/.test(part)) {
+      headerBlocks.push(part)
+      continue
+    }
+    // Everything after the last header block is the body, which may hold blank lines itself.
+    body = parseJsonOrNull(parts.slice(i).join('\n\n'))
+    break
+  }
+  const last = headerBlocks[headerBlocks.length - 1] ?? ''
+  const lines = last.split('\n').filter(l => l.trim() !== '')
+  const status = Number(/^HTTP\/[\d.]+ (\d{3})/.exec(lines[0] ?? '')?.[1] ?? 0)
+  const headers: Record<string, string> = {}
+  for (const line of lines.slice(1)) {
+    const at = line.indexOf(':')
+    if (at > 0) {
+      headers[line.slice(0, at).trim().toLowerCase()] = line.slice(at + 1).trim()
+    }
+  }
+  return { status, headers, body }
+}
+
+function parseJsonOrNull(text: string): unknown {
+  if (text.trim() === '') {
+    return null
+  }
+  try {
+    return JSON.parse(text) as unknown
+  } catch {
+    return null
+  }
+}
+
+export class HostCliError extends Error {
+  readonly cli: HostCli
+  readonly path: string
+  readonly stderr: string
+  readonly exitCode: number
+  /** True when the CLI binary is not on PATH. */
+  readonly missingBinary: boolean
+
+  constructor(cli: HostCli, path: string, stderr: string, exitCode: number, missingBinary = false) {
+    super(`${cli} api ${path} failed (${exitCode}): ${stderr.trim()}`)
+    this.name = 'HostCliError'
+    this.cli = cli
+    this.path = path
+    this.stderr = stderr
+    this.exitCode = exitCode
+    this.missingBinary = missingBinary
+  }
+  /** Both CLIs exit 1 and name the status in stderr for a missing resource. */
+  get notFound(): boolean {
+    return /HTTP 404|404 Not Found/i.test(this.stderr)
+  }
+  get unauthenticated(): boolean {
+    return /HTTP 401|401 Unauthorized|not logged in|auth login/i.test(this.stderr)
+  }
+}
+
+interface ExecResult {
+  stdout: string
+  stderr: string
+  code: number
+  missingBinary: boolean
+}
+
+export interface CliExecOptions {
+  binary?: string
+  env?: Record<string, string>
+  /** Written to the child's stdin, for `api --input -`. */
+  input?: string
+}
+
+export function execCli(args: string[], opts: CliExecOptions = {}): Promise<ExecResult> {
+  return new Promise(resolve => {
+    const child = execFile(
+      opts.binary ?? 'gh',
+      args,
+      { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, env: { ...process.env, ...opts.env } },
+      (error, stdout, stderr) => {
+        const missingBinary = error !== null && 'code' in error && error.code === 'ENOENT'
+        const code = error && typeof error.code === 'number' ? error.code : error ? 1 : 0
+        resolve({ stdout, stderr, code, missingBinary })
+      }
+    )
+    if (opts.input !== undefined) {
+      child.stdin?.on('error', () => undefined)
+      child.stdin?.end(opts.input)
+    }
+  })
+}
+
+export type CliExec = typeof execCli
+
+export const GH_CLI: HostCliSpec = { cli: 'gh', env: {}, tokenArgs: ['auth', 'token'] }
+
+/** `glab` reads its instance from GITLAB_HOST, and prints a login's token through `config get`. */
+export function glabCli(hostname: string): HostCliSpec {
+  return {
+    cli: 'glab',
+    env: { GITLAB_HOST: hostname },
+    tokenArgs: ['config', 'get', 'token', '--host', hostname],
+  }
+}
+
+export function createHostClient(spec: HostCliSpec, exec: CliExec = execCli): HostClient {
+  const run = async (path: string, args: string[], input?: string): Promise<ExecResult> => {
+    const r = await exec(args, { binary: spec.cli, env: spec.env, ...(input === undefined ? {} : { input }) })
+    if (r.code !== 0) {
+      throw new HostCliError(
+        spec.cli,
+        path,
+        r.missingBinary ? `${spec.cli}: command not found` : r.stderr,
+        r.code,
+        r.missingBinary
+      )
+    }
+    return r
+  }
+  return {
+    api: async (path, params = {}) => {
+      // `api` switches to POST as soon as a field is given; these are reads, so pin GET.
+      const args = ['api', '--method', 'GET', path]
+      for (const [k, v] of Object.entries(params)) {
+        args.push('-F', `${k}=${v}`)
+      }
+      return JSON.parse((await run(path, args)).stdout) as unknown
+    },
+    apiWithHeaders: async path =>
+      parseIncludedResponse((await run(path, ['api', '-i', '--method', 'GET', path])).stdout),
+    post: async (path, body, method = 'POST') => {
+      // The payload goes over stdin, so no comment text ever appears in an argument list. The
+      // content type is named because `glab` does not infer it and GitLab answers 415 without it.
+      const args = ['api', '--method', method, path, '--input', '-', '-H', 'Content-Type: application/json']
+      const { stdout } = await run(path, args, JSON.stringify(body))
+      return stdout.trim() === '' ? null : (JSON.parse(stdout) as unknown)
+    },
+    graphql: async (query, variables) => {
+      const args = ['api', 'graphql', '-f', `query=${query}`]
+      for (const [k, v] of Object.entries(variables)) {
+        args.push(typeof v === 'number' ? '-F' : '-f', `${k}=${v}`)
+      }
+      const body = JSON.parse((await run('graphql', args)).stdout) as {
+        data?: unknown
+        errors?: Array<{ message: string }>
+      }
+      if (body.errors && body.errors.length > 0) {
+        throw new HostCliError(spec.cli, 'graphql', body.errors.map(e => e.message).join('; '), 1)
+      }
+      return body.data
+    },
+    authStatus: async () => {
+      const r = await exec(['auth', 'status'], { binary: spec.cli, env: spec.env })
+      if (r.missingBinary) {
+        return { installed: false, authenticated: false, detail: `${spec.cli} is not on PATH` }
+      }
+      const detail = (r.stdout + r.stderr).trim().split('\n')[0] ?? ''
+      return { installed: true, authenticated: r.code === 0, detail }
+    },
+    authToken: async () => {
+      const r = await exec(spec.tokenArgs, { binary: spec.cli, env: spec.env })
+      const token = r.stdout.trim()
+      return r.code === 0 && token !== '' ? token : null
+    },
+  }
+}
+
+export const COMMENTS_PAGE_SIZE = 100
+
+/** Every item of a REST list endpoint, following `page=` until a page comes back short. */
+export async function fetchAllPages(client: HostClient, path: string): Promise<unknown[]> {
+  const out: unknown[] = []
+  for (let page = 1; ; page++) {
+    const batch = z
+      .array(z.unknown())
+      .parse(await client.api(path, { per_page: String(COMMENTS_PAGE_SIZE), page: String(page) }))
+    out.push(...batch)
+    if (batch.length < COMMENTS_PAGE_SIZE) {
+      return out
+    }
+  }
+}

package/src/host/host.ts

@@ -0,0 +1,154 @@
+import { shareGithubCanvas } from '../github/canvas-comment.js'
+import { shareGitlabCanvas } from '../gitlab/canvas-comment.js'
+import type { Capabilities, PublicHost, ReviewSummary } from '../contract/api.js'
+import type {
+  FetchCommentsResult,
+  PostCommentInput,
+  PostCommentResult,
+  ReviewComment,
+} from '../contract/comments.js'
+import type { Repo } from '../contract/review-artifact.js'
+import { GITHUB_ATTACHMENTS } from '../github/attachments.js'
+import { probeCapabilities } from '../github/capabilities.js'
+import { fetchComments } from '../github/comments.js'
+import { postComment } from '../github/post-comment.js'
+import type { PendingComment } from '../contract/pending.js'
+import type { ReviewEvent } from '../contract/reviews.js'
+import { postReview } from '../github/post-review.js'
+import { fetchPrMeta } from '../github/pr.js'
+import type { PrMeta } from './pr.js'
+import { gitlabAttachments } from '../gitlab/attachments.js'
+import { probeGitlabCapabilities } from '../gitlab/capabilities.js'
+import { fetchGitlabComments } from '../gitlab/comments.js'
+import { fetchMrMeta } from '../gitlab/mr.js'
+import { postGitlabComment } from '../gitlab/post-comment.js'
+import { postGitlabReview } from '../gitlab/post-review.js'
+import type { Derived } from '../store/derived-store.js'
+import type { AttachmentLink } from './attachments.js'
+import { GH_CLI, glabCli, type HostClient, type HostCliSpec } from './client.js'
+
+export type HostKind = PublicHost['kind']
+
+/** The review and the comments created by this submission. */
+export interface PostedReview extends ReviewSummary {
+  comments: ReviewComment[]
+  warnings: string[]
+}
+
+/** How canvas zips attached to a review are found and fetched on one forge. */
+export interface HostAttachments {
+  /** Zip links in one markdown text, as absolute URLs this host serves. */
+  findLinks(text: string, repo: Repo): AttachmentLink[]
+  /** Where an attachment may be served from. Everything else is refused before any request. */
+  allowedHosts: ReadonlySet<string>
+  /** The header that carries the CLI token to the forge itself; a storage redirect gets none. */
+  authHeader(token: string): Record<string, string>
+}
+
+/**
+ * One forge: the words the page uses for it, the CLI that talks to it, and every operation whose
+ * request or answer differs between GitHub and GitLab. Everything that is the same for both (the
+ * local refs, the stored Pr, the download loop, the routes) takes a Host and never asks its kind.
+ */
+export interface Host {
+  kind: HostKind
+  hostname: string
+  /** `GitHub` or `GitLab`, for messages. */
+  label: string
+  cli: HostCliSpec
+  webBase: string
+  /** `pull request` or `merge request`, and its abbreviation. */
+  noun: string
+  nounShort: string
+  /** The remote ref that holds a review's head, fetched into the same local ref for both hosts. */
+  remoteHeadRef(number: number): string
+  compareUrl(repo: Repo, base: string, head: string): string
+  fetchPrMeta(client: HostClient, repo: Repo, number: number): Promise<PrMeta>
+  fetchComments(
+    client: HostClient,
+    repo: Repo,
+    number: number,
+    headSha: string,
+    now: () => Date
+  ): Promise<FetchCommentsResult>
+  /** GitLab needs the diff for renamed paths and both coordinates of context lines. */
+  postComment(
+    client: HostClient,
+    repo: Repo,
+    number: number,
+    headSha: string,
+    input: PostCommentInput,
+    diff: Derived
+  ): Promise<PostCommentResult>
+  /**
+   * Submits the review, with the comments the reviewer had waiting. GitHub takes them in the one
+   * call that creates the review; GitLab stages and batch-publishes draft notes, which is why the
+   * diff is passed here too.
+   */
+  postReview(
+    client: HostClient,
+    repo: Repo,
+    number: number,
+    headSha: string,
+    input: { event: ReviewEvent; body: string; comments?: ReadonlyArray<PendingComment> },
+    diff: Derived
+  ): Promise<PostedReview>
+  probeCapabilities(client: HostClient, repo: Repo): Promise<Capabilities>
+  canvasCommentLimit: number
+  shareCanvas(client: HostClient, repo: Repo, number: number, body: string): Promise<string>
+  attachments: HostAttachments
+}
+
+export const GITHUB_HOST: Host = {
+  kind: 'github',
+  hostname: 'github.com',
+  label: 'GitHub',
+  cli: GH_CLI,
+  webBase: 'https://github.com',
+  noun: 'pull request',
+  nounShort: 'PR',
+  remoteHeadRef: number => `pull/${number}/head`,
+  compareUrl: (repo, base, head) => `https://github.com/${repo.owner}/${repo.name}/compare/${base}...${head}`,
+  fetchPrMeta,
+  fetchComments,
+  postComment,
+  postReview,
+  probeCapabilities,
+  canvasCommentLimit: 65_536,
+  shareCanvas: shareGithubCanvas,
+  attachments: GITHUB_ATTACHMENTS,
+}
+
+/** A GitLab instance. `hostname` is gitlab.com or the self-hosted instance the origin names. */
+export function gitlabHost(hostname: string): Host {
+  const webUrl = new URL(`https://${hostname}`)
+  hostname = webUrl.host
+  const webBase = webUrl.origin
+  return {
+    kind: 'gitlab',
+    hostname,
+    label: 'GitLab',
+    cli: glabCli(hostname),
+    webBase,
+    noun: 'merge request',
+    nounShort: 'MR',
+    remoteHeadRef: number => `merge-requests/${number}/head`,
+    compareUrl: (repo, base, head) => `${webBase}/${repo.owner}/${repo.name}/-/compare/${base}...${head}`,
+    fetchPrMeta: fetchMrMeta,
+    fetchComments: (client, repo, number, headSha, now) =>
+      fetchGitlabComments(client, repo, number, headSha, now, webBase),
+    postComment: (client, repo, number, headSha, input, diff) =>
+      postGitlabComment(client, repo, number, headSha, input, { webBase, ...diff }),
+    postReview: (client, repo, number, headSha, input, diff) =>
+      postGitlabReview(client, repo, number, headSha, input, webBase, diff),
+    probeCapabilities: probeGitlabCapabilities,
+    canvasCommentLimit: 1_000_000,
+    shareCanvas: (client, repo, number, body) => shareGitlabCanvas(client, repo, number, body, webBase),
+    attachments: gitlabAttachments(hostname, webBase),
+  }
+}
+
+/** The part of a Host the page and the health endpoint are told. */
+export function publicHost(host: Host): PublicHost {
+  return { kind: host.kind, label: host.label, webBase: host.webBase }
+}

package/src/host/pr.ts

@@ -0,0 +1,51 @@
+import type { Pr, Repo } from '../contract/review-artifact.js'
+
+export class PrNotFoundError extends Error {
+  readonly number: number
+
+  constructor(number: number) {
+    super(`pull request #${number} not found`)
+    this.name = 'PrNotFoundError'
+    this.number = number
+  }
+}
+
+export interface PrMeta {
+  number: number
+  title: string
+  body: string
+  author: string
+  url: string
+  state: string
+  draft: boolean
+  updatedAt: string
+  baseRef: string
+  headRef: string
+  headSha: string
+  /** The commit that merged the PR into its base, once merged. */
+  mergeCommitSha: string | null
+  additions: number
+  deletions: number
+  changedFiles: number
+}
+
+export function toPr(meta: PrMeta, repo: Repo, shas: { headSha: string; mergeBaseSha: string }): Pr {
+  return {
+    number: meta.number,
+    title: meta.title,
+    body: meta.body,
+    author: meta.author,
+    url: meta.url,
+    state: meta.state,
+    draft: meta.draft,
+    updatedAt: meta.updatedAt,
+    baseRef: meta.baseRef,
+    headRef: meta.headRef,
+    headSha: shas.headSha,
+    mergeBaseSha: shas.mergeBaseSha,
+    additions: meta.additions,
+    deletions: meta.deletions,
+    changedFiles: meta.changedFiles,
+    repo,
+  }
+}

package/src/host/remote.ts

@@ -0,0 +1,42 @@
+import type { Repo } from '../contract/review-artifact.js'
+import { GITHUB_HOST, gitlabHost, type Host } from './host.js'
+
+export interface OriginRemote {
+  host: Host
+  repo: Repo
+}
+
+/** Hostname and repository path from the three remote forms git gives out: scp-like ssh, ssh://, https. */
+export function splitGitRemote(url: string): { hostname: string; path: string } | null {
+  const m =
+    /^ssh:\/\/git@([^:/]+)(?::\d+)?\/(.+)$/.exec(url.trim()) ??
+    /^git@([^:/]+):(.+)$/.exec(url.trim()) ??
+    /^https?:\/\/(?:[^@/]+@)?([^/]+)\/(.+)$/.exec(url.trim())
+  if (m?.[1] === undefined || m[2] === undefined) {
+    return null
+  }
+  return { hostname: m[1].toLowerCase(), path: m[2].replace(/\.git$/i, '').replace(/\/$/, '') }
+}
+
+/**
+ * Classifies origin. github.com is GitHub; gitlab.com, a hostname that contains "gitlab", or any
+ * other host when `PR_REVIEW_HOST=gitlab` is set (a self-hosted GitLab whose name does not say
+ * so) is GitLab. A GitLab path may nest groups, which become the owner with slashes.
+ */
+export function parseOriginRemote(url: string, env: NodeJS.ProcessEnv = {}): OriginRemote | null {
+  const split = splitGitRemote(url)
+  if (split === null) {
+    return null
+  }
+  const parts = split.path.split('/').filter(p => p !== '')
+  const name = parts[parts.length - 1]
+  if (parts.length < 2 || name === undefined) {
+    return null
+  }
+  const repo: Repo = { owner: parts.slice(0, -1).join('/'), name }
+  if (split.hostname === 'github.com') {
+    return parts.length === 2 ? { host: GITHUB_HOST, repo } : null
+  }
+  const forced = env['PR_REVIEW_HOST']?.trim().toLowerCase() === 'gitlab'
+  return forced || split.hostname.includes('gitlab') ? { host: gitlabHost(split.hostname), repo } : null
+}

package/src/project-config.ts

@@ -41,6 +41,10 @@ export const PromptOverridesSchema = z
     'generation-format.md': z.string().min(1).optional(),
     'generation-strict.md': z.string().min(1).optional(),
     'generation-surfacing.md': z.string().min(1).optional(),
+    'generation-strict-incremental.md': z.string().min(1).optional(),
+    'generation-surfacing-incremental.md': z.string().min(1).optional(),
+    'judging-strict.md': z.string().min(1).optional(),
+    'judging-surfacing.md': z.string().min(1).optional(),
     'quality-standards.md': z.string().min(1).optional(),
     'layering-guidance.md': z.string().min(1).optional(),
     'chat-seed.md': z.string().min(1).optional(),
@@ -65,6 +69,19 @@ export const ProjectConfigSchema = z.object({
   /** Which paths count as tests, for the layering rules and the `isTest` flag on a file. */
   tests: z.object({ patterns: z.array(z.string().min(1)) }),
   chat: z.object({ enabled: z.boolean() }),
+  canvas: z.object({
+    /**
+     * A canvas still stands for a later head whose diff is identical to the one it was generated
+     * from, as after merging the base branch in. False marks the canvas outdated on any commit.
+     */
+    keepForIdenticalDiff: z.boolean(),
+    /**
+     * Regenerating a canvas for a new head starts from the newest canvas of a commit the head was
+     * built on, carrying what the head's diff leaves untouched. False generates every canvas from
+     * a blank page, as `--force` always does.
+     */
+    incremental: z.boolean(),
+  }),
 })
 export type ProjectConfig = z.infer<typeof ProjectConfigSchema>
 
@@ -86,6 +103,9 @@ const PartialProjectConfigSchema = z.object({
     .optional(),
   tests: z.object({ patterns: z.array(z.string().min(1)).optional() }).optional(),
   chat: z.object({ enabled: z.boolean().optional() }).optional(),
+  canvas: z
+    .object({ keepForIdenticalDiff: z.boolean().optional(), incremental: z.boolean().optional() })
+    .optional(),
 })
 
 export const DEFAULT_PROJECT_CONFIG: ProjectConfig = {
@@ -95,6 +115,7 @@ export const DEFAULT_PROJECT_CONFIG: ProjectConfig = {
   generation: { mode: 'strict', maxRepairRounds: 3, inlineDiffMaxLines: 1500, smallPrHunks: 10 },
   tests: { patterns: [...DEFAULT_TEST_PATTERNS] },
   chat: { enabled: true },
+  canvas: { keepForIdenticalDiff: true, incremental: true },
 }
 
 export interface LoadedProjectConfig {
@@ -135,6 +156,11 @@ export function mergeProjectConfig(raw: unknown): { config: ProjectConfig; warni
     generation,
     tests: { patterns: user.tests?.patterns ?? [...DEFAULT_TEST_PATTERNS] },
     chat: { enabled: user.chat?.enabled ?? true },
+    canvas: {
+      keepForIdenticalDiff:
+        user.canvas?.keepForIdenticalDiff ?? DEFAULT_PROJECT_CONFIG.canvas.keepForIdenticalDiff,
+      incremental: user.canvas?.incremental ?? DEFAULT_PROJECT_CONFIG.canvas.incremental,
+    },
   }
   if (user.rulebook !== undefined) {
     config.rulebook = user.rulebook

package/src/review/carry-marks.ts

@@ -0,0 +1,131 @@
+// Review marks following an incremental canvas forward. Each canvas names the one it was generated
+// from, and that line of descent decides which of the reviewer's marks may follow — worked out here,
+// on the reviewer's own machine, from the two canvases and the two diffs it can read itself. The
+// published canvas is a pointer along that line and never a statement about what anyone reviewed.
+import { reviewedId } from '../contract/keys.js'
+import type { ReviewArtifact } from '../contract/review-artifact.js'
+import type { PrState } from '../contract/state.js'
+import type { AppContext } from '../server/context.js'
+import { fileDelta } from './incremental.js'
+
+function samePaths(a: readonly string[], b: readonly string[]): boolean {
+  const set = new Set(b)
+  return a.length === b.length && a.every(p => set.has(p))
+}
+
+/**
+ * The marks that still describe code the reviewer has seen. `marked` is the canvas they made the
+ * marks on. A file mark follows when that file is in both canvases under the same layer key and
+ * its patch is byte-identical; a layer mark follows only when the layer holds exactly the same
+ * files and none of them changed, since a layer mark claims the whole layer was read. Marks on
+ * anything else are left behind.
+ */
+export function carriedMarks(
+  marked: ReviewArtifact,
+  next: ReviewArtifact,
+  unchangedPaths: ReadonlySet<string>,
+  reviewed: Readonly<Record<string, true>>
+): Record<string, true> {
+  const carried: Record<string, true> = {}
+  for (const layer of next.layers) {
+    const before = marked.layers.find(l => l.key === layer.key)
+    if (before === undefined) {
+      continue
+    }
+    const paths = layer.files.map(f => f.path)
+    const beforePaths = before.files.map(f => f.path)
+    for (const path of paths) {
+      const id = reviewedId(layer.key, path)
+      if (unchangedPaths.has(path) && beforePaths.includes(path) && reviewed[id] === true) {
+        carried[id] = true
+      }
+    }
+    const id = reviewedId(layer.key)
+    if (reviewed[id] === true && samePaths(paths, beforePaths) && paths.every(p => unchangedPaths.has(p))) {
+      carried[id] = true
+    }
+  }
+  return carried
+}
+
+export interface MarksForCanvas {
+  /** The stored state as it applies to this canvas: only the marks that count for it. */
+  state: PrState
+  /** The canvas the marks were made on, when any of them followed. The page says so. */
+  carriedFrom?: string
+}
+
+/**
+ * Whether the line of descent that starts at `basisSha` reaches `ancestorSha`. The canvas on screen
+ * states its own basis, so the walk starts from the artifact's own pointer; the canvases further
+ * back are read from the index, which one read already holds, so following the line costs no extra
+ * canvas reads on the page's hot path.
+ *
+ * The line matters because the reviewer's marks only move to a canvas generated from the one they
+ * were made on. It has to be a line rather than a single step: the stored commit advances only when
+ * the reviewer marks something (`setReviewed` is its only writer), so a reviewer who opens a canvas,
+ * finds it already ticked, and clicks nothing leaves their marks keyed to a canvas two or more
+ * generations back.
+ */
+async function descendsFrom(
+  ctx: AppContext,
+  basisSha: string | undefined,
+  ancestorSha: string
+): Promise<boolean> {
+  const index = await ctx.canvases.readIndex()
+  const seen = new Set<string>()
+  let at = basisSha
+  while (at !== undefined && !seen.has(at)) {
+    if (at === ancestorSha) {
+      return true
+    }
+    seen.add(at)
+    at = index.canvases[at]?.basisCanvasSha
+  }
+  return false
+}
+
+/**
+ * The marks to show for one canvas. Marks made on it stand. Marks made on a canvas it descends
+ * from follow it for the parts of the diff those two canvases share, whatever the canvases in
+ * between did: a mark says the reviewer read one patch, so the patch they read and the patch on
+ * screen are compared directly, and a file the intervening canvases changed and changed back reads
+ * as untouched because it is. Anything else describes other code and counts for nothing, which is
+ * also what happens when this machine cannot read the older canvas or rebuild either diff.
+ */
+export async function marksForCanvas(
+  ctx: AppContext,
+  artifact: ReviewArtifact,
+  canvasSha: string,
+  stored: PrState
+): Promise<MarksForCanvas> {
+  if (stored.reviewedCanvasSha === canvasSha) {
+    return { state: stored }
+  }
+  const dropped: MarksForCanvas = { state: { ...stored, reviewed: {} } }
+  const markedOn = stored.reviewedCanvasSha
+  if (markedOn === undefined || !(await descendsFrom(ctx, artifact.basisCanvasSha, markedOn))) {
+    return dropped
+  }
+  const [markedArtifact, markedManifest, manifest] = await Promise.all([
+    ctx.canvases.readArtifact(markedOn),
+    ctx.canvases.readManifest(markedOn),
+    ctx.canvases.readManifest(canvasSha),
+  ])
+  if (markedArtifact === null || markedManifest === null || manifest === null) {
+    return dropped
+  }
+  const [markedDiff, diff] = await Promise.all([
+    ctx.derived.readOrBuild(markedOn, markedManifest.mergeBaseSha),
+    ctx.derived.readOrBuild(canvasSha, manifest.mergeBaseSha),
+  ])
+  if (markedDiff === null || diff === null) {
+    return dropped
+  }
+  const unchanged = new Set(fileDelta(markedDiff, diff).unchanged)
+  const reviewed = carriedMarks(markedArtifact, artifact, unchanged, stored.reviewed)
+  if (Object.keys(reviewed).length === 0) {
+    return dropped
+  }
+  return { state: { ...stored, reviewed, reviewedCanvasSha: canvasSha }, carriedFrom: markedOn }
+}