@vintasoftware/pr-review-canvas 0.3.0 → 0.5.0

package/src/commands.ts

@@ -7,10 +7,11 @@ import { exportCanvas } from './canvas/export.js'
 import { importCanvas } from './canvas/import.js'
 import { CANVAS_ZIP_MAX_BYTES } from './canvas/zip.js'
 import type { ErrorCode } from './contract/api.js'
-import type { GenerationContext, PrepareTarget } from './contract/generation-context.js'
+import type { GenerationContext, PrepareTargetInput } from './contract/generation-context.js'
+import type { LocalKey } from './contract/review-key.js'
 import { HARNESSES, type ReviewArtifact, ReviewArtifactSchema } from './contract/review-artifact.js'
 import { formatValidationError, type ValidationReport } from './contract/validation.js'
-import { fetchPrMeta, fetchPrRefs } from './github/pr.js'
+import { fetchPrRefs } from './git/pr-refs.js'
 import { type DoctorDeps, runDoctorChecks } from './review/doctor.js'
 import {
   CLAUDE_SKILLS_DIR,
@@ -32,7 +33,7 @@ import {
 import { applyTitleTrims, type TitleTrim } from './review/trim-caps.js'
 import { validateModelOutput } from './review/validate.js'
 import type { AppContext } from './server/context.js'
-import { AppError, toAppError } from './server/errors.js'
+import { AppError, CLI_SETUP_CODES, toAppError } from './server/errors.js'
 import { readText, writeTextAtomic } from './store/atomic-json.js'
 
 export interface CliIo {
@@ -40,7 +41,7 @@ export interface CliIo {
   stderr(line: string): void
 }
 
-/** Exit codes: 0 ok, 1 error, 2 usage, 4 gh auth or missing, 5 invalid model output. */
+/** Exit codes: 0 ok, 1 error, 2 usage, 4 gh/glab auth or missing, 5 invalid model output. */
 export const EXIT = { ok: 0, error: 1, usage: 2, gh: 4, invalid: 5 } as const
 
 export class UsageError extends Error {
@@ -94,7 +95,7 @@ export function reportFailure(io: CliIo, err: unknown): number {
   }
   const appErr = toAppError(err)
   printErrorEnvelope(io, appErr.code, appErr.message, appErr.hint)
-  return appErr.code === 'GH_UNAUTHENTICATED' || appErr.code === 'GH_MISSING' ? EXIT.gh : EXIT.error
+  return CLI_SETUP_CODES.has(appErr.code) ? EXIT.gh : EXIT.error
 }
 
 /**
@@ -145,17 +146,39 @@ function parsePrNumber(raw: string): number {
   return n
 }
 
-export function parsePrepareTarget(values: { pr?: string; base?: string; head?: string }): PrepareTarget {
+export interface PrepareFlags {
+  pr?: string | undefined
+  base?: string | undefined
+  head?: string | undefined
+  branch?: boolean | undefined
+  uncommitted?: boolean | undefined
+}
+
+const LOCAL_FLAGS = 'pass one of --pr <n>, --branch, --uncommitted, or --base <ref> --head <ref>'
+
+/** The target the flags name. `prepare` resolves a local review's base against the clone. */
+export function parsePrepareTarget(values: PrepareFlags): PrepareTargetInput {
+  const local: LocalKey | undefined =
+    values.branch === true ? 'branch' : values.uncommitted === true ? 'uncommitted' : undefined
+  if (values.branch === true && values.uncommitted === true) {
+    throw new UsageError('--branch and --uncommitted are two reviews; ask for one of them')
+  }
   if (values.pr !== undefined) {
-    if (values.base !== undefined || values.head !== undefined) {
-      throw new UsageError('pass either --pr <n> or --base <ref> --head <ref>, not both')
+    if (values.base !== undefined || values.head !== undefined || local !== undefined) {
+      throw new UsageError(LOCAL_FLAGS)
     }
     return { kind: 'pr', number: parsePrNumber(values.pr) }
   }
+  if (local !== undefined) {
+    if (values.head !== undefined) {
+      throw new UsageError(`--${local} reviews this clone, so it takes no --head`)
+    }
+    return { kind: 'local', source: local, base: values.base }
+  }
   if (values.base !== undefined && values.head !== undefined) {
     return { kind: 'refs', base: values.base, head: values.head }
   }
-  throw new UsageError('prepare needs --pr <n> or --base <ref> --head <ref>')
+  throw new UsageError(`prepare needs a target: ${LOCAL_FLAGS}`)
 }
 
 export async function runPrepare(ctx: AppContext, argv: string[], io: CliIo): Promise<number> {
@@ -165,12 +188,16 @@ export async function runPrepare(ctx: AppContext, argv: string[], io: CliIo): Pr
       pr: { type: 'string' },
       base: { type: 'string' },
       head: { type: 'string' },
+      branch: { type: 'boolean' },
+      uncommitted: { type: 'boolean' },
       force: { type: 'boolean' },
     },
     strict: true,
   })
-  const target = parsePrepareTarget(values)
-  const result = await prepare(ctx, target, { force: values.force === true, log: phase => io.stderr(phase) })
+  const result = await prepare(ctx, parsePrepareTarget(values), {
+    force: values.force === true,
+    log: phase => io.stderr(phase),
+  })
   printJson(io, result)
   return EXIT.ok
 }
@@ -186,7 +213,11 @@ async function validateFile(
   }
   const artifact = ReviewArtifactSchema.safeParse(parsed.raw)
   const input = artifact.success ? artifactToModelOutput(artifact.data satisfies ReviewArtifact) : parsed.raw
-  const result = validateModelOutput(input, await validationInput(ctx, context, input))
+  // A stored canvas may predate the rules about what a generation must hide; only its correctness is checked.
+  const result = validateModelOutput(input, {
+    ...(await validationInput(ctx, context, input)),
+    storedArtifact: artifact.success,
+  })
   return { ok: result.ok, errors: result.errors }
 }
 
