@vintasoftware/pr-review-canvas 0.2.0 → 0.4.0

package/src/host/host.ts

@@ -0,0 +1,136 @@
+import { shareGithubCanvas } from '../github/canvas-comment.js'
+import { shareGitlabCanvas } from '../gitlab/canvas-comment.js'
+import type { Capabilities, PublicHost, ReviewSummary } from '../contract/api.js'
+import type { FetchCommentsResult, PostCommentInput, PostCommentResult } from '../contract/comments.js'
+import type { Repo } from '../contract/review-artifact.js'
+import { GITHUB_ATTACHMENTS } from '../github/attachments.js'
+import { probeCapabilities } from '../github/capabilities.js'
+import { fetchComments } from '../github/comments.js'
+import { postComment } from '../github/post-comment.js'
+import type { ReviewEvent } from '../contract/reviews.js'
+import { postReview } from '../github/post-review.js'
+import { fetchPrMeta } from '../github/pr.js'
+import type { PrMeta } from './pr.js'
+import { gitlabAttachments } from '../gitlab/attachments.js'
+import { probeGitlabCapabilities } from '../gitlab/capabilities.js'
+import { fetchGitlabComments } from '../gitlab/comments.js'
+import { fetchMrMeta } from '../gitlab/mr.js'
+import { postGitlabComment } from '../gitlab/post-comment.js'
+import { postGitlabReview } from '../gitlab/post-review.js'
+import type { Derived } from '../store/derived-store.js'
+import type { AttachmentLink } from './attachments.js'
+import { GH_CLI, glabCli, type HostClient, type HostCliSpec } from './client.js'
+
+export type HostKind = PublicHost['kind']
+
+/** How canvas zips attached to a review are found and fetched on one forge. */
+export interface HostAttachments {
+  /** Zip links in one markdown text, as absolute URLs this host serves. */
+  findLinks(text: string, repo: Repo): AttachmentLink[]
+  /** Where an attachment may be served from. Everything else is refused before any request. */
+  allowedHosts: ReadonlySet<string>
+  /** The header that carries the CLI token to the forge itself; a storage redirect gets none. */
+  authHeader(token: string): Record<string, string>
+}
+
+/**
+ * One forge: the words the page uses for it, the CLI that talks to it, and every operation whose
+ * request or answer differs between GitHub and GitLab. Everything that is the same for both (the
+ * local refs, the stored Pr, the download loop, the routes) takes a Host and never asks its kind.
+ */
+export interface Host {
+  kind: HostKind
+  hostname: string
+  /** `GitHub` or `GitLab`, for messages. */
+  label: string
+  cli: HostCliSpec
+  webBase: string
+  /** `pull request` or `merge request`, and its abbreviation. */
+  noun: string
+  nounShort: string
+  /** The remote ref that holds a review's head, fetched into the same local ref for both hosts. */
+  remoteHeadRef(number: number): string
+  compareUrl(repo: Repo, base: string, head: string): string
+  fetchPrMeta(client: HostClient, repo: Repo, number: number): Promise<PrMeta>
+  fetchComments(
+    client: HostClient,
+    repo: Repo,
+    number: number,
+    headSha: string,
+    now: () => Date
+  ): Promise<FetchCommentsResult>
+  /** GitLab needs the diff for renamed paths and both coordinates of context lines. */
+  postComment(
+    client: HostClient,
+    repo: Repo,
+    number: number,
+    headSha: string,
+    input: PostCommentInput,
+    diff: Derived
+  ): Promise<PostCommentResult>
+  postReview(
+    client: HostClient,
+    repo: Repo,
+    number: number,
+    headSha: string,
+    input: { event: ReviewEvent; body: string }
+  ): Promise<ReviewSummary>
+  probeCapabilities(client: HostClient, repo: Repo): Promise<Capabilities>
+  canvasCommentLimit: number
+  shareCanvas(client: HostClient, repo: Repo, number: number, body: string): Promise<string>
+  attachments: HostAttachments
+}
+
+export const GITHUB_HOST: Host = {
+  kind: 'github',
+  hostname: 'github.com',
+  label: 'GitHub',
+  cli: GH_CLI,
+  webBase: 'https://github.com',
+  noun: 'pull request',
+  nounShort: 'PR',
+  remoteHeadRef: number => `pull/${number}/head`,
+  compareUrl: (repo, base, head) => `https://github.com/${repo.owner}/${repo.name}/compare/${base}...${head}`,
+  fetchPrMeta,
+  fetchComments,
+  postComment,
+  postReview,
+  probeCapabilities,
+  canvasCommentLimit: 65_536,
+  shareCanvas: shareGithubCanvas,
+  attachments: GITHUB_ATTACHMENTS,
+}
+
+/** A GitLab instance. `hostname` is gitlab.com or the self-hosted instance the origin names. */
+export function gitlabHost(hostname: string): Host {
+  const webUrl = new URL(`https://${hostname}`)
+  hostname = webUrl.host
+  const webBase = webUrl.origin
+  return {
+    kind: 'gitlab',
+    hostname,
+    label: 'GitLab',
+    cli: glabCli(hostname),
+    webBase,
+    noun: 'merge request',
+    nounShort: 'MR',
+    remoteHeadRef: number => `merge-requests/${number}/head`,
+    compareUrl: (repo, base, head) => `${webBase}/${repo.owner}/${repo.name}/-/compare/${base}...${head}`,
+    fetchPrMeta: fetchMrMeta,
+    fetchComments: (client, repo, number, headSha, now) =>
+      fetchGitlabComments(client, repo, number, headSha, now, webBase),
+    postComment: (client, repo, number, headSha, input, diff) =>
+      postGitlabComment(client, repo, number, headSha, input, { webBase, ...diff }),
+    postReview: (client, repo, number, headSha, input) =>
+      postGitlabReview(client, repo, number, headSha, input, webBase),
+    probeCapabilities: probeGitlabCapabilities,
+    canvasCommentLimit: 1_000_000,
+    shareCanvas: (client, repo, number, body) => shareGitlabCanvas(client, repo, number, body, webBase),
+    attachments: gitlabAttachments(hostname, webBase),
+  }
+}
+
+/** The part of a Host the page and the health endpoint are told. */
+export function publicHost(host: Host): PublicHost {
+  return { kind: host.kind, label: host.label, webBase: host.webBase }
+}

