@vintasoftware/pr-review-canvas 0.3.0 → 0.5.0

package/src/github/pr.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod'
-import type { Pr, Repo } from '../contract/review-artifact.js'
-import type { Git } from '../git/git.js'
-import { GitHubApiError, type GitHubClient } from './gh.js'
+import { PrNotFoundError, type PrMeta } from '../host/pr.js'
+import type { Repo } from '../contract/review-artifact.js'
+import { type HostClient, HostCliError } from '../host/client.js'
 
 /** The subset of GitHub's pull request object the tool reads. */
 const GhPullSchema = z.object({
@@ -22,35 +22,6 @@ const GhPullSchema = z.object({
   head: z.object({ ref: z.string(), sha: z.string() }),
 })
 
-export class PrNotFoundError extends Error {
-  readonly number: number
-
-  constructor(number: number) {
-    super(`pull request #${number} not found`)
-    this.name = 'PrNotFoundError'
-    this.number = number
-  }
-}
-
-export interface PrMeta {
-  number: number
-  title: string
-  body: string
-  author: string
-  url: string
-  state: string
-  draft: boolean
-  updatedAt: string
-  baseRef: string
-  headRef: string
-  headSha: string
-  /** The commit that merged the PR into its base, once merged. */
-  mergeCommitSha: string | null
-  additions: number
-  deletions: number
-  changedFiles: number
-}
-
 export function mapPull(raw: unknown): PrMeta {
   const p = GhPullSchema.parse(raw)
   return {
@@ -72,65 +43,13 @@ export function mapPull(raw: unknown): PrMeta {
   }
 }
 
-export async function fetchPrMeta(gh: GitHubClient, repo: Repo, number: number): Promise<PrMeta> {
+export async function fetchPrMeta(client: HostClient, repo: Repo, number: number): Promise<PrMeta> {
   try {
-    return mapPull(await gh.api(`repos/${repo.owner}/${repo.name}/pulls/${number}`))
+    return mapPull(await client.api(`repos/${repo.owner}/${repo.name}/pulls/${number}`))
   } catch (err) {
-    if (err instanceof GitHubApiError && err.notFound) {
+    if (err instanceof HostCliError && err.notFound) {
       throw new PrNotFoundError(number)
     }
     throw err
   }
 }
-
-export function prHeadRef(number: number): string {
-  return `refs/pr/${number}/head`
-}
-
-export function prBaseRef(number: number): string {
-  return `refs/pr/${number}/base`
-}
-
-/**
- * Fetches the PR head and base into local refs and resolves the two commits the diff needs.
- * The refs are the same ones the prior-art skill used, so an existing clone keeps working.
- *
- * A merged PR is diffed against the base as it was at merge time: the merge commit's first
- * parent (a merge commit, a squash, or the last rebased commit all sit on the base branch, so
- * it is local once the base was fetched). Today's base tip would contain the PR and give an
- * empty diff.
- */
-export async function fetchPrRefs(
-  git: Git,
-  meta: PrMeta
-): Promise<{ headSha: string; mergeBaseSha: string }> {
-  await git.fetch('origin', [
-    `+pull/${meta.number}/head:${prHeadRef(meta.number)}`,
-    `+refs/heads/${meta.baseRef}:${prBaseRef(meta.number)}`,
-  ])
-  const headSha = await git.revParse(prHeadRef(meta.number))
-  const base = meta.mergeCommitSha === null ? prBaseRef(meta.number) : `${meta.mergeCommitSha}^1`
-  const mergeBaseSha = await git.mergeBase(base, headSha)
-  return { headSha, mergeBaseSha }
-}
-
-export function toPr(meta: PrMeta, repo: Repo, shas: { headSha: string; mergeBaseSha: string }): Pr {
-  return {
-    number: meta.number,
-    title: meta.title,
-    body: meta.body,
-    author: meta.author,
-    url: meta.url,
-    state: meta.state,
-    draft: meta.draft,
-    updatedAt: meta.updatedAt,
-    baseRef: meta.baseRef,
-    headRef: meta.headRef,
-    headSha: shas.headSha,
-    mergeBaseSha: shas.mergeBaseSha,
-    additions: meta.additions,
-    deletions: meta.deletions,
-    changedFiles: meta.changedFiles,
-    repo,
-  }
-}

package/src/github/threads.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
 import type { Repo } from '../contract/review-artifact.js'
-import type { GitHubClient } from './gh.js'
+import type { HostClient } from '../host/client.js'
 
 const ThreadsPageSchema = z.object({
   repository: z.object({
@@ -34,7 +34,7 @@ export const THREADS_QUERY = `query($owner: String!, $name: String!, $number: In
  * so this one GraphQL query is joined to the REST comments by id.
  */
 export async function fetchResolvedCommentIds(
-  gh: GitHubClient,
+  gh: HostClient,
   repo: Repo,
   number: number
 ): Promise<Set<number>> {

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