@vintasoftware/pr-review-canvas 0.2.0 → 0.4.0

package/src/host/attachments.ts

@@ -0,0 +1,293 @@
+// Finding the canvas zip a human attached to the review and downloading it with the host CLI's
+// token. The token is read per request, sent to the forge alone, and never logged or stored.
+import { readCanvasComment } from '../canvas/comment.js'
+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'
+import type { HostAttachments } from './host.js'
+
+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
+}
+
+export interface AttachmentCandidate extends AttachmentLink {
+  bytes?: Uint8Array
+  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,
+  attachments: HostAttachments
+): 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 attachments.findLinks(text, repo)) {
+      const parsed = parseCanvasZipName(link.name, repo)
+      if (parsed !== null) {
+        candidates.push({ ...link, parsed, postedAt, order: order++ })
+      }
+    }
+  }
+  for (const comment of sources.comments.issueComments) {
+    const embedded = readCanvasComment(comment.body)
+    if (embedded === null) continue
+    const parsed = parseCanvasZipName(embedded.name, repo)
+    if (parsed !== null) {
+      candidates.push({ ...embedded, url: comment.url, parsed, postedAt: comment.updatedAt, order: order++ })
+    }
+  }
+  return candidates
+}
+
+/** True when the name names a pull request, and it is not the one being looked at. */
+function namesAnotherPr(c: AttachmentCandidate, prNumber: number): boolean {
+  return c.parsed.prNumber !== undefined && c.parsed.prNumber !== prNumber
+}
+
+/**
+ * The canvas for this head wins, then one exported for this PR, then the one attached last. A name
+ * that carries another pull request's number sorts below all of them: import refuses it, so it may
+ * never take a place in the try budget from an attachment that could be used.
+ */
+export function rankCandidates(
+  candidates: AttachmentCandidate[],
+  target: { headSha: string; prNumber: number }
+): AttachmentCandidate[] {
+  const shaPrefix = target.headSha.slice(0, 8)
+  const score = (c: AttachmentCandidate): number =>
+    namesAnotherPr(c, target.prNumber)
+      ? -1
+      : (c.parsed.shaPrefix === shaPrefix ? 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 `namesHead` 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, hosts: ReadonlySet<string>, base?: string): URL | null {
+  let url: URL
+  try {
+    url = new URL(raw, base)
+  } catch {
+    return null
+  }
+  return url.protocol === 'https:' && hosts.has(url.host) ? url : null
+}
+
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308])
+
+/**
+ * Downloads one attachment. The CLI token goes to the forge alone: a redirect leads to signed
+ * storage, which refuses a request that holds both a signature and a token, and a link that
+ * points at storage from the start is fetched bare for the same reason.
+ */
+export async function downloadAttachment(ctx: AppContext, rawUrl: string): Promise<DownloadResult> {
+  const { hostname, attachments } = ctx.config.host
+  const { allowedHosts, authHeader } = attachments
+  const first = allowedUrl(rawUrl, allowedHosts)
+  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
+  // 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 = url.host === hostname ? { accept, ...authHeader(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') ?? '', allowedHosts, url.toString())
+        if (next === null) {
+          return { ok: false, reason: 'network' }
+        }
+        url = next
+        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'
+  }
+  if (err.code === 'CANVAS_PR_MISMATCH') {
+    return 'pr-mismatch'
+  }
+  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, ctx.config.host.attachments), {
+    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,
+    namesHead: candidate.parsed.shaPrefix === pr.headSha.slice(0, 8),
+  }
+  // A name that carries another pull request's number is a zip attached to the wrong PR. Import
+  // would refuse it anyway, so it is reported without spending a download on it.
+  if (namesAnotherPr(candidate, prNumber)) {
+    return {
+      sharedCanvas: { ...shared, downloadable: false, reason: 'pr-mismatch' },
+      imported: null,
+      warnings: [`${candidate.name} was exported for #${candidate.parsed.prNumber}, not #${prNumber}`],
+    }
+  }
+  const download: DownloadResult =
+    candidate.bytes === undefined
+      ? await downloadAttachment(ctx, candidate.url)
+      : { ok: true, bytes: candidate.bytes }
+  if (!download.ok) {
+    return {
+      sharedCanvas: { ...shared, downloadable: false, reason: download.reason },
+      imported: null,
+      warnings: [],
+    }
+  }
+  try {
+    const imported = await importCanvas(ctx, { bytes: download.bytes, prNumber, currentHead: pr })
+    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)],
+    }
+  }
+}

package/src/host/capabilities.ts

@@ -0,0 +1,38 @@
+import type { Capabilities } from '../contract/api.js'
+
+/** What a page assumes before the probe answers: posting is tried and the host decides. */
+export const UNKNOWN_CAPABILITIES: Capabilities = {
+  canComment: 'unknown',
+  tokenKind: 'unprobed',
+  login: null,
+}
+
+/** How long a probe answer is reused. A new token needs `?refresh=1` or ten minutes. */
+export const CAPABILITY_TTL_MS = 10 * 60 * 1000
+
+export interface CapabilityProbe {
+  get(opts?: { refresh?: boolean }): Promise<Capabilities>
+}
+
+/**
+ * The probe with its cache. One per server process; `refresh` skips the cache after the user
+ * changed their token.
+ */
+export function createCapabilityProbe(
+  probe: () => Promise<Capabilities>,
+  now: () => Date,
+  ttlMs = CAPABILITY_TTL_MS
+): CapabilityProbe {
+  let cached: { at: number; value: Capabilities } | null = null
+  return {
+    get: async (opts = {}) => {
+      const at = now().getTime()
+      if (!opts.refresh && cached !== null && at - cached.at < ttlMs) {
+        return cached.value
+      }
+      const value = await probe()
+      cached = { at, value }
+      return value
+    },
+  }
+}

package/src/host/client.ts

@@ -0,0 +1,245 @@
+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'): 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']
+      return JSON.parse((await run(path, args, JSON.stringify(body))).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
+    }
+  }
+}