@vintasoftware/pr-review-canvas 0.1.0

package/src/git/diff-collector.ts

@@ -0,0 +1,151 @@
+import { sanitizeKey, uniqueKey } from '../contract/keys.js'
+import type { FileEntry } from '../contract/review-artifact.js'
+import { FILE_STATUSES } from '../contract/review-artifact.js'
+import type { Git } from './git.js'
+import { langForPath } from './lang.js'
+import { buildHunkIndex } from './patch-lines.js'
+
+export type FileStatus = (typeof FILE_STATUSES)[number]
+
+/** One file of the diff with its patch. The patch starts at the first `@@` line. */
+export interface CollectedFile {
+  path: string
+  oldPath?: string
+  key: string
+  status: FileStatus
+  additions: number
+  deletions: number
+  lang?: string
+  patch: string
+}
+
+/** Splits `git diff` output into one block per `diff --git` header. */
+export function splitBlocks(diffText: string): string[][] {
+  const blocks: string[][] = []
+  let cur: string[] | null = null
+  for (const line of diffText.split('\n')) {
+    if (line.startsWith('diff --git ')) {
+      if (cur !== null) {
+        blocks.push(cur)
+      }
+      cur = []
+    }
+    if (cur !== null) {
+      cur.push(line)
+    }
+  }
+  if (cur !== null) {
+    blocks.push(cur)
+  }
+  return blocks
+}
+
+function stripPrefix(p: string | null): string | null {
+  if (p === null || p === '/dev/null') {
+    return null
+  }
+  return p.length > 2 && p[1] === '/' ? p.slice(2) : p
+}
+
+/** Parses one `diff --git` block. Returns null when no path can be found. */
+export function parseBlock(lines: string[]): Omit<CollectedFile, 'key'> | null {
+  const hunkAt = lines.findIndex(l => l.startsWith('@@'))
+  const header = hunkAt === -1 ? lines : lines.slice(0, hunkAt)
+  const body = hunkAt === -1 ? [] : lines.slice(hunkAt)
+
+  let oldRaw: string | null = null
+  let newRaw: string | null = null
+  let renameFrom: string | null = null
+  for (const l of header) {
+    if (l.startsWith('--- ')) {
+      oldRaw = l.slice(4).trim()
+    } else if (l.startsWith('+++ ')) {
+      newRaw = l.slice(4).trim()
+    } else if (l.startsWith('rename from ')) {
+      renameFrom = l.slice('rename from '.length)
+    }
+  }
+  const oldPath = stripPrefix(oldRaw)
+  const newPath = stripPrefix(newRaw)
+  let path = newPath ?? oldPath
+
+  if (path === null) {
+    // No ---/+++ pair: a pure mode change, a rename without content change, or a binary file.
+    // Take the b-side of the "diff --git" line.
+    const m = /^diff --git a\/(.*) b\/(.*)$/.exec(lines[0] ?? '')
+    path = m?.[2] ?? null
+  }
+  if (path === null) {
+    return null
+  }
+
+  const isBinary = header.some(l => l.startsWith('Binary files ')) || header.some(l => l === 'GIT binary patch')
+  let status: FileStatus
+  if (renameFrom !== null) {
+    status = 'renamed'
+  } else if (oldPath === null && newPath !== null) {
+    status = 'added'
+  } else if (newPath === null && oldPath !== null) {
+    status = 'deleted'
+  } else if (isBinary) {
+    status = 'binary'
+  } else {
+    status = 'modified'
+  }
+
+  // Trailing empty line from the final "\n" split belongs to no hunk.
+  const bodyLines = body.length > 0 && body[body.length - 1] === '' ? body.slice(0, -1) : body
+  const additions = bodyLines.filter(l => l.startsWith('+')).length
+  const deletions = bodyLines.filter(l => l.startsWith('-')).length
+
+  const file: Omit<CollectedFile, 'key'> = { path, status, additions, deletions, patch: bodyLines.join('\n') }
+  const lang = langForPath(path)
+  if (lang !== undefined) {
+    file.lang = lang
+  }
+  if (renameFrom !== null) {
+    file.oldPath = renameFrom
+  }
+  return file
+}
+
+/** Pure parse of a whole `git diff` output. Keys are unique across the result. */
+export function parseUnifiedDiff(diffText: string): CollectedFile[] {
+  const used = new Set<string>()
+  const out: CollectedFile[] = []
+  for (const block of splitBlocks(diffText)) {
+    const parsed = parseBlock(block)
+    if (parsed === null) {
+      continue
+    }
+    out.push({ ...parsed, key: uniqueKey(sanitizeKey(parsed.path), used) })
+  }
+  return out
+}
+
+export async function collectDiffs(git: Git, base: string, head: string): Promise<CollectedFile[]> {
+  return parseUnifiedDiff(await git.diff(base, head))
+}
+
+/** The manifest entry for a collected file: everything but the patch, plus the hunk index. */
+export function toFileEntry(file: CollectedFile): FileEntry {
+  const entry: FileEntry = {
+    path: file.path,
+    key: file.key,
+    status: file.status,
+    additions: file.additions,
+    deletions: file.deletions,
+    hunks: buildHunkIndex(file.key, file.patch),
+  }
+  if (file.oldPath !== undefined) {
+    entry.oldPath = file.oldPath
+  }
+  if (file.lang !== undefined) {
+    entry.lang = file.lang
+  }
+  return entry
+}
+
+export function toPatchMap(files: CollectedFile[]): Record<string, string> {
+  return Object.fromEntries(files.map(f => [f.key, f.patch]))
+}

