@vintasoftware/pr-review-canvas 0.3.0 → 0.5.0

package/src/github/attachments.ts

@@ -1,27 +1,5 @@
-// 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
-}
+import type { AttachmentLink } from '../host/attachments.js'
+import type { HostAttachments } from '../host/host.js'
 
 const FILE_LINK_RE = /https:\/\/github\.com\/user-attachments\/files\/\d+\/([A-Za-z0-9._-]+\.zip)/g
 const ASSET_LINK_RE =
@@ -31,7 +9,7 @@ const ASSET_LINK_RE =
  * 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[] {
+export function findGithubAttachmentLinks(text: string): AttachmentLink[] {
   const links: AttachmentLink[] = []
   const seen = new Set<string>()
   for (const m of text.matchAll(FILE_LINK_RE)) {
@@ -51,238 +29,12 @@ export function findAttachmentLinks(text: string): AttachmentLink[] {
   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 shaPrefix = target.headSha.slice(0, 8)
-  const score = (c: AttachmentCandidate): number =>
-    (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 `matchesHead` are answers about that commit.
+ * github.com answers an attachment request with a redirect to signed object storage, which must
+ * not see the token: the header is for github.com alone.
  */
-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.shaPrefix === pr.headSha.slice(0, 8),
-  }
-  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)],
-    }
-  }
+export const GITHUB_ATTACHMENTS: HostAttachments = {
+  findLinks: findGithubAttachmentLinks,
+  allowedHosts: new Set(['github.com', 'objects.githubusercontent.com']),
+  authHeader: token => ({ authorization: `token ${token}` }),
 }

package/src/github/canvas-comment.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod'
+import { CANVAS_COMMENT_MARKER } from '../canvas/comment.js'
+import type { Repo } from '../contract/review-artifact.js'
+import { fetchAllPages, type HostClient } from '../host/client.js'
+import { mapIssueComment } from './comments.js'
+
+export async function shareGithubCanvas(
+  client: HostClient,
+  repo: Repo,
+  number: number,
+  body: string
+): Promise<string> {
+  const user = z.object({ login: z.string() }).parse(await client.api('user'))
+  const base = `repos/${repo.owner}/${repo.name}`
+  const comments = (await fetchAllPages(client, `${base}/issues/${number}/comments`)).map(mapIssueComment)
+  const existing = comments.find(c => c.author === user.login && c.body.includes(CANVAS_COMMENT_MARKER))
+  const response =
+    existing === undefined
+      ? await client.post(`${base}/issues/${number}/comments`, { body })
+      : await client.post(`${base}/issues/comments/${existing.id}`, { body }, 'PATCH')
+  return mapIssueComment(response).url
+}

package/src/github/capabilities.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod'
 import type { Capabilities } from '../contract/api.js'
 import type { Repo } from '../contract/review-artifact.js'
