@vintasoftware/pr-review-canvas 0.3.0 → 0.5.0

package/src/review/prompt.ts

@@ -1,7 +1,7 @@
 // Renders prompt.md from the selected generation template and the prepared context. The template carries
 // the prose; this module fills the `{{TOKENS}}` with data so a wording change never touches code.
 import { z } from 'zod'
-import { type GenerationContext, LARGE_PR } from '../contract/generation-context.js'
+import { type BasisSplit, type GenerationContext, LARGE_PR } from '../contract/generation-context.js'
 import { type FileEntry, modelOutputSchema } from '../contract/review-artifact.js'
 import { labelPatch } from '../git/patch-lines.js'
 import { loadPromptFile, type ProjectPrompts } from '../prompt-files.js'
@@ -12,20 +12,48 @@ export { PROMPTS_DIR }
 
 export interface PromptSources {
   generation: Record<GenerationMode, string>
+  /** The same two modes, worded as an update of a basis canvas. Used when `ctx.basis` is set. */
+  incremental: Record<GenerationMode, string>
+  /**
+   * The judging rules of each mode: the half of the task that does not change between writing a
+   * canvas and updating one. Both task files of a mode end with it, so its wording has one home.
+   */
+  judging: Record<GenerationMode, string>
   format: string
   layeringGuidance: string
   qualityStandards: string
 }
 
 export async function loadPromptSources(dir = PROMPTS_DIR, project?: ProjectPrompts): Promise<PromptSources> {
-  const [format, layeringGuidance, qualityStandards, strict, surfacing] = await Promise.all([
+  const [
+    format,
+    layeringGuidance,
+    qualityStandards,
+    strict,
+    surfacing,
+    strictInc,
+    surfacingInc,
+    judgingStrict,
+    judgingSurfacing,
+  ] = await Promise.all([
     loadPromptFile('generation-format.md', dir, project),
     loadPromptFile('layering-guidance.md', dir, project),
     loadPromptFile('quality-standards.md', dir, project),
     loadPromptFile('generation-strict.md', dir, project),
     loadPromptFile('generation-surfacing.md', dir, project),
+    loadPromptFile('generation-strict-incremental.md', dir, project),
+    loadPromptFile('generation-surfacing-incremental.md', dir, project),
+    loadPromptFile('judging-strict.md', dir, project),
+    loadPromptFile('judging-surfacing.md', dir, project),
   ])
-  return { format, layeringGuidance, qualityStandards, generation: { strict, surfacing } }
+  return {
+    format,
+    layeringGuidance,
+    qualityStandards,
+    generation: { strict, surfacing },
+    incremental: { strict: strictInc, surfacing: surfacingInc },
+    judging: { strict: judgingStrict, surfacing: judgingSurfacing },
+  }
 }
 
 /** The line ranges of a hunk header; the trailing function context can hold backticks. */
@@ -197,6 +225,74 @@ export function schemaMarkdown(ctx: GenerationContext): string {
   return `\`\`\`json\n${JSON.stringify(schema, null, 2)}\n\`\`\``
 }
 
+function list(items: readonly string[], empty: string): string {
+  return items.length === 0 ? `_${empty}_` : items.map(i => `- \`${i}\``).join('\n')
+}
+
+function basisMarkdown(basis: BasisSplit | undefined): string {
+  if (basis === undefined) {
+    return ''
+  }
+  return [
+    `- Basis canvas: \`${basis.canvasSha}\``,
+    `- Its canvas file: \`${basis.reviewJsonPath}\` — read it for the wording you carry`,
+  ].join('\n')
+}
+
+function fileDeltaMarkdown(basis: BasisSplit | undefined): string {
+  if (basis === undefined) {
+    return ''
+  }
+  const f = basis.files
+  return [
+    `**Untouched** — the patch is byte-identical to the basis canvas's:\n\n${list(f.unchanged, 'none')}`,
+    `**Changed** — the patch differs, so every line number in it may have moved:\n\n${list(f.changed, 'none')}`,
+    `**New** — not in the basis canvas at all:\n\n${list(f.added, 'none')}`,
+    `**Gone** — in the basis canvas, not in this diff:\n\n${list(f.removed, 'none')}`,
+  ].join('\n\n')
+}
+
+/** The two lists the generator works from: what to copy across, and what to decide anew. */
+function carriedMarkdown(basis: BasisSplit | undefined): string {
+  if (basis === undefined) {
+    return ''
+  }
+  const layers = basis.layers
+    .filter(l => l.status === 'carried')
+    .map(l => `- layer \`${l.key}\` — **${l.title}** (${l.carriedFiles.length} files, all untouched)`)
+  const files = basis.layers
+    .filter(l => l.status === 're-judged')
+    .flatMap(l => l.carriedFiles.map(p => `- \`${p}\`, from layer \`${l.key}\``))
+  const points = basis.points
+    .filter(p => p.status === 'carried')
+    .map(p => `- ${p.kind} on \`${p.path}\` — "${p.title}"`)
+  return [
+    `**Whole layers** — copy the layer with its title, rationale, decisions, checkByHand, tests, files, notes, folds, and annotations:\n\n${layers.length === 0 ? '_none_' : layers.join('\n')}`,
+    `**Single files of a re-judged layer** — the file is untouched, so its note, folds, and annotations still fit wherever you put the file:\n\n${files.length === 0 ? '_none_' : files.join('\n')}`,
+    `**Attention points** — repeat the kind, path, and title exactly, so the point keeps its identity and any dismissal the reviewer made:\n\n${points.length === 0 ? '_none_' : points.join('\n')}`,
+  ].join('\n\n')
+}
+
+function reJudgedMarkdown(basis: BasisSplit | undefined): string {
+  if (basis === undefined) {
+    return ''
+  }
+  const layers = basis.layers
+    .filter(l => l.status === 're-judged')
+    .map(
+      l =>
+        `- layer \`${l.key}\` — **${l.title}**; touched: ${l.reJudgedFiles.map(p => `\`${p}\``).join(', ')}`
+    )
+  const points = basis.points
+    .filter(p => p.status === 're-judged')
+    .map(p => `- ${p.kind} on \`${p.path}\` — "${p.title}"`)
+  return [
+    `**Layers** — the head touched at least one of their files, so decide the grouping, the prose, and the anchors again:\n\n${layers.length === 0 ? '_none_' : layers.join('\n')}`,
+    `**Attention points** — the code under them moved; keep one only if you read the new code and it still holds:\n\n${points.length === 0 ? '_none_' : points.join('\n')}`,
+    '**The summary and the pull-request-wide risk** are always written again: they describe the whole change set, which the new commits changed.',
+  ].join('\n\n')
+}
+
 /** Selects one task and fills its data and format placeholders before the generator sees it. */
 export function renderPrompt(
   ctx: GenerationContext,
@@ -227,12 +323,23 @@ export function renderPrompt(
     TEST_PATTERNS: testPatternsMarkdown(ctx),
     SMALL_PR: smallPrMarkdown(ctx),
     MAX_REPAIR_ROUNDS: String(ctx.generation.maxRepairRounds),
+    BASIS: basisMarkdown(ctx.basis),
+    FILE_DELTA: fileDeltaMarkdown(ctx.basis),
+    CARRIED: carriedMarkdown(ctx.basis),
+    RE_JUDGED: reJudgedMarkdown(ctx.basis),
   }
-  const template = sources.generation[ctx.generation.mode].replace('{{FORMAT}}', () => sources.format)
+  // A prepared basis picks the incremental wording: one prompt states one job, with no conditions.
+  // Both wordings end with the mode's judging rules, which are assembled first so the tokens inside
+  // them are filled by the one pass below.
+  const task = ctx.basis === undefined ? sources.generation : sources.incremental
+  const template = task[ctx.generation.mode]
+    .replace('{{JUDGING}}', () => sources.judging[ctx.generation.mode])
+    .replace('{{FORMAT}}', () => sources.format)
   return template.replace(/\{\{([A-Z_]+)\}\}/g, (_m, name: string) => {
     const value = tokens[name]
     if (value === undefined) {
-      throw new Error(`generation-${ctx.generation.mode}.md uses an unknown token {{${name}}}`)
+      const suffix = ctx.basis === undefined ? '' : '-incremental'
+      throw new Error(`generation-${ctx.generation.mode}${suffix}.md uses an unknown token {{${name}}}`)
     }
     return value
   })

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'
       )
     }