package/src/host/pr.ts

@@ -0,0 +1,51 @@
+import type { Pr, Repo } from '../contract/review-artifact.js'
+
+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 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/host/remote.ts

@@ -0,0 +1,42 @@
+import type { Repo } from '../contract/review-artifact.js'
+import { GITHUB_HOST, gitlabHost, type Host } from './host.js'
+
+export interface OriginRemote {
+  host: Host
+  repo: Repo
+}
+
+/** Hostname and repository path from the three remote forms git gives out: scp-like ssh, ssh://, https. */
+export function splitGitRemote(url: string): { hostname: string; path: string } | null {
+  const m =
+    /^ssh:\/\/git@([^:/]+)(?::\d+)?\/(.+)$/.exec(url.trim()) ??
+    /^git@([^:/]+):(.+)$/.exec(url.trim()) ??
+    /^https?:\/\/(?:[^@/]+@)?([^/]+)\/(.+)$/.exec(url.trim())
+  if (m?.[1] === undefined || m[2] === undefined) {
+    return null
+  }
+  return { hostname: m[1].toLowerCase(), path: m[2].replace(/\.git$/i, '').replace(/\/$/, '') }
+}
+
+/**
+ * Classifies origin. github.com is GitHub; gitlab.com, a hostname that contains "gitlab", or any
+ * other host when `PR_REVIEW_HOST=gitlab` is set (a self-hosted GitLab whose name does not say
+ * so) is GitLab. A GitLab path may nest groups, which become the owner with slashes.
+ */
+export function parseOriginRemote(url: string, env: NodeJS.ProcessEnv = {}): OriginRemote | null {
+  const split = splitGitRemote(url)
+  if (split === null) {
+    return null
+  }
+  const parts = split.path.split('/').filter(p => p !== '')
+  const name = parts[parts.length - 1]
+  if (parts.length < 2 || name === undefined) {
+    return null
+  }
+  const repo: Repo = { owner: parts.slice(0, -1).join('/'), name }
+  if (split.hostname === 'github.com') {
+    return parts.length === 2 ? { host: GITHUB_HOST, repo } : null
+  }
+  const forced = env['PR_REVIEW_HOST']?.trim().toLowerCase() === 'gitlab'
+  return forced || split.hostname.includes('gitlab') ? { host: gitlabHost(split.hostname), repo } : null
+}

package/src/project-config.ts

@@ -36,14 +36,16 @@ const capsShape = {
   diagram: cap(),
 } satisfies Record<keyof TextCaps, z.ZodOptional<z.ZodNumber>>
 
