@vintasoftware/pr-review-canvas 0.1.0

package/src/review/publish.ts

@@ -0,0 +1,209 @@
+// `pr-review publish`: validate model.json against context.json, normalize, and store the
+// canvas. Nothing is written when the report is not clean.
+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 type { ValidationError, ValidationReport } from '../contract/validation.js'
+import { fetchPrMeta } from '../github/pr.js'
+import type { AppContext } from '../server/context.js'
+import { readJson, readText } from '../store/atomic-json.js'
+import { normalize } from './normalize.js'
+import { coveredTestPaths, type ValidationInput, validateModelOutput } from './validate.js'
+
+export interface PublishOptions {
+  agent: string
+  model?: string | undefined
+  harness: Generator['harness']
+  allowStale: boolean
+}
+
+export interface PublishResult {
+  status: 'published'
+  headSha: string
+  reviewJsonPath: string
+  attempts: number
+  /** Where the canvas shows once the server runs; absent for a change set without a PR. */
+  reviewUrl?: string
+}
+
+/** The report of a failed publish. The CLI prints one line per error and exits 5. */
+export class ModelInvalidError extends Error {
+  readonly report: ValidationReport
+  readonly attempts: number
+
+  constructor(report: ValidationReport, attempts: number) {
+    super(`model.json has ${report.errors.length} problem${report.errors.length === 1 ? '' : 's'}`)
+    this.name = 'ModelInvalidError'
+    this.report = report
+    this.attempts = attempts
+  }
+}
+
+export class PublishError extends Error {
+  readonly code: 'NOT_FOUND' | 'CANVAS_STALE'
+  readonly hint: string
+
+  constructor(code: 'NOT_FOUND' | 'CANVAS_STALE', message: string, hint: string) {
+    super(message)
+    this.name = 'PublishError'
+    this.code = code
+    this.hint = hint
+  }
+}
+
+export async function readContext(canvasDir: string): Promise<GenerationContext> {
+  const context = await readJson(path.join(canvasDir, 'context.json'), GenerationContextSchema)
+  if (context === null) {
+    throw new PublishError('NOT_FOUND', `${canvasDir} has no context.json`, 'run `pr-review prepare` first')
+  }
+  return context
+}
+
+/** The file's JSON, or the one SCHEMA error that says it is not JSON. */
+export function parseModelText(text: string, name: string): { raw: unknown } | { error: ValidationError } {
+  try {
+    return { raw: JSON.parse(text) }
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    return { error: { code: 'SCHEMA', where: '(root)', message: `${name} is not valid JSON: ${reason}` } }
+  }
+}
+
+async function readModel(canvasDir: string): Promise<{ raw: unknown } | { error: ValidationError }> {
+  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')
+  }
+  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> {
+  if (context.target.kind === 'pr') {
+    return (await fetchPrMeta(ctx.gh, ctx.config.repo, context.target.number)).headSha
+  }
+  return ctx.git.revParse(context.target.head)
+}
+
+/** Publish runs since prepare last wrote a context (its `prepared` line), this one included. */
+export function attemptsSincePrepare(log: string): number {
+  const lines = log.split('\n').filter(l => l !== '')
+  const lastPrepared = lines.map(l => l.split(' ')[1] === 'prepared').lastIndexOf(true)
+  return lines.length - (lastPrepared + 1)
+}
+
+/**
+ * Appends one line for this publish run and returns its attempt number. Every field is named, so
+ * the file reads without the code: `<time> published attempts=2` and
+ * `<time> invalid attempts=1 errors=2 TEXT_TOO_LONG,HUNK_UNASSIGNED`.
+ */
+async function recordAttempt(
+  canvasDir: string,
+  now: string,
+  result: { ok: boolean; errors: ReadonlyArray<{ code: string }> }
+): Promise<number> {
+  const file = path.join(canvasDir, 'publish.log')
+  const attempts = attemptsSincePrepare((await readText(file)) ?? '') + 1
+  const codes = result.errors.map(e => e.code).join(',')
+  const line = result.ok
+    ? `${now} published attempts=${attempts}`
+    : `${now} invalid attempts=${attempts} errors=${result.errors.length}${codes === '' ? '' : ` ${codes}`}`
+  await appendFile(file, `${line}\n`, 'utf8')
+  return attempts
+}
+
+/**
+ * The validator's input for one canvas. `covered` test paths outside the diff are looked up at the
+ * PR head through git, so an untouched test file that covers the change counts as present.
+ */
+export async function validationInput(
+  ctx: AppContext,
+  context: GenerationContext,
+  raw: unknown
+): Promise<ValidationInput> {
+  const inDiff = new Set(context.files.map(f => f.path))
+  const headPaths = new Set<string>()
+  for (const p of coveredTestPaths(raw)) {
+    if (!(inDiff.has(p) || headPaths.has(p)) && (await ctx.git.blobSize(context.headSha, p)) !== null) {
+      headPaths.add(p)
+    }
+  }
+  return {
+    files: context.files,
+    caps: context.caps,
+    limits: context.limits,
+    highRisk: context.highRisk,
+    headPaths,
+    testPatterns: context.tests.patterns,
+  }
+}
+
+export function buildManifest(context: GenerationContext, artifact: ReviewArtifact, version: string): CanvasManifest {
+  const manifest: CanvasManifest = {
+    formatVersion: 1,
+    tool: { name: 'pr-review', version },
+    repo: context.repo,
+    headSha: context.headSha,
+    mergeBaseSha: context.mergeBaseSha,
+    baseRef: context.pr.baseRef,
+    headRef: context.pr.headRef,
+    generatedAt: artifact.generatedAt,
+    generator: artifact.generator,
+  }
+  if (context.target.kind === 'pr') {
+    manifest.prNumber = context.target.number
+  }
+  return manifest
+}
+
+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) {
+      throw new PublishError(
+        'CANVAS_STALE',
+        `the target moved to ${head.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'
+      )
+    }
+  }
+  const model = await readModel(canvasDir)
+  const result =
+    'error' in model
+      ? { ok: false, errors: [model.error], output: null }
+      : validateModelOutput(model.raw, await validationInput(ctx, context, model.raw))
+  const now = ctx.now().toISOString()
+  const attempts = await recordAttempt(canvasDir, now, result)
+  if (!result.ok || result.output === null) {
+    throw new ModelInvalidError({ ok: false, errors: result.errors }, attempts)
+  }
+  const generator: Generator = { agent: opts.agent, harness: opts.harness, attempts }
+  if (opts.model !== undefined) {
+    generator.model = opts.model
+  }
+  const artifact = normalize(result.output, {
+    pr: context.pr,
+    files: context.files,
+    highRisk: context.highRisk,
+    caps: context.caps,
+    generatedAt: now,
+    generator,
+    testPatterns: context.tests.patterns,
+  })
+  const manifest = buildManifest(context, artifact, ctx.version)
+  await ctx.canvases.write(context.headSha, artifact, manifest, manifest.prNumber)
+  const published: PublishResult = {
+    status: 'published',
+    headSha: context.headSha,
+    reviewJsonPath: path.join(ctx.canvases.canvasDir(context.headSha), 'review.json'),
+    attempts,
+  }
+  if (context.target.kind === 'pr') {
+    published.reviewUrl = `http://localhost:${ctx.config.port}/review/${context.target.number}`
+  }
+  return published
+}

