@vintasoftware/pr-review-canvas 0.1.0

package/src/github/capabilities.ts

@@ -0,0 +1,112 @@
+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'
+
+const UserSchema = z.object({ login: z.string() })
+const RepoBodySchema = z.object({
+  private: z.boolean().optional(),
+  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 {
+  const parsed = RepoBodySchema.safeParse(response.body)
+  const body = parsed.success ? parsed.data : {}
+  const canPull = body.permissions?.pull === true
+  const isPrivate = body.private !== false
+  const header = response.headers['x-oauth-scopes']
+  if (header === undefined) {
+    return {
+      canComment: 'unknown',
+      tokenKind: 'fine-grained',
+      login,
+      reason: 'this token does not report its scopes, so posting is tried and GitHub decides',
+    }
+  }
+  const scopes = header
+    .split(',')
+    .map(s => s.trim())
+    .filter(s => s !== '')
+  const hasScope = scopes.includes('repo') || (!isPrivate && scopes.includes('public_repo'))
+  if (!hasScope) {
+    return {
+      canComment: false,
+      tokenKind: 'classic',
+      login,
+      reason: `this token has no ${isPrivate ? 'repo' : 'public_repo'} scope`,
+      hint: SCOPE_HINT,
+    }
+  }
+  if (!canPull) {
+    return {
+      canComment: false,
+      tokenKind: 'classic',
+      login,
+      reason: 'this login cannot read the repository',
+      hint: 'ask for access to the repository',
+    }
+  }
+  return { canComment: true, tokenKind: 'classic', login }
+}
+
+/** The probe itself: who the token belongs to, and what it may do here. */
+export async function probeCapabilities(gh: GitHubClient, repo: Repo): Promise<Capabilities> {
+  let login: string | null = null
+  try {
+    login = UserSchema.parse(await gh.api('user')).login
+  } catch {
+    login = null
+  }
+  try {
+    return decideCapabilities(login, await gh.apiWithHeaders(`repos/${repo.owner}/${repo.name}`))
+  } catch (err) {
+    return {
+      canComment: false,
+      tokenKind: 'unknown',
+      login,
+      reason: err instanceof Error ? err.message : String(err),
+      hint: 'run `gh auth status` and log in again',
+    }
+  }
+}
+
+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

@@ -0,0 +1,132 @@
+import { z } from 'zod'
+import type { CommentsPayload, IssueComment, ReviewComment } from '../contract/comments.js'
+import type { Repo } from '../contract/review-artifact.js'
+import type { GitHubClient } from './gh.js'
+import { fetchResolvedCommentIds } from './threads.js'
+
+const GhReviewCommentSchema = z.object({
+  id: z.number().int(),
+  user: z.object({ login: z.string(), avatar_url: z.string().optional() }).nullable(),
+  body: z.string(),
+  path: z.string(),
+  line: z.number().int().nullable().optional(),
+  original_line: z.number().int().nullable().optional(),
+  side: z.enum(['LEFT', 'RIGHT']).nullable().optional(),
+  start_line: z.number().int().nullable().optional(),
+  commit_id: z.string(),
+  in_reply_to_id: z.number().int().optional(),
+  created_at: z.string(),
+  updated_at: z.string().optional(),
+  html_url: z.string(),
+})
+
+const GhIssueCommentSchema = z.object({
+  id: z.number().int(),
+  user: z.object({ login: z.string(), avatar_url: z.string().optional() }).nullable(),
+  body: z.string().nullable(),
+  created_at: z.string(),
+  updated_at: z.string().optional(),
+  html_url: z.string(),
+})
+
+export function mapReviewComment(raw: unknown, resolvedIds: ReadonlySet<number>): ReviewComment {
+  const c = GhReviewCommentSchema.parse(raw)
+  const line = c.line ?? null
+  const out: ReviewComment = {
+    id: c.id,
+    author: c.user?.login ?? 'ghost',
+    ...(c.user?.avatar_url ? { avatarUrl: c.user.avatar_url } : {}),
+    body: c.body,
+    path: c.path,
+    line,
+    originalLine: c.original_line ?? null,
+    side: c.side === 'LEFT' ? 'old' : 'new',
+    // GitHub clears `line` when the commented code is no longer in the diff.
+    outdated: line === null,
+    commitId: c.commit_id,
+    createdAt: c.created_at,
+    updatedAt: c.updated_at ?? c.created_at,
+    url: c.html_url,
+    resolved: resolvedIds.has(c.id),
+  }
+  if (typeof c.start_line === 'number') {
+    out.startLine = c.start_line
+  }
+  if (c.in_reply_to_id !== undefined) {
+    out.inReplyToId = c.in_reply_to_id
+  }
+  return out
+}
+
+export function mapIssueComment(raw: unknown): IssueComment {
+  const c = GhIssueCommentSchema.parse(raw)
+  return {
+    id: c.id,
+    author: c.user?.login ?? 'ghost',
+    ...(c.user?.avatar_url ? { avatarUrl: c.user.avatar_url } : {}),
+    body: c.body ?? '',
+    createdAt: c.created_at,
+    updatedAt: c.updated_at ?? c.created_at,
+    url: c.html_url,
+  }
+}
+
+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,
+  repo: Repo,
+  number: number,
+  headSha: string,
+  now: () => Date
+): Promise<FetchCommentsResult> {
+  const warnings: string[] = []
+  const base = `repos/${repo.owner}/${repo.name}`
+  const [reviewRaw, issueRaw] = await Promise.all([
+    fetchAllPages(gh, `${base}/pulls/${number}/comments`),
+    fetchAllPages(gh, `${base}/issues/${number}/comments`),
+  ])
+  const reviews = (await fetchAllPages(gh, `${base}/pulls/${number}/reviews`)).flatMap(raw => {
+    const review = GhIssueCommentSchema.omit({ created_at: true }).extend({
+      submitted_at: z.string().nullable().optional(), state: z.string(),
+    }).parse(raw)
+    if (!review.submitted_at || review.state === 'PENDING') return []
+    return [{ ...mapIssueComment({ ...review, created_at: review.submitted_at }), state: review.state }]
+  })
+  let resolvedIds: Set<number>
+  try {
+    resolvedIds = await fetchResolvedCommentIds(gh, repo, number)
+  } catch (err) {
+    resolvedIds = new Set()
+    warnings.push(`resolved state unavailable: ${err instanceof Error ? err.message : String(err)}`)
+  }
+  const reviewComments = reviewRaw.map(c => mapReviewComment(c, resolvedIds))
+  const issueComments = issueRaw.map(mapIssueComment)
+  return {
+    payload: { fetchedAt: now().toISOString(), headSha, reviewComments, issueComments, reviews },
+    warnings,
+  }
+}

package/src/github/gh.ts

@@ -0,0 +1,196 @@
+import { execFile } from 'node:child_process'
+
+/**
+ * The GitHub operations the tool needs, all through the `gh` CLI so the user's own login is
+ * used and no token is ever read by this code. Routes receive an implementation through
+ * AppContext; tests use an in-memory fake.
+ */
+export interface GitHubClient {
+  /** `gh api --method GET <path>` with optional query params; returns the parsed JSON body. */
+  api(path: string, params?: Record<string, string>): Promise<unknown>
+  /** `gh api -i --method GET <path>`: the response headers as well as the body. */
+  apiWithHeaders(path: string): Promise<GhResponse>
+  /** `gh api --method POST <path> --input -`; the JSON body goes over stdin, never the command line. */
+  post(path: string, body: unknown): Promise<unknown>
+  /** `gh api graphql`; returns the parsed `data` object. */
+  graphql(query: string, variables: Record<string, string | number>): Promise<unknown>
+  /** `gh auth status`: is the CLI installed and logged in? */
+  authStatus(): Promise<{ installed: boolean; authenticated: boolean; detail: string }>
+  /**
+   * `gh auth token`: 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>
+}
+
+/** One HTTP answer from `gh api -i`: the status, the header names in lower case, and the body. */
+export interface GhResponse {
+  status: number
+  headers: Record<string, string>
+  body: unknown
+}
+
+/**
+ * Splits the output of `gh 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): GhResponse {
+  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 GitHubApiError extends Error {
+  readonly path: string
+  readonly stderr: string
+  readonly exitCode: number
+  /** True when the `gh` binary is not on PATH. */
+  readonly missingBinary: boolean
+
+  constructor(path: string, stderr: string, exitCode: number, missingBinary = false) {
+    super(`gh api ${path} failed (${exitCode}): ${stderr.trim()}`)
+    this.name = 'GitHubApiError'
+    this.path = path
+    this.stderr = stderr
+    this.exitCode = exitCode
+    this.missingBinary = missingBinary
+  }
+  /** `gh api` exits 1 with "HTTP 404" in stderr for a missing resource. */
+  get notFound(): boolean {
+    return /HTTP 404/.test(this.stderr)
+  }
+  get unauthenticated(): boolean {
+    return /HTTP 401|not logged into|gh auth login/i.test(this.stderr)
+  }
+}
+
+interface ExecResult {
+  stdout: string
+  stderr: string
+  code: number
+  missingBinary: boolean
+}
+
+export interface GhExecOptions {
+  binary?: string
+  /** Written to the child's stdin, for `gh api --input -`. */
+  input?: string
+}
+
+export function execGh(args: string[], opts: GhExecOptions = {}): Promise<ExecResult> {
+  return new Promise(resolve => {
+    const child = execFile(
+      opts.binary ?? 'gh',
+      args,
+      { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 },
+      (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 GhExec = typeof execGh
+
+export function createGitHubClient(exec: GhExec = execGh): GitHubClient {
+  return {
+    api: async (path, params = {}) => {
+      // `gh 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}`)
+      }
+      const r = await exec(args)
+      if (r.code !== 0) {
+        throw new GitHubApiError(path, r.missingBinary ? 'gh: command not found' : r.stderr, r.code, r.missingBinary)
+      }
+      return JSON.parse(r.stdout) as unknown
+    },
+    apiWithHeaders: async path => {
+      const r = await exec(['api', '-i', '--method', 'GET', path])
+      if (r.code !== 0) {
+        throw new GitHubApiError(path, r.missingBinary ? 'gh: command not found' : r.stderr, r.code, r.missingBinary)
+      }
+      return parseIncludedResponse(r.stdout)
+    },
+    post: async (path, body) => {
+      // The payload goes over stdin, so no comment text ever appears in an argument list.
+      const r = await exec(['api', '--method', 'POST', path, '--input', '-'], { input: JSON.stringify(body) })
+      if (r.code !== 0) {
+        throw new GitHubApiError(path, r.missingBinary ? 'gh: command not found' : r.stderr, r.code, r.missingBinary)
+      }
+      return JSON.parse(r.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 r = await exec(args)
+      if (r.code !== 0) {
+        throw new GitHubApiError(
+          'graphql',
+          r.missingBinary ? 'gh: command not found' : r.stderr,
+          r.code,
+          r.missingBinary
+        )
+      }
+      const body = JSON.parse(r.stdout) as { data?: unknown; errors?: Array<{ message: string }> }
+      if (body.errors && body.errors.length > 0) {
+        throw new GitHubApiError('graphql', body.errors.map(e => e.message).join('; '), 1)
+      }
+      return body.data
+    },
+    authStatus: async () => {
+      const r = await exec(['auth', 'status'])
+      if (r.missingBinary) {
+        return { installed: false, authenticated: false, detail: 'gh 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(['auth', 'token'])
+      const token = r.stdout.trim()
+      return r.code === 0 && token !== '' ? token : null
+    },
+  }
+}

package/src/github/post-comment.ts

@@ -0,0 +1,104 @@
+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 { mapIssueComment, mapReviewComment } from './comments.js'
+import type { GitHubClient } from './gh.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
+  commit_id: string
+  path: string
+  line: number
+  side: 'LEFT' | 'RIGHT'
+  start_line?: number
+  start_side?: 'LEFT' | 'RIGHT'
+}
+
+export type CommentRequestBody = InlineCommentBody | { body: string }
+
+/** The JSON body of the REST call for one comment, next to the path it goes to. */
+export function commentRequest(
+  repo: Repo,
+  number: number,
+  headSha: string,
+  input: PostCommentInput
+): { path: string; body: CommentRequestBody } {
+  const base = `repos/${repo.owner}/${repo.name}`
+  switch (input.kind) {
+    case 'inline': {
+      // A range is sent only when it covers more than the anchor line; GitHub rejects a
+      // start_line equal to line.
+      const range =
+        input.startLine !== undefined && input.startLine !== input.line
+          ? { start_line: input.startLine, start_side: ghSide(input.side) }
+          : {}
+      const body: InlineCommentBody = {
+        body: input.body,
+        commit_id: headSha,
+        path: input.path,
+        line: input.line,
+        side: ghSide(input.side),
+        ...range,
+      }
+      return { path: `${base}/pulls/${number}/comments`, body }
+    }
+    case 'reply':
+      return { path: `${base}/pulls/${number}/comments/${input.inReplyToId}/replies`, body: { body: input.body } }
+    case 'issue':
+      return { path: `${base}/issues/${number}/comments`, body: { body: input.body } }
+  }
+}
+
+/** Posts one comment and maps GitHub's answer into the shape the page already renders. */
+export async function postComment(
+  gh: GitHubClient,
+  repo: Repo,
+  number: number,
+  headSha: string,
+  input: PostCommentInput
+): Promise<PostCommentResult> {
+  const { path, body } = commentRequest(repo, number, headSha, input)
+  const raw = await gh.post(path, body)
+  if (input.kind === 'issue') {
+    return { kind: 'issue', comment: mapIssueComment(raw) }
+  }
+  return { kind: 'review', comment: mapReviewComment(raw, new Set()) }
+}

package/src/github/post-review.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod'
+import type { ReviewSummary } from './../contract/api.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>
+
+const GhReviewSchema = z.object({
+  id: z.number().int(),
+  state: z.string(),
+  html_url: z.string(),
+  submitted_at: z.string().nullable().optional(),
+})
+
+/** Posts the review. GitHub decides what the event means; the tool only fills the body and sha. */
+export async function postReview(
+  gh: GitHubClient,
+  repo: Repo,
+  number: number,
+  headSha: string,
+  input: { event: ReviewEvent; body: string }
+): Promise<ReviewSummary> {
+  const raw = await gh.post(`repos/${repo.owner}/${repo.name}/pulls/${number}/reviews`, {
+    event: input.event,
+    body: input.body,
+    commit_id: headSha,
+  })
+  const r = GhReviewSchema.parse(raw)
+  return { id: r.id, state: r.state, url: r.html_url, submittedAt: r.submitted_at ?? null }
+}