@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/code/prreview.ts

@@ -0,0 +1,649 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+import type { CodeEvent, Usage } from "../types.ts"
+import type { Card } from "../card.ts"
+import { adoSettings } from "../cases/ado.ts"
+import { htmlToText, http } from "../cases/http.ts"
+import { privateEnvNames } from "../childEnv.ts"
+import type { AppConfig } from "../config.ts"
+import { sh } from "../mcp/git.ts"
+import { runDirectory } from "../run.ts"
+import { loadSkills } from "../skills/registry.ts"
+import type { Price } from "../usage.ts"
+import { openSession, type AgentSpec, type OpencodeSession } from "./runtime.ts"
+import { prompt } from "../prompts.ts"
+import { domainNotes } from "../domain.ts"
+
+const API = "api-version=7.1"
+/** The diff is shown in the prompt up to this size; the reviewer runs git diff for the rest. */
+const DIFF_CHARS = 60_000
+const ITEM_CHARS = 2_000
+const DESCRIPTION_CHARS = 6_000
+
+export type Platform = "azure_devops" | "github"
+
+/** Where a pull request lives. Azure DevOps: org URL, project, repository name. GitHub: owner/name in `repo`. */
+export type PrRef = { platform: Platform; number: number; org?: string; project?: string; repo?: string }
+
+export type PrInfo = {
+  ref: PrRef
+  url: string
+  title: string
+  description: string
+  author: string
+  state: string
+  draft: boolean
+  sourceBranch: string
+  targetBranch: string
+  /** The commit the review read; posting checks the PR still points at it. */
+  headSha: string
+  /** Work items (Azure DevOps) or issues (GitHub) the PR is linked to. */
+  linked: { id: string; title: string; text?: string }[]
+  /** Azure DevOps: the linked work items' ids. */
+  workItemIds?: number[]
+}
+
+export type Severity = "blocker" | "major" | "minor" | "nit"
+export type PrFinding = { file?: string; line?: number; end_line?: number; severity: Severity; title: string; problem: string; suggestion?: string }
+export type Verdict = "approve" | "approve_with_suggestions" | "request_changes"
+
+export type PrReview = {
+  id: string
+  dir: string
+  repo: string
+  pr: PrInfo
+  base: string
+  files: { path: string; added: number; removed: number }[]
+  verdict: Verdict
+  summary: string
+  findings: PrFinding[]
+  /** Per finding: its line is in the diff, so it can be posted on that line. */
+  inline: boolean[]
+  model: string
+  usage: Usage
+  price?: Price
+  createdAt: string
+  posted?: { at: string; links: string[] }
+}
+
+// ---- Which pull request ----
+
+type Remote = { name: string; url: string; ref: Omit<PrRef, "number"> }
+
+/** The repository a git remote URL points at, for Azure DevOps (https, ssh, visualstudio.com) and GitHub. */
+export function parseRemote(url: string): Omit<PrRef, "number"> | null {
+  const u = url.trim().replace(/\.git$/, "")
+  const gh = /github\.com[/:]([^/]+)\/([^/]+)$/.exec(u)
+  if (gh) return { platform: "github", repo: `${gh[1]}/${gh[2]}` }
+  const ssh = /ssh\.dev\.azure\.com:v3\/([^/]+)\/([^/]+)\/([^/]+)$/.exec(u)
+  if (ssh) return { platform: "azure_devops", org: `https://dev.azure.com/${ssh[1]}`, project: decodeURIComponent(ssh[2]), repo: decodeURIComponent(ssh[3]) }
+  const vs = /^[^@]+@vs-ssh\.visualstudio\.com:v3\/([^/]+)\/([^/]+)\/([^/]+)$/.exec(u)
+  if (vs) return { platform: "azure_devops", org: `https://${vs[1]}.visualstudio.com`, project: decodeURIComponent(vs[2]), repo: decodeURIComponent(vs[3]) }
+  const git = /^(https?:\/\/)(?:[^@/]+@)?(.+)\/([^/]+)\/_git\/([^/?#]+)/.exec(u)
+  if (git) return { platform: "azure_devops", org: `${git[1]}${git[2]}`, project: decodeURIComponent(git[3]), repo: decodeURIComponent(git[4]) }
+  return null
+}
+
+/**
+ * A pull request link (Azure DevOps .../_git/<repo>/pullrequest/12, GitHub .../pull/12) or a number ("12", "#12",
+ * "!12", "PR 12"); a number is a pull request of the repository the working directory is a clone of.
+ */
+export function parsePrRef(input: string, remotes: Remote[], platform?: Platform): PrRef {
+  const text = input.trim()
+  const ado = /^(https?:\/\/)(?:[^@/]+@)?(.+)\/([^/]+)\/_git\/([^/?#]+)\/pullrequest\/(\d+)/i.exec(text)
+  if (ado) return { platform: "azure_devops", org: `${ado[1]}${ado[2]}`, project: decodeURIComponent(ado[3]), repo: decodeURIComponent(ado[4]), number: Number(ado[5]) }
+  const gh = /github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/i.exec(text)
+  if (gh) return { platform: "github", repo: `${gh[1]}/${gh[2]}`, number: Number(gh[3]) }
+  const num = /^(?:(?:PR|pull request)\s*)?[#!]?\s*(\d+)$/i.exec(text)
+  if (!num) throw new Error(`"${input}" is not a pull request: give its link, or its number in this repository.`)
+  const candidates = remotes.filter((r) => !platform || r.ref.platform === platform)
+  const remote = candidates.find((r) => r.name === "origin") || candidates[0]
+  if (!remote) throw new Error(`Pull request ${num[1]}: the working directory has no ${platform === "github" ? "GitHub" : platform === "azure_devops" ? "Azure DevOps" : "GitHub or Azure DevOps"} remote, so give the pull request's link.`)
+  return { ...remote.ref, number: Number(num[1]) }
+}
+
+/** The repository's remotes that point at GitHub or Azure DevOps, as written in .git/config. */
+export async function gitRemotes(repo: string): Promise<Remote[]> {
+  const res = await sh(["git", "config", "--get-regexp", "^remote\\..*\\.url$"], repo)
+  if (res.code !== 0) return []
+  return res.out
+    .split("\n")
+    .map((l) => /^remote\.(.+)\.url\s+(.+)$/.exec(l.trim()))
+    .flatMap((m) => {
+      const ref = m ? parseRemote(m[2]) : null
+      return m && ref ? [{ name: m[1], url: m[2], ref }] : []
+    })
+}
+
+const sameRepo = (a: Omit<PrRef, "number">, b: Omit<PrRef, "number">) => {
+  const low = (s?: string) => (s || "").toLowerCase()
+  if (a.platform !== b.platform || low(a.repo) !== low(b.repo)) return false
+  return a.platform === "github" || low(a.project) === low(b.project)
+}
+
+const describe = (r: Omit<PrRef, "number">) => (r.platform === "github" ? `GitHub ${r.repo}` : `Azure DevOps ${r.project}/${r.repo}`)
+
+// ---- Reading the pull request ----
+
+export function adoBase(ref: PrRef): string {
+  return `${ref.org!.replace(/\/+$/, "")}/${encodeURIComponent(ref.project!)}/_apis/git/repositories/${encodeURIComponent(ref.repo!)}`
+}
+
+async function adoPr(ref: PrRef, cfg: AppConfig): Promise<PrInfo> {
+  const { auth } = adoSettings(cfg.sources)
+  const base = adoBase(ref)
+  const { data: pr } = await http<Record<string, any>>(`${base}/pullrequests/${ref.number}?${API}`, { auth })
+  const linked: PrInfo["linked"] = []
+  const workItemIds: number[] = []
+  try {
+    const { data } = await http<{ value?: { id: string }[] }>(`${base}/pullRequests/${ref.number}/workitems?${API}`, { auth })
+    const ids = (data?.value || []).map((w) => Number(w.id)).filter(Boolean).slice(0, 20)
+    workItemIds.push(...ids)
+    if (ids.length) {
+      const fields = ["System.Title", "System.WorkItemType", "System.Description", "Microsoft.VSTS.Common.AcceptanceCriteria"]
+      const { data: items } = await http<{ value?: { id: number; fields: Record<string, unknown> }[] }>(
+        `${ref.org!.replace(/\/+$/, "")}/_apis/wit/workitemsbatch?${API}`,
+        { auth, body: { ids, fields, errorPolicy: "omit" } },
+      )
+      for (const w of items?.value || []) {
+        const f = w.fields || {}
+        const criteria = htmlToText(String(f["Microsoft.VSTS.Common.AcceptanceCriteria"] || ""))
+        const text = [htmlToText(String(f["System.Description"] || "")), criteria ? `Acceptance criteria:\n${criteria}` : ""].filter(Boolean).join("\n")
+        linked.push({ id: `${f["System.WorkItemType"] || "Work item"} ${w.id}`, title: String(f["System.Title"] || ""), text: text.slice(0, ITEM_CHARS) || undefined })
+      }
+    }
+  } catch {
+    // Linked work items are context for the review; the review goes on without them.
+  }
+  const branch = (r: unknown) => String(r || "").replace(/^refs\/heads\//, "")
+  return {
+    ref,
+    url: `${ref.org!.replace(/\/+$/, "")}/${encodeURIComponent(ref.project!)}/_git/${encodeURIComponent(ref.repo!)}/pullrequest/${ref.number}`,
+    title: String(pr.title || ""),
+    description: String(pr.description || ""),
+    author: String(pr.createdBy?.displayName || ""),
+    state: String(pr.status || ""),
+    draft: Boolean(pr.isDraft),
+    sourceBranch: branch(pr.sourceRefName),
+    targetBranch: branch(pr.targetRefName),
+    headSha: String(pr.lastMergeSourceCommit?.commitId || ""),
+    linked,
+    ...(workItemIds.length ? { workItemIds } : {}),
+  }
+}
+
+export async function gh(args: string[], cwd: string, stdin?: string): Promise<string> {
+  const res = await sh(["gh", ...args], cwd, stdin === undefined ? {} : { stdin })
+  if (res.code !== 0) {
+    const missing = /not found|ENOENT|No such file/i.test(res.out) && !Bun.which("gh")
+    throw new Error(missing ? "GitHub pull requests need the gh CLI: install it and run gh auth login." : `gh ${args.slice(0, 2).join(" ")} failed: ${res.out.slice(-1500)}`)
+  }
+  return res.out
+}
+
+async function githubPr(ref: PrRef, cwd: string): Promise<PrInfo> {
+  if (!Bun.which("gh")) throw new Error("GitHub pull requests need the gh CLI: install it and run gh auth login.")
+  const fields = "number,title,body,author,state,isDraft,baseRefName,headRefName,headRefOid,url,closingIssuesReferences"
+  const pr = JSON.parse(await gh(["pr", "view", String(ref.number), "--repo", ref.repo!, "--json", fields], cwd)) as Record<string, any>
+  return {
+    ref,
+    url: String(pr.url || `https://github.com/${ref.repo}/pull/${ref.number}`),
+    title: String(pr.title || ""),
+    description: String(pr.body || ""),
+    author: String(pr.author?.login || ""),
+    state: String(pr.state || "").toLowerCase(),
+    draft: Boolean(pr.isDraft),
+    sourceBranch: String(pr.headRefName || ""),
+    targetBranch: String(pr.baseRefName || ""),
+    headSha: String(pr.headRefOid || ""),
+    linked: ((pr.closingIssuesReferences || []) as { number: number; title?: string }[]).map((i) => ({ id: `#${i.number}`, title: String(i.title || "") })),
+  }
+}
+
+export function fetchPr(ref: PrRef, cfg: AppConfig, cwd: string): Promise<PrInfo> {
+  return ref.platform === "github" ? githubPr(ref, cwd) : adoPr(ref, cfg)
+}
+
+// ---- The code ----
+
+/** Right-side line numbers (added and context lines) per file in a unified diff: where a comment can sit. */
+export function diffLines(diff: string): Map<string, Set<number>> {
+  const map = new Map<string, Set<number>>()
+  let file = ""
+  let line = 0
+  let hunk = false
+  for (const l of diff.split("\n")) {
+    if (l.startsWith("diff --git ")) {
+      hunk = false
+      file = ""
+      continue
+    }
+    if (!hunk) {
+      if (l.startsWith("+++ ")) {
+        file = l === "+++ /dev/null" ? "" : l.slice(4).replace(/^b\//, "")
+        if (file && !map.has(file)) map.set(file, new Set())
+      }
+      const h = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(l)
+      if (h) {
+        hunk = true
+        line = Number(h[1])
+      }
+      continue
+    }
+    const h = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(l)
+    if (h) line = Number(h[1])
+    else if (l.startsWith("+") || l.startsWith(" ")) {
+      if (file) map.get(file)!.add(line)
+      line++
+    }
+  }
+  return map
+}
+
+type Checkout = { tree: string; base: string; diff: string; files: PrReview["files"]; cleanup: () => Promise<void> }
+
+/**
+ * Fetch the pull request's branches from the clone's remote into refs/forgeqe/pr/<n>/ and check the head out in a
+ * temporary worktree, so the reviewer reads the PR's code without touching the user's branch or working tree.
+ */
+async function checkout(repo: string, remote: string, pr: PrInfo): Promise<Checkout> {
+  const n = pr.ref.number
+  const { base, dropRefs } = await fetchPrBranches(repo, remote, pr)
+  const git = (args: string[]) => sh(["git", "-c", "core.quotepath=false", ...args], repo)
+  const tree = mkdtempSync(path.join(os.tmpdir(), `forgeqe-pr-${n}-`))
+  const added = await git(["worktree", "add", "--detach", "--force", tree, pr.headSha])
+  if (added.code !== 0) {
+    await dropRefs()
+    rmSync(tree, { recursive: true, force: true })
+    throw new Error(`git worktree add failed:\n${added.out.slice(-1500)}`)
+  }
+  const range = [base, pr.headSha]
+  const diff = (await sh(["git", "-c", "core.quotepath=false", "diff", "--no-color", "--no-ext-diff", "-M", "--src-prefix=a/", "--dst-prefix=b/", ...range], tree)).out
+  const numstat = (await git(["diff", "--numstat", "-M", ...range])).out
+  const files = numstat
+    .split("\n")
+    .map((l) => l.split("\t"))
+    .filter((p) => p.length >= 3)
+    .map(([a, r, ...name]) => ({ path: name.join("\t").replace(/^(.*)\{(.*) => (.*)\}(.*)$/, "$1$3$4").replace(/^.* => /, ""), added: Number(a) || 0, removed: Number(r) || 0 }))
+  return {
+    tree,
+    base,
+    diff,
+    files,
+    cleanup: async () => {
+      await git(["worktree", "remove", "--force", tree])
+      rmSync(tree, { recursive: true, force: true })
+      await git(["worktree", "prune"])
+      await dropRefs()
+    },
+  }
+}
+
+/**
+ * Fetch a pull request's head and target branch into refs/forgeqe/pr/<n>/ and find their merge base. pr.headSha is
+ * set to the commit fetched. dropRefs removes the refs again.
+ */
+export async function fetchPrBranches(repo: string, remote: string, pr: PrInfo): Promise<{ base: string; dropRefs: () => Promise<void> }> {
+  const n = pr.ref.number
+  const head = `refs/forgeqe/pr/${n}/head`
+  const target = `refs/forgeqe/pr/${n}/base`
+  const source = pr.ref.platform === "github" ? `refs/pull/${n}/head` : `refs/heads/${pr.sourceBranch}`
+  const git = (args: string[]) => sh(["git", "-c", "core.quotepath=false", ...args], repo)
+  const fetched = await git(["fetch", "--no-tags", "--quiet", remote, `+${source}:${head}`, `+refs/heads/${pr.targetBranch}:${target}`])
+  if (fetched.code !== 0) throw new Error(`git fetch of the pull request's branches from ${remote} failed:\n${fetched.out.slice(-1500)}`)
+  const dropRefs = async () => {
+    await git(["update-ref", "-d", head])
+    await git(["update-ref", "-d", target])
+  }
+  const sha = (await git(["rev-parse", head])).out.trim()
+  if (pr.headSha && sha !== pr.headSha) {
+    // The branch moved after the API answered, or (Azure DevOps) the PR's source commit is not the branch tip yet.
+    const at = await git(["cat-file", "-e", `${pr.headSha}^{commit}`])
+    if (at.code === 0) await git(["update-ref", head, pr.headSha])
+  }
+  pr.headSha = (await git(["rev-parse", head])).out.trim()
+  const mb = await git(["merge-base", target, head])
+  if (mb.code !== 0) {
+    await dropRefs()
+    throw new Error(`The pull request's branch has no common history with ${pr.targetBranch}.`)
+  }
+  return { base: mb.out.trim(), dropRefs }
+}
+
+/** A pull request from a link or number, with the clone's remote that holds it; throws when the clone is another repo's. */
+export async function resolvePr(repo: string, input: string, platform?: Platform): Promise<{ root: string; ref: PrRef; remote: string }> {
+  const top = await sh(["git", "rev-parse", "--show-toplevel"], repo)
+  if (top.code !== 0) throw new Error(`${repo} is not a git clone.`)
+  const root = top.out.trim()
+  const remotes = await gitRemotes(root)
+  const ref = parsePrRef(input, remotes, platform)
+  const remote = remotes.find((r) => sameRepo(r.ref, ref))
+  if (!remote) throw new Error(`The pull request is in ${describe(ref)}, but ${root} is a clone of ${remotes.map((r) => describe(r.ref)).join(", ") || "no GitHub or Azure DevOps remote"}. Pass repo with the path of a local clone of ${ref.repo}.`)
+  return { root, ref, remote: remote.name }
+}
+
+// ---- The reviewer ----
+
+export const prReviewAgentPrompt = () => prompt("pr-review")
+
+export const PR_REVIEW_AGENT: AgentSpec = {
+  name: "forgeqe-pr-review",
+  description: "Reviews a pull request's changes for bugs, security, requirements, and tests, without changing anything",
+  get prompt() {
+    return prReviewAgentPrompt()
+  },
+  permission: {
+    edit: "deny",
+    bash: {
+      "*": "deny",
+      "git diff*": "allow",
+      "git log*": "allow",
+      "git show*": "allow",
+      "git blame*": "allow",
+      "git status*": "allow",
+      "git ls-files*": "allow",
+      "ls*": "allow",
+    },
+    webfetch: "deny",
+    task: "deny",
+  },
+  skills: "scribe",
+}
+
+export const PR_REVIEW_SCHEMA = {
+  type: "object",
+  properties: {
+    verdict: { type: "string", enum: ["approve", "approve_with_suggestions", "request_changes"] },
+    summary: { type: "string", description: "Two to four sentences: what the pull request does and the verdict's reason" },
+    findings: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          file: { type: "string", description: "Path relative to the repository root; empty for the change as a whole" },
+          line: { type: "number", description: "Line in the pull request's version of the file" },
+          end_line: { type: "number", description: "Last line, when the finding spans several" },
+          severity: { type: "string", enum: ["blocker", "major", "minor", "nit"] },
+          title: { type: "string", description: "A few words" },
+          problem: { type: "string", description: "What is wrong and why it matters" },
+          suggestion: { type: "string", description: "What to change" },
+        },
+        required: ["severity", "title", "problem"],
+      },
+    },
+  },
+  required: ["verdict", "summary", "findings"],
+} as const
+
+type ReviewReport = { verdict?: string; summary?: string; findings?: Partial<PrFinding>[] }
+
+const SEVERITIES: Severity[] = ["blocker", "major", "minor", "nit"]
+const VERDICTS: Verdict[] = ["approve", "approve_with_suggestions", "request_changes"]
+
+export function reviewPrPrompt(pr: PrInfo, base: string, files: PrReview["files"], diff: string, focus?: string): string {
+  const desc = htmlToText(pr.description) || pr.description.trim()
+  const shown = diff.length > DIFF_CHARS ? `${diff.slice(0, DIFF_CHARS)}\n… (the rest is not shown here; run git diff ${base} HEAD)` : diff
+  return [
+    `Review pull request ${pr.ref.platform === "github" ? "#" : "!"}${pr.ref.number}: ${pr.title}`,
+    `${pr.sourceBranch} into ${pr.targetBranch}${pr.author ? `, by ${pr.author}` : ""}${pr.draft ? " (draft)" : ""}.`,
+    focus ? `The user asks you to focus on: ${focus}` : "",
+    "",
+    "Description:",
+    desc ? (desc.length > DESCRIPTION_CHARS ? `${desc.slice(0, DESCRIPTION_CHARS)}…` : desc) : "(none)",
+    ...(pr.linked.length ? ["", "Linked work items:", ...pr.linked.map((w) => [`- ${w.id}: ${w.title}`, ...(w.text ? [w.text.replace(/^/gm, "  ")] : [])].join("\n"))] : []),
+    "",
+    `Merge base: ${base}. The working directory is at the pull request's head, ${pr.headSha}; git diff ${base} HEAD shows the change.`,
+    `Files changed (${files.length}): ${files.map((f) => `${f.path} (+${f.added} -${f.removed})`).join(", ") || "(none)"}`,
+    "",
+    "```diff",
+    shown || "(empty diff)",
+    "```",
+  ]
+    .filter((l, i, all) => l !== "" || all[i - 1] !== "")
+    .join("\n")
+}
+
+function cleanFindings(raw: unknown): PrFinding[] {
+  const list = Array.isArray(raw) ? (raw as Partial<PrFinding>[]) : []
+  return list
+    .filter((f) => f && String(f.problem || "").trim())
+    .map((f) => {
+      const line = Number(f.line) > 0 ? Math.floor(Number(f.line)) : undefined
+      const end = line && Number(f.end_line) > line ? Math.floor(Number(f.end_line)) : undefined
+      return {
+        ...(f.file ? { file: String(f.file).replace(/^\.?\//, "") } : {}),
+        ...(line ? { line } : {}),
+        ...(end ? { end_line: end } : {}),
+        severity: SEVERITIES.includes(f.severity as Severity) ? (f.severity as Severity) : "minor",
+        title: String(f.title || "").trim() || "Finding",
+        problem: String(f.problem).trim(),
+        ...(f.suggestion?.trim() ? { suggestion: f.suggestion.trim() } : {}),
+      }
+    })
+    .sort((a, b) => SEVERITIES.indexOf(a.severity) - SEVERITIES.indexOf(b.severity))
+}
+
+/**
+ * Review a pull request: read it from Azure DevOps or GitHub, check its head out from the local clone in a temporary
+ * worktree, and have a read-only Scribe session review the diff. The review is saved as review.json and review.md in a
+ * new folder under <export.outDir>/reviews; nothing is posted.
+ */
+export async function reviewPullRequest(opts: {
+  config: AppConfig
+  repo: string
+  pr: string
+  platform?: Platform
+  focus?: string
+  signal?: AbortSignal
+  onEvent?: (e: CodeEvent) => void
+  open?: (o: Parameters<typeof openSession>[0]) => Promise<OpencodeSession>
+}): Promise<PrReview> {
+  const repo = path.resolve(opts.repo)
+  if (!existsSync(repo) || !statSync(repo).isDirectory()) throw new Error(`Repo not found: ${repo}`)
+  const top = await sh(["git", "rev-parse", "--show-toplevel"], repo)
+  if (top.code !== 0) throw new Error(`${repo} is not a git clone; reviewing a pull request needs a local clone of its repository (pass repo).`)
+  const root = top.out.trim()
+  const emit = opts.onEvent || (() => {})
+  const remotes = await gitRemotes(root)
+  const ref = parsePrRef(opts.pr, remotes, opts.platform)
+  const remote = remotes.find((r) => sameRepo(r.ref, ref))
+  if (!remote) {
+    const here = remotes.length ? remotes.map((r) => describe(r.ref)).join(", ") : "no GitHub or Azure DevOps remote"
+    throw new Error(`The pull request is in ${describe(ref)}, but ${root} is a clone of ${here}. Pass repo with the path of a local clone of ${ref.repo}.`)
+  }
+
+  emit({ type: "code", kind: "info", text: `Reading pull request ${ref.number} from ${describe(ref)}…` })
+  const pr = await fetchPr(ref, opts.config, root)
+  if (!pr.sourceBranch || !pr.targetBranch) throw new Error(`Pull request ${ref.number} has no source or target branch.`)
+  emit({ type: "code", kind: "info", text: `Fetching ${pr.sourceBranch} and ${pr.targetBranch} from ${remote.name}…` })
+  const co = await checkout(root, remote.name, pr)
+  try {
+    if (!co.diff.trim()) throw new Error(`Pull request ${ref.number} changes nothing against ${pr.targetBranch}.`)
+    // code.review_profile: a cheaper llms.json profile for reading and judging; else the session's profile (or code.model).
+    const named = opts.config.code.reviewProfile ? opts.config.profiles[opts.config.code.reviewProfile] : undefined
+    const profile = named || opts.config.llm
+    const open = (opts.open || openSession) as (o: Parameters<typeof openSession>[0]) => Promise<OpencodeSession<ReviewReport>>
+    const session = await open({
+      repo: co.tree,
+      profile,
+      domain: domainNotes(opts.config),
+      model: profile === opts.config.llm ? opts.config.code.model : undefined,
+      bin: opts.config.code.opencode,
+      readDirs: [co.tree],
+      hide: privateEnvNames(opts.config),
+      role: "reviewer",
+      signal: opts.signal,
+      onEvent: emit,
+      agent: PR_REVIEW_AGENT,
+      skills: loadSkills(opts.config.skills, co.tree).skills,
+      schema: PR_REVIEW_SCHEMA as unknown as Record<string, unknown>,
+      title: `ForgeQE PR review ${ref.number}`,
+    })
+    try {
+      emit({ type: "code", kind: "info", text: `Scribe (${session.model}) is reviewing ${co.files.length} changed file${co.files.length === 1 ? "" : "s"} in "${pr.title}"` })
+      let reply = await session.prompt(reviewPrPrompt(pr, co.base, co.files, co.diff, opts.focus))
+      if (!reply.report && !reply.error && !opts.signal?.aborted) reply = await session.prompt("Give the structured result: verdict, summary, and findings.")
+      if (opts.signal?.aborted) throw new Error("Stopped.")
+      const r = reply.report
+      if (!r || !VERDICTS.includes(r.verdict as Verdict)) throw new Error(`Scribe gave no review${reply.error ? `: ${reply.error}` : "."}`)
+      const findings = cleanFindings(r.findings)
+      const lines = diffLines(co.diff)
+      const dir = runDirectory(path.join(opts.config.export.outDir, "reviews"))
+      const review: PrReview = {
+        id: path.basename(dir),
+        dir,
+        repo: root,
+        pr,
+        base: co.base,
+        files: co.files,
+        verdict: r.verdict as Verdict,
+        summary: String(r.summary || "").trim(),
+        findings,
+        inline: findings.map((f) => Boolean(f.file && f.line && lines.get(f.file)?.has(f.line))),
+        model: session.model,
+        usage: { ...session.usage },
+        price: named ? named.price : opts.config.code.model ? undefined : opts.config.llm.price,
+        createdAt: new Date().toISOString(),
+      }
+      saveReview(review)
+      return review
+    } finally {
+      await session.close()
+    }
+  } finally {
+    await co.cleanup()
+  }
+}
+
+// ---- Saving, showing, posting ----
+
+const VERDICT_TEXT: Record<Verdict, string> = { approve: "Approve", approve_with_suggestions: "Approve with suggestions", request_changes: "Changes requested" }
+const where = (f: PrFinding) => (f.file ? `${f.file}${f.line ? `:${f.line}${f.end_line ? `-${f.end_line}` : ""}` : ""}` : "")
+
+export function findingMarkdown(f: PrFinding, withPlace = true): string {
+  const place = withPlace && where(f) ? ` · \`${where(f)}\`` : ""
+  return [`**${f.severity}: ${f.title}**${place}`, "", f.problem, ...(f.suggestion ? ["", `**Suggestion:** ${f.suggestion}`] : [])].join("\n")
+}
+
+/** The summary comment: verdict, summary, and every finding that cannot sit on a line of the diff. */
+export function summaryMarkdown(review: PrReview, onlyOffDiff = true): string {
+  const rest = review.findings.filter((_, i) => !onlyOffDiff || !review.inline[i])
+  const counts = SEVERITIES.map((s) => [s, review.findings.filter((f) => f.severity === s).length] as const).filter(([, n]) => n)
+  return [
+    `### ForgeQE review: ${VERDICT_TEXT[review.verdict]}`,
+    "",
+    review.summary,
+    ...(counts.length ? ["", counts.map(([s, n]) => `${n} ${s}`).join(" · ")] : []),
+    ...(rest.length ? ["", onlyOffDiff ? "Findings not on a changed line:" : "Findings:", "", ...rest.map((f) => `- ${findingMarkdown(f).replace(/\n\n/g, "\n  ").replace(/\n(?! )/g, "\n  ")}`)] : []),
+  ].join("\n")
+}
+
+function saveReview(review: PrReview) {
+  writeFileSync(path.join(review.dir, "review.json"), JSON.stringify(review, null, 2))
+  const md = [
+    `# Pull request ${review.pr.ref.number}: ${review.pr.title}`,
+    "",
+    `${review.pr.url}`,
+    `${review.pr.sourceBranch} → ${review.pr.targetBranch}, head ${review.pr.headSha.slice(0, 10)}, reviewed ${review.createdAt} by ${review.model}`,
+    "",
+    summaryMarkdown(review, false),
+  ].join("\n")
+  writeFileSync(path.join(review.dir, "review.md"), `${md}\n`)
+}
+
+export function loadReview(config: AppConfig, id: string): PrReview {
+  const file = path.join(config.export.outDir, "reviews", path.basename(id), "review.json")
+  if (!existsSync(file)) throw new Error(`No pull request review "${id}": call review_pull_request first.`)
+  return JSON.parse(readFileSync(file, "utf8")) as PrReview
+}
+
+const rel = (cwd: string, p: string) => {
+  const r = path.relative(cwd, p)
+  return r && !r.startsWith("..") && !path.isAbsolute(r) ? r : p
+}
+
+const MARK: Record<Severity, string> = { blocker: "●", major: "●", minor: "○", nit: "·" }
+
+export function reviewCard(review: PrReview, cwd: string): Card {
+  const body: string[] = [review.summary, ""]
+  for (const f of review.findings.slice(0, 30)) {
+    body.push(`${MARK[f.severity]} ${f.severity.padEnd(7)} ${f.title}${where(f) ? `  ${where(f)}` : ""}`)
+    body.push(`    ${f.problem}`)
+    if (f.suggestion) body.push(`    → ${f.suggestion}`)
+  }
+  if (review.findings.length > 30) body.push(`and ${review.findings.length - 30} more (review.md has all of them)`)
+  if (!review.findings.length) body.push("Nothing to fix.")
+  body.push("", `PR        ${review.pr.url}`, `Saved     ${rel(cwd, path.join(review.dir, "review.md"))}`)
+  const n = review.findings.length
+  return {
+    status: review.verdict === "request_changes" ? "fail" : review.verdict === "approve" ? "ok" : "info",
+    title: `PR ${review.pr.ref.number} reviewed: ${review.pr.title}`,
+    stats: [VERDICT_TEXT[review.verdict], `${n} finding${n === 1 ? "" : "s"}`, `${review.files.length} file${review.files.length === 1 ? "" : "s"}`].join(" · "),
+    body,
+  }
+}
+
+/**
+ * Post a saved review to its pull request: one comment per finding on its line of the diff, and one summary comment
+ * with the verdict and the findings that have no line. On GitHub it is a review with event COMMENT; it never approves
+ * or requests changes in the user's name. Refuses when the pull request has new commits since the review.
+ */
+export async function postReview(review: PrReview, config: AppConfig): Promise<string[]> {
+  if (review.posted) throw new Error(`This review was already posted on ${review.posted.at}.`)
+  const now = await fetchPr(review.pr.ref, config, review.repo)
+  if (now.headSha && now.headSha !== review.pr.headSha) {
+    throw new Error(`Pull request ${review.pr.ref.number} has new commits since the review (${review.pr.headSha.slice(0, 10)} → ${now.headSha.slice(0, 10)}), so the lines may have moved. Review it again before posting.`)
+  }
+  const inline = review.findings.filter((_, i) => review.inline[i])
+  const links: string[] = []
+  if (review.pr.ref.platform === "github") {
+    const body = {
+      commit_id: review.pr.headSha,
+      event: "COMMENT",
+      body: summaryMarkdown(review),
+      comments: inline.map((f) => ({
+        path: f.file,
+        side: "RIGHT",
+        line: f.end_line || f.line,
+        ...(f.end_line ? { start_line: f.line, start_side: "RIGHT" } : {}),
+        body: findingMarkdown(f, false),
+      })),
+    }
+    const out = await gh(["api", "-X", "POST", `repos/${review.pr.ref.repo}/pulls/${review.pr.ref.number}/reviews`, "--input", "-"], review.repo, JSON.stringify(body))
+    let url = review.pr.url
+    try {
+      url = String((JSON.parse(out) as { html_url?: string }).html_url || url)
+    } catch {}
+    links.push(url)
+  } else {
+    const { auth } = adoSettings(config.sources)
+    const threads = `${adoBase(review.pr.ref)}/pullRequests/${review.pr.ref.number}/threads?${API}`
+    const post = (content: string, context?: Record<string, unknown>) =>
+      http<{ id: number }>(threads, { auth, body: { comments: [{ parentCommentId: 0, content, commentType: 1 }], status: "active", ...(context ? { threadContext: context } : {}) } })
+    await post(summaryMarkdown(review))
+    for (const f of inline) {
+      await post(findingMarkdown(f, false), {
+        filePath: `/${f.file}`,
+        rightFileStart: { line: f.line, offset: 1 },
+        rightFileEnd: { line: f.end_line || f.line, offset: 1 },
+      })
+    }
+    links.push(review.pr.url)
+  }
+  review.posted = { at: new Date().toISOString(), links }
+  saveReview(review)
+  return links
+}
+
+/** Post one markdown comment on a pull request (an Azure DevOps thread, or a GitHub PR comment). Returns its link. */
+export async function postPrComment(ref: PrRef, config: AppConfig, repo: string, markdown: string): Promise<string> {
+  if (ref.platform === "github") {
+    const out = await gh(["pr", "comment", String(ref.number), "--repo", ref.repo!, "--body-file", "-"], repo, markdown)
+    return out.trim().split("\n").find((l) => l.startsWith("http")) || `https://github.com/${ref.repo}/pull/${ref.number}`
+  }
+  const { auth } = adoSettings(config.sources)
+  await http(`${adoBase(ref)}/pullRequests/${ref.number}/threads?${API}`, { auth, body: { comments: [{ parentCommentId: 0, content: markdown, commentType: 1 }], status: "closed" } })
+  return `${ref.org!.replace(/\/+$/, "")}/${encodeURIComponent(ref.project!)}/_git/${encodeURIComponent(ref.repo!)}/pullrequest/${ref.number}`
+}