@vintasoftware/pr-review-canvas 0.4.0 → 0.5.0

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),

package/src/contract/reviews.ts

@@ -1,6 +1,10 @@
 import { z } from 'zod'
 
-export const REVIEW_EVENTS = ['APPROVE', 'REQUEST_CHANGES'] as const
+/**
+ * `COMMENT` leaves a review with no verdict, the way a thread-level review does: the body and the
+ * comments land, and nothing is approved or rejected.
+ */
+export const REVIEW_EVENTS = ['COMMENT', 'APPROVE', 'REQUEST_CHANGES'] as const
 export const ReviewEventSchema = z.enum(REVIEW_EVENTS)
 export type ReviewEvent = (typeof REVIEW_EVENTS)[number]
 
@@ -8,6 +12,11 @@ export const PostReviewInputSchema = z.object({
   event: ReviewEventSchema,
   /** The dialog sends the body the user read, edited or not. */
   body: z.string().min(1).max(65536).optional(),
+  /**
+   * Whether the pending comments go out with this review. True unless the page says otherwise, so
+   * a reviewer who wrote drafts never submits a review that silently leaves them behind.
+   */
+  includePending: z.boolean().default(true),
   /** The commit the dialog named. The server refuses the review when the head moved on. */
   headSha: z
     .string()

package/src/contract/settings.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { DEFAULT_FOLD_LEVEL, FOLD_LEVELS } from '../../static/js/fold-levels.js'
 import { DEFAULT_SKIN, isSkin, SKINS, type Skin } from '../../static/js/skin.js'
 import { DEFAULT_THEME, isTheme, THEMES, type Theme } from '../../static/js/theme.js'
 
@@ -24,6 +25,8 @@ export const SettingsSchema = z.object({
   version: z.literal(1),
   skin: z.enum(SKINS),
   theme: z.enum(THEMES),
+  /** The reading level every review opens at; the control on the page changes it for one page. */
+  foldLevel: z.enum(FOLD_LEVELS),
   agent: z.enum(CHAT_AGENTS),
   model: z.string().min(1).nullable(),
   chatTimeoutSec: z.number().int().min(CHAT_TIMEOUT_MIN_SEC).max(CHAT_TIMEOUT_MAX_SEC),
@@ -35,6 +38,7 @@ export const DEFAULT_SETTINGS: Settings = {
   version: 1,
   skin: DEFAULT_SKIN,
   theme: DEFAULT_THEME,
+  foldLevel: DEFAULT_FOLD_LEVEL,
   agent: 'claude',
   model: null,
   chatTimeoutSec: 600,
@@ -45,6 +49,7 @@ export const DEFAULT_SETTINGS: Settings = {
 export const SettingsInputSchema = z.object({
   skin: z.enum(SKINS).optional(),
   theme: z.enum(THEMES).optional(),
+  foldLevel: z.enum(FOLD_LEVELS).optional(),
   agent: z.enum(CHAT_AGENTS).optional(),
   model: z.string().max(200).nullable().optional(),
   chatTimeoutSec: z.number().int().min(CHAT_TIMEOUT_MIN_SEC).max(CHAT_TIMEOUT_MAX_SEC).optional(),

package/src/contract/state.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { PendingCommentSchema } from './pending.js'
 
 export const ChatThreadSchema = z.object({
   name: z.string(),
@@ -12,25 +13,27 @@ export const ChatThreadSchema = z.object({
 export type ChatThread = z.infer<typeof ChatThreadSchema>
 
 /**
- * State files written before the marks were keyed to the canvas carry `reviewedHeadSha`, which
- * held the same commit under its older name. The old key is read when the new one is absent, so
- * a reviewer's marks survive the upgrade; the next write stores the new name.
+ * Version 1 keyed a reviewed mark by the layer's position in the canvas (`layer:layer-2`). Marks
+ * are keyed by the layer's own key now, so a regenerated canvas that reorders its layers keeps
+ * them straight, and the old positional marks cannot be translated without the canvas they were
+ * made on. They are dropped; the rest of the file (dismissals, posted comments, chat threads)
+ * carries over untouched.
  */
-const withRenamedMarksKey = (raw: unknown): unknown => {
+const dropPositionalMarks = (raw: unknown): unknown => {
   if (raw === null || typeof raw !== 'object') {
     return raw
   }
-  const { reviewedHeadSha, ...rest } = raw as Record<string, unknown>
-  if (reviewedHeadSha === undefined || 'reviewedCanvasSha' in rest) {
-    return raw
+  const { reviewedHeadSha: _reviewedHeadSha, ...rest } = raw as Record<string, unknown>
+  if (rest['version'] !== 1) {
+    return rest
   }
-  return { ...rest, reviewedCanvasSha: reviewedHeadSha }
+  return { ...rest, version: 2, reviewed: {}, reviewedCanvasSha: undefined }
 }
 
 export const PrStateSchema = z.preprocess(
-  withRenamedMarksKey,
+  dropPositionalMarks,
   z.object({
-    version: z.literal(1),
+    version: z.literal(2),
     /**
      * Counts the writes to this file. The page uses it to tell a newer answer from an older one
      * when two of its requests overlap. Absent in state files of older tool versions.
@@ -40,7 +43,8 @@ export const PrStateSchema = z.preprocess(
     /**
      * The commit of the canvas the reviewed marks were made on: the head, or the commit a carried-over
      * canvas was generated for. A canvas for another commit describes other code, so the marks start
-     * again with it. Absent in state files of older tool versions.
+     * again with it, unless that canvas names this one as its basis and the code behind a mark is
+     * untouched. Absent in state files of older tool versions.
      */
     reviewedCanvasSha: z.string().optional(),
     hiddenThreads: z.record(z.string(), z.object({ at: z.string() })),
@@ -48,6 +52,12 @@ export const PrStateSchema = z.preprocess(
       z.object({ commentId: z.number().int(), pointFingerprint: z.string().optional(), at: z.string() })
     ),
     dismissed: z.record(z.string(), z.object({ at: z.string(), reason: z.string().optional() })),
+    /**
+     * The comments of the review being written, in the order they were added. They live here and
+     * nowhere else until the review is submitted, so a reload does not lose a draft. A state file
+     * of an older tool version has none, which reads as an empty list.
+     */
+    pending: z.array(PendingCommentSchema).default([]),
     chat: z.object({ threads: z.array(ChatThreadSchema), activeThread: z.string().optional() }),
     updatedAt: z.string(),
   })
@@ -56,12 +66,13 @@ export type PrState = z.infer<typeof PrStateSchema>
 
 export function emptyState(updatedAt: string): PrState {
   return {
-    version: 1,
+    version: 2,
     rev: 0,
     reviewed: {},
     hiddenThreads: {},
     posted: [],
     dismissed: {},
+    pending: [],
     chat: { threads: [] },
     updatedAt,
   }

package/src/contract/validation.ts

@@ -15,6 +15,7 @@ export const VALIDATION_CODES = [
   'RISK_IN_OTHER',
   'ANNOTATION_OUTSIDE_HUNK',
   'FOLD_INVALID',
+  'FOLD_MISSING',
   'POINT_OUTSIDE_DIFF',
   'TOO_MANY_POINTS',
   'TEST_PATH_UNKNOWN',

package/src/github/post-review.ts

@@ -1,8 +1,11 @@
 import { z } from 'zod'
+import type { PendingComment } from '../contract/pending.js'
 import type { ReviewEvent } from '../contract/reviews.js'
-import type { ReviewSummary } from '../contract/api.js'
+import type { PostedReview } from '../host/host.js'
 import type { Repo } from '../contract/review-artifact.js'
-import type { HostClient } from '../host/client.js'
+import { fetchAllPages, type HostClient } from '../host/client.js'
+import { mapReviewComment } from './comments.js'
+import { ghSide } from './post-comment.js'
 
 const GhReviewSchema = z.object({
   id: z.number().int(),
@@ -11,19 +14,72 @@ const GhReviewSchema = z.object({
   submitted_at: z.string().nullable().optional(),
 })
 
-/** Posts the review. GitHub decides what the event means; the tool only fills the body and sha. */
+/** One entry of the `comments` array GitHub reads when a review is created with its comments. */
+interface GhReviewComment {
+  path: string
+  body: string
+  line: number
+  side: 'LEFT' | 'RIGHT'
+  start_line?: number
+  start_side?: 'LEFT' | 'RIGHT'
+}
+
+/**
+ * The pending comments as GitHub's review payload names them. A range is sent only when it covers
+ * more than the anchor line, because GitHub rejects a start_line equal to line.
+ */
+export function reviewComments(pending: ReadonlyArray<PendingComment>): GhReviewComment[] {
+  return pending.map(p => ({
+    path: p.path,
+    body: p.body,
+    line: p.line,
+    side: ghSide(p.side),
+    ...(p.startLine !== undefined && p.startLine !== p.line
+      ? { start_line: p.startLine, start_side: ghSide(p.side) }
+      : {}),
+  }))
+}
+
+/**
+ * Posts the review. GitHub decides what the event means; the tool only fills the body, the sha,
+ * and the comments the reviewer had waiting, which land as part of the same review.
+ */
 export async function postReview(
   gh: HostClient,
   repo: Repo,
   number: number,
   headSha: string,
-  input: { event: ReviewEvent; body: string }
-): Promise<ReviewSummary> {
+  input: { event: ReviewEvent; body: string; comments?: ReadonlyArray<PendingComment> }
+): Promise<PostedReview> {
+  const comments = input.comments ?? []
   const raw = await gh.post(`repos/${repo.owner}/${repo.name}/pulls/${number}/reviews`, {
     event: input.event,
     body: input.body,
     commit_id: headSha,
+    ...(comments.length === 0 ? {} : { comments: reviewComments(comments) }),
   })
   const r = GhReviewSchema.parse(raw)
-  return { id: r.id, state: r.state, url: r.html_url, submittedAt: r.submitted_at ?? null }
+  const posted: PostedReview = {
+    id: r.id,
+    state: r.state,
+    url: r.html_url,
+    submittedAt: r.submitted_at ?? null,
+    comments: [],
+    warnings: [],
+  }
+  if (comments.length > 0) {
+    try {
+      const rawComments = await fetchAllPages(
+        gh,
+        `repos/${repo.owner}/${repo.name}/pulls/${number}/reviews/${r.id}/comments`
+      )
+      posted.comments = rawComments.map(c => mapReviewComment(c, new Set()))
+    } catch (err) {
+      // The write succeeded. A failed read must not invite submitting the same review again.
+      posted.warnings.push(
+        `Review posted, but its comments could not be loaded: ${err instanceof Error ? err.message : String(err)}. Refresh to see them.`
+      )
+    }
+  }
+  return posted
 }

package/src/gitlab/post-review.ts

@@ -1,8 +1,11 @@
 import { z } from 'zod'
-import type { ReviewSummary } from '../contract/api.js'
+import type { PostedReview } from '../host/host.js'
+import type { PendingComment } from '../contract/pending.js'
 import type { Repo } from '../contract/review-artifact.js'
 import type { ReviewEvent } from '../contract/reviews.js'
 import type { HostClient } from '../host/client.js'
+import type { Derived } from '../store/derived-store.js'
+import { publishGitlabDrafts } from './publish-drafts.js'
 import { gitlabMrUrl, gitlabNoteUrl, gitlabProjectApi } from './project.js'
 
 const GlNoteSchema = z.object({
@@ -17,37 +20,73 @@ const GlMrSchema = z.object({
 })
 
 /**
- * GitLab has no GitHub-style review event. Approve calls the approvals API; request-changes posts
- * the review body as an MR note so the text still lands on the merge request.
+ * GitLab has no GitHub-style review event. Approve calls the approvals API; request-changes and a
+ * comment-only review post the review body as an MR note so the text still lands on the merge
+ * request. Pending comments and the summary publish together through the Draft Notes API.
  */
 export async function postGitlabReview(
   client: HostClient,
   repo: Repo,
   number: number,
   headSha: string,
-  input: { event: ReviewEvent; body: string },
-  webBase: string
-): Promise<ReviewSummary> {
+  input: { event: ReviewEvent; body: string; comments?: ReadonlyArray<PendingComment> },
+  webBase: string,
+  diff: Derived = { files: [], patches: {} }
+): Promise<PostedReview> {
   const base = `${gitlabProjectApi(repo)}/merge_requests/${number}`
   const mrUrl = gitlabMrUrl(webBase, repo, number)
+  const batched = (input.comments?.length ?? 0) > 0
+  const { comments, warnings } = batched
+    ? await publishGitlabDrafts(client, repo, number, headSha, input, webBase, diff)
+    : { comments: [], warnings: [] }
   if (input.event === 'APPROVE') {
-    if (input.body.trim() !== '') {
+    if (!batched && input.body.trim() !== '') {
       await client.post(`${base}/notes`, { body: input.body })
     }
-    const raw = await client.post(`${base}/approve`, { sha: headSha })
+    let raw: unknown
+    try {
+      raw = await client.post(`${base}/approve`, { sha: headSha })
+    } catch (error) {
+      if (!batched) throw error
+      return {
+        comments,
+        warnings: [
+          ...warnings,
+          'Comments published, but approval failed. Approve the merge request in GitLab.',
+        ],
+        id: number,
+        state: 'COMMENTED',
+        url: mrUrl,
+        submittedAt: new Date().toISOString(),
+      }
+    }
     const mr = GlMrSchema.safeParse(raw).data ?? {}
     return {
+      comments,
+      warnings,
       id: mr.id ?? mr.iid ?? number,
       state: 'APPROVED',
       url: mr.web_url ?? mrUrl,
       submittedAt: new Date().toISOString(),
     }
   }
+  if (batched) {
+    return {
+      comments,
+      warnings,
+      id: number,
+      state: input.event === 'COMMENT' ? 'COMMENTED' : 'CHANGES_REQUESTED',
+      url: mrUrl,
+      submittedAt: new Date().toISOString(),
+    }
+  }
   const raw = await client.post(`${base}/notes`, { body: input.body })
   const note = GlNoteSchema.parse(raw)
   return {
+    comments,
+    warnings: [],
     id: note.id,
-    state: 'CHANGES_REQUESTED',
+    state: input.event === 'COMMENT' ? 'COMMENTED' : 'CHANGES_REQUESTED',
     url: gitlabNoteUrl(webBase, repo, number, note.id),
     submittedAt: note.created_at ?? new Date().toISOString(),
   }

package/src/gitlab/publish-drafts.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod'
+import type { PendingComment } from '../contract/pending.js'
+import type { Repo } from '../contract/review-artifact.js'
+import type { HostClient } from '../host/client.js'
+import type { Derived } from '../store/derived-store.js'
+import { fetchGitlabComments } from './comments.js'
+import { fetchMrDiffRefs } from './mr.js'
+import { inlinePosition } from './post-comment.js'
+import { gitlabProjectApi } from './project.js'
+
+const DraftSchema = z.object({ id: z.number().int() })
+
+/** Stage this submission privately, then publish it as one GitLab review. */
+export async function publishGitlabDrafts(
+  client: HostClient,
+  repo: Repo,
+  number: number,
+  headSha: string,
+  input: { body: string; comments?: ReadonlyArray<PendingComment> },
+  webBase: string,
+  diff: Derived
+) {
+  const base = `${gitlabProjectApi(repo)}/merge_requests/${number}/draft_notes`
+  const list = async () => z.array(DraftSchema).parse(await client.api(base))
+  if ((await list()).length > 0) {
+    throw new Error('Finish or discard your pending review in GitLab before submitting from the canvas.')
+  }
+  const refs = await fetchMrDiffRefs(client, repo, number)
+  if (refs.head_sha !== headSha) throw new Error('The merge request changed. Refresh before submitting.')
+  const notes: Array<{ note: string; position?: Record<string, unknown> }> = (input.comments ?? []).map(
+    p => ({
+      note: p.body,
+      position: inlinePosition(refs, { ...p, kind: 'inline' }, diff),
+    })
+  )
+  if (input.body.trim() !== '') notes.push({ note: input.body })
+  const fetchComments = () => fetchGitlabComments(client, repo, number, headSha, () => new Date(), webBase)
+  const before = new Set((await fetchComments()).payload.reviewComments.map(c => c.id))
+  const staged: number[] = []
+  try {
+    for (const note of notes) staged.push(DraftSchema.parse(await client.post(base, note)).id)
+    const current = await list()
+    if (current.length !== staged.length || current.some(d => !staged.includes(d.id))) {
+      throw new Error(
+        'Your pending review changed in GitLab. Finish it there before submitting from the canvas.'
+      )
+    }
+    await client.post(`${base}/bulk_publish`, {})
+  } catch (error) {
+    // Delete only drafts created by this attempt; local copies remain available for retry.
+    const cleanup = await Promise.allSettled(staged.map(id => client.post(`${base}/${id}`, {}, 'DELETE')))
+    if (cleanup.some(result => result.status === 'rejected')) {
+      throw new Error(
+        'Submission failed and some staged drafts remain in GitLab. Inspect your pending review there before retrying.',
+        { cause: error }
+      )
+    }
+    throw error
+  }
+  try {
+    const { payload } = await fetchComments()
+    return { comments: payload.reviewComments.filter(c => !before.has(c.id)), warnings: [] as string[] }
+  } catch {
+    return {
+      comments: [],
+      warnings: ['Review published, but its comments could not be refreshed. Reload to see them.'],
+    }
+  }
+}

package/src/host/client.ts

@@ -13,7 +13,7 @@ export interface HostClient {
   /** `<cli> api -i --method GET <path>`: the response headers as well as the body. */
   apiWithHeaders(path: string): Promise<CliResponse>
   /** Send JSON over stdin. Defaults to POST; comment edits use PATCH or PUT. */
-  post(path: string, body: unknown, method?: 'POST' | 'PATCH' | 'PUT'): Promise<unknown>
+  post(path: string, body: unknown, method?: 'POST' | 'PATCH' | 'PUT' | 'DELETE'): Promise<unknown>
   /** `<cli> api graphql`; returns the parsed `data` object. */
   graphql(query: string, variables: Record<string, string | number>): Promise<unknown>
   /** `<cli> auth status`: is the CLI installed and logged in? */
@@ -196,7 +196,8 @@ export function createHostClient(spec: HostCliSpec, exec: CliExec = execCli): Ho
       // The payload goes over stdin, so no comment text ever appears in an argument list. The
       // content type is named because `glab` does not infer it and GitLab answers 415 without it.
       const args = ['api', '--method', method, path, '--input', '-', '-H', 'Content-Type: application/json']
-      return JSON.parse((await run(path, args, JSON.stringify(body))).stdout) as unknown
+      const { stdout } = await run(path, args, JSON.stringify(body))
+      return stdout.trim() === '' ? null : (JSON.parse(stdout) as unknown)
     },
     graphql: async (query, variables) => {
       const args = ['api', 'graphql', '-f', `query=${query}`]

package/src/host/host.ts

@@ -1,12 +1,18 @@
 import { shareGithubCanvas } from '../github/canvas-comment.js'
 import { shareGitlabCanvas } from '../gitlab/canvas-comment.js'
 import type { Capabilities, PublicHost, ReviewSummary } from '../contract/api.js'
-import type { FetchCommentsResult, PostCommentInput, PostCommentResult } from '../contract/comments.js'
+import type {
+  FetchCommentsResult,
+  PostCommentInput,
+  PostCommentResult,
+  ReviewComment,
+} from '../contract/comments.js'
 import type { Repo } from '../contract/review-artifact.js'
 import { GITHUB_ATTACHMENTS } from '../github/attachments.js'
 import { probeCapabilities } from '../github/capabilities.js'
 import { fetchComments } from '../github/comments.js'
 import { postComment } from '../github/post-comment.js'
+import type { PendingComment } from '../contract/pending.js'
 import type { ReviewEvent } from '../contract/reviews.js'
 import { postReview } from '../github/post-review.js'
 import { fetchPrMeta } from '../github/pr.js'
@@ -23,6 +29,12 @@ import { GH_CLI, glabCli, type HostClient, type HostCliSpec } from './client.js'
 
 export type HostKind = PublicHost['kind']
 
+/** The review and the comments created by this submission. */
+export interface PostedReview extends ReviewSummary {
+  comments: ReviewComment[]
+  warnings: string[]
+}
+
 /** How canvas zips attached to a review are found and fetched on one forge. */
 export interface HostAttachments {
   /** Zip links in one markdown text, as absolute URLs this host serves. */
@@ -68,13 +80,19 @@ export interface Host {
     input: PostCommentInput,
     diff: Derived
   ): Promise<PostCommentResult>
+  /**
+   * Submits the review, with the comments the reviewer had waiting. GitHub takes them in the one
+   * call that creates the review; GitLab stages and batch-publishes draft notes, which is why the
+   * diff is passed here too.
+   */
   postReview(
     client: HostClient,
     repo: Repo,
     number: number,
     headSha: string,
-    input: { event: ReviewEvent; body: string }
-  ): Promise<ReviewSummary>
+    input: { event: ReviewEvent; body: string; comments?: ReadonlyArray<PendingComment> },
+    diff: Derived
+  ): Promise<PostedReview>
   probeCapabilities(client: HostClient, repo: Repo): Promise<Capabilities>
   canvasCommentLimit: number
   shareCanvas(client: HostClient, repo: Repo, number: number, body: string): Promise<string>
@@ -121,8 +139,8 @@ export function gitlabHost(hostname: string): Host {
       fetchGitlabComments(client, repo, number, headSha, now, webBase),
     postComment: (client, repo, number, headSha, input, diff) =>
       postGitlabComment(client, repo, number, headSha, input, { webBase, ...diff }),
-    postReview: (client, repo, number, headSha, input) =>
-      postGitlabReview(client, repo, number, headSha, input, webBase),
+    postReview: (client, repo, number, headSha, input, diff) =>
+      postGitlabReview(client, repo, number, headSha, input, webBase, diff),
     probeCapabilities: probeGitlabCapabilities,
     canvasCommentLimit: 1_000_000,
     shareCanvas: (client, repo, number, body) => shareGitlabCanvas(client, repo, number, body, webBase),

package/src/project-config.ts

@@ -41,6 +41,10 @@ export const PromptOverridesSchema = z
     'generation-format.md': z.string().min(1).optional(),
     'generation-strict.md': z.string().min(1).optional(),
     'generation-surfacing.md': z.string().min(1).optional(),
+    'generation-strict-incremental.md': z.string().min(1).optional(),
+    'generation-surfacing-incremental.md': z.string().min(1).optional(),
+    'judging-strict.md': z.string().min(1).optional(),
+    'judging-surfacing.md': z.string().min(1).optional(),
     'quality-standards.md': z.string().min(1).optional(),
     'layering-guidance.md': z.string().min(1).optional(),
     'chat-seed.md': z.string().min(1).optional(),
@@ -71,6 +75,12 @@ export const ProjectConfigSchema = z.object({
      * from, as after merging the base branch in. False marks the canvas outdated on any commit.
      */
     keepForIdenticalDiff: z.boolean(),
+    /**
+     * Regenerating a canvas for a new head starts from the newest canvas of a commit the head was
+     * built on, carrying what the head's diff leaves untouched. False generates every canvas from
+     * a blank page, as `--force` always does.
+     */
+    incremental: z.boolean(),
   }),
 })
 export type ProjectConfig = z.infer<typeof ProjectConfigSchema>
@@ -93,7 +103,9 @@ const PartialProjectConfigSchema = z.object({
     .optional(),
   tests: z.object({ patterns: z.array(z.string().min(1)).optional() }).optional(),
   chat: z.object({ enabled: z.boolean().optional() }).optional(),
-  canvas: z.object({ keepForIdenticalDiff: z.boolean().optional() }).optional(),
+  canvas: z
+    .object({ keepForIdenticalDiff: z.boolean().optional(), incremental: z.boolean().optional() })
+    .optional(),
 })
 
 export const DEFAULT_PROJECT_CONFIG: ProjectConfig = {
@@ -103,7 +115,7 @@ export const DEFAULT_PROJECT_CONFIG: ProjectConfig = {
   generation: { mode: 'strict', maxRepairRounds: 3, inlineDiffMaxLines: 1500, smallPrHunks: 10 },
   tests: { patterns: [...DEFAULT_TEST_PATTERNS] },
   chat: { enabled: true },
-  canvas: { keepForIdenticalDiff: true },
+  canvas: { keepForIdenticalDiff: true, incremental: true },
 }
 
 export interface LoadedProjectConfig {
@@ -147,6 +159,7 @@ export function mergeProjectConfig(raw: unknown): { config: ProjectConfig; warni
     canvas: {
       keepForIdenticalDiff:
         user.canvas?.keepForIdenticalDiff ?? DEFAULT_PROJECT_CONFIG.canvas.keepForIdenticalDiff,
+      incremental: user.canvas?.incremental ?? DEFAULT_PROJECT_CONFIG.canvas.incremental,
     },
   }
   if (user.rulebook !== undefined) {