@vintasoftware/pr-review-canvas 0.2.0 → 0.4.0

package/src/review/prepare.ts

@@ -2,16 +2,25 @@
 // the canvas directory. The agent reads those two files; publish reads context.json back.
 import { appendFile, readdir, rm } from 'node:fs/promises'
 import path from 'node:path'
-import { type GenerationContext, isLargePr, type PrepareTarget } from '../contract/generation-context.js'
+import {
+  type GenerationContext,
+  isLargePr,
+  type PrepareTarget,
+  type PrepareTargetInput,
+} from '../contract/generation-context.js'
 import { effectiveCaps, LIMITS, type Pr } from '../contract/review-artifact.js'
-import { fetchPrMeta, fetchPrRefs, toPr } from '../github/pr.js'
+import type { LocalKey } from '../contract/review-key.js'
+import { describeLocalWork, resolveLocalBase, UNCOMMITTED_STATE } from '../git/local-target.js'
+import { fetchPrRefs } from '../git/pr-refs.js'
+
+import { toPr } from '../host/pr.js'
 import type { AppContext } from '../server/context.js'
 import { readText, writeJsonAtomic, writeTextAtomic } from '../store/atomic-json.js'
 import { loadPromptSources, type PromptSources, renderPrompt } from './prompt.js'
 
 export interface PrepareOptions {
   force: boolean
-  /** Progress lines: `fetch-pr`, `fetch-refs`, `collect-diffs`, `prompt`. */
+  /** Progress lines: `fetch-pr`, `fetch-refs`, `snapshot`, `collect-diffs`, `prompt`. */
   log: (phase: string) => void
   promptSources?: PromptSources
 }
@@ -23,21 +32,50 @@ export interface PrepareResult {
   promptPath: string
   contextPath: string
   status: 'prepared' | 'exists'
+  /** Local targets only: which review it is, the base resolved for it, and what its head holds. */
+  local?: { review: LocalKey; base: string; headRef: string; uncommitted: boolean }
 }
 
 /** The PR meta, live from GitHub, with the head and base refs fetched into the local clone. */
 async function resolvePr(ctx: AppContext, number: number, log: PrepareOptions['log']): Promise<Pr> {
   log('fetch-pr')
-  const meta = await fetchPrMeta(ctx.gh, ctx.config.repo, number)
+  const meta = await ctx.config.host.fetchPrMeta(ctx.gh, ctx.config.repo, number)
   log('fetch-refs')
-  const shas = await fetchPrRefs(ctx.git, meta)
+  const shas = await fetchPrRefs(ctx.git, ctx.config.host, meta)
   const pr = toPr(meta, ctx.config.repo, shas)
-  await ctx.prs.writePr(pr)
+  await ctx.prs.writePr(number, pr)
+  return pr
+}
+
+/**
+ * The work in this clone that has no pull request yet: the current branch, or a snapshot commit
+ * of the working tree when it carries edits. The meta is cached under `prs/<branch|uncommitted>/`,
+ * which is what the matching page reads.
+ */
+async function resolveLocal(
+  ctx: AppContext,
+  target: Extract<PrepareTarget, { kind: 'local' }>,
+  log: PrepareOptions['log']
+): Promise<Pr> {
+  log('snapshot')
+  const pr = await describeLocalWork(ctx.git, {
+    base: target.base,
+    source: target.source,
+    repo: ctx.config.repo,
+    now: ctx.now,
+  })
+  await ctx.prs.writePr(target.source, pr)
+  await ctx.prs.writeLocalTarget(target.source, target)
   return pr
 }
 
 /** A change set before a PR exists: the refs must already be in the clone. */