package/src/review/skill-command.ts

@@ -0,0 +1,4 @@
+/** 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' : ''}`
+}

package/src/review/test-paths.ts

@@ -0,0 +1,32 @@
+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.
+ */
+export const DEFAULT_TEST_PATTERNS: readonly string[] = ['**/*.test.*', '**/*.spec.*', '**/__tests__/**']
+
+/** True when one of the patterns matches the repo-relative path. */
+export function isTestPath(filePath: string, patterns: readonly string[] = DEFAULT_TEST_PATTERNS): boolean {
+  return patterns.some(p => matchesGlob(p, filePath))
+}
+
+/**
+ * The path stem a test file covers: `src/__tests__/a.test.ts` → `src/a`. A source file matches
+ * when its own stem (path without extension) is the same string. This strips the naming habits
+ * of the default patterns, so a project with other patterns still gets `TEST_NOT_LAST` but may
+ * not get `TEST_IN_OTHER`, which needs the source file behind a test name.
+ */
+export function coveredStem(testPath: string): string {
+  const withoutTestsDir = testPath.replace(/(^|\/)__tests__\//, '$1')
+  const ext = path.posix.extname(withoutTestsDir)
+  const base = ext === '' ? withoutTestsDir : withoutTestsDir.slice(0, -ext.length)
+  return base.replace(/\.(test|spec)$/, '')
+}
+
+export function sourceStem(filePath: string): string {
+  const ext = path.posix.extname(filePath)
+  return ext === '' ? filePath : filePath.slice(0, -ext.length)
+}

package/src/review/text-length.ts

@@ -0,0 +1,15 @@
+/**
+ * The length a reader sees. Caps measure this, so a long link target or a code fence does not eat
+ * the budget: `[text](#hunk:a/very/long/path.ts#2)` counts as `text`, backticks and fence lines
+ * count as nothing.
+ */
+export function visibleText(markdown: string): string {
+  return markdown
+    .replace(/^[ \t]*`{3,}[^\n]*$/gm, '')
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/`/g, '')
+}
+
+export function visibleLength(markdown: string): number {
+  return visibleText(markdown).length
+}

package/src/review/trim-caps.ts

@@ -0,0 +1,114 @@
+/**
+ * Mechanical repairs for text that is over its cap.
+ *
+ * Caps are measured on the text a reader sees, which a writer cannot count while writing, so an
+ * over-cap field usually comes back over-cap after a rewrite. Two things help without touching
+ * meaning: trimming a title's trailing explainer, which the length rules ask for anyway, and
+ * telling the writer where the cap actually falls in their own text.
+ */
+
+import { visibleLength, visibleText } from './text-length.js'
+
+/** Separators that introduce an explainer after a name: "Storage: how it works". */
+const EXPLAINER = /\s+[:—–-]\s+|:\s+/
+
+/**
+ * The visible prefix that fits in `cap`, ending on a word boundary when one is near the cut.
+ * Used to tell a writer where their text crosses the cap, never to rewrite prose for them.
+ */
+export function visiblePrefix(text: string, cap: number): string {
+  const visible = visibleText(text)
+  if (visible.length <= cap) {
+    return visible
+  }
+  const cut = visible.slice(0, cap)
+  if (/\s/.test(visible.charAt(cap))) {
+    return cut.trimEnd()
+  }
+  const lastSpace = cut.lastIndexOf(' ')
+  return lastSpace > 0 && lastSpace > cap - 24 ? cut.slice(0, lastSpace) : cut
+}
+
+/**
+ * A title with its trailing explainer removed, when dropping it brings the title under the cap.
+ * Returns null when the title already fits or when no cut helps, so the caller leaves it alone.
+ *
+ * Only the first separator counts: "Endpoints: update, create" keeps "Endpoints", and a title
+ * with no separator is never cut mid-phrase — a truncated name is worse than a long one.
+ */
+export function trimTitle(title: string, cap: number): string | null {
+  const tidied = title.trim().replace(/\s+/g, ' ').replace(/\.$/, '')
+  if (visibleLength(tidied) <= cap) {
+    return tidied === title ? null : tidied
+  }
+  const match = EXPLAINER.exec(tidied)
+  if (match === undefined || match === null || match.index === 0) {
+    return null
+  }
+  const head = tidied.slice(0, match.index).trim()
+  return head !== '' && visibleLength(head) <= cap ? head : null
+}
+
+/** A title this pass repaired or could not shorten safely. */
+export type TitleTrim =
+  | { outcome: 'fixed'; where: string; from: string; to: string }
+  | { outcome: 'unfixable'; where: string; length: number; cap: number; reason: string }
+
+interface TitledFold {
+  title?: string
+}
+
+interface TitledFile {
+  folds?: TitledFold[]
+}
+
+interface TitledLayer {
+  title?: string
+  files?: TitledFile[]
+}
+
+interface TitledOutput {
+  layers?: TitledLayer[]
+  points?: Array<{ title?: string }>
+}
+
+/**
+ * Trims every title of a parsed model that is over its cap, in place, and reports what changed.
+ * 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[] {
+  const trims: TitleTrim[] = []
+  const trim = (where: string, holder: { title?: string }, cap: number): void => {
+    if (typeof holder.title !== 'string') {
+      return
+    }
+    const trimmed = trimTitle(holder.title, cap)
+    if (trimmed !== null) {
+      trims.push({ outcome: 'fixed', where, from: holder.title, to: trimmed })
+      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'
+      trims.push({ outcome: 'unfixable', where, length: visibleLength(holder.title), cap, reason })
+    }
+  }
+
+  const model = output as TitledOutput
+  model.layers?.forEach((layer, i) => {
+    trim(`layers.${i}.title`, layer, caps.layerTitle)
+    layer.files?.forEach((file, j) => {
+      file.folds?.forEach((fold, k) => {
+        trim(`layers.${i}.files.${j}.folds.${k}.title`, fold, caps.pointTitle)
+      })
+    })
+  })
+  model.points?.forEach((point, i) => {
+    trim(`points.${i}.title`, point, caps.pointTitle)
+  })
+  return trims
+}

package/src/review/validate-folds.ts

@@ -0,0 +1,110 @@
+import type { CodeFold, FileEntry, Hunk, ModelLayer, ModelOutput } from '../contract/review-artifact.js'
+import type { ValidationError } from '../contract/validation.js'
+import { hunkForLine } from '../git/patch-lines.js'
+
+type SourceRange = Pick<CodeFold, 'side' | 'startLine' | 'endLine'>
+type ModelFile = ModelLayer['files'][number]
+
+function assignedHunk(fold: CodeFold, file: ModelFile, hunks: readonly Hunk[]): Hunk | null {
+  if (fold.endLine < fold.startLine) {
+    return null
+  }
+
+  const start = hunkForLine(hunks, fold.side, fold.startLine)
+  const end = hunkForLine(hunks, fold.side, fold.endLine)
+
+  if (start === null || end?.id !== start.id || !file.hunks.includes(start.id)) {
+    return null
+  }
+
+  return start
+}
+
+/** Different coordinate sides in one hunk need the full patch to prove they are separate. */
+function rangesOverlap(left: SourceRange, right: SourceRange, hunks: readonly Hunk[]): boolean {
+  const leftHunk = hunkForLine(hunks, left.side, left.startLine)
+  const rightHunk = hunkForLine(hunks, right.side, right.startLine)
+
+  if (leftHunk === null || leftHunk.id !== rightHunk?.id) {
+    return false
+  }
+
+  return left.side !== right.side || (left.startLine <= right.endLine && right.startLine <= left.endLine)
+}
+
+function protectedRanges(
+  file: ModelFile,
+  layer: ModelLayer,
+  output: ModelOutput,
+  hunks: readonly Hunk[]
+): SourceRange[] {
+  const ranges: SourceRange[] = [...file.annotations]
+  const points = output.points.filter(point => point.path === file.path)
+
+  for (const point of points) {
+    const side = point.side ?? 'new'
+    const hunk = hunkForLine(hunks, side, point.line)
+
+    if (hunk !== null && file.hunks.includes(hunk.id)) {
+      ranges.push({ side, startLine: point.line, endLine: point.endLine ?? point.line })
+    }
+  }
+
+  const needsTestPoint = layer.files[0] === file && layer.tests.some(test => test.status === 'missing')
+  const firstHunk = needsTestPoint ? hunks.find(hunk => hunk.id === file.hunks[0]) : undefined
+
+  if (firstHunk !== undefined) {
+    const side = firstHunk.newLines === 0 ? 'old' : 'new'
+    const line = side === 'new' ? firstHunk.newStart : firstHunk.oldStart
+    ranges.push({ side, startLine: line, endLine: line })
+  }
+
+  return ranges
+}
+
+function validateFileFolds(
+  file: ModelFile,
+  layer: ModelLayer,
+  output: ModelOutput,
+  hunks: readonly Hunk[]
+): ValidationError[] {
+  const errors: ValidationError[] = []
+  const where = `layer:${layer.key}/file:${file.path}`
+  const protectedCode = protectedRanges(file, layer, output, hunks)
+  const folds = file.folds ?? []
+
+  const fail = (message: string): void => {
+    errors.push({ code: 'FOLD_INVALID', where, message: `${where}: ${message}` })
+  }
+
+  if (file.collapsed && protectedCode.length > 0) {
+    fail('a file with annotations or attention points must start expanded')
+  }
+
+  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`)
+      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`)
+    }
+
+    if (protectedCode.some(range => rangesOverlap(fold, range, hunks))) {
+      fail(`fold ${index + 1} would hide an annotation or attention point`)
+    }
+  }
+
+  return errors
+}
+
+/** Checks fold coordinates and keeps attention points and annotations visible. */
+export function validateFolds(output: ModelOutput, files: readonly FileEntry[]): ValidationError[] {
+  const byPath = new Map(files.map(file => [file.path, file]))
+
+  return output.layers.flatMap(layer =>
+    layer.files.flatMap(file => validateFileFolds(file, layer, output, byPath.get(file.path)?.hunks ?? []))
+  )
+}