@@ -205,17 +232,42 @@ export async function publish(
     generatedAt: now,
     generator,
     testPatterns: context.tests.patterns,
+    basisCanvasSha: context.basis?.canvasSha,
   })
   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/test-paths.ts

@@ -2,11 +2,51 @@ import path from 'node:path'
 import { matchesGlob } from './glob.js'
 
 /**
- * What counts as a test file when the project config says nothing: the JavaScript and TypeScript
- * conventions this repository uses. `tests.patterns` in `pr-review.config.yml` replaces the list,
- * so a Python or Go project can name `test_*.py` or `*_test.go` instead.
+ * The languages whose test classes are named `XTest` or `XTests`. Only these extensions, so a
+ * component such as `ABTest.tsx` is not taken for a test.
  */
-export const DEFAULT_TEST_PATTERNS: readonly string[] = ['**/*.test.*', '**/*.spec.*', '**/__tests__/**']
+const CLASS_TEST_EXTENSIONS = ['java', 'kt', 'scala', 'groovy', 'cs', 'fs', 'vb', 'swift', 'php'] as const
+
+/**
+ * The test conventions found across stacks, by directory and by file-name shape rather than by
+ * language, so a repository without a `pr-review.config.yml` still gets its tests labelled,
+ * ordered after the code they cover, and kept open at the light reading level. Directories:
+ * `__tests__`, `tests`, `test`. Names: `x.test.*` and `x.spec.*` (JS/TS), `x_test.*` (Go,
+ * Python, Elixir, Dart, Rust), `test_x.py` and `conftest.py` (pytest), `x_spec.*` (Ruby),
+ * `XTest` and `XTests` in the class-test languages above. A `spec/` directory is left out: it
+ * often holds API specs rather than tests. `tests.patterns` replaces the list.
+ */
+export const DEFAULT_TEST_PATTERNS: readonly string[] = [
+  '**/__tests__/**',
+  '**/tests/**',
+  '**/test/**',
+  '**/*.test.*',
+  '**/*.spec.*',
+  '**/*_test.*',
+  '**/*_spec.*',
+  '**/test_*.py',
+  '**/conftest.py',
+  ...CLASS_TEST_EXTENSIONS.flatMap(ext => [`**/*Test.${ext}`, `**/*Tests.${ext}`]),
+]
+
+/**
+ * Generated content that lives beside tests: snapshots and fixtures. They are test paths, but
+ * nobody reads them line by line, so they may hide at the light level like any generated file.
+ */
+export const GENERATED_TEST_PATTERNS: readonly string[] = [
+  '**/__snapshots__/**',
+  '**/*.snap',
+  '**/fixtures/**',
+  '**/__fixtures__/**',
+]
+
+/** True for a test path a reviewer reads as written: a test path that is not a snapshot or fixture. */
+export function isHandWrittenTest(
+  filePath: string,
+  patterns: readonly string[] = DEFAULT_TEST_PATTERNS
+): boolean {
+  return isTestPath(filePath, patterns) && !isTestPath(filePath, GENERATED_TEST_PATTERNS)
+}
 
 /** True when one of the patterns matches the repo-relative path. */
 export function isTestPath(filePath: string, patterns: readonly string[] = DEFAULT_TEST_PATTERNS): boolean {