@vintasoftware/pr-review-canvas 0.1.0

package/src/server/bundle.ts

@@ -0,0 +1,266 @@
+import type { CanvasInfo, PrBundle, SharedCanvasInfo, StaleInfo } from '../contract/api.js'
+import type { CommentsPayload } from '../contract/comments.js'
+import { isLargePr } from '../contract/generation-context.js'
+import type { FileEntry, Pr, ReviewArtifact } from '../contract/review-artifact.js'
+import { discoverSharedCanvas, discoveryFingerprint } from '../github/attachments.js'
+import { fetchComments } from '../github/comments.js'
+import { fetchPrMeta, fetchPrRefs, toPr } from '../github/pr.js'
+import { stateForHead } from '../github/review-body.js'
+import { buildSkillCommand } from '../review/skill-command.js'
+import type { CanvasLookup } from '../store/canvas-store.js'
+import type { AppContext } from './context.js'
+import { AppError } from './errors.js'
+
+export interface BundleOptions {
+  refresh: boolean
+}
+
+export interface DiscoveryRun {
+  sharedCanvas: SharedCanvasInfo | null
+  imported: boolean
+  warnings: string[]
+}
+
+/**
+ * Scans the pull request for an attached canvas and imports the best one. The scan is skipped
+ * while the PR text is the same as at the last scan, unless the caller asks for a fresh run.
+ */
+export async function runDiscovery(
+  ctx: AppContext,
+  pr: Pr,
+  comments: CommentsPayload,
+  opts: { refresh: boolean }
+): Promise<DiscoveryRun> {
+  if (pr.number === null) {
+    return { sharedCanvas: null, imported: false, warnings: [] }
+  }
+  const fingerprint = discoveryFingerprint(pr.body, comments, pr.headSha)
+  const cached = await ctx.prs.readDiscovery(pr.number)
+  if (!opts.refresh && cached !== null && cached.fingerprint === fingerprint) {
+    return { sharedCanvas: cached.sharedCanvas, imported: false, warnings: [] }
+  }
+  const outcome = await discoverSharedCanvas(ctx, pr, comments)
+  await ctx.prs.writeDiscovery(pr.number, {
+    fingerprint,
+    checkedAt: ctx.now().toISOString(),
+    sharedCanvas: outcome.sharedCanvas,
+  })
+  return { sharedCanvas: outcome.sharedCanvas, imported: outcome.imported !== null, warnings: outcome.warnings }
+}
+
+/**
+ * Live PR meta and comments. The first request for a PR in this process always asks GitHub;
+ * later ones answer from `prs/<n>/` unless `refresh` is set, so polling stays cheap.
+ */
+export function createPrLoader(ctx: AppContext) {
+  const refreshed = new Set<number>()
+
+  async function refreshPr(number: number): Promise<{ pr: Pr; comments: CommentsPayload; warnings: string[] }> {
+    const meta = await fetchPrMeta(ctx.gh, ctx.config.repo, number)
+    const shas = await fetchPrRefs(ctx.git, meta)
+    const pr = toPr(meta, ctx.config.repo, shas)
+    await ctx.prs.writePr(pr)
+    const { payload, warnings } = await fetchComments(ctx.gh, ctx.config.repo, number, shas.headSha, ctx.now)
+    await ctx.prs.writeComments(number, payload)
+    refreshed.add(number)
+    return { pr, comments: payload, warnings }
+  }
+
+  return {
+    async load(
+      number: number,
+      opts: BundleOptions
+    ): Promise<{ pr: Pr; comments: CommentsPayload; warnings: string[] }> {
+      if (!opts.refresh && refreshed.has(number)) {
+        const [pr, comments] = await Promise.all([ctx.prs.readPr(number), ctx.prs.readComments(number)])
+        if (pr !== null && comments !== null) {
+          return { pr, comments, warnings: [] }
+        }
+      }
+      return refreshPr(number)
+    },
+    async refreshComments(number: number): Promise<{ comments: CommentsPayload; warnings: string[] }> {
+      const pr = (await ctx.prs.readPr(number)) ?? (await refreshPr(number)).pr
+      const { payload, warnings } = await fetchComments(ctx.gh, ctx.config.repo, number, pr.headSha, ctx.now)
+      await ctx.prs.writeComments(number, payload)
+      return { comments: payload, warnings }
+    },
+    async currentPr(number: number): Promise<Pr> {
+      return (await ctx.prs.readPr(number)) ?? (await refreshPr(number)).pr
+    },
+  }
+}
+export type PrLoader = ReturnType<typeof createPrLoader>
+
+/** Whether the change set on screen is large, counted from the files the page is showing. */
+function largePrOf(files: readonly FileEntry[]): boolean {
+  return isLargePr({
+    files: files.length,
+    additions: files.reduce((n, f) => n + f.additions, 0),
+    deletions: files.reduce((n, f) => n + f.deletions, 0),
+  })
+}
+
+/** Dev fixture: the committed artifact presented as the canvas of the live PR head. */
+export function rekeyFixture(fixture: ReviewArtifact, pr: Pr): ReviewArtifact {
+  return { ...fixture, pr, source: 'local' }
+}
+
+/**
+ * The stored canvas and the block that describes it. Null when review.json was written by an
+ * older tool version: the page then offers to generate a new one.
+ */
+async function loadCanvas(
+  ctx: AppContext,
+  found: Extract<CanvasLookup, { headSha: string }>
+): Promise<{ artifact: ReviewArtifact; canvas: CanvasInfo } | null> {
+  let artifact: ReviewArtifact | null
+  try {
+    artifact = await ctx.canvases.readArtifact(found.headSha)
+  } catch {
+    return null
+  }
+  if (artifact === null) {
+    throw new AppError('CANVAS_INVALID', `index lists ${found.headSha} but review.json is missing`, 500)
+  }
+  const canvas: CanvasInfo = {
+    headSha: found.headSha,
+    source: artifact.source,
+    manifest: await ctx.canvases.readManifest(found.headSha),
+  }
+  if (artifact.importedAt !== undefined) {
+    canvas.importedAt = artifact.importedAt
+  }
+  return { artifact, canvas }
+}
+
+/** The diffs of one canvas: the stored ones, or freshly built when both commits are local. */
+async function readOrBuildDerived(
+  ctx: AppContext,
+  headSha: string,
+  mergeBaseSha: string | undefined
+): Promise<{ files: FileEntry[] } | null> {
+  const stored = await ctx.derived.read(headSha)
+  if (stored !== null || mergeBaseSha === undefined) {
+    return stored
+  }
+  if (!(await ctx.derived.derivable(headSha, mergeBaseSha))) {
+    return null
+  }
+  return ctx.derived.ensure(headSha, mergeBaseSha)
+}
+
+export async function resolveBundle(
+  ctx: AppContext,
+  loader: PrLoader,
+  number: number,
+  opts: BundleOptions
+): Promise<PrBundle> {
+  const { pr, comments, warnings } = await loader.load(number, opts)
+  const allWarnings = [...ctx.projectConfig.warnings, ...warnings]
+
+  const derivable = await ctx.derived.derivable(pr.headSha, pr.mergeBaseSha)
+  let files: FileEntry[] = []
+  if (derivable) {
+    files = (await ctx.derived.ensure(pr.headSha, pr.mergeBaseSha)).files
+  } else {
+    allWarnings.push('the PR head or merge base is not in the local clone; diffs are not available')
+  }
+
+  const chatEnabled = ctx.projectConfig.config.chat.enabled
+  const [stored, capabilities, settings, acpx] = await Promise.all([
+    ctx.state.read(number),
+    ctx.capabilities.get(),
+    chatEnabled ? ctx.chat.effectiveSettings() : Promise.resolve(null),
+    chatEnabled ? ctx.preflight.get() : Promise.resolve({ installed: false, version: null }),
+  ])
+  if (chatEnabled && !acpx.installed) {
+    allWarnings.push('acpx is not on PATH, so the AI Chat pane is off; install acpx to turn it on')
+  }
+  // Marks made on another commit describe other code, so the page never shows them as reviewed.
+  const state = stateForHead(stored, pr.headSha)
+  const base = {
+    pr,
+    files,
+    derivable,
+    comments,
+    state,
+    capabilities,
+    chat: {
+      enabled: chatEnabled && acpx.installed,
+      acpx: acpx.installed,
+      ...(settings === null ? {} : { agent: settings.agent, model: settings.model }),
+    },
+    largePr: largePrOf(files),
+    warnings: allWarnings,
+  }
+
+  if (ctx.fixtureArtifact !== null) {
+    const artifact = rekeyFixture(ctx.fixtureArtifact, pr)
+    const canvas: CanvasInfo = { headSha: pr.headSha, source: 'fixture', manifest: null }
+    allWarnings.push('showing the --fixture-canvas artifact (dev only)')
+    return {
+      ...base,
+      status: 'ready',
+      artifact,
+      canvas,
+      files: files.length > 0 ? files : artifact.files,
+      largePr: largePrOf(files.length > 0 ? files : artifact.files),
+      skillCommand: buildSkillCommand(number, { force: true }),
+    }
+  }
+
+  let found = await ctx.canvases.findForPr(number, pr.headSha)
+  let sharedCanvas: SharedCanvasInfo | null = null
+  // A canvas for this very head beats anything attached to the PR, so discovery runs only
+  // when there is none, and its import can turn a stale or missing bundle into a ready one.
+  if (found.status !== 'ready') {
+    const discovery = await runDiscovery(ctx, pr, comments, { refresh: opts.refresh })
+    sharedCanvas = discovery.sharedCanvas
+    allWarnings.push(...discovery.warnings)
+    if (discovery.imported) {
+      found = await ctx.canvases.findForPr(number, pr.headSha)
+    }
+  }
+  const shared = sharedCanvas === null ? {} : { sharedCanvas }
+
+  if (found.status === 'missing') {
+    return { ...base, ...shared, status: 'missing', skillCommand: buildSkillCommand(number, { force: false }) }
+  }
+  const loaded = await loadCanvas(ctx, found)
+  if (loaded === null) {
+    allWarnings.push(`the canvas for ${found.headSha.slice(0, 7)} does not match the current format; regenerate it`)
+    return { ...base, ...shared, status: 'missing', skillCommand: buildSkillCommand(number, { force: true }) }
+  }
+  // A canvas exists for this PR, so regenerating always needs --force.
+  const skillCommand = buildSkillCommand(number, { force: true })
+  if (found.status === 'ready') {
+    return { ...base, ...shared, ...loaded, status: 'ready', skillCommand }
+  }
+  const stale: StaleInfo = {
+    canvasHeadSha: found.headSha,
+    currentHeadSha: pr.headSha,
+    relation: found.relation,
+  }
+  if (found.commitsBehind !== undefined) {
+    stale.commitsBehind = found.commitsBehind
+  }
+  // The page shows the canvas of the older commit, so the files and the diffs are that commit's.
+  // They are rebuilt when the clone has the commits, which is how a canvas imported before the
+  // fetch becomes readable once the commits arrive.
+  const staleDerived = await readOrBuildDerived(ctx, found.headSha, loaded.canvas.manifest?.mergeBaseSha)
+  // A stale canvas describes an older commit, so its own files decide both the diffs and
+  // whether the notice about large change sets belongs on the page.
+  const staleFiles = staleDerived?.files ?? loaded.artifact.files
+  return {
+    ...base,
+    ...shared,
+    ...loaded,
+    files: staleFiles,
+    largePr: largePrOf(staleFiles),
+    derivable: staleDerived !== null,
+    status: 'stale',
+    stale,
+    skillCommand,
+  }
+}