-export const PromptOverridesSchema = z.object({
-  'generation-format.md': z.string().min(1).optional(),
-  'generation-strict.md': z.string().min(1).optional(),
-  'generation-surfacing.md': z.string().min(1).optional(),
-  'quality-standards.md': z.string().min(1).optional(),
-  'layering-guidance.md': z.string().min(1).optional(),
-  'chat-seed.md': z.string().min(1).optional(),
-}).strict()
+export const PromptOverridesSchema = z
+  .object({
+    'generation-format.md': z.string().min(1).optional(),
+    'generation-strict.md': z.string().min(1).optional(),
+    'generation-surfacing.md': z.string().min(1).optional(),
+    'quality-standards.md': z.string().min(1).optional(),
+    'layering-guidance.md': z.string().min(1).optional(),
+    'chat-seed.md': z.string().min(1).optional(),
+  })
+  .strict()
 export type PromptOverrides = z.infer<typeof PromptOverridesSchema>
 
 export const ProjectConfigSchema = z.object({
@@ -63,6 +65,13 @@ export const ProjectConfigSchema = z.object({
   /** Which paths count as tests, for the layering rules and the `isTest` flag on a file. */
   tests: z.object({ patterns: z.array(z.string().min(1)) }),
   chat: z.object({ enabled: z.boolean() }),
+  canvas: z.object({
+    /**
+     * A canvas still stands for a later head whose diff is identical to the one it was generated
+     * from, as after merging the base branch in. False marks the canvas outdated on any commit.
+     */
+    keepForIdenticalDiff: z.boolean(),
+  }),
 })
 export type ProjectConfig = z.infer<typeof ProjectConfigSchema>
 
@@ -84,6 +93,7 @@ const PartialProjectConfigSchema = z.object({
     .optional(),
   tests: z.object({ patterns: z.array(z.string().min(1)).optional() }).optional(),
   chat: z.object({ enabled: z.boolean().optional() }).optional(),
+  canvas: z.object({ keepForIdenticalDiff: z.boolean().optional() }).optional(),
 })
 
 export const DEFAULT_PROJECT_CONFIG: ProjectConfig = {
@@ -93,6 +103,7 @@ export const DEFAULT_PROJECT_CONFIG: ProjectConfig = {
   generation: { mode: 'strict', maxRepairRounds: 3, inlineDiffMaxLines: 1500, smallPrHunks: 10 },
   tests: { patterns: [...DEFAULT_TEST_PATTERNS] },
   chat: { enabled: true },
+  canvas: { keepForIdenticalDiff: true },
 }
 
 export interface LoadedProjectConfig {
@@ -119,7 +130,8 @@ export function mergeProjectConfig(raw: unknown): { config: ProjectConfig; warni
   const generation: ProjectConfig['generation'] = {
     mode: user.generation?.mode ?? DEFAULT_PROJECT_CONFIG.generation.mode,
     maxRepairRounds: user.generation?.maxRepairRounds ?? DEFAULT_PROJECT_CONFIG.generation.maxRepairRounds,
-    inlineDiffMaxLines: user.generation?.inlineDiffMaxLines ?? DEFAULT_PROJECT_CONFIG.generation.inlineDiffMaxLines,
+    inlineDiffMaxLines:
+      user.generation?.inlineDiffMaxLines ?? DEFAULT_PROJECT_CONFIG.generation.inlineDiffMaxLines,
     smallPrHunks: user.generation?.smallPrHunks ?? DEFAULT_PROJECT_CONFIG.generation.smallPrHunks,
   }
   if (user.generation?.caps !== undefined) {
@@ -132,6 +144,10 @@ export function mergeProjectConfig(raw: unknown): { config: ProjectConfig; warni
     generation,
     tests: { patterns: user.tests?.patterns ?? [...DEFAULT_TEST_PATTERNS] },
     chat: { enabled: user.chat?.enabled ?? true },
+    canvas: {
+      keepForIdenticalDiff:
+        user.canvas?.keepForIdenticalDiff ?? DEFAULT_PROJECT_CONFIG.canvas.keepForIdenticalDiff,
+    },
   }
   if (user.rulebook !== undefined) {
     config.rulebook = user.rulebook

package/src/prompt-files.ts

@@ -15,9 +15,10 @@ export async function loadPromptFile(
   project?: ProjectPrompts
 ): Promise<string> {
   const override = project?.overrides?.[name]
-  const file = project !== undefined && override !== undefined
-    ? path.resolve(project.repoRoot, override)
-    : path.join(dir, name)
+  const file =
+    project !== undefined && override !== undefined
+      ? path.resolve(project.repoRoot, override)
+      : path.join(dir, name)
   try {
     return await readFile(file, 'utf8')
   } catch (cause) {

package/src/review/carry-over.ts

@@ -0,0 +1,79 @@
+// A canvas carried over to a later head: the head's diff is identical to the diff the canvas was
+// generated from, so the canvas stands for it. The one place that reads the rule.
+import type { CarriedOverInfo } from '../contract/api.js'
+import type { Pr } from '../contract/review-artifact.js'
+import type { AppContext } from '../server/context.js'
+import type { CanvasLookup } from '../store/canvas-store.js'
+import type { Derived } from '../store/derived-store.js'
+
+/** A commit with the merge base its diff runs from; `Pr`, a prepared context, and a canvas manifest all provide it. */
+export interface DiffedCommit {
+  headSha: string
+  mergeBaseSha: string
+}
+
+/**
+ * True when `commit` stands for the head: it is the head, or the head's diff against its merge
+ * base is identical to `commit`'s diff against its own, file by file and byte for byte. Layers,
+ * hunk ids, folds, and attention points all assume the diff on screen is the one the canvas was
+ * generated from, and identity is what guarantees that; a base merge that only moves a hunk down
+ * already breaks it. How the head reached that diff does not matter. A diff missing on this
+ * machine, and a change set that is empty on both sides, keep the strict reading. Off when the
+ * project marks the canvas outdated on any commit.
+ */
+export async function standsForHead(
+  ctx: AppContext,
+  pr: DiffedCommit,
+  commit: DiffedCommit
+): Promise<boolean> {
+  if (commit.headSha === pr.headSha) {
+    return true
+  }
+  if (!ctx.projectConfig.config.canvas.keepForIdenticalDiff) {
+    return false
+  }
+  const [older, head] = await Promise.all([
+    ctx.derived.readOrBuild(commit.headSha, commit.mergeBaseSha),
+    ctx.derived.readOrBuild(pr.headSha, pr.mergeBaseSha),
+  ])
+  if (older === null || head === null) {
+    return false
+  }
+  // Two empty diffs are equal by having nothing to compare, which is no evidence that the canvas
+  // explains the head. An empty change set has nothing to review either way, so the strict
+  // reading costs the reviewer nothing here.
+  return Object.keys(head.patches).length > 0 && samePatches(older, head)
+}
+
+/**
+ * Whether two diffs change the same code: the same patch keys, each with the same patch body.
+ * The patches are the diff; the files array beside them only counts and flags what the patches
+ * already say, so comparing the patches is comparing the whole change.
+ */
+export function samePatches(a: Derived, b: Derived): boolean {
+  const keys = Object.keys(a.patches)
+  return keys.length === Object.keys(b.patches).length && keys.every(k => a.patches[k] === b.patches[k])
+}
+
+/**
+ * The canvas for this pull request: the store's answer, with a canvas of another commit read as
+ * ready when that commit stands for the head. A canvas has a manifest naming its merge base;
+ * one whose manifest is gone cannot be compared.
+ */
+export async function lookupCanvas(ctx: AppContext, number: number, pr: Pr): Promise<CanvasLookup> {
+  const found = await ctx.canvases.findForPr(number, pr.headSha)
+  if (found.status !== 'stale') {
+    return found
+  }
+  const manifest = await ctx.canvases.readManifest(found.headSha)
+  if (manifest !== null && (await standsForHead(ctx, pr, manifest))) {
+    const carriedOver: CarriedOverInfo = { canvasHeadSha: found.headSha, currentHeadSha: pr.headSha }
+    // How far the head moved, when the head was built on the canvas's commit. A head that
+    // reached the identical diff another way, by a rebase, is no distance from it at all.
+    if (found.relation === 'ancestor') {
+      carriedOver.commitsBehind = found.commitsBehind
+    }
+    return { status: 'ready', headSha: found.headSha, carriedOver }
+  }
+  return found
+}

package/src/review/doctor.ts

@@ -3,9 +3,11 @@
 import { randomBytes } from 'node:crypto'
 import { readFile, rm, writeFile } from 'node:fs/promises'
 import path from 'node:path'
-import { parseGithubRemote } from '../config.js'
+import { ORIGIN_HINT } from '../config.js'
 import type { Git } from '../git/git.js'
-import type { GitHubClient } from '../github/gh.js'
+import { CLI_INFO, type HostClient } from '../host/client.js'
+import { GITHUB_HOST, type Host } from '../host/host.js'
+import { parseOriginRemote } from '../host/remote.js'
 import { ensureDataDir, resolveDataDir } from '../store/data-dir.js'
 import { CLAUDE_SKILLS_DIR, CODEX_SKILLS_DIR, SKILL_NAME, SKILL_SOURCE_DIR } from './install-skill.js'
 import { skillContent } from './skill-content.js'
@@ -27,7 +29,10 @@ export interface DoctorReport {
 
 export interface DoctorDeps {
   git: Git
-  gh: GitHubClient
+  /** Where `PR_REVIEW_HOST` is read from. */
+  env: NodeJS.ProcessEnv
+  /** The CLI client for the host origin names; without a usable origin, GitHub's is checked. */
+  client: (host: Host) => HostClient
   version: string
   acpxVersion: () => Promise<string | null>
   /** `--data-dir` or `PR_REVIEW_DATA_DIR`; without it the dir sits next to the git common dir. */
@@ -88,7 +93,11 @@ export async function checkSkill(
     }
   }
   if (stale.length > 0) {
-    return { ok: false, detail: `outdated or modified skill: ${stale.join(', ')}`, hint: 'run `pr-review install-skill`' }
+    return {
+      ok: false,
+      detail: `outdated or modified skill: ${stale.join(', ')}`,
+      hint: 'run `pr-review install-skill`',
+    }
   }
   if (found.length === 0) {
     return {
@@ -113,7 +122,10 @@ async function checkAcpx(deps: DoctorDeps): Promise<DoctorCheck> {
 }
 
 /** Runs core checks and, with allChecks, checks acpx for AI Chat. */
-export async function runDoctorChecks(deps: DoctorDeps, options: { allChecks?: boolean } = {}): Promise<DoctorReport> {
+export async function runDoctorChecks(
+  deps: DoctorDeps,
+  options: { allChecks?: boolean } = {}
+): Promise<DoctorReport> {
   let repoRoot: string | null = null
   let git: DoctorCheck
   try {
@@ -123,25 +135,30 @@ export async function runDoctorChecks(deps: DoctorDeps, options: { allChecks?: b
     git = { ok: false, detail: message(err), hint: 'run from a clone or pass --repo <dir>' }
   }
 
+  let host = GITHUB_HOST
   let origin: DoctorCheck
   try {
     const url = await deps.git.remoteUrl('origin')
-    const repo = url === null ? null : parseGithubRemote(url)
-    origin =
-      repo === null
-        ? { ok: false, detail: url ?? 'no origin remote', hint: 'add a github.com origin' }
-        : { ok: true, detail: `${repo.owner}/${repo.name}` }
+    const parsed = url === null ? null : parseOriginRemote(url, deps.env)
+    if (parsed === null) {
+      origin = { ok: false, detail: url ?? 'no origin remote', hint: ORIGIN_HINT }
+    } else {
+      host = parsed.host
+      origin = { ok: true, detail: `${parsed.repo.owner}/${parsed.repo.name} (${host.label})` }
+    }
   } catch (err) {
-    origin = { ok: false, detail: message(err), hint: 'add a github.com origin' }
+    origin = { ok: false, detail: message(err), hint: ORIGIN_HINT }
   }
 
-  const status = await deps.gh.authStatus()
+  // The `gh` keys are the report's public names; for a GitLab origin they describe glab.
+  const status = await deps.client(host).authStatus()
+  const cli = CLI_INFO[host.cli.cli]
   const gh: DoctorCheck = status.installed
     ? { ok: true, detail: status.detail }
-    : { ok: false, detail: status.detail, hint: 'install it from https://cli.github.com' }
+    : { ok: false, detail: status.detail, hint: `install it from ${cli.installUrl}` }
   const ghAuth: DoctorCheck = status.authenticated
     ? { ok: true, detail: status.detail }
-    : { ok: false, detail: status.detail, hint: 'run `gh auth login`' }
+    : { ok: false, detail: status.detail, hint: `run \`${cli.loginCommand}\`` }
 
   let dataDir: DoctorCheck
   try {

package/src/review/normalize.ts

@@ -195,7 +195,9 @@ export function artifactToModelOutput(artifact: ReviewArtifact): ModelOutput {
     summary: artifact.summary,
     layers: artifact.layers.map(layer => {
       const { id: _id, risk, files, ...rest } = layer
-      const modelRisk = risk.filter(r => r.source === 'model').map(r => ({ label: r.label, reason: r.reason ?? '' }))
+      const modelRisk = risk
+        .filter(r => r.source === 'model')
+        .map(r => ({ label: r.label, reason: r.reason ?? '' }))
       const out: ModelLayer = { ...rest, files: files.map(({ isTest: _isTest, ...f }) => f) }
       if (modelRisk.length > 0) {
         out.risk = modelRisk