@@ -308,6 +339,8 @@ export async function runPublish(ctx: AppContext, argv: string[], io: CliIo): Pr
     harness: parseHarness(values.harness),
     allowStale: values['allow-stale'] === true,
   })
+  if (result.sharing.status === 'failed')
+    io.stderr(`${result.sharing.warning} ZIP: ${result.sharing.zipPath}`)
   printJson(io, result)
   return EXIT.ok
 }
@@ -368,8 +401,8 @@ async function resolveHead(
   if (prNumber === undefined) {
     throw new UsageError('export needs --pr <n> or --head <ref|sha>')
   }
-  const meta = await fetchPrMeta(ctx.gh, ctx.config.repo, prNumber)
-  const { headSha } = await fetchPrRefs(ctx.git, meta)
+  const meta = await ctx.config.host.fetchPrMeta(ctx.gh, ctx.config.repo, prNumber)
+  const { headSha } = await fetchPrRefs(ctx.git, ctx.config.host, meta)
   return { headSha, prNumber }
 }
 
@@ -387,7 +420,7 @@ export async function runExport(ctx: AppContext, argv: string[], io: CliIo): Pro
     out: values.out,
   })
   printJson(io, result)
-  io.stderr(`drag ${result.path} into the pull request description or a comment`)
+  io.stderr(`drag ${result.path} into the ${ctx.config.host.noun} description or a comment`)
   return EXIT.ok
 }
 
@@ -445,9 +478,9 @@ export async function runImport(ctx: AppContext, argv: string[], io: CliIo): Pro
   const options: Parameters<typeof importCanvas>[1] = { bytes, force: values.force === true }
   if (values.pr !== undefined) {
     const prNumber = parsePrNumber(values.pr)
-    const meta = await fetchPrMeta(ctx.gh, ctx.config.repo, prNumber)
+    const meta = await ctx.config.host.fetchPrMeta(ctx.gh, ctx.config.repo, prNumber)
     options.prNumber = prNumber
-    options.currentHeadSha = (await fetchPrRefs(ctx.git, meta)).headSha
+    options.currentHead = await fetchPrRefs(ctx.git, ctx.config.host, meta)
   }
   printJson(io, await importCanvas(ctx, options))
   return EXIT.ok