package/src/server/capped-body.ts

@@ -0,0 +1,62 @@
+// Reading a request or response body under a size limit. Both the attachment download and the
+// canvas upload go through this, so a body that never ends, or one that lies about its length,
+// stops at the limit instead of growing without bound.
+
+/** The bytes of the body. Throws BodyTooLargeError as soon as it grows past `cap`. */
+export async function readCappedStream(
+  body: ReadableStream<Uint8Array> | null,
+  cap: number
+): Promise<Uint8Array<ArrayBuffer>> {
+  if (body === null) {
+    return new Uint8Array(0)
+  }
+  const reader = body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) {
+        break
+      }
+      total += value.length
+      if (total > cap) {
+        throw new BodyTooLargeError(cap)
+      }
+      chunks.push(value)
+    }
+  } finally {
+    await reader.cancel().catch(() => undefined)
+  }
+  const out = new Uint8Array(total)
+  let at = 0
+  for (const chunk of chunks) {
+    out.set(chunk, at)
+    at += chunk.length
+  }
+  return out
+}
+
+export class BodyTooLargeError extends Error {
+  readonly cap: number
+  constructor(cap: number) {
+    super(`the body is larger than ${cap} bytes`)
+    this.name = 'BodyTooLargeError'
+    this.cap = cap
+  }
+}
+
+/**
+ * The body of one HTTP message under a cap. A `Content-Length` above the cap is refused before a
+ * byte is read; a body that lies about its length is stopped mid-stream.
+ */
+export async function readCappedBody(
+  message: { headers: Headers; body: ReadableStream<Uint8Array> | null },
+  cap: number
+): Promise<Uint8Array<ArrayBuffer>> {
+  const declared = Number(message.headers.get('content-length') ?? '')
+  if (Number.isFinite(declared) && declared > cap) {
+    throw new BodyTooLargeError(cap)
+  }
+  return readCappedStream(message.body, cap)
+}

