@vintasoftware/pr-review-canvas 0.3.0 → 0.4.0

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
 }
 
@@ -84,12 +92,31 @@ async function readModel(canvasDir: string): Promise<{ raw: unknown } | { error:
   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. */
@@ -175,10 +202,10 @@ export async function publish(
   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'
       )
     }
@@ -207,15 +234,39 @@ export async function publish(
     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/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

@@ -217,7 +217,7 @@ 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
         }
@@ -269,7 +269,7 @@ function checkLayers(output: ModelOutput, report: Report): void {
       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.
@@ -366,7 +366,7 @@ function checkRisk(output: ModelOutput, highRisk: readonly HighRiskRule[], repor
     report.add(
       'RISK_IN_OTHER',
       where,
-      `other: carries the risk tag "${tag.label}"; move the hunks to a real layer`
+      `other: carries the risk tag "${tag.label}"; move the chunks to a real layer`
     )
   }
   for (const file of other.files) {
@@ -403,7 +403,7 @@ function checkAnnotations(output: ModelOutput, index: Index, report: Report): vo
           report.add(
             'ANNOTATION_OUTSIDE_HUNK',
             where,
-            `${label} is not inside one hunk of the diff (${hunkLineRanges(entry?.hunks ?? [], a.side)})`
+            `${label} is not inside one chunk of the diff (${hunkLineRanges(entry?.hunks ?? [], a.side)})`
           )
         } else if (!file.hunks.includes(start.id)) {
           report.add(