@vintasoftware/pr-review-canvas 0.3.0 → 0.4.0

package/src/gitlab/attachments.ts

@@ -0,0 +1,40 @@
+import type { Repo } from '../contract/review-artifact.js'
+import type { HostAttachments } from '../host/host.js'
+
+const MARKDOWN_LINK_RE = /\[([A-Za-z0-9._-]+\.zip)\]\(([^)\s]+)\)/g
+const UPLOAD_URL_RE = /https?:\/\/[^\s)]+\/uploads\/[A-Za-z0-9/_-]+\/([A-Za-z0-9._-]+\.zip)/gi
+const UPLOAD_PATH_RE = /(?:^|[\s(])(\/uploads\/[A-Za-z0-9/_-]+\/([A-Za-z0-9._-]+\.zip))/g
+
+/**
+ * Zip links in GitLab markdown: `[name.zip](url)`, a project-relative `/uploads/.../name.zip`
+ * path as the editor inserts it, or a full URL on this instance. The instance serves its uploads
+ * itself, so that one hostname is the whole allow list and the token goes in a Bearer header.
+ */
+export function gitlabAttachments(hostname: string, webBase: string): HostAttachments {
+  const resolve = (raw: string, repo: Repo): string | null => {
+    const projectBase = `${webBase}/${repo.owner}/${repo.name}`
+    try {
+      const url = new URL(raw.startsWith('/uploads/') ? `${projectBase}${raw}` : raw, `${projectBase}/`)
+      return url.protocol === 'https:' && url.host === hostname ? url.toString() : null
+    } catch {
+      return null
+    }
+  }
+  return {
+    findLinks(text, repo) {
+      const found = new Map<string, string>()
+      const add = (href: string | undefined, name: string | undefined): void => {
+        const url = href === undefined || name === undefined ? null : resolve(href, repo)
+        if (url !== null && !found.has(url)) {
+          found.set(url, name as string)
+        }
+      }
+      for (const m of text.matchAll(MARKDOWN_LINK_RE)) add(m[2], m[1])
+      for (const m of text.matchAll(UPLOAD_URL_RE)) add(m[0], m[1])
+      for (const m of text.matchAll(UPLOAD_PATH_RE)) add(m[1], m[2])
+      return [...found].map(([url, name]) => ({ url, name }))
+    },
+    allowedHosts: new Set([hostname]),
+    authHeader: token => ({ authorization: `Bearer ${token}` }),
+  }
+}

package/src/gitlab/canvas-comment.ts

@@ -0,0 +1,26 @@
+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 { GlNoteSchema } from './comments.js'
+import { gitlabNoteUrl, gitlabProjectApi } from './project.js'
+
+export async function shareGitlabCanvas(
+  client: HostClient,
+  repo: Repo,
+  number: number,
+  body: string,
+  webBase: string
+): Promise<string> {
+  const user = z.object({ username: z.string() }).parse(await client.api('user'))
+  const base = `${gitlabProjectApi(repo)}/merge_requests/${number}/notes`
+  const notes = (await fetchAllPages(client, base)).map(raw => GlNoteSchema.parse(raw))
+  const existing = notes.find(
+    n => n.author?.username === user.username && n.body?.includes(CANVAS_COMMENT_MARKER)
+  )
+  const response =
+    existing === undefined
+      ? await client.post(base, { body })
+      : await client.post(`${base}/${existing.id}`, { body }, 'PUT')
+  return gitlabNoteUrl(webBase, repo, number, GlNoteSchema.parse(response).id)
+}

package/src/gitlab/capabilities.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod'
+import type { Capabilities } from '../contract/api.js'
+import type { Repo } from '../contract/review-artifact.js'
+import type { HostClient } from '../host/client.js'
+import { gitlabProjectApi } from './project.js'
+
+const UserSchema = z.object({ username: z.string() })
+const AccessSchema = z.object({ access_level: z.number().int() }).nullable().optional()
+const ProjectSchema = z.object({
+  permissions: z.object({ project_access: AccessSchema, group_access: AccessSchema }).optional(),
+})
+
+/** Reporter (20) and above can comment on merge requests. */
+export const GITLAB_COMMENT_ACCESS_LEVEL = 20
+
+/**
+ * Whether this login may post on this project, from the access level the project object reports
+ * for the token. A token that gets no permissions block is one this check cannot read: posting
+ * stays enabled and GitLab's own answer decides.
+ */
+export function decideGitlabCapabilities(login: string | null, projectRaw: unknown): Capabilities {
+  const permissions = ProjectSchema.safeParse(projectRaw).data?.permissions
+  if (permissions === undefined) {
+    return {
+      canComment: 'unknown',
+      tokenKind: 'glab',
+      login,
+      reason: 'this GitLab token does not report project permissions, so posting is tried and GitLab decides',
+    }
+  }
+  const level = Math.max(
+    permissions.project_access?.access_level ?? 0,
+    permissions.group_access?.access_level ?? 0
+  )
+  if (level < GITLAB_COMMENT_ACCESS_LEVEL) {
+    return {
+      canComment: false,
+      tokenKind: 'glab',
+      login,
+      reason: 'this login cannot comment on merge requests in this project',
+      hint: 'ask for Reporter access or higher',
+    }
+  }
+  return { canComment: true, tokenKind: 'glab', login }
+}
+
+/** The probe itself: who the token belongs to, and what it may do here. */
+export async function probeGitlabCapabilities(client: HostClient, repo: Repo): Promise<Capabilities> {
+  const login = await client
+    .api('user')
+    .then(raw => UserSchema.parse(raw).username)
+    .catch(() => null)
+  try {
+    return decideGitlabCapabilities(login, await client.api(gitlabProjectApi(repo)))
+  } catch (err) {
+    return {
+      canComment: false,
+      tokenKind: 'unknown',
+      login,
+      reason: err instanceof Error ? err.message : String(err),
+      hint: 'run `glab auth status` and log in again',
+    }
+  }
+}

package/src/gitlab/comments.ts

@@ -0,0 +1,164 @@
+import { z } from 'zod'
+import type { IssueComment, ReviewComment } from '../contract/comments.js'
+import type { Repo } from '../contract/review-artifact.js'
+import type { FetchCommentsResult } from '../contract/comments.js'
+import { fetchAllPages, type HostClient } from '../host/client.js'
+import { gitlabNoteUrl, gitlabProjectApi } from './project.js'
+
+const GlPositionSchema = z.object({
+  new_path: z.string().nullable().optional(),
+  old_path: z.string().nullable().optional(),
+  new_line: z.number().int().nullable().optional(),
+  old_line: z.number().int().nullable().optional(),
+  head_sha: z.string().optional(),
+  line_range: z
+    .object({
+      start: z
+        .object({
+          new_line: z.number().int().nullable().optional(),
+          old_line: z.number().int().nullable().optional(),
+        })
+        .optional(),
+    })
+    .nullable()
+    .optional(),
+})
+
+/** The subset of a GitLab note the tool reads. A note on a diff line carries a `position`. */
+export const GlNoteSchema = z.object({
+  id: z.number().int(),
+  body: z.string().nullable().optional(),
+  system: z.boolean().optional(),
+  author: z.object({ username: z.string(), avatar_url: z.string().optional() }).nullable().optional(),
+  created_at: z.string(),
+  updated_at: z.string().optional(),
+  resolved: z.boolean().optional(),
+  position: GlPositionSchema.nullable().optional(),
+})
+type GlNote = z.infer<typeof GlNoteSchema>
+type GlPosition = z.infer<typeof GlPositionSchema>
+
+const GlDiscussionSchema = z.object({ id: z.string(), notes: z.array(GlNoteSchema) })
+
+function isDiffNote(note: GlNote): boolean {
+  return Boolean(note.position?.new_path || note.position?.old_path)
+}
+
+/** Which side and line the note sits on, and where a range starts when it spans more than one line. */
+function sideAndLine(
+  pos: GlPosition
+): Pick<ReviewComment, 'side' | 'line' | 'originalLine'> & { startLine?: number } {
+  const side = pos.new_line !== null && pos.new_line !== undefined ? 'new' : 'old'
+  const line = (side === 'new' ? pos.new_line : pos.old_line) ?? null
+  const start = pos.line_range?.start
+  const startLine = (side === 'new' ? start?.new_line : start?.old_line) ?? null
+  return {
+    side,
+    line,
+    originalLine: pos.old_line ?? pos.new_line ?? null,
+    ...(startLine !== null && startLine !== line ? { startLine } : {}),
+  }
+}
+
+export interface NoteContext {
+  webBase: string
+  repo: Repo
+  iid: number
+  headSha: string
+  inReplyToId?: number
+}
+
+export function mapGitLabReviewComment(note: GlNote, ctx: NoteContext): ReviewComment {
+  const pos = note.position ?? null
+  const loc = pos === null ? { side: 'new' as const, line: null, originalLine: null } : sideAndLine(pos)
+  const comment: ReviewComment = {
+    ...mapGitLabIssueComment(note, ctx),
+    path: pos?.new_path || pos?.old_path || '',
+    line: loc.line,
+    originalLine: loc.originalLine,
+    side: loc.side,
+    // GitLab keeps the note's position on the head it was made for; a note whose head is not the
+    // current one, or that lost its line, is about code the diff no longer shows.
+    outdated: loc.line === null || (pos?.head_sha !== undefined && pos.head_sha !== ctx.headSha),
+    commitId: pos?.head_sha ?? ctx.headSha,
+    resolved: note.resolved === true,
+  }
+  if (loc.startLine !== undefined) {
+    comment.startLine = loc.startLine
+  }
+  if (ctx.inReplyToId !== undefined) {
+    comment.inReplyToId = ctx.inReplyToId
+  }
+  return comment
+}
+
+export function mapGitLabIssueComment(
+  note: GlNote,
+  ctx: Pick<NoteContext, 'webBase' | 'repo' | 'iid'>
+): IssueComment {
+  return {
+    id: note.id,
+    author: note.author?.username ?? 'ghost',
+    ...(note.author?.avatar_url ? { avatarUrl: note.author.avatar_url } : {}),
+    body: note.body ?? '',
+    createdAt: note.created_at,
+    updatedAt: note.updated_at ?? note.created_at,
+    url: gitlabNoteUrl(ctx.webBase, ctx.repo, ctx.iid, note.id),
+  }
+}
+
+/** Every discussion of the merge request that the tool can read; anything else GitLab lists is skipped. */
+async function fetchDiscussions(client: HostClient, repo: Repo, number: number) {
+  const raw = await fetchAllPages(client, `${gitlabProjectApi(repo)}/merge_requests/${number}/discussions`)
+  return raw.flatMap(item => {
+    const parsed = GlDiscussionSchema.safeParse(item)
+    return parsed.success ? [parsed.data] : []
+  })
+}
+
+/**
+ * GitLab has one list of discussions; each is a thread on a diff line or a thread of merge request
+ * notes. The former become review comments with the thread's first note as the parent, the latter
+ * issue comments. System notes (assigned, pushed) are not comments.
+ */
+export async function fetchGitlabComments(
+  client: HostClient,
+  repo: Repo,
+  number: number,
+  headSha: string,
+  now: () => Date,
+  webBase: string
+): Promise<FetchCommentsResult> {
+  const reviewComments: ReviewComment[] = []
+  const issueComments: IssueComment[] = []
+  const ctx: NoteContext = { webBase, repo, iid: number, headSha }
+  for (const discussion of await fetchDiscussions(client, repo, number)) {
+    const [first, ...replies] = discussion.notes.filter(n => n.system !== true)
+    if (first === undefined) {
+      continue
+    }
+    if (isDiffNote(first)) {
+      reviewComments.push(
+        mapGitLabReviewComment(first, ctx),
+        ...replies.map(note => mapGitLabReviewComment(note, { ...ctx, inReplyToId: first.id }))
+      )
+    } else {
+      issueComments.push(...[first, ...replies].map(note => mapGitLabIssueComment(note, ctx)))
+    }
+  }
+  return {
+    payload: { fetchedAt: now().toISOString(), headSha, reviewComments, issueComments },
+    warnings: [],
+  }
+}
+
+/** Finds the discussion that contains a note, so a reply can be posted to that thread. */
+export async function findDiscussionId(
+  client: HostClient,
+  repo: Repo,
+  number: number,
+  noteId: number
+): Promise<string | null> {
+  const discussions = await fetchDiscussions(client, repo, number)
+  return discussions.find(d => d.notes.some(n => n.id === noteId))?.id ?? null
+}

package/src/gitlab/mr.ts

@@ -0,0 +1,115 @@
+import { z } from 'zod'
+import type { Repo } from '../contract/review-artifact.js'
+import { type PrMeta, PrNotFoundError } from '../host/pr.js'
+import { type HostClient, HostCliError } from '../host/client.js'
+import { gitlabProjectApi } from './project.js'
+
+/** The subset of GitLab's merge request object the tool reads. */
+const GlMergeRequestSchema = z.object({
+  iid: z.number().int(),
+  title: z.string(),
+  description: z.string().nullable(),
+  web_url: z.string(),
+  state: z.enum(['opened', 'closed', 'locked', 'merged']),
+  draft: z.boolean().optional(),
+  updated_at: z.string(),
+  merge_commit_sha: z.string().nullable().optional(),
+  target_branch: z.string(),
+  source_branch: z.string(),
+  sha: z.string(),
+  /** The number of changed files, which REST reports as a string ("7" or "1000+"). */
+  changes_count: z.string().nullable().optional(),
+  author: z.object({ username: z.string() }).nullable(),
+  diff_refs: z
+    .object({ base_sha: z.string(), head_sha: z.string(), start_sha: z.string() })
+    .nullable()
+    .optional(),
+})
+
+/** Line counts live in GraphQL only; REST has the file count. */
+export const MR_STATS_QUERY = `query($path: ID!, $iid: String!) {
+  project(fullPath: $path) {
+    mergeRequest(iid: $iid) {
+      diffStatsSummary { additions deletions }
+    }
+  }
+}`
+
+const DiffStatsSchema = z.object({
+  project: z
+    .object({
+      mergeRequest: z
+        .object({
+          diffStatsSummary: z.object({ additions: z.number().int(), deletions: z.number().int() }).nullable(),
+        })
+        .nullable(),
+    })
+    .nullable(),
+})
+
+/** The three commits GitLab anchors an inline comment to. */
+export type MrDiffRefs = NonNullable<z.infer<typeof GlMergeRequestSchema>['diff_refs']>
+
+const STATES: Record<z.infer<typeof GlMergeRequestSchema>['state'], string> = {
+  opened: 'open',
+  closed: 'closed',
+  locked: 'closed',
+  merged: 'merged',
+}
+
+export function mapMergeRequest(raw: unknown, stats: { additions: number; deletions: number }): PrMeta {
+  const m = GlMergeRequestSchema.parse(raw)
+  return {
+    number: m.iid,
+    title: m.title,
+    body: m.description ?? '',
+    author: m.author?.username ?? 'ghost',
+    url: m.web_url,
+    state: STATES[m.state],
+    draft: m.draft === true,
+    updatedAt: m.updated_at,
+    baseRef: m.target_branch,
+    headRef: m.source_branch,
+    headSha: m.diff_refs?.head_sha ?? m.sha,
+    mergeCommitSha: m.state === 'merged' ? (m.merge_commit_sha ?? null) : null,
+    additions: stats.additions,
+    deletions: stats.deletions,
+    changedFiles: Number.parseInt(m.changes_count ?? '0', 10) || 0,
+  }
+}
+
+async function fetchMr(client: HostClient, repo: Repo, number: number): Promise<unknown> {
+  try {
+    return await client.api(`${gitlabProjectApi(repo)}/merge_requests/${number}`)
+  } catch (err) {
+    if (err instanceof HostCliError && err.notFound) {
+      throw new PrNotFoundError(number)
+    }
+    throw err
+  }
+}
+
+/**
+ * The merge request as a PrMeta. The line counts are a separate GraphQL query; an instance that
+ * refuses it still gets a review, with the header showing +0 −0.
+ */
+export async function fetchMrMeta(client: HostClient, repo: Repo, number: number): Promise<PrMeta> {
+  const [raw, stats] = await Promise.all([
+    fetchMr(client, repo, number),
+    client
+      .graphql(MR_STATS_QUERY, { path: `${repo.owner}/${repo.name}`, iid: String(number) })
+      .then(page => DiffStatsSchema.parse(page).project?.mergeRequest?.diffStatsSummary ?? null)
+      .catch(() => null),
+  ])
+  return mapMergeRequest(raw, stats ?? { additions: 0, deletions: 0 })
+}
+
+/** The refs an inline comment is positioned against, read live so they name the current head. */
+export async function fetchMrDiffRefs(client: HostClient, repo: Repo, number: number): Promise<MrDiffRefs> {
+  const m = GlMergeRequestSchema.parse(await fetchMr(client, repo, number))
+  const refs = m.diff_refs
+  if (refs === undefined || refs === null) {
+    throw new Error(`merge request !${number} reports no diff refs; GitLab may still be computing its diff`)
+  }
+  return refs
+}

package/src/gitlab/post-comment.ts

@@ -0,0 +1,111 @@
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+import type { PostCommentInput, PostCommentResult } from '../contract/comments.js'
+import type { Repo, Side } from '../contract/review-artifact.js'
+import { splitHunks } from '../git/patch-lines.js'
+import type { Derived } from '../store/derived-store.js'
+import type { HostClient } from '../host/client.js'
+import { findDiscussionId, GlNoteSchema, mapGitLabIssueComment, mapGitLabReviewComment } from './comments.js'
+import { fetchMrDiffRefs, type MrDiffRefs } from './mr.js'
+import { gitlabProjectApi } from './project.js'
+
+/** A new discussion comes back as the thread holding its first note. */
+const GlDiscussionSchema = z.object({ notes: z.tuple([GlNoteSchema]).rest(z.unknown()) })
+
+/** Context lines need both coordinates, including offsets introduced by earlier changes. */
+function diffLine(patch: string, side: Side, line: number): { old_line?: number; new_line?: number } {
+  for (const hunk of splitHunks(patch)) {
+    let oldLine = hunk.oldStart
+    let newLine = hunk.newStart
+    for (const text of hunk.lines) {
+      if (![' ', '+', '-'].includes(text[0] ?? '')) continue
+      const point = {
+        ...(text.startsWith('+') ? {} : { old_line: oldLine++ }),
+        ...(text.startsWith('-') ? {} : { new_line: newLine++ }),
+      }
+      if ((side === 'old' ? point.old_line : point.new_line) === line) return point
+    }
+  }
+  throw new Error(`${side}-side line ${line} is not in the patch`)
+}
+
+/** The `position` GitLab anchors an inline comment to. A range names both of its ends by line code. */
+export function inlinePosition(
+  refs: MrDiffRefs,
+  input: Extract<PostCommentInput, { kind: 'inline' }>,
+  diff: Derived
+): Record<string, unknown> {
+  const newPath = input.path
+  const file = diff.files.find(f => f.path === input.path)
+  const patch = file === undefined ? undefined : diff.patches[file.key]
+  if (file === undefined || patch === undefined) {
+    throw new Error(`no diff available for ${input.path}`)
+  }
+  const oldPath = file.oldPath ?? input.path
+  const position: Record<string, unknown> = {
+    ...refs,
+    position_type: 'text',
+    old_path: oldPath,
+    new_path: newPath,
+    ...diffLine(patch, input.side, input.line),
+  }
+  if (input.startLine !== undefined && input.startLine !== input.line) {
+    const hash = createHash('sha1').update(newPath).digest('hex')
+    const endpoint = (line: number) => {
+      const point = diffLine(patch, input.side, line)
+      return {
+        ...point,
+        line_code: `${hash}_${point.old_line ?? ''}_${point.new_line ?? ''}`,
+        type: point.old_line === undefined ? 'new' : 'old',
+      }
+    }
+    position['line_range'] = { start: endpoint(input.startLine), end: endpoint(input.line) }
+  }
+  return position
+}
+
+/**
+ * Posts one comment and maps GitLab's answer into the shape the page already renders. An inline
+ * comment opens a discussion positioned on the live diff refs; a reply joins the discussion that
+ * holds its parent; a review-level comment is a plain note.
+ */
+export async function postGitlabComment(
+  client: HostClient,
+  repo: Repo,
+  number: number,
+  headSha: string,
+  input: PostCommentInput,
+  opts: Derived & { webBase: string }
+): Promise<PostCommentResult> {
+  const base = `${gitlabProjectApi(repo)}/merge_requests/${number}`
+  const mapped = { webBase: opts.webBase, repo, iid: number, headSha }
+  switch (input.kind) {
+    case 'inline': {
+      const refs = await fetchMrDiffRefs(client, repo, number)
+      const raw = await client.post(`${base}/discussions`, {
+        body: input.body,
+        position: inlinePosition(refs, input, opts),
+      })
+      return {
+        kind: 'review',
+        comment: mapGitLabReviewComment(GlDiscussionSchema.parse(raw).notes[0], mapped),
+      }
+    }
+    case 'reply': {
+      const discussionId = await findDiscussionId(client, repo, number, input.inReplyToId)
+      if (discussionId === null) {
+        throw new Error(`no GitLab discussion contains note ${input.inReplyToId}`)
+      }
+      const raw = await client.post(`${base}/discussions/${discussionId}/notes`, { body: input.body })
+      const note = GlNoteSchema.parse(raw)
+      return {
+        kind: 'review',
+        comment: mapGitLabReviewComment(note, { ...mapped, inReplyToId: input.inReplyToId }),
+      }
+    }
+    case 'issue': {
+      const raw = await client.post(`${base}/notes`, { body: input.body })
+      return { kind: 'issue', comment: mapGitLabIssueComment(GlNoteSchema.parse(raw), mapped) }
+    }
+  }
+}

package/src/gitlab/post-review.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod'
+import type { ReviewSummary } from '../contract/api.js'
+import type { Repo } from '../contract/review-artifact.js'
+import type { ReviewEvent } from '../contract/reviews.js'
+import type { HostClient } from '../host/client.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 posts
+ * the review body as an MR note so the text still lands on the merge request.
+ */
+export async function postGitlabReview(
+  client: HostClient,
+  repo: Repo,
+  number: number,
+  headSha: string,
+  input: { event: ReviewEvent; body: string },
+  webBase: string
+): Promise<ReviewSummary> {
+  const base = `${gitlabProjectApi(repo)}/merge_requests/${number}`
+  const mrUrl = gitlabMrUrl(webBase, repo, number)
+  if (input.event === 'APPROVE') {
+    if (input.body.trim() !== '') {
+      await client.post(`${base}/notes`, { body: input.body })
+    }
+    const raw = await client.post(`${base}/approve`, { sha: headSha })
+    const mr = GlMrSchema.safeParse(raw).data ?? {}
+    return {
+      id: mr.id ?? mr.iid ?? number,
+      state: 'APPROVED',
+      url: mr.web_url ?? mrUrl,
+      submittedAt: new Date().toISOString(),
+    }
+  }
+  const raw = await client.post(`${base}/notes`, { body: input.body })
+  const note = GlNoteSchema.parse(raw)
+  return {
+    id: note.id,
+    state: '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}`
+}