package/src/server/context.ts

@@ -0,0 +1,174 @@
+import { createRequire } from 'node:module'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { type AgentRunner, createAgentRunner } from '../acpx/acpx.js'
+import { type AgentDirectory, createAgentDirectory } from '../acpx/agents.js'
+import { createPreflightProbe, type PreflightProbe } from '../acpx/preflight.js'
+import { type ChatManager, createChatManager } from '../chat/chat-manager.js'
+import type { PromptOverrides } from '../project-config.js'
+import { loadSeedTemplate } from '../chat/seed.js'
+import { createTranscriptStore, type TranscriptStore } from '../chat/threads.js'
+import type { RuntimeConfig } from '../config.js'
+import type { ReviewArtifact } from '../contract/review-artifact.js'
+import { createGit, type Git } from '../git/git.js'
+import { type CapabilityProbe, createCapabilityProbe } from '../github/capabilities.js'
+import { createGitHubClient, type GitHubClient } from '../github/gh.js'
+import { PACKAGE_ROOT, STATIC_DIR } from '../paths.js'
+import type { LoadedProjectConfig } from '../project-config.js'
+import { type CanvasStore, createCanvasStore } from '../store/canvas-store.js'
+import { repoDir } from '../store/data-dir.js'
+import { createDerivedStore, type DerivedStore } from '../store/derived-store.js'
+import { createPrStore, type PrStore } from '../store/pr-store.js'
+import { createSettingsStore, type SettingsStore } from '../store/settings-store.js'
+import { createStateStore, type StateStore } from '../store/state-store.js'
+
+/** Directory roots the `/vendor/*` route may serve from. Exact files are listed in routes/static.ts. */
+export interface VendorRoots {
+  diff: string
+  marked: string
+  dompurify: string
+  hljs: string
+  mermaid: string
+}
+
+/**
+ * Everything a route or pipeline needs, as a plain object. Real adapters are built once by
+ * `createAppContext`; tests assemble their own with fakes and a temp data dir.
+ */
+export interface AppContext {
+  config: RuntimeConfig
+  projectConfig: LoadedProjectConfig
+  git: Git
+  gh: GitHubClient
+  /** The only outbound HTTP the tool makes: attachment downloads. Tests inject a fake. */
+  fetch: typeof fetch
+  canvases: CanvasStore
+  derived: DerivedStore
+  prs: PrStore
+  state: StateStore
+  /** What this GitHub login may post here, probed once and reused for ten minutes. */
+  capabilities: CapabilityProbe
+  /** Personal chat settings, in `.pr-review/settings.yml`. */
+  settings: SettingsStore
+  /** Which chat agents can run right now, and the one-shot probe behind the settings dialog. */
+  agents: AgentDirectory
+  /** Is acpx itself installed? A missing acpx disables the chat pane with a banner. */
+  preflight: PreflightProbe
+  chat: ChatManager
+  transcripts: TranscriptStore
+  now: () => Date
+  version: string
+  staticDir: string
+  vendorRoots: VendorRoots
+  fixtureArtifact: ReviewArtifact | null
+}
+
+export { PACKAGE_ROOT, STATIC_DIR }
+
+const require = createRequire(import.meta.url)
+
+export function resolveVendorRoots(): VendorRoots {
+  return {
+    diff: path.dirname(fileURLToPath(import.meta.resolve('diff'))),
+    marked: fileURLToPath(import.meta.resolve('marked')),
+    dompurify: fileURLToPath(import.meta.resolve('dompurify')),
+    hljs: path.join(path.dirname(require.resolve('@highlightjs/cdn-assets/package.json')), 'es', 'highlight.min.js'),
+    mermaid: path.dirname(fileURLToPath(import.meta.resolve('mermaid'))),
+  }
+}
+
+export function readPackageVersion(): string {
+  const pkg = require(path.join(PACKAGE_ROOT, 'package.json')) as { version: string }
+  return pkg.version
+}
+
+export interface StoreSet {
+  canvases: CanvasStore
+  derived: DerivedStore
+  prs: PrStore
+  state: StateStore
+}
+
+/** The four stores over one repo directory. Shared by the real context and by tests. */
+export function createStores(dataDir: string, config: RuntimeConfig, git: Git, now: () => Date): StoreSet {
+  const root = repoDir(dataDir, config.repo)
+  const canvases = createCanvasStore(root, git)
+  const prs = createPrStore(root)
+  return {
+    canvases,
+    derived: createDerivedStore(canvases, git, now),
+    prs,
+    state: createStateStore(prs, now),
+  }
+}
+
+export interface CreateAppContextOptions {
+  config: RuntimeConfig
+  projectConfig: LoadedProjectConfig
+  fixtureArtifact: ReviewArtifact | null
+  git?: Git
+  gh?: GitHubClient
+  fetch?: typeof fetch
+  runner?: AgentRunner
+  now?: () => Date
+}
+
+export interface ChatSet {
+  settings: SettingsStore
+  agents: AgentDirectory
+  preflight: PreflightProbe
+  chat: ChatManager
+  transcripts: TranscriptStore
+}
+
+/** The chat side of the context, built over the same stores. Shared by the real context and tests. */
+export function createChatSet(
+  config: RuntimeConfig,
+  runner: AgentRunner,
+  stores: StoreSet,
+  now: () => Date,
+  prompts?: PromptOverrides
+): ChatSet {
+  const settings = createSettingsStore(config.dataDir)
+  const preflight = createPreflightProbe(runner, now)
+  const transcripts = createTranscriptStore(number => stores.prs.prDir(number))
+  return {
+    settings,
+    preflight,
+    transcripts,
+    agents: createAgentDirectory({ runner, preflight, cwd: config.repoRoot, now }),
+    chat: createChatManager({
+      runner,
+      settings,
+      state: stores.state,
+      transcripts,
+      repo: config.repo,
+      repoRoot: config.repoRoot,
+      overrides: config.chatOverrides,
+      loadSeedTemplate: () => loadSeedTemplate(undefined, { repoRoot: config.repoRoot, overrides: prompts }),
+      now,
+    }),
+  }
+}
+
+export function createAppContext(opts: CreateAppContextOptions): AppContext {
+  const git = opts.git ?? createGit(opts.config.repoRoot)
+  const now = opts.now ?? (() => new Date())
+  const gh = opts.gh ?? createGitHubClient()
+  const stores = createStores(opts.config.dataDir, opts.config, git, now)
+  return {
+    config: opts.config,
+    projectConfig: opts.projectConfig,
+    git,
+    gh,
+    capabilities: createCapabilityProbe(gh, opts.config.repo, now),
+    fetch: opts.fetch ?? ((input, init) => globalThis.fetch(input, init)),
+    ...stores,
+    ...createChatSet(opts.config, opts.runner ?? createAgentRunner(), stores, now, opts.projectConfig.config.prompts),
+    now,
+    version: readPackageVersion(),
+    staticDir: STATIC_DIR,
+    vendorRoots: resolveVendorRoots(),
+    fixtureArtifact: opts.fixtureArtifact,
+  }
+}