package/src/git/git.ts

@@ -0,0 +1,115 @@
+import { execFile } from 'node:child_process'
+
+/**
+ * The git operations the tool needs. Routes, stores, and the CLI receive an implementation
+ * through AppContext and never spawn git themselves. Tests use an in-memory fake.
+ */
+export interface Git {
+  /** `git rev-parse <ref>`; throws GitError when the ref is unknown. */
+  revParse(ref: string): Promise<string>
+  mergeBase(a: string, b: string): Promise<string>
+  /** True when the commit object exists locally. */
+  commitExists(sha: string): Promise<boolean>
+  /** `git merge-base --is-ancestor a b`: false when either commit is missing. */
+  isAncestor(a: string, b: string): Promise<boolean>
+  /** `git rev-list --count a..b`: how many commits b is ahead of a. */
+  countCommitsBetween(a: string, b: string): Promise<number>
+  /** Full unified diff between two commits, rename detection on, 3 lines of context. */
+  diff(base: string, head: string): Promise<string>
+  fetch(remote: string, refspecs: string[]): Promise<void>
+  /** Content of `<ref>:<path>`; null when the path does not exist at that ref. */
+  show(ref: string, path: string): Promise<Buffer | null>
+  /** Byte size of `<ref>:<path>`; null when missing. */
+  blobSize(ref: string, path: string): Promise<number | null>
+  /** Author name of one commit (`git log -1 --format=%an`). */
+  commitAuthor(ref: string): Promise<string>
+  topLevel(): Promise<string>
+  commonDir(): Promise<string>
+  remoteUrl(name: string): Promise<string | null>
+}
+
+export const STDERR_MESSAGE_MAX = 300
+
+/**
+ * git stderr fit for an error message that reaches the JSON envelope or the CLI: credentials in
+ * URLs (`https://user:token@host`) are replaced by `***`, and the text is cut at STDERR_MESSAGE_MAX.
+ */
+export function redactStderr(stderr: string): string {
+  const redacted = stderr.trim().replace(/(\w+:\/\/)[^/\s@]+@/g, '$1***@')
+  return redacted.length > STDERR_MESSAGE_MAX ? `${redacted.slice(0, STDERR_MESSAGE_MAX)}…` : redacted
+}
+
+export class GitError extends Error {
+  readonly args: string[]
+  readonly stderr: string
+  readonly exitCode: number
+
+  constructor(args: string[], stderr: string, exitCode: number) {
+    super(`git ${args.join(' ')} failed (${exitCode}): ${redactStderr(stderr)}`)
+    this.name = 'GitError'
+    this.args = args
+    this.stderr = stderr
+    this.exitCode = exitCode
+  }
+}
+
+interface ExecResult {
+  stdout: Buffer
+  stderr: string
+  code: number
+}
+
+/** Runs git with an argument array; never a shell. */
+export function execGit(cwd: string, args: string[]): Promise<ExecResult> {
+  return new Promise(resolve => {
+    execFile('git', args, { cwd, 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 })
+    })
+  })
+}
+
+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)
+    if (r.code !== 0) {
+      throw new GitError(args, r.stderr, r.code)
+    }
+    return r.stdout.toString('utf8').replace(/\n$/, '')
+  }
+
+  return {
+    revParse: ref => run(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]),
+    mergeBase: (a, b) => run(['merge-base', a, b]),
+    commitExists: async sha => {
+      const r = await exec(cwd, ['cat-file', '-e', `${sha}^{commit}`])
+      return r.code === 0
+    },
+    isAncestor: async (a, b) => {
+      const r = await exec(cwd, ['merge-base', '--is-ancestor', a, b])
+      return r.code === 0
+    },
+    countCommitsBetween: async (a, b) => Number(await run(['rev-list', '--count', `${a}..${b}`])),
+    diff: (base, head) => run(['diff', '--no-color', '--no-ext-diff', '-M', '-U3', base, head]),
+    fetch: async (remote, refspecs) => {
+      await run(['fetch', '--no-tags', '--quiet', remote, ...refspecs])
+    },
+    show: async (ref, path) => {
+      const r = await exec(cwd, ['show', `${ref}:${path}`])
+      return r.code === 0 ? r.stdout : null
+    },
+    blobSize: async (ref, path) => {
+      const r = await exec(cwd, ['cat-file', '-s', `${ref}:${path}`])
+      return r.code === 0 ? Number(r.stdout.toString('utf8').trim()) : null
+    },
+    commitAuthor: ref => run(['log', '-1', '--format=%an', ref]),
+    topLevel: () => run(['rev-parse', '--show-toplevel']),
+    commonDir: () => run(['rev-parse', '--path-format=absolute', '--git-common-dir']),
+    remoteUrl: async name => {
+      const r = await exec(cwd, ['remote', 'get-url', name])
+      return r.code === 0 ? r.stdout.toString('utf8').trim() : null
+    },
+  }
+}