package/src/config.ts

@@ -2,6 +2,8 @@ import path from 'node:path'
 import type { Repo } from './contract/review-artifact.js'
 import { isChatAgent, type SettingsOverrides } from './contract/settings.js'
 import { type Git, GitError } from './git/git.js'
+import type { Host } from './host/host.js'
+import { type OriginRemote, parseOriginRemote } from './host/remote.js'
 import { resolveDataDir } from './store/data-dir.js'
 
 export const DEFAULT_PORT = 3010
@@ -22,6 +24,8 @@ export interface RuntimeConfig {
   commonDir: string
   dataDir: string
   repo: Repo
+  /** The forge origin points at, which owns every request or answer that differs between them. */
+  host: Host
   /** Dev only: every PR reports `ready` with this artifact re-keyed to the live head. */
   fixtureCanvasPath: string | null
   /** Chat agent and model the flags force for this run, if any. */
@@ -61,36 +65,19 @@ export async function resolveCommonDir(git: Git): Promise<string> {
   return git.commonDir()
 }
 
-/** Parses the two URL forms GitHub gives out: ssh (`git@github.com:o/r.git`) and https. */
-export function parseGithubRemote(url: string): Repo | null {
-  const m =
-    /^(?:git@github\.com:|ssh:\/\/git@github\.com\/|https?:\/\/(?:[^@/]+@)?github\.com\/)([^/]+)\/([^/]+?)(?:\.git)?\/?$/.exec(
-      url.trim()
-    )
-  if (!m || m[1] === undefined || m[2] === undefined) {
-    return null
-  }
-  return { owner: m[1], name: m[2] }
-}
+export const ORIGIN_HINT =
+  'add a github.com or GitLab origin, or set PR_REVIEW_HOST=gitlab for self-hosted GitLab'
 
-export async function resolveGithubRepo(git: Git): Promise<Repo> {
+export async function resolveOrigin(git: Git, env: NodeJS.ProcessEnv = {}): Promise<OriginRemote> {
   const url = await git.remoteUrl('origin')
   if (url === null) {
-    throw new ConfigError(
-      'NO_ORIGIN',
-      'the repository has no "origin" remote',
-      'add one that points at GitHub'
-    )
+    throw new ConfigError('NO_ORIGIN', 'the repository has no "origin" remote', ORIGIN_HINT)
   }
-  const repo = parseGithubRemote(url)
-  if (repo === null) {
-    throw new ConfigError(
-      'NO_ORIGIN',
-      `origin is not a GitHub URL: ${url}`,
-      'only github.com repositories are supported'
-    )
+  const parsed = parseOriginRemote(url, env)
+  if (parsed === null) {
+    throw new ConfigError('NO_ORIGIN', `origin is not a GitHub or GitLab URL: ${url}`, ORIGIN_HINT)
   }
-  return repo
+  return parsed
 }
 
 /** `--agent` names one of the agents the chat knows; anything else is a usage error. */
@@ -139,7 +126,7 @@ export async function loadRuntimeConfig(
 ): Promise<RuntimeConfig> {
   const repoRoot = await resolveRepoRoot(git)
   const commonDir = await resolveCommonDir(git)
-  const repo = await resolveGithubRepo(git)
+  const { repo, host } = await resolveOrigin(git, env)
   const port = flags.port ?? parsePort(readEnv(env, 'PR_REVIEW_PORT'), DEFAULT_PORT)
   const dataDir = resolveDataDir({ override: flags.dataDir ?? readEnv(env, 'PR_REVIEW_DATA_DIR'), commonDir })
   return {
@@ -148,6 +135,7 @@ export async function loadRuntimeConfig(
     commonDir,
     dataDir,
     repo,
+    host,
     fixtureCanvasPath: flags.fixtureCanvas === undefined ? null : path.resolve(cwd, flags.fixtureCanvas),
     chatOverrides: parseChatOverrides(flags),
   }

package/src/contract/api.ts

@@ -2,7 +2,8 @@ import type { z } from 'zod'
 import type { CanvasManifest } from './canvas-manifest.js'
 import type { CommentsPayload, IssueComment, ReviewComment } from './comments.js'
 import type { SharedCanvasInfoSchema } from './discovery.js'
-import type { FileEntry, Pr, ReviewArtifact } from './review-artifact.js'
+import type { FileEntry, FoldLevel, Pr, ReviewArtifact } from './review-artifact.js'
+import type { LocalKey, ReviewKey } from './review-key.js'
 import type { PrState } from './state.js'
 
 export const ERROR_CODES = [
@@ -16,10 +17,14 @@ export const ERROR_CODES = [
   'GH_MISSING',
   'GH_UNAUTHENTICATED',
   'GITHUB_API_ERROR',
+  'GLAB_MISSING',
+  'GLAB_UNAUTHENTICATED',
+  'GITLAB_API_ERROR',
   'PR_NOT_FOUND',
   'CANVAS_NOT_FOUND',
   'CANVAS_INVALID',
   'CANVAS_REPO_MISMATCH',
+  'CANVAS_PR_MISMATCH',
   'CANVAS_TOO_LARGE',
   'CANVAS_STALE',
   'MODEL_INVALID',
@@ -65,6 +70,17 @@ export interface StaleInfo {
   commitsBehind?: number
 }
 
+/**
+ * A ready canvas generated for an earlier commit of the pull request whose diff is identical to
+ * the head's, so the page keeps it and says so.
+ */
+export interface CarriedOverInfo {
+  canvasHeadSha: string
+  currentHeadSha: string
+  /** How many commits the head is ahead of the canvas's commit; absent when the head does not contain it. */
+  commitsBehind?: number
+}
+
 /** The answer of `POST /import`, of `pr-review import`, and of an imported shared canvas. */
 export interface ImportResult {
   status: 'ready' | 'stale' | 'exists'
@@ -88,6 +104,15 @@ export interface SharedCanvasFetchResponse {
 /** A canvas zip found on the pull request. Shaped by the schema the discovery cache stores. */
 export type SharedCanvasInfo = z.infer<typeof SharedCanvasInfoSchema>
 
+/** The forge the server talks to, as the page and the health endpoint learn it. */
+export interface PublicHost {
+  kind: 'github' | 'gitlab'
+  /** `GitHub` or `GitLab`, for the words on the page. */
+  label: string
+  /** `https://github.com` or the GitLab instance, for links to profiles. */
+  webBase: string
+}
+
 export interface PrBundle {
   status: BundleStatus
   pr: Pr
@@ -96,8 +121,18 @@ export interface PrBundle {
   artifact?: ReviewArtifact
   canvas?: CanvasInfo
   stale?: StaleInfo
+  /** Set on a ready bundle whose canvas was generated for another commit with an identical diff. */
+  carriedOver?: CarriedOverInfo
+  /**
+   * The canvas the reviewed marks on this page were made on, when they followed a line of descent
+   * onto this one; absent when none did. Not necessarily this canvas's own basis: the reviewer may
+   * have marked nothing on the canvases in between.
+   */
+  marksCarriedFrom?: string
   sharedCanvas?: SharedCanvasInfo
   skillCommand: string
+  /** Set on a local review: work that has no pull request, so the forge side of the page is off. */
+  local?: LocalKey
   comments: CommentsPayload
   state: PrState
   capabilities: Capabilities
@@ -111,7 +146,8 @@ export interface PrBundle {
 
 /** Every answer of a state route, so the page can replace its copy of the state in one step. */
 export interface StateResponse {
-  prNumber: number
+  /** The target the state belongs to: a pull request number, or `local`. */
+  prNumber: ReviewKey
   state: PrState
 }
 
@@ -132,12 +168,20 @@ export interface ReviewSummary {
 export interface ReviewBodyResponse {
   headSha: string
   body: string
+  /** How many pending comments would go out with the review. */
+  pending: number
   /** The titles of the layers that still need a look; approve is refused while this is not empty. */
   unreviewed: string[]
 }
 
 export interface PostReviewResponse {
   review: ReviewSummary
+  comments: ReviewComment[]
+  warnings: string[]
+  /** How many pending comments went out with the review. */
+  submitted: number
+  /** The state after the pending review was cleared, so the page drops its drafts in one step. */
+  state: PrState
 }
 
 export interface PatchesResponse {
@@ -172,6 +216,7 @@ export interface HealthResponse {
     agentAuth?: HealthCheck
   }
   repo: { owner: string; name: string } | null
+  host: PublicHost
   dataDir: string
   chat: ChatStatus
 }
@@ -188,3 +233,14 @@ export interface ChatStatus {
 export interface HomeData {
   recentPrs: Array<{ number: number; title: string; updatedAt: string }>
 }
+
+/** The JSON the review page carries in its bootstrap script; the app reads it before any request. */
+export interface ReviewBootstrap {
+  prNumber: ReviewKey
+  owner: string
+  repo: string
+  version: string
+  host: PublicHost
+  /** The reading level the canvas opens at, from the settings file. */
+  foldLevel: FoldLevel
+}

package/src/contract/canvas-manifest.ts

@@ -23,6 +23,13 @@ export const CanvasIndexSchema = z.object({
       generatedAt: z.string(),
       source: z.enum(['local', 'import']),
       importedAt: z.string().optional(),
+      /**
+       * The canvas this one was generated from. Kept here as well as on the artifact so the line
+       * of descent can be walked from the index alone, without opening every canvas on the way.
+       */
+      basisCanvasSha: z.string().optional(),
+      /** A snapshot of uncommitted work: it sits on no branch, so no pull request can claim it. */
+      worktree: z.boolean().optional(),
     })
   ),
 })

package/src/contract/comments.ts

@@ -96,3 +96,8 @@ export {
 export function emptyComments(headSha: string, fetchedAt: string): CommentsPayload {
   return { fetchedAt, headSha, reviewComments: [], issueComments: [] }
 }
+
+export interface FetchCommentsResult {
+  payload: CommentsPayload
+  warnings: string[]
+}

package/src/contract/discovery.ts

@@ -3,9 +3,12 @@ import { z } from 'zod'
 export const SharedCanvasInfoSchema = z.object({
   url: z.string(),
   name: z.string(),
-  matchesHead: z.boolean(),
+  /** The attachment's file name carries the head's sha; it says nothing about whether it is current. */
+  namesHead: z.boolean(),
   downloadable: z.boolean(),
-  reason: z.enum(['auth-required', 'not-zip', 'too-large', 'network', 'name-mismatch']).optional(),
+  reason: z
+    .enum(['auth-required', 'not-zip', 'too-large', 'network', 'name-mismatch', 'pr-mismatch'])
+    .optional(),
 })
 
 /**

package/src/contract/generation-context.ts

@@ -1,15 +1,45 @@
 import { z } from 'zod'
 import { DefaultLayerSchema, GenerationModeSchema, HighRiskRuleSchema } from '../project-config.js'
 import { DEFAULT_TEST_PATTERNS } from '../review/test-paths.js'
-import { FileEntrySchema, LIMITS, PrSchema, RepoSchema, type TextCaps } from './review-artifact.js'
+import { type LocalKey, LocalKeySchema } from './review-key.js'
+import {
+  FileEntrySchema,
+  LIMITS,
+  POINT_KINDS,
+  PrSchema,
+  RepoSchema,
+  type TextCaps,
+} from './review-artifact.js'
+
+/**
+ * What `prepare` was asked to describe: a pull request, two refs, or one of the two reviews of
+ * work in this clone that has no pull request yet. A `local` target names only its base, because
+ * its head is whatever the branch or the working tree holds when the command runs.
+ */
+export const LocalPrepareTargetSchema = z.object({
+  kind: z.literal('local'),
+  base: z.string().min(1),
+  /** Which local review this is, which is also the key it is filed and served under. */
+  source: LocalKeySchema,
+})
+export type LocalPrepareTarget = z.infer<typeof LocalPrepareTargetSchema>
 
-/** What `prepare` was asked to describe: a pull request, or two refs before a PR exists. */
 export const PrepareTargetSchema = z.discriminatedUnion('kind', [
   z.object({ kind: z.literal('pr'), number: z.number().int().positive() }),
   z.object({ kind: z.literal('refs'), base: z.string().min(1), head: z.string().min(1) }),
+  LocalPrepareTargetSchema,
 ])
 export type PrepareTarget = z.infer<typeof PrepareTargetSchema>
 
+/**
+ * What the CLI parsed, before git has been asked anything. A local review's base may still be
+ * open here: only the clone knows which branch `origin/HEAD` points at. `prepare` resolves it and
+ * records the answer, so `publish` reads a base that cannot drift.
+ */
+export type PrepareTargetInput =
+  | Extract<PrepareTarget, { kind: 'pr' } | { kind: 'refs' }>
+  | { kind: 'local'; base?: string | undefined; source: LocalKey }
+
 const capsShape = {
   summary: z.number().int().positive(),
   layerTitle: z.number().int().positive(),
@@ -23,6 +53,48 @@ const capsShape = {
   diagram: z.number().int().positive(),
 } satisfies Record<keyof TextCaps, z.ZodNumber>
 
+/** Which files the head changes relative to the basis canvas's diff, by path. */
+export const FileDeltaSchema = z.object({
+  unchanged: z.array(z.string()),
+  changed: z.array(z.string()),
+  added: z.array(z.string()),
+  removed: z.array(z.string()),
+})
+export type FileDelta = z.infer<typeof FileDeltaSchema>
+
+export const BasisSplitLayerSchema = z.object({
+  key: z.string().min(1),
+  title: z.string(),
+  /** `carried` when the head touches none of the layer's files. */
+  status: z.enum(['carried', 're-judged']),
+  carriedFiles: z.array(z.string()),
+  reJudgedFiles: z.array(z.string()),
+})
+export type BasisSplitLayer = z.infer<typeof BasisSplitLayerSchema>
+
+export const BasisSplitPointSchema = z.object({
+  kind: z.enum(POINT_KINDS),
+  path: z.string().min(1),
+  title: z.string(),
+  status: z.enum(['carried', 're-judged']),
+})
+export type BasisSplitPoint = z.infer<typeof BasisSplitPointSchema>
+
+/**
+ * The basis canvas of an incremental run, already divided into what the head leaves untouched and
+ * what has to be decided anew. `prepare` computes it, so the generator reads two lists instead of
+ * comparing diffs itself, and `publish` records `canvasSha` on the canvas it stores.
+ */
+export const BasisSplitSchema = z.object({
+  canvasSha: z.string().regex(/^[0-9a-f]{40}$/),
+  /** Absolute path of the basis canvas's `review.json`, in the canvas store. */
+  reviewJsonPath: z.string().min(1),
+  files: FileDeltaSchema,
+  layers: z.array(BasisSplitLayerSchema),
+  points: z.array(BasisSplitPointSchema),
+})
+export type BasisSplit = z.infer<typeof BasisSplitSchema>
+
 /**
  * `context.json`: everything the agent and `publish` need about one prepared canvas. Written by
  * `prepare` next to `prompt.md`; `publish` validates `model.json` against the hunk index and the
@@ -64,6 +136,8 @@ export const GenerationContextSchema = z.object({
   smallPr: z.boolean(),
   /** More than 400 files or 50 000 changed lines: the prompt inlines nothing and tightens the caps. */
   largePr: z.boolean(),
+  /** Absent when this canvas is generated from a blank page: no basis, `--force`, or turned off. */
+  basis: BasisSplitSchema.optional(),
   preparedAt: z.string(),
 })
 export type GenerationContext = z.infer<typeof GenerationContextSchema>

package/src/contract/keys.ts

@@ -9,6 +9,7 @@ export {
   parseHunkId,
   parseLineId,
   pointAnchorId,
+  reviewedId,
   sanitizeKey,
   uniqueKey,
 } from '../../static/js/keys.js'

package/src/contract/pending.ts

@@ -0,0 +1,49 @@
+// A review the reviewer is still writing: comments kept on this machine until the review is
+// submitted, the way a pending review works on the forge's own page.
+import { z } from 'zod'
+import { SideSchema } from './review-artifact.js'
+import { COMMENT_BODY_MAX } from './comments.js'
+
+/**
+ * One comment waiting in the pending review. It names a line the way a posted inline comment
+ * does, so submitting it needs nothing the page has to look up again.
+ */
+export const PendingCommentSchema = z.object({
+  /** Local id, unique inside one target's state. Never a forge id: nothing was posted yet. */
+  id: z.string().min(1),
+  path: z.string().min(1),
+  line: z.number().int().positive(),
+  side: SideSchema,
+  /** The first line of a multi-line comment, absent when it covers one line. */
+  startLine: z.number().int().positive().optional(),
+  body: z.string().min(1).max(COMMENT_BODY_MAX),
+  /** Set when the comment came from an attention point, so the point can be marked posted. */
+  pointFingerprint: z.string().min(1).optional(),
+  /** The commit the reviewer was reading when they wrote it. */
+  headSha: z.string(),
+  createdAt: z.string(),
+  /** Creation time until the reviewer edits the draft. */
+  updatedAt: z.string(),
+})
+export type PendingComment = z.infer<typeof PendingCommentSchema>
+
+/** What the page sends to `POST /api/prs/:n/pending`. */
+export const AddPendingInputSchema = z.object({
+  path: z.string().min(1),
+  line: z.number().int().positive(),
+  side: SideSchema,
+  startLine: z.number().int().positive().optional(),
+  body: z.string().min(1).max(COMMENT_BODY_MAX),
+  pointFingerprint: z.string().min(1).optional(),
+  headSha: z
+    .string()
+    .regex(/^[0-9a-f]{40}$/)
+    .optional(),
+})
+export type AddPendingInput = z.infer<typeof AddPendingInputSchema>
+
+/** What the page sends to `PATCH /api/prs/:n/pending/:id`. */
+export const EditPendingInputSchema = z.object({
+  body: z.string().min(1).max(COMMENT_BODY_MAX),
+})
+export type EditPendingInput = z.infer<typeof EditPendingInputSchema>

package/src/contract/review-artifact.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { DEFAULT_FOLD_LEVEL, FOLD_LEVELS } from '../../static/js/fold-levels.js'
 
 /** Character caps applied to model output. Numbers, so the prompt can print them. */
 export const TEXT_CAPS = {
@@ -79,6 +80,33 @@ export const HARNESSES = ['claude-code', 'codex', 'other'] as const
 export const SideSchema = z.enum(['new', 'old'])
 export type Side = z.infer<typeof SideSchema>
 
+export {
+  contains,
+  coveredRows,
+  fileRows,
+  foldLevelRank,
+  hiddenLines,
+  UNDISCUSSED,
+} from '../../static/js/fold-levels.js'
+export { FOLD_LEVELS }
+export const FoldLevelSchema = z.enum(FOLD_LEVELS)
+export type FoldLevel = z.infer<typeof FoldLevelSchema>
+
+/**
+ * How a stored canvas names its levels. One written before levels existed says `collapsed: true`
+ * and gives its folds no level; both read as light, so it hides exactly what it hid before. Past
+ * this parse every canvas names a level wherever it hides something.
+ */
+const STORED_LEVELS = {
+  collapsed: z
+    .union([z.boolean(), FoldLevelSchema])
+    .transform(value => (value === true ? DEFAULT_FOLD_LEVEL : value === false ? undefined : value)),
+  fold: FoldLevelSchema.default(DEFAULT_FOLD_LEVEL),
+}
+/** The model names a level for every fold and every collapsed file. */
+const MODEL_LEVELS = { collapsed: FoldLevelSchema, fold: FoldLevelSchema }
+type Levels = typeof STORED_LEVELS | typeof MODEL_LEVELS
+
 export const HunkSchema = z.object({
   id: z.string().min(1),
   header: z.string(),
@@ -199,29 +227,35 @@ export function annotationSchema(caps: Caps) {
 export const AnnotationSchema = annotationSchema(ARTIFACT_HARD_CAPS)
 export type Annotation = z.infer<typeof AnnotationSchema>
 
-function codeFoldSchema(caps: Caps) {
+function codeFoldSchema(caps: Caps, level: Levels['fold']) {
   return z.object({
     title: z.string().max(caps.pointTitle).regex(/\S/, 'A fold title must contain visible text'),
     side: SideSchema,
     startLine: z.number().int().positive(),
     endLine: z.number().int().positive(),
+    /** The lowest reading level that hides this range. */
+    level,
   })
 }
-export const CodeFoldSchema = codeFoldSchema(ARTIFACT_HARD_CAPS)
+export const CodeFoldSchema = codeFoldSchema(ARTIFACT_HARD_CAPS, STORED_LEVELS.fold)
 export type CodeFold = z.infer<typeof CodeFoldSchema>
 
-function layerFileBase(caps: Caps, foldTitleCap = caps.pointTitle) {
+function layerFileBase<L extends Levels>(caps: Caps, foldTitleCap: number, levels: L) {
   return {
     path: z.string().min(1),
     hunks: z.array(z.string().min(1)).min(1),
     note: textOrEmpty(caps, 'annotation').optional(),
     annotations: z.array(annotationSchema(caps)),
-    collapsed: z.boolean().optional(),
-    folds: z.array(codeFoldSchema({ ...caps, pointTitle: foldTitleCap })).optional(),
+    /** The lowest reading level that hides the whole file body. */
+    collapsed: levels.collapsed.optional(),
+    folds: z.array(codeFoldSchema({ ...caps, pointTitle: foldTitleCap }, levels.fold)).optional(),
   }
 }
 
-export const LayerFileSchema = z.object({ ...layerFileBase(ARTIFACT_HARD_CAPS), isTest: z.boolean() })
+export const LayerFileSchema = z.object({
+  ...layerFileBase(ARTIFACT_HARD_CAPS, ARTIFACT_HARD_CAPS.pointTitle, STORED_LEVELS),
+  isTest: z.boolean(),
+})
 export type LayerFile = z.infer<typeof LayerFileSchema>
 
 export const LayerKeySchema = z
@@ -298,6 +332,15 @@ export const ReviewArtifactSchema = z.object({
   generator: GeneratorSchema,
   source: z.enum(['local', 'import']),
   importedAt: z.string().optional(),
+  /**
+   * The basis canvas this one was generated from, when the run was incremental. It records where
+   * the carried content came from; a reviewer's server recomputes for itself which marks may
+   * follow, so this sha is a pointer and never a claim about what was reviewed.
+   */
+  basisCanvasSha: z
+    .string()
+    .regex(/^[0-9a-f]{40}$/)
+    .optional(),
 })
 export type ReviewArtifact = z.infer<typeof ReviewArtifactSchema>
 
@@ -317,7 +360,7 @@ export function modelOutputSchema(textCaps: TextCaps) {
         z.object({
           ...layerBase(caps),
           risk: z.array(z.object({ label: z.string().min(1), reason: z.string().min(1) })).optional(),
-          files: z.array(z.object(layerFileBase(caps, textCaps.pointTitle))),
+          files: z.array(z.object(layerFileBase(caps, textCaps.pointTitle, MODEL_LEVELS))),
         })
       )
       .min(1),