package/src/server/env.ts

@@ -0,0 +1,7 @@
+/** What the middleware puts on the request context. Hono types every route from this. */
+export interface AppEnv {
+  Variables: {
+    /** The nonce of this response's inline scripts, set by `responseHeaders`. */
+    cspNonce: string
+  }
+}

package/src/server/errors.ts

@@ -0,0 +1,65 @@
+import type { ContentfulStatusCode } from 'hono/utils/http-status'
+import { ConfigError } from '../config.js'
+import type { ErrorCode, ErrorEnvelope } from '../contract/api.js'
+import { GitError } from '../git/git.js'
+import { GitHubApiError } from '../github/gh.js'
+import { PrNotFoundError } from '../github/pr.js'
+
+export class AppError extends Error {
+  readonly code: ErrorCode
+  readonly status: ContentfulStatusCode
+  readonly hint: string | undefined
+  /** What a rejected file got wrong, one line each. Never the file's content. */
+  readonly issues: string[] | undefined
+
+  constructor(code: ErrorCode, message: string, status: ContentfulStatusCode, hint?: string, issues?: string[]) {
+    super(message)
+    this.name = 'AppError'
+    this.code = code
+    this.status = status
+    this.hint = hint
+    this.issues = issues
+  }
+
+  toEnvelope(): ErrorEnvelope {
+    const error: ErrorEnvelope['error'] = { code: this.code, message: this.message }
+    if (this.hint !== undefined) {
+      error.hint = this.hint
+    }
+    if (this.issues !== undefined) {
+      error.issues = this.issues
+    }
+    return { error }
+  }
+}
+
+/** Maps every error the routes can see to one AppError, so the envelope is built in one place. */
+export function toAppError(err: unknown): AppError {
+  if (err instanceof AppError) {
+    return err
+  }
+  if (err instanceof PrNotFoundError) {
+    return new AppError('PR_NOT_FOUND', err.message, 404, 'check the number and that origin is the right repository')
+  }
+  if (err instanceof GitHubApiError) {
+    if (err.missingBinary) {
+      return new AppError(
+        'GH_MISSING',
+        'the GitHub CLI (gh) is not installed',
+        500,
+        'install it from https://cli.github.com'
+      )
+    }
+    if (err.unauthenticated) {
+      return new AppError('GH_UNAUTHENTICATED', 'gh is not logged in', 401, 'run `gh auth login`')
+    }
+    return new AppError('GITHUB_API_ERROR', err.message, 502)
+  }
+  if (err instanceof GitError) {
+    return new AppError('GIT_ERROR', err.message, 500)
+  }
+  if (err instanceof ConfigError) {
+    return new AppError(err.code, err.message, 500, err.hint)
+  }
+  return new AppError('INTERNAL', err instanceof Error ? err.message : String(err), 500)
+}