@vintasoftware/pr-review-canvas 0.3.0 → 0.5.0

package/src/gitlab/post-review.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod'
+import type { PostedReview } from '../host/host.js'
+import type { PendingComment } from '../contract/pending.js'
+import type { Repo } from '../contract/review-artifact.js'
+import type { ReviewEvent } from '../contract/reviews.js'
+import type { HostClient } from '../host/client.js'
+import type { Derived } from '../store/derived-store.js'
+import { publishGitlabDrafts } from './publish-drafts.js'
+import { gitlabMrUrl, gitlabNoteUrl, gitlabProjectApi } from './project.js'
+
+const GlNoteSchema = z.object({
+  id: z.number().int(),
+  created_at: z.string().optional(),
+})
+
+const GlMrSchema = z.object({
+  id: z.number().int().optional(),
+  iid: z.number().int().optional(),
+  web_url: z.string().optional(),
+})
+
+/**
+ * GitLab has no GitHub-style review event. Approve calls the approvals API; request-changes and a
+ * comment-only review post the review body as an MR note so the text still lands on the merge
+ * request. Pending comments and the summary publish together through the Draft Notes API.
+ */
+export async function postGitlabReview(
+  client: HostClient,
+  repo: Repo,
+  number: number,
+  headSha: string,
+  input: { event: ReviewEvent; body: string; comments?: ReadonlyArray<PendingComment> },
+  webBase: string,
+  diff: Derived = { files: [], patches: {} }
+): Promise<PostedReview> {
+  const base = `${gitlabProjectApi(repo)}/merge_requests/${number}`
+  const mrUrl = gitlabMrUrl(webBase, repo, number)
+  const batched = (input.comments?.length ?? 0) > 0
+  const { comments, warnings } = batched
+    ? await publishGitlabDrafts(client, repo, number, headSha, input, webBase, diff)
+    : { comments: [], warnings: [] }
+  if (input.event === 'APPROVE') {
+    if (!batched && input.body.trim() !== '') {
+      await client.post(`${base}/notes`, { body: input.body })
+    }
+    let raw: unknown
+    try {
+      raw = await client.post(`${base}/approve`, { sha: headSha })
+    } catch (error) {
+      if (!batched) throw error
+      return {
+        comments,
+        warnings: [
+          ...warnings,
+          'Comments published, but approval failed. Approve the merge request in GitLab.',
+        ],
+        id: number,
+        state: 'COMMENTED',
+        url: mrUrl,
+        submittedAt: new Date().toISOString(),
+      }
+    }
+    const mr = GlMrSchema.safeParse(raw).data ?? {}
+    return {
+      comments,
+      warnings,
+      id: mr.id ?? mr.iid ?? number,
+      state: 'APPROVED',
+      url: mr.web_url ?? mrUrl,
+      submittedAt: new Date().toISOString(),
+    }
+  }
+  if (batched) {
+    return {
+      comments,
+      warnings,
+      id: number,
+      state: input.event === 'COMMENT' ? 'COMMENTED' : 'CHANGES_REQUESTED',
+      url: mrUrl,
+      submittedAt: new Date().toISOString(),
+    }
+  }
+  const raw = await client.post(`${base}/notes`, { body: input.body })
+  const note = GlNoteSchema.parse(raw)
+  return {
+    comments,
+    warnings: [],
+    id: note.id,
+    state: input.event === 'COMMENT' ? 'COMMENTED' : 'CHANGES_REQUESTED',
+    url: gitlabNoteUrl(webBase, repo, number, note.id),
+    submittedAt: note.created_at ?? new Date().toISOString(),
+  }
+}

package/src/gitlab/project.ts

@@ -0,0 +1,13 @@
+import type { Repo } from '../contract/review-artifact.js'
+
+export function gitlabProjectApi(repo: Repo): string {
+  return `projects/${encodeURIComponent(`${repo.owner}/${repo.name}`)}`
+}
+
+export function gitlabMrUrl(webBase: string, repo: Repo, iid: number): string {
+  return `${webBase}/${repo.owner}/${repo.name}/-/merge_requests/${iid}`
+}
+
+export function gitlabNoteUrl(webBase: string, repo: Repo, iid: number, noteId: number): string {
+  return `${gitlabMrUrl(webBase, repo, iid)}#note_${noteId}`
+}

package/src/gitlab/publish-drafts.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod'
+import type { PendingComment } from '../contract/pending.js'
+import type { Repo } from '../contract/review-artifact.js'
+import type { HostClient } from '../host/client.js'
+import type { Derived } from '../store/derived-store.js'
+import { fetchGitlabComments } from './comments.js'
+import { fetchMrDiffRefs } from './mr.js'
+import { inlinePosition } from './post-comment.js'
+import { gitlabProjectApi } from './project.js'
+
+const DraftSchema = z.object({ id: z.number().int() })
+
+/** Stage this submission privately, then publish it as one GitLab review. */
+export async function publishGitlabDrafts(
+  client: HostClient,
+  repo: Repo,
+  number: number,
+  headSha: string,
+  input: { body: string; comments?: ReadonlyArray<PendingComment> },
+  webBase: string,
+  diff: Derived
+) {
+  const base = `${gitlabProjectApi(repo)}/merge_requests/${number}/draft_notes`
+  const list = async () => z.array(DraftSchema).parse(await client.api(base))
+  if ((await list()).length > 0) {
+    throw new Error('Finish or discard your pending review in GitLab before submitting from the canvas.')
+  }
+  const refs = await fetchMrDiffRefs(client, repo, number)
+  if (refs.head_sha !== headSha) throw new Error('The merge request changed. Refresh before submitting.')
+  const notes: Array<{ note: string; position?: Record<string, unknown> }> = (input.comments ?? []).map(
+    p => ({
+      note: p.body,
+      position: inlinePosition(refs, { ...p, kind: 'inline' }, diff),
+    })
+  )
+  if (input.body.trim() !== '') notes.push({ note: input.body })
+  const fetchComments = () => fetchGitlabComments(client, repo, number, headSha, () => new Date(), webBase)
+  const before = new Set((await fetchComments()).payload.reviewComments.map(c => c.id))
+  const staged: number[] = []
+  try {
+    for (const note of notes) staged.push(DraftSchema.parse(await client.post(base, note)).id)
+    const current = await list()
+    if (current.length !== staged.length || current.some(d => !staged.includes(d.id))) {
+      throw new Error(
+        'Your pending review changed in GitLab. Finish it there before submitting from the canvas.'
+      )
+    }
+    await client.post(`${base}/bulk_publish`, {})
+  } catch (error) {
+    // Delete only drafts created by this attempt; local copies remain available for retry.
+    const cleanup = await Promise.allSettled(staged.map(id => client.post(`${base}/${id}`, {}, 'DELETE')))
+    if (cleanup.some(result => result.status === 'rejected')) {
+      throw new Error(
+        'Submission failed and some staged drafts remain in GitLab. Inspect your pending review there before retrying.',
+        { cause: error }
+      )
+    }
+    throw error
+  }
+  try {
+    const { payload } = await fetchComments()
+    return { comments: payload.reviewComments.filter(c => !before.has(c.id)), warnings: [] as string[] }
+  } catch {
+    return {
+      comments: [],
+      warnings: ['Review published, but its comments could not be refreshed. Reload to see them.'],
+    }
+  }
+}

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
+    },
+  }
+}