-async function resolveRefs(ctx: AppContext, base: string, head: string, log: PrepareOptions['log']): Promise<Pr> {
+async function resolveRefs(
+  ctx: AppContext,
+  base: string,
+  head: string,
+  log: PrepareOptions['log']
+): Promise<Pr> {
   log('fetch-refs')
   const headSha = await ctx.git.revParse(head)
   const mergeBaseSha = await ctx.git.mergeBase(base, headSha)
@@ -48,7 +86,7 @@ async function resolveRefs(ctx: AppContext, base: string, head: string, log: Pre
     title: head,
     body: '',
     author,
-    url: `https://github.com/${repo.owner}/${repo.name}/compare/${base}...${head}`,
+    url: ctx.config.host.compareUrl(repo, base, head),
     state: 'pre-pr',
     draft: false,
     updatedAt: ctx.now().toISOString(),
@@ -93,21 +131,44 @@ async function clearCanvasDir(canvasDir: string): Promise<void> {
   }
 }
 
-export async function prepare(ctx: AppContext, target: PrepareTarget, opts: PrepareOptions): Promise<PrepareResult> {
+/** The target with its base resolved, which is the form `context.json` records. */
+async function resolveTarget(ctx: AppContext, input: PrepareTargetInput): Promise<PrepareTarget> {
+  if (input.kind !== 'local') {
+    return input
+  }
+  return { kind: 'local', source: input.source, base: await resolveLocalBase(ctx.git, input.base) }
+}
+
+export async function prepare(
+  ctx: AppContext,
+  input: PrepareTargetInput,
+  opts: PrepareOptions
+): Promise<PrepareResult> {
+  const target = await resolveTarget(ctx, input)
   const pr =
     target.kind === 'pr'
       ? await resolvePr(ctx, target.number, opts.log)
-      : await resolveRefs(ctx, target.base, target.head, opts.log)
+      : target.kind === 'local'
+        ? await resolveLocal(ctx, target, opts.log)
+        : await resolveRefs(ctx, target.base, target.head, opts.log)
   const canvasDir = ctx.canvases.canvasDir(pr.headSha)
   const promptPath = path.join(canvasDir, 'prompt.md')
   const contextPath = path.join(canvasDir, 'context.json')
-  const result = {
+  const result: Omit<PrepareResult, 'status'> = {
     canvasDir,
     headSha: pr.headSha,
     mergeBaseSha: pr.mergeBaseSha,
     promptPath,
     contextPath,
   }
+  if (target.kind === 'local') {
+    result.local = {
+      review: target.source,
+      base: target.base,
+      headRef: pr.headRef,
+      uncommitted: pr.state === UNCOMMITTED_STATE,
+    }
+  }
   if (!opts.force && (await ctx.canvases.exists(pr.headSha))) {
     return { ...result, status: 'exists' }
   }
@@ -116,7 +177,10 @@ export async function prepare(ctx: AppContext, target: PrepareTarget, opts: Prep
   const derived = await ctx.derived.ensure(pr.headSha, pr.mergeBaseSha)
   const additions = derived.files.reduce((n, f) => n + f.additions, 0)
   const deletions = derived.files.reduce((n, f) => n + f.deletions, 0)
-  const fullPr: Pr = target.kind === 'pr' ? pr : { ...pr, additions, deletions, changedFiles: derived.files.length }
+  // A pull request's counts are the forge's; anything else is counted from the diff itself. The
+  // page derives its own from the files it shows, so this is only what the canvas records.
+  const fullPr: Pr =
+    target.kind === 'pr' ? pr : { ...pr, additions, deletions, changedFiles: derived.files.length }
   const derivedDir = ctx.derived.derivedDir(pr.headSha)
   const config = ctx.projectConfig.config
 
@@ -152,14 +216,20 @@ export async function prepare(ctx: AppContext, target: PrepareTarget, opts: Prep
     largePr: isLargePr({ files: derived.files.length, additions, deletions }),
     preparedAt: ctx.now().toISOString(),
   }
-  const sources = opts.promptSources ?? (await loadPromptSources(undefined, {
-    repoRoot: ctx.config.repoRoot,
-    overrides: ctx.projectConfig.config.prompts,
-  }))
+  const sources =
+    opts.promptSources ??
+    (await loadPromptSources(undefined, {
+      repoRoot: ctx.config.repoRoot,
+      overrides: ctx.projectConfig.config.prompts,
+    }))
   await clearCanvasDir(canvasDir)
   await writeTextAtomic(promptPath, renderPrompt(context, derived.patches, sources))
   await writeJsonAtomic(contextPath, context)
   // The log keeps the whole history; publish counts attempts from this line on.
-  await appendFile(path.join(canvasDir, 'publish.log'), `${context.preparedAt} prepared ${pr.headSha}\n`, 'utf8')
+  await appendFile(
+    path.join(canvasDir, 'publish.log'),
+    `${context.preparedAt} prepared ${pr.headSha}\n`,
+    'utf8'
+  )
   return { ...result, status: 'prepared' }
 }

package/src/review/prompt.ts

@@ -71,7 +71,9 @@ function configuredLayersMarkdown(ctx: GenerationContext): string {
   return ctx.defaultLayers
     .map((l, i) => {
       const paths =
-        l.paths === undefined || l.paths.length === 0 ? '' : ` Path hints: ${l.paths.map(p => `\`${p}\``).join(', ')}.`
+        l.paths === undefined || l.paths.length === 0
+          ? ''
+          : ` Path hints: ${l.paths.map(p => `\`${p}\``).join(', ')}.`
       return `${i + 1}. \`${l.id}\` **${l.title}** — ${l.description}${paths}`
     })
     .join('\n')
@@ -196,7 +198,11 @@ export function schemaMarkdown(ctx: GenerationContext): string {
 }
 
 /** Selects one task and fills its data and format placeholders before the generator sees it. */
-export function renderPrompt(ctx: GenerationContext, patches: Record<string, string>, sources: PromptSources): string {
+export function renderPrompt(
+  ctx: GenerationContext,
+  patches: Record<string, string>,
+  sources: PromptSources
+): string {
   const tokens: Record<string, string> = {
     TARGET_WORD: ctx.target.kind === 'pr' ? 'pull request' : 'change set',
     META: metaMarkdown(ctx),

package/src/review/publish.ts

@@ -1,14 +1,18 @@
 // `pr-review publish`: validate model.json against context.json, normalize, and store the
-// canvas. Nothing is written when the report is not clean.
+// canvas, then share it on the PR/MR. Invalid models are never stored or shared.
+import { buildCanvasComment } from '../canvas/comment.js'
+import { buildCanvasZipFor, exportCanvas } from '../canvas/export.js'
 import { appendFile } from 'node:fs/promises'
 import path from 'node:path'
 import type { CanvasManifest } from '../contract/canvas-manifest.js'
 import { type GenerationContext, GenerationContextSchema } from '../contract/generation-context.js'
 import type { Generator, ReviewArtifact } from '../contract/review-artifact.js'
+import { UNCOMMITTED_STATE, resolveLocalHead } from '../git/local-target.js'
 import type { ValidationError, ValidationReport } from '../contract/validation.js'
-import { fetchPrMeta } from '../github/pr.js'
+import { fetchPrRefs } from '../git/pr-refs.js'
 import type { AppContext } from '../server/context.js'
 import { readJson, readText } from '../store/atomic-json.js'
+import { standsForHead } from './carry-over.js'
 import { normalize } from './normalize.js'
 import { coveredTestPaths, type ValidationInput, validateModelOutput } from './validate.js'
 
@@ -24,7 +28,11 @@ export interface PublishResult {
   headSha: string
   reviewJsonPath: string
   attempts: number
-  /** Where the canvas shows once the server runs; absent for a change set without a PR. */
+  sharing:
+    | { status: 'shared'; url: string }
+    | { status: 'failed'; warning: string; zipPath: string }
+    | { status: 'local' }
+  /** Where the canvas shows once the server runs; absent only for a `--base/--head` change set. */
   reviewUrl?: string
 }
 
@@ -75,17 +83,40 @@ async function readModel(canvasDir: string): Promise<{ raw: unknown } | { error:
   const file = path.join(canvasDir, 'model.json')
   const text = await readText(file)
   if (text === null) {
-    throw new PublishError('NOT_FOUND', `${file} does not exist`, 'write the model output there and publish again')
+    throw new PublishError(
+      'NOT_FOUND',
+      `${file} does not exist`,
+      'write the model output there and publish again'
+    )
   }
   return parseModelText(text, 'model.json')
 }
 
-/** The current head of the target; a push during generation makes the prepared context stale. */
-async function currentHead(ctx: AppContext, context: GenerationContext): Promise<string> {
+/**
+ * The current head of the target; a push during generation makes the prepared context stale. For
+ * a pull request whose head moved, the head and base are fetched again, and a head whose diff is
+ * identical to the prepared commit's still counts as that commit. For a local target the working
+ * tree is snapshotted again, so an edit made while the agent worked is caught the same way a push
+ * is.
+ */
+async function currentHead(
+  ctx: AppContext,
+  context: GenerationContext
+): Promise<{ headSha: string; moved: boolean }> {
   if (context.target.kind === 'pr') {
-    return (await fetchPrMeta(ctx.gh, ctx.config.repo, context.target.number)).headSha
+    const { host, repo } = ctx.config
+    const meta = await host.fetchPrMeta(ctx.gh, repo, context.target.number)
+    if (meta.headSha === context.headSha || !ctx.projectConfig.config.canvas.keepForIdenticalDiff) {
+      return { headSha: meta.headSha, moved: meta.headSha !== context.headSha }
+    }
+    const head = await fetchPrRefs(ctx.git, host, meta)
+    return { headSha: head.headSha, moved: !(await standsForHead(ctx, head, context)) }
   }
-  return ctx.git.revParse(context.target.head)
+  const headSha =
+    context.target.kind === 'local'
+      ? (await resolveLocalHead(ctx.git, context.target.source)).headSha
+      : await ctx.git.revParse(context.target.head)
+  return { headSha, moved: headSha !== context.headSha }
 }
 
 /** Publish runs since prepare last wrote a context (its `prepared` line), this one included. */
@@ -141,7 +172,11 @@ export async function validationInput(
   }
 }
 
-export function buildManifest(context: GenerationContext, artifact: ReviewArtifact, version: string): CanvasManifest {
+export function buildManifest(
+  context: GenerationContext,
+  artifact: ReviewArtifact,
+  version: string
+): CanvasManifest {
   const manifest: CanvasManifest = {
     formatVersion: 1,
     tool: { name: 'pr-review', version },
@@ -159,14 +194,18 @@ export function buildManifest(context: GenerationContext, artifact: ReviewArtifa
   return manifest
 }
 
-export async function publish(ctx: AppContext, canvasDir: string, opts: PublishOptions): Promise<PublishResult> {
+export async function publish(
+  ctx: AppContext,
+  canvasDir: string,
+  opts: PublishOptions
+): Promise<PublishResult> {
   const context = await readContext(canvasDir)
   if (!opts.allowStale) {
     const head = await currentHead(ctx, context)
-    if (head !== context.headSha) {
+    if (head.moved) {
       throw new PublishError(
         'CANVAS_STALE',
-        `the target moved to ${head.slice(0, 7)} while this canvas was prepared for ${context.headSha.slice(0, 7)}`,
+        `the target moved to ${head.headSha.slice(0, 7)} while this canvas was prepared for ${context.headSha.slice(0, 7)}`,
         'run `pr-review prepare` again, or pass --allow-stale to publish for the old commit'
       )
     }
@@ -195,15 +234,39 @@ export async function publish(ctx: AppContext, canvasDir: string, opts: PublishO
     testPatterns: context.tests.patterns,
   })
   const manifest = buildManifest(context, artifact, ctx.version)
-  await ctx.canvases.write(context.headSha, artifact, manifest, manifest.prNumber)
+  // A snapshot commit is on no branch, so it must never be offered as a pull request's canvas.
+  const worktree = context.target.kind === 'local' && context.pr.state === UNCOMMITTED_STATE
+  await ctx.canvases.write(context.headSha, artifact, manifest, manifest.prNumber, { worktree })
+  if (worktree) {
+    // The snapshot ref moves with the working tree. This canvas stays, and the page reads its
+    // diffs from its own commit, so it gets an anchor that the next edit cannot take away.
+    await ctx.git.anchorCommit(context.headSha)
+  }
   const published: PublishResult = {
     status: 'published',
+    sharing: { status: 'local' },
     headSha: context.headSha,
     reviewJsonPath: path.join(ctx.canvases.canvasDir(context.headSha), 'review.json'),
     attempts,
   }
+  if (context.target.kind === 'local') {
+    published.reviewUrl = `http://localhost:${ctx.config.port}/review/${context.target.source}`
+  }
   if (context.target.kind === 'pr') {
     published.reviewUrl = `http://localhost:${ctx.config.port}/review/${context.target.number}`
+    try {
+      const zip = await buildCanvasZipFor(ctx, context.headSha, context.target.number)
+      const body = buildCanvasComment(zip, ctx.config.host.canvasCommentLimit)
+      const url = await ctx.config.host.shareCanvas(ctx.gh, ctx.config.repo, context.target.number, body)
+      published.sharing = { status: 'shared', url }
+    } catch (err) {
+      const exported = await exportCanvas(ctx, { headSha: context.headSha, prNumber: context.target.number })
+      published.sharing = {
+        status: 'failed',
+        warning: `Automatic canvas sharing failed: ${err instanceof Error ? err.message : String(err)}. Upload the ZIP to the ${ctx.config.host.noun} description manually.`,
+        zipPath: exported.path,
+      }
+    }
   }
   return published
 }

package/src/{github → review}/review-body.ts

@@ -1,14 +1,15 @@
 // The same reviewed rules the page uses, so the body and the header never disagree.
 import { layerProgress } from '../../static/js/progress.js'
 import type { CommentsPayload } from '../contract/comments.js'
-import type { Layer, ReviewArtifact } from '../contract/review-artifact.js'
+import type { Layer, Pr, ReviewArtifact } from '../contract/review-artifact.js'
 import type { PrState } from '../contract/state.js'
+import type { CanvasLookup } from '../store/canvas-store.js'
 
 export const REVIEW_BODY_FOOTER = 'Reviewed with the pr-review canvas (localhost).'
 
 /**
  * Model text on one line of a list. Markdown characters are escaped so a title cannot open a
- * heading, a link, or a code span in the review GitHub publishes.
+ * heading, a link, or a code span in the published review.
  */
 export function inlineText(text: string): string {
   return text
@@ -18,11 +19,22 @@ export function inlineText(text: string): string {
 }
 
 /**
- * The state as it applies to one commit. Marks made on another commit, and marks whose commit
+ * The state as it applies to one canvas. Marks made on another canvas, and marks whose canvas
  * is unknown, describe other code, so they count for nothing here.
  */
-export function stateForHead(state: PrState, headSha: string): PrState {
-  return state.reviewedHeadSha === headSha ? state : { ...state, reviewed: {} }
+export function stateForCanvas(state: PrState, canvasSha: string): PrState {
+  return state.reviewedCanvasSha === canvasSha ? state : { ...state, reviewed: {} }
+}
+
+/**
+ * The commit the marks on this page describe: the commit of the canvas on the page, whether it is
+ * current, carried over, or read as outdated, since its diff is what the reviewer looked at. The
+ * head only when there is no canvas. Keyed this way, a carried-over canvas keeps its marks however
+ * often the head moves, and marks made on an outdated canvas never credit a later one. The page
+ * sends this commit back with every mark it makes, as `bundle.canvas.headSha`.
+ */
+export function reviewedCommit(found: CanvasLookup, pr: Pr): string {
+  return found.status === 'missing' ? pr.headSha : found.headSha
 }
 
 /** The layers a human still has to look at. Empty means approve is allowed. */

package/src/review/skill-command.ts

@@ -1,4 +1,6 @@
-/** The exact command the user runs in Claude Code or Codex to generate a canvas for a PR. */
-export function buildSkillCommand(prNumber: number, opts: { force: boolean }): string {
-  return `/pr-review-canvas ${prNumber}${opts.force ? ' --force' : ''}`
+import { keyToString, type ReviewKey } from '../contract/review-key.js'
+
+/** The exact command the user runs in Claude Code or Codex to generate a canvas for a target. */
+export function buildSkillCommand(key: ReviewKey, opts: { force: boolean }): string {
+  return `/pr-review-canvas ${keyToString(key)}${opts.force ? ' --force' : ''}`
 }

package/src/review/trim-caps.ts

@@ -77,7 +77,10 @@ interface TitledOutput {
  * Titles only: a rationale or a body is prose a reader will read, and cutting it is the author's
  * call, not the tool's.
  */
-export function applyTitleTrims(output: unknown, caps: { layerTitle: number; pointTitle: number }): TitleTrim[] {
+export function applyTitleTrims(
+  output: unknown,
+  caps: { layerTitle: number; pointTitle: number }
+): TitleTrim[] {
   const trims: TitleTrim[] = []
   const trim = (where: string, holder: { title?: string }, cap: number): void => {
     if (typeof holder.title !== 'string') {
@@ -89,11 +92,12 @@ export function applyTitleTrims(output: unknown, caps: { layerTitle: number; poi
       holder.title = trimmed
     } else if (visibleLength(holder.title) > cap) {
       const match = EXPLAINER.exec(holder.title.trim().replace(/\s+/g, ' '))
-      const reason = match === null
-        ? 'no explainer separator (:, —, – or -) to drop'
-        : match.index === 0
-          ? 'dropping the explainer would leave an empty title'
-          : 'the title before the explainer still exceeds the cap'
+      const reason =
+        match === null
+          ? 'no explainer separator (:, —, – or -) to drop'
+          : match.index === 0
+            ? 'dropping the explainer would leave an empty title'
+            : 'the title before the explainer still exceeds the cap'
       trims.push({ outcome: 'unfixable', where, length: visibleLength(holder.title), cap, reason })
     }
   }

package/src/review/validate-folds.ts

@@ -83,13 +83,13 @@ function validateFileFolds(
 
   for (const [index, fold] of folds.entries()) {
     if (assignedHunk(fold, file, hunks) === null) {
-      fail(`fold ${index + 1} must be an ordered range inside one hunk assigned to this file in this layer`)
+      fail(`fold ${index + 1} must be an ordered range inside one chunk assigned to this file in this layer`)
       continue
     }
 
     const earlierFolds = folds.slice(0, index)
     if (earlierFolds.some(earlier => rangesOverlap(fold, earlier, hunks))) {
-      fail(`fold ${index + 1} overlaps an earlier fold or uses another coordinate side in the same hunk`)
+      fail(`fold ${index + 1} overlaps an earlier fold or uses another coordinate side in the same chunk`)
     }
 
     if (protectedCode.some(range => rangesOverlap(fold, range, hunks))) {

package/src/review/validate.ts

@@ -152,7 +152,11 @@ function checkLengths(output: ModelOutput, caps: TextCaps, report: Report): void
       f.folds?.forEach((fold, k) => {
         const where = `${at}.files.${j}.folds.${k}.title`
         if (fold.title.length > caps.pointTitle) {
-          report.add('TEXT_TOO_LONG', where, `${where}: ${fold.title.length} visible chars, cap ${caps.pointTitle}`)
+          report.add(
+            'TEXT_TOO_LONG',
+            where,
+            `${where}: ${fold.title.length} visible chars, cap ${caps.pointTitle}`
+          )
         }
       })
       f.annotations.forEach((a, k) => {
@@ -213,12 +217,16 @@ function checkHunks(output: ModelOutput, index: Index, report: Report): Map<stri
       for (const id of file.hunks) {
         const hit = index.byHunkId.get(id)
         if (hit === undefined) {
-          const hint = entry === undefined ? '' : ` (${file.path} has ${entry.hunks.length} hunks)`
+          const hint = entry === undefined ? '' : ` (${file.path} has ${entry.hunks.length} chunks)`
           report.add('HUNK_UNKNOWN', where, `${layerLabel(layer)}: ${id} does not exist${hint}`)
           continue
         }
         if (hit.file.path !== file.path) {
-          report.add('HUNK_UNKNOWN', where, `${layerLabel(layer)}: ${id} belongs to ${hit.file.path}, not ${file.path}`)
+          report.add(
+            'HUNK_UNKNOWN',
+            where,
+            `${layerLabel(layer)}: ${id} belongs to ${hit.file.path}, not ${file.path}`
+          )
           continue
         }
         const first = owner.get(id)
@@ -236,7 +244,11 @@ function checkHunks(output: ModelOutput, index: Index, report: Report): Map<stri
   }
   for (const { file, hunk } of index.byHunkId.values()) {
     if (!owner.has(hunk.id)) {
-      report.add('HUNK_UNASSIGNED', `hunk:${hunk.id}`, `${hunk.id} in ${file.path} (${hunk.header}) is in no layer`)
+      report.add(
+        'HUNK_UNASSIGNED',
+        `hunk:${hunk.id}`,
+        `${hunk.id} in ${file.path} (${hunk.header}) is in no layer`
+      )
     }
   }
   return owner
@@ -248,12 +260,16 @@ function checkLayers(output: ModelOutput, report: Report): void {
     const where = `layer:${layer.key}`
     const seen = keys.get(layer.key)
     if (seen !== undefined) {
-      report.add('LAYER_KEY_DUPLICATE', where, `layer ${i + 1}: key "${layer.key}" is also used by layer ${seen + 1}`)
+      report.add(
+        'LAYER_KEY_DUPLICATE',
+        where,
+        `layer ${i + 1}: key "${layer.key}" is also used by layer ${seen + 1}`
+      )
     } else {
       keys.set(layer.key, i)
     }
     if (layer.files.length === 0) {
-      report.add('LAYER_EMPTY', where, `${layerLabel(layer)} has no hunks`)
+      report.add('LAYER_EMPTY', where, `${layerLabel(layer)} has no chunks`)
     }
   })
   // Other is optional: at most one, and last when present.
@@ -268,7 +284,11 @@ function checkLayers(output: ModelOutput, report: Report): void {
   }
   const last = output.layers[output.layers.length - 1]
   if (first !== undefined && first !== last) {
-    report.add('OTHER_NOT_LAST', `layer:${first.key}`, `layer ${first.key} (kind other) must be the last layer`)
+    report.add(
+      'OTHER_NOT_LAST',
+      `layer:${first.key}`,
+      `layer ${first.key} (kind other) must be the last layer`
+    )
   }
 }
 
@@ -308,7 +328,11 @@ function checkTests(
         continue
       }
       if (t.testPath === undefined) {
-        report.add('TEST_PATH_UNKNOWN', where, `${layerLabel(layer)}: "${t.behavior}" is covered but names no testPath`)
+        report.add(
+          'TEST_PATH_UNKNOWN',
+          where,
+          `${layerLabel(layer)}: "${t.behavior}" is covered but names no testPath`
+        )
       } else if (!(index.byPath.has(t.testPath) || headPaths.has(t.testPath))) {
         report.add('TEST_PATH_UNKNOWN', where, `${layerLabel(layer)}: ${t.testPath} is not in the PR head`)
       }
@@ -339,12 +363,20 @@ function checkRisk(output: ModelOutput, highRisk: readonly HighRiskRule[], repor
   }
   const where = `layer:${other.key}`
   for (const tag of other.risk ?? []) {
-    report.add('RISK_IN_OTHER', where, `other: carries the risk tag "${tag.label}"; move the hunks to a real layer`)
+    report.add(
+      'RISK_IN_OTHER',
+      where,
+      `other: carries the risk tag "${tag.label}"; move the chunks to a real layer`
+    )
   }
   for (const file of other.files) {
     const rule = highRisk.find(r => matchesGlob(r.pattern, file.path))
     if (rule !== undefined) {
-      report.add('RISK_IN_OTHER', where, `other: ${file.path} matches highRisk "${rule.pattern}" (${rule.label})`)
+      report.add(
+        'RISK_IN_OTHER',
+        where,
+        `other: ${file.path} matches highRisk "${rule.pattern}" (${rule.label})`
+      )
     }
   }
 }
@@ -368,9 +400,17 @@ function checkAnnotations(output: ModelOutput, index: Index, report: Report): vo
         const start = hunkAt(entry, a.side, a.startLine)
         const end = hunkAt(entry, a.side, a.endLine)
         if (start === null || end === null || start.id !== end.id) {
-          report.add('ANNOTATION_OUTSIDE_HUNK', where, `${label} is not inside one hunk of the diff (${hunkLineRanges(entry?.hunks ?? [], a.side)})`)
+          report.add(
+            'ANNOTATION_OUTSIDE_HUNK',
+            where,
+            `${label} is not inside one chunk of the diff (${hunkLineRanges(entry?.hunks ?? [], a.side)})`
+          )
         } else if (!file.hunks.includes(start.id)) {
-          report.add('ANNOTATION_OUTSIDE_HUNK', where, `${label} is in ${start.id}, which this layer does not list`)
+          report.add(
+            'ANNOTATION_OUTSIDE_HUNK',
+            where,
+            `${label} is in ${start.id}, which this layer does not list`
+          )
         }
       })
     }
@@ -378,7 +418,10 @@ function checkAnnotations(output: ModelOutput, index: Index, report: Report): vo
 }
 
 function checkPoints(output: ModelOutput, index: Index, limits: Limits, report: Report): void {
-  const missingTests = output.layers.reduce((n, l) => n + l.tests.filter(t => t.status === 'missing').length, 0)
+  const missingTests = output.layers.reduce(
+    (n, l) => n + l.tests.filter(t => t.status === 'missing').length,
+    0
+  )
   const total = output.points.length + missingTests
   if (total > limits.maxPoints) {
     report.add(
@@ -464,7 +507,12 @@ function checkLinks(output: ModelOutput, files: readonly FileEntry[], report: Re
  * The sidecar map of a layer's diagram: each key names a node of the mermaid source, each value
  * is a canvas link, and a diagram carries at most `maxDiagramLinks` of them.
  */
-function checkDiagramLinks(output: ModelOutput, files: readonly FileEntry[], limits: Limits, report: Report): void {
+function checkDiagramLinks(
+  output: ModelOutput,
+  files: readonly FileEntry[],
+  limits: Limits,
+  report: Report
+): void {
   const targets: LinkTargets = { layers: output.layers, files }
   for (const layer of output.layers) {
     if (layer.diagram === undefined) {
@@ -474,7 +522,11 @@ function checkDiagramLinks(output: ModelOutput, files: readonly FileEntry[], lim
     const label = `${layerLabel(layer)} diagram`
     const entries = Object.entries(layer.diagram.links)
     if (entries.length > limits.maxDiagramLinks) {
-      report.add('DIAGRAM_LIMIT', where, `${label}: ${entries.length} node links, at most ${limits.maxDiagramLinks}`)
+      report.add(
+        'DIAGRAM_LIMIT',
+        where,
+        `${label}: ${entries.length} node links, at most ${limits.maxDiagramLinks}`
+      )
     }
     const kind = diagramKind(layer.diagram.mermaid)
     const nodes = diagramNodeIds(layer.diagram.mermaid)

package/src/server/app.ts

@@ -1,7 +1,7 @@
 import { type Context, Hono } from 'hono'
 import type { AppContext } from './context.js'
 import type { AppEnv } from './env.js'
-import { AppError, toAppError } from './errors.js'
+import { AppError, logRequestError, toAppError } from './errors.js'
 import { errorPage } from './html.js'
 import { apiRoutes } from './routes/api.js'
 import { appearanceFor, appearanceQuery, pageRoutes } from './routes/pages.js'
@@ -29,14 +29,22 @@ export function createApp(ctx: AppContext): Hono<AppEnv> {
     const nonce = c.get('cspNonce') ?? createNonce()
     const res = wantsJson(c.req.path)
       ? c.json(envelope, err.status)
-      : await c.html(errorPage(envelope.error, nonce, await appearanceFor(ctx, appearanceQuery(c))), err.status)
+      : await c.html(
+          errorPage(envelope.error, nonce, await appearanceFor(ctx, appearanceQuery(c))),
+          err.status
+        )
     applyResponseHeaders(res, c.req.path, nonce)
     return res
   }
 
-  app.onError((err, c) => errorResponse(c, toAppError(err)))
+  app.onError((err, c) => {
+    logRequestError(ctx.log, c.req, err)
+    return errorResponse(c, toAppError(err))
+  })
 
-  app.notFound(c => errorResponse(c, new AppError('NOT_FOUND', `no route for ${c.req.method} ${c.req.path}`, 404)))
+  app.notFound(c =>
+    errorResponse(c, new AppError('NOT_FOUND', `no route for ${c.req.method} ${c.req.path}`, 404))
+  )
 
   app.route('/api', apiRoutes(ctx))
   app.route('/', staticRoutes(ctx))