-import type { GhResponse, GitHubClient } from './gh.js'
+import type { CliResponse, HostClient } from '../host/client.js'
 
 const UserSchema = z.object({ login: z.string() })
 const RepoBodySchema = z.object({
@@ -9,24 +9,14 @@ const RepoBodySchema = z.object({
   permissions: z.object({ pull: z.boolean().optional(), push: z.boolean().optional() }).optional(),
 })
 
-/** What a page assumes before the probe answers: posting is tried and GitHub decides. */
-export const UNKNOWN_CAPABILITIES: Capabilities = {
-  canComment: 'unknown',
-  tokenKind: 'unprobed',
-  login: null,
-}
-
 export const SCOPE_HINT = 'gh auth refresh -h github.com -s repo'
 
-/** How long a probe answer is reused. A new token needs `?refresh=1` or ten minutes. */
-export const CAPABILITY_TTL_MS = 10 * 60 * 1000
-
 /**
  * Whether this login may post on this repository, from the token's scopes and the repository
  * permissions. A token without a scopes header is a fine-grained or app token, whose rights this
  * check cannot read: posting stays enabled and GitHub's own answer decides.
  */
-export function decideCapabilities(login: string | null, response: GhResponse): Capabilities {
+export function decideCapabilities(login: string | null, response: CliResponse): Capabilities {
   const parsed = RepoBodySchema.safeParse(response.body)
   const body = parsed.success ? parsed.data : {}
   const canPull = body.permissions?.pull === true
@@ -67,7 +57,7 @@ export function decideCapabilities(login: string | null, response: GhResponse):
 }
 
 /** The probe itself: who the token belongs to, and what it may do here. */
-export async function probeCapabilities(gh: GitHubClient, repo: Repo): Promise<Capabilities> {
+export async function probeCapabilities(gh: HostClient, repo: Repo): Promise<Capabilities> {
   let login: string | null = null
   try {
     login = UserSchema.parse(await gh.api('user')).login
@@ -86,31 +76,3 @@ export async function probeCapabilities(gh: GitHubClient, repo: Repo): Promise<C
     }
   }
 }
-
-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(
-  gh: GitHubClient,
-  repo: Repo,
-  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 probeCapabilities(gh, repo)
-      cached = { at, value }
-      return value
-    },
-  }
-}

package/src/github/comments.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod'
-import type { CommentsPayload, IssueComment, ReviewComment } from '../contract/comments.js'
+import type { FetchCommentsResult, IssueComment, ReviewComment } from '../contract/comments.js'
 import type { Repo } from '../contract/review-artifact.js'
-import type { GitHubClient } from './gh.js'
+import { fetchAllPages, type HostClient } from '../host/client.js'
 import { fetchResolvedCommentIds } from './threads.js'
 
 const GhReviewCommentSchema = z.object({
@@ -71,33 +71,12 @@ export function mapIssueComment(raw: unknown): IssueComment {
   }
 }
 
-export interface FetchCommentsResult {
-  payload: CommentsPayload
-  warnings: string[]
-}
-
-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(gh: GitHubClient, path: string): Promise<unknown[]> {
-  const out: unknown[] = []
-  for (let page = 1; ; page++) {
-    const batch = z
-      .array(z.unknown())
-      .parse(await gh.api(path, { per_page: String(COMMENTS_PAGE_SIZE), page: String(page) }))
-    out.push(...batch)
-    if (batch.length < COMMENTS_PAGE_SIZE) {
-      return out
-    }
-  }
-}
-
 /**
  * Review comments (on diff lines) and issue comments (PR-level), with the resolved flag from
  * GraphQL. A GraphQL failure degrades to `resolved: false` everywhere plus a warning.
  */
 export async function fetchComments(
-  gh: GitHubClient,
+  gh: HostClient,
   repo: Repo,
   number: number,
   headSha: string,

package/src/github/post-comment.ts

@@ -1,46 +1,13 @@
 import type { PostCommentInput, PostCommentResult } from '../contract/comments.js'
-import type { FileEntry, Repo, Side } from '../contract/review-artifact.js'
-import { hunkForLine } from '../git/patch-lines.js'
+import type { Repo, Side } from '../contract/review-artifact.js'
 import { mapIssueComment, mapReviewComment } from './comments.js'
-import type { GitHubClient } from './gh.js'
+import type { HostClient } from '../host/client.js'
 
 /** GitHub names the two sides of a diff LEFT and RIGHT. */
 export function ghSide(side: Side): 'LEFT' | 'RIGHT' {
   return side === 'old' ? 'LEFT' : 'RIGHT'
 }
 
-export interface InlineTarget {
-  path: string
-  line: number
-  side: Side
-  startLine?: number | undefined
-}
-
-/**
- * Whether GitHub will accept a comment on these lines: the file is in the diff, and the whole
- * range sits inside one hunk on that side. Returns the reason when it will not, so the route can
- * refuse before the request leaves the machine.
- */
-export function checkInlineTarget(files: ReadonlyArray<FileEntry>, target: InlineTarget): string | null {
-  const file = files.find(f => f.path === target.path)
-  if (file === undefined) {
-    return `${target.path} is not in the diff`
-  }
-  const hunk = hunkForLine(file.hunks, target.side, target.line)
-  if (hunk === null) {
-    return `${target.path}:${target.line} (${target.side}) is not in the diff`
-  }
-  if (target.startLine !== undefined) {
-    if (target.startLine > target.line) {
-      return `the first line of the range must come before ${target.line}`
-    }
-    if (hunkForLine(file.hunks, target.side, target.startLine) !== hunk) {
-      return `${target.path}:${target.startLine}-${target.line} (${target.side}) spans more than one hunk`
-    }
-  }
-  return null
-}
-
 /** The fields GitHub reads for a comment on a diff line. */
 interface InlineCommentBody {
   body: string
@@ -92,7 +59,7 @@ export function commentRequest(
 
 /** Posts one comment and maps GitHub's answer into the shape the page already renders. */
 export async function postComment(
-  gh: GitHubClient,
+  gh: HostClient,
   repo: Repo,
   number: number,
   headSha: string,

package/src/github/post-review.ts

@@ -1,23 +1,11 @@
 import { z } from 'zod'
-import type { ReviewSummary } from './../contract/api.js'
+import type { PendingComment } from '../contract/pending.js'
+import type { ReviewEvent } from '../contract/reviews.js'
+import type { PostedReview } from '../host/host.js'
 import type { Repo } from '../contract/review-artifact.js'
-import type { GitHubClient } from './gh.js'
-
-export const REVIEW_EVENTS = ['APPROVE', 'REQUEST_CHANGES'] as const
-export const ReviewEventSchema = z.enum(REVIEW_EVENTS)
-export type ReviewEvent = (typeof REVIEW_EVENTS)[number]
-
-export const PostReviewInputSchema = z.object({
-  event: ReviewEventSchema,
-  /** The dialog sends the body the user read, edited or not. */
-  body: z.string().min(1).max(65536).optional(),
-  /** The commit the dialog named. The server refuses the review when the head moved on. */
-  headSha: z
-    .string()
-    .regex(/^[0-9a-f]{40}$/)
-    .optional(),
-})
-export type PostReviewInput = z.infer<typeof PostReviewInputSchema>
+import { fetchAllPages, type HostClient } from '../host/client.js'
+import { mapReviewComment } from './comments.js'
+import { ghSide } from './post-comment.js'
 
 const GhReviewSchema = z.object({
   id: z.number().int(),
@@ -26,19 +14,72 @@ const GhReviewSchema = z.object({
   submitted_at: z.string().nullable().optional(),
 })
 
-/** Posts the review. GitHub decides what the event means; the tool only fills the body and sha. */
+/** One entry of the `comments` array GitHub reads when a review is created with its comments. */
+interface GhReviewComment {
+  path: string
+  body: string
+  line: number
+  side: 'LEFT' | 'RIGHT'
+  start_line?: number
+  start_side?: 'LEFT' | 'RIGHT'
+}
+
+/**
+ * The pending comments as GitHub's review payload names them. A range is sent only when it covers
+ * more than the anchor line, because GitHub rejects a start_line equal to line.
+ */
+export function reviewComments(pending: ReadonlyArray<PendingComment>): GhReviewComment[] {
+  return pending.map(p => ({
+    path: p.path,
+    body: p.body,
+    line: p.line,
+    side: ghSide(p.side),
+    ...(p.startLine !== undefined && p.startLine !== p.line
+      ? { start_line: p.startLine, start_side: ghSide(p.side) }
+      : {}),
+  }))
+}
+
+/**
+ * Posts the review. GitHub decides what the event means; the tool only fills the body, the sha,
+ * and the comments the reviewer had waiting, which land as part of the same review.
+ */
 export async function postReview(
-  gh: GitHubClient,
+  gh: HostClient,
   repo: Repo,
   number: number,
   headSha: string,
-  input: { event: ReviewEvent; body: string }
-): Promise<ReviewSummary> {
+  input: { event: ReviewEvent; body: string; comments?: ReadonlyArray<PendingComment> }
+): Promise<PostedReview> {
+  const comments = input.comments ?? []
   const raw = await gh.post(`repos/${repo.owner}/${repo.name}/pulls/${number}/reviews`, {
     event: input.event,
     body: input.body,
     commit_id: headSha,
+    ...(comments.length === 0 ? {} : { comments: reviewComments(comments) }),
   })
   const r = GhReviewSchema.parse(raw)
-  return { id: r.id, state: r.state, url: r.html_url, submittedAt: r.submitted_at ?? null }
+  const posted: PostedReview = {
+    id: r.id,
+    state: r.state,
+    url: r.html_url,
+    submittedAt: r.submitted_at ?? null,
+    comments: [],
+    warnings: [],
+  }
+  if (comments.length > 0) {
+    try {
+      const rawComments = await fetchAllPages(
+        gh,
+        `repos/${repo.owner}/${repo.name}/pulls/${number}/reviews/${r.id}/comments`
+      )
+      posted.comments = rawComments.map(c => mapReviewComment(c, new Set()))
+    } catch (err) {
+      // The write succeeded. A failed read must not invite submitting the same review again.
+      posted.warnings.push(
+        `Review posted, but its comments could not be loaded: ${err instanceof Error ? err.message : String(err)}. Refresh to see them.`
+      )
+    }
+  }
+  return posted
 }