package/src/git/lang.ts

@@ -0,0 +1 @@
+export { LANG_BY_EXT, langForPath } from '../../static/js/lang.js'

package/src/git/materialize.ts

@@ -0,0 +1,79 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import type { CollectedFile } from './diff-collector.js'
+import type { Git } from './git.js'
+
+export const MATERIALIZE_MAX_BYTES = 1024 * 1024
+
+export interface MaterializeOptions {
+  headSha: string
+  mergeBaseSha: string
+  files: readonly CollectedFile[]
+  outDir: string
+}
+
+export interface MaterializeResult {
+  written: string[]
+  skipped: Array<{ path: string; reason: 'binary' | 'too-large' | 'missing' }>
+}
+
+/** Rejects paths that would escape the output directory. */
+export function safeJoin(root: string, rel: string): string | null {
+  const full = path.resolve(root, rel)
+  const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep
+  return full.startsWith(rootWithSep) ? full : null
+}
+
+async function writeSide(
+  git: Git,
+  ref: string,
+  filePath: string,
+  sideDir: string,
+  result: MaterializeResult
+): Promise<void> {
+  const target = safeJoin(sideDir, filePath)
+  if (target === null) {
+    result.skipped.push({ path: filePath, reason: 'missing' })
+    return
+  }
+  const size = await git.blobSize(ref, filePath)
+  if (size === null) {
+    result.skipped.push({ path: filePath, reason: 'missing' })
+    return
+  }
+  if (size > MATERIALIZE_MAX_BYTES) {
+    result.skipped.push({ path: filePath, reason: 'too-large' })
+    return
+  }
+  const content = await git.show(ref, filePath)
+  if (content === null) {
+    result.skipped.push({ path: filePath, reason: 'missing' })
+    return
+  }
+  await mkdir(path.dirname(target), { recursive: true })
+  await writeFile(target, content)
+  result.written.push(path.relative(path.dirname(sideDir), target))
+}
+
+/**
+ * Writes the changed files as they are at the PR head (`head/<path>`) and at the merge base
+ * (`base/<path>`), so the agent and the context route read the PR without a checkout.
+ */
+export async function materialize(git: Git, opts: MaterializeOptions): Promise<MaterializeResult> {
+  const result: MaterializeResult = { written: [], skipped: [] }
+  const headDir = path.join(opts.outDir, 'head')
+  const baseDir = path.join(opts.outDir, 'base')
+  for (const f of opts.files) {
+    if (f.status === 'binary') {
+      result.skipped.push({ path: f.path, reason: 'binary' })
+      continue
+    }
+    if (f.status !== 'deleted') {
+      await writeSide(git, opts.headSha, f.path, headDir, result)
+    }
+    if (f.status !== 'added') {
+      await writeSide(git, opts.mergeBaseSha, f.oldPath ?? f.path, baseDir, result)
+    }
+  }
+  return result
+}

package/src/git/patch-lines.ts

@@ -0,0 +1,60 @@
+// 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 { hunkId } from '../contract/keys.js'
+import type { Hunk } from '../contract/review-artifact.js'
+
+export { hunkForLine, hunkLineRanges, parseHunkHeader } from '../../static/js/hunks.js'
+
+export interface ParsedHunk {
+  header: string
+  oldStart: number
+  oldLines: number
+  newStart: number
+  newLines: number
+  /** Body lines with their leading marker (`+`, `-`, ` `, `\`). */
+  lines: string[]
+}
+
+/** Splits a patch (starting at its first `@@`) into hunks. Lines before the first header are dropped. */
+export function splitHunks(patch: string): ParsedHunk[] {
+  const out: ParsedHunk[] = []
+  if (patch === '') {
+    return out
+  }
+  let cur: ParsedHunk | null = null
+  for (const line of patch.split('\n')) {
+    const head = parseHunkHeader(line)
+    if (head !== null) {
+      cur = { ...head, header: line, lines: [] }
+      out.push(cur)
+      continue
+    }
+    if (cur !== null) {
+      cur.lines.push(line)
+    }
+  }
+  return out
+}
+
+/** Hunk ids are `<key>#<n>` with n the 1-based position in the file's patch. */
+export function buildHunkIndex(key: string, patch: string): Hunk[] {
+  return splitHunks(patch).map((h, i) => ({
+    id: hunkId(key, i + 1),
+    header: h.header,
+    oldStart: h.oldStart,
+    oldLines: h.oldLines,
+    newStart: h.newStart,
+    newLines: h.newLines,
+  }))
+}
+
+/**
+ * The patch with a `### hunk <id>` line before every hunk header, so the agent reads the same
+ * ids from `derived/patches/<key>.diff` that the manifest and the prompt use.
+ */
+export function labelPatch(key: string, patch: string): string {
+  return splitHunks(patch)
+    .map((h, i) => [`### hunk ${hunkId(key, i + 1)}`, h.header, ...h.lines].join('\n'))
+    .join('\n')
+}

package/src/github/attachments.ts

@@ -0,0 +1,288 @@
+// Finding the canvas zip a human attached to the pull request and downloading it with the gh
+// token. The token is read per request, passed to github.com only, and never logged or stored.
+import { createHash } from 'node:crypto'
+import { importCanvas } from '../canvas/import.js'
+import { type ParsedCanvasName, parseCanvasZipName } from '../canvas/name.js'
+import { CANVAS_ZIP_MAX_BYTES, hasZipMagic } from '../canvas/zip.js'
+import type { ImportResult, SharedCanvasInfo } from '../contract/api.js'
+import type { CommentsPayload } from '../contract/comments.js'
+import type { Pr, Repo } from '../contract/review-artifact.js'
+import { BodyTooLargeError, readCappedBody } from '../server/capped-body.js'
+import type { AppContext } from '../server/context.js'
+import { AppError } from '../server/errors.js'
+
+/** Where an attachment may be served from. Everything else is refused before any request. */
+export const ALLOWED_ATTACHMENT_HOSTS = new Set(['github.com', 'objects.githubusercontent.com'])
+export const MAX_REDIRECTS = 3
+export const DOWNLOAD_TIMEOUT_MS = 30_000
+
+export type DownloadFailure = NonNullable<SharedCanvasInfo['reason']>
+
+export interface AttachmentLink {
+  url: string
+  name: string
+}
+
+const FILE_LINK_RE = /https:\/\/github\.com\/user-attachments\/files\/\d+\/([A-Za-z0-9._-]+\.zip)/g
+const ASSET_LINK_RE =
+  /\[([A-Za-z0-9._-]+\.zip)\]\((https:\/\/github\.com\/user-attachments\/assets\/[0-9a-fA-F-]{36})\)/g
+
+/**
+ * Zip links in one markdown text. GitHub serves an attachment either under `files/<id>/<name>`,
+ * where the name is in the URL, or under `assets/<uuid>`, where only the markdown label has it.
+ */
+export function findAttachmentLinks(text: string): AttachmentLink[] {
+  const links: AttachmentLink[] = []
+  const seen = new Set<string>()
+  for (const m of text.matchAll(FILE_LINK_RE)) {
+    const [url, name] = [m[0], m[1]]
+    if (name !== undefined && !seen.has(url)) {
+      seen.add(url)
+      links.push({ url, name })
+    }
+  }
+  for (const m of text.matchAll(ASSET_LINK_RE)) {
+    const [, name, url] = m
+    if (name !== undefined && url !== undefined && !seen.has(url)) {
+      seen.add(url)
+      links.push({ url, name })
+    }
+  }
+  return links
+}
+
+export interface AttachmentCandidate extends AttachmentLink {
+  parsed: ParsedCanvasName
+  /**
+   * When the text carrying the link was last edited. A link added to an old comment counts from
+   * the edit, which is when the attachment appeared.
+   */
+  postedAt: string
+  /** Position in the scan, used when two links carry the same time. */
+  order: number
+}
+
+export interface DiscoverySources {
+  /** The PR body and the time the pull request was last edited. */
+  body: string
+  bodyUpdatedAt: string
+  comments: CommentsPayload
+}
+
+/** Every link in the PR body and its comments whose name is a canvas zip of this repository. */
+export function collectCandidates(sources: DiscoverySources, repo: Repo): AttachmentCandidate[] {
+  const texts: Array<{ text: string; postedAt: string }> = [
+    { text: sources.body, postedAt: sources.bodyUpdatedAt },
+    ...sources.comments.issueComments.map(c => ({ text: c.body, postedAt: c.updatedAt })),
+    ...sources.comments.reviewComments.map(c => ({ text: c.body, postedAt: c.updatedAt })),
+  ]
+  const candidates: AttachmentCandidate[] = []
+  let order = 0
+  for (const { text, postedAt } of texts) {
+    for (const link of findAttachmentLinks(text)) {
+      const parsed = parseCanvasZipName(link.name, repo)
+      if (parsed !== null) {
+        candidates.push({ ...link, parsed, postedAt, order: order++ })
+      }
+    }
+  }
+  return candidates
+}
+
+/** The canvas for this head wins, then one exported for this PR, then the one attached last. */
+export function rankCandidates(
+  candidates: AttachmentCandidate[],
+  target: { headSha: string; prNumber: number }
+): AttachmentCandidate[] {
+  const sha7 = target.headSha.slice(0, 7)
+  const score = (c: AttachmentCandidate): number =>
+    (c.parsed.sha7 === sha7 ? 2 : 0) + (c.parsed.prNumber === target.prNumber ? 1 : 0)
+  return [...candidates].sort(
+    (a, b) => score(b) - score(a) || b.postedAt.localeCompare(a.postedAt) || b.order - a.order
+  )
+}
+
+/** How many attachments one scan tries before it reports the best one as unusable. */
+export const MAX_CANDIDATES_TRIED = 3
+
+/**
+ * A fingerprint of everything discovery reads, so an unchanged pull request is not scanned again.
+ * It covers the text of every comment, because an edit can swap one zip link for another, and the
+ * head sha, because the ranking and `matchesHead` are answers about that commit.
+ */
+export function discoveryFingerprint(body: string, comments: CommentsPayload, headSha: string): string {
+  const hash = createHash('sha1')
+  hash.update(`${headSha}\n${body}`)
+  for (const c of [...comments.issueComments, ...comments.reviewComments]) {
+    hash.update(`\u0000${c.id}:${c.createdAt}:${c.body}`)
+  }
+  return hash.digest('hex')
+}
+
+export type DownloadResult = { ok: true; bytes: Uint8Array } | { ok: false; reason: DownloadFailure }
+
+function allowedUrl(raw: string, base?: string): URL | null {
+  let url: URL
+  try {
+    url = new URL(raw, base)
+  } catch {
+    return null
+  }
+  return url.protocol === 'https:' && ALLOWED_ATTACHMENT_HOSTS.has(url.hostname) ? url : null
+}
+
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308])
+
+/**
+ * Downloads one attachment. GitHub answers the first request with a redirect to a signed storage
+ * URL; that request carries no Authorization header, because storage refuses a request holding
+ * both a signature and a token.
+ */
+export async function downloadAttachment(ctx: AppContext, rawUrl: string): Promise<DownloadResult> {
+  const first = allowedUrl(rawUrl)
+  if (first === null) {
+    return { ok: false, reason: 'network' }
+  }
+  const token = await ctx.gh.authToken()
+  if (token === null) {
+    return { ok: false, reason: 'auth-required' }
+  }
+  let url = first
+  // Storage refuses a request that carries both a signature and a token, and the token has no
+  // business there anyway: only github.com is ever asked with it.
+  let withToken = url.hostname === 'github.com'
+  // One deadline for the redirects and the body together, so three slow hops cannot add up.
+  const deadline = AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS)
+  try {
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+      const accept = 'application/octet-stream'
+      const headers = withToken ? { accept, authorization: `token ${token}` } : { accept }
+      const res: Response = await ctx.fetch(url, {
+        headers,
+        redirect: 'manual',
+        signal: deadline,
+      })
+      if (REDIRECT_STATUSES.has(res.status)) {
+        const next = allowedUrl(res.headers.get('location') ?? '', url.toString())
+        if (next === null) {
+          return { ok: false, reason: 'network' }
+        }
+        url = next
+        withToken = false
+        continue
+      }
+      if (res.status === 401 || res.status === 403 || res.status === 404) {
+        return { ok: false, reason: 'auth-required' }
+      }
+      if (res.status !== 200) {
+        return { ok: false, reason: 'network' }
+      }
+      let bytes: Uint8Array
+      try {
+        bytes = await readCappedBody(res, CANVAS_ZIP_MAX_BYTES)
+      } catch (err) {
+        if (err instanceof BodyTooLargeError) {
+          return { ok: false, reason: 'too-large' }
+        }
+        throw err
+      }
+      return hasZipMagic(bytes) ? { ok: true, bytes } : { ok: false, reason: 'not-zip' }
+    }
+  } catch {
+    // A network failure, a timeout, or a body that stopped mid-stream all read the same here.
+    return { ok: false, reason: 'network' }
+  }
+  return { ok: false, reason: 'network' }
+}
+
+/** A downloaded zip that import refused, told in the words the callout uses. */
+export function importFailureReason(err: unknown): DownloadFailure {
+  if (!(err instanceof AppError)) {
+    return 'not-zip'
+  }
+  if (err.code === 'CANVAS_TOO_LARGE') {
+    return 'too-large'
+  }
+  return err.code === 'CANVAS_REPO_MISMATCH' ? 'name-mismatch' : 'not-zip'
+}
+
+export interface DiscoveryOutcome {
+  sharedCanvas: SharedCanvasInfo | null
+  imported: ImportResult | null
+  warnings: string[]
+}
+
+/**
+ * Looks for a canvas attached to the PR and imports the best one. A found-but-unusable zip is
+ * reported to the page, which offers the link and the drop zone instead.
+ */
+export async function discoverSharedCanvas(
+  ctx: AppContext,
+  pr: Pr,
+  comments: CommentsPayload
+): Promise<DiscoveryOutcome> {
+  if (pr.number === null) {
+    return { sharedCanvas: null, imported: null, warnings: [] }
+  }
+  const sources: DiscoverySources = { body: pr.body, bodyUpdatedAt: pr.updatedAt ?? '', comments }
+  const ranked = rankCandidates(collectCandidates(sources, ctx.config.repo), {
+    headSha: pr.headSha,
+    prNumber: pr.number,
+  })
+  const best = ranked[0]
+  if (best === undefined) {
+    return { sharedCanvas: null, imported: null, warnings: [] }
+  }
+  const warnings: string[] = []
+  const first = await tryCandidate(ctx, pr, pr.number, best)
+  warnings.push(...first.warnings)
+  if (first.imported !== null) {
+    return { ...first, warnings }
+  }
+  // A broken attachment must not hide a good one behind it, so the next ones are tried too.
+  for (const candidate of ranked.slice(1, MAX_CANDIDATES_TRIED)) {
+    const attempt = await tryCandidate(ctx, pr, pr.number, candidate)
+    warnings.push(...attempt.warnings)
+    if (attempt.imported !== null) {
+      return { ...attempt, warnings }
+    }
+  }
+  // Every attachment failed; the page shows the best one, its reason, and the drop zone.
+  return { ...first, warnings }
+}
+
+/** One attachment: download it and import it, or say why that did not work. */
+async function tryCandidate(
+  ctx: AppContext,
+  pr: Pr,
+  prNumber: number,
+  candidate: AttachmentCandidate
+): Promise<DiscoveryOutcome> {
+  const shared = {
+    url: candidate.url,
+    name: candidate.name,
+    matchesHead: candidate.parsed.sha7 === pr.headSha.slice(0, 7),
+  }
+  const download = await downloadAttachment(ctx, candidate.url)
+  if (!download.ok) {
+    return {
+      sharedCanvas: { ...shared, downloadable: false, reason: download.reason },
+      imported: null,
+      warnings: [],
+    }
+  }
+  try {
+    const imported = await importCanvas(ctx, {
+      bytes: download.bytes,
+      prNumber,
+      currentHeadSha: pr.headSha,
+    })
+    return { sharedCanvas: { ...shared, downloadable: true }, imported, warnings: imported.warnings }
+  } catch (err) {
+    return {
+      sharedCanvas: { ...shared, downloadable: false, reason: importFailureReason(err) },
+      imported: null,
+      warnings: [err instanceof Error ? err.message : String(err)],
+    }
+  }
+}