@vintasoftware/pr-review-canvas 0.4.0 → 0.5.0

package/src/server/routes/review-routes.ts

@@ -3,11 +3,13 @@ import { Hono } from 'hono'
 import { z } from 'zod'
 import type { ReviewBodyResponse, StateResponse } from '../../contract/api.js'
 import { PostCommentInputSchema, type PostCommentResult } from '../../contract/comments.js'
+import { AddPendingInputSchema, EditPendingInputSchema, type PendingComment } from '../../contract/pending.js'
 import type { Pr, ReviewArtifact } from '../../contract/review-artifact.js'
 import type { PrState } from '../../contract/state.js'
 import { checkInlineTarget } from '../../git/patch-lines.js'
 import { PostReviewInputSchema } from '../../contract/reviews.js'
-import { lookupCanvas } from '../../review/carry-over.js'
+import { lookupCanvas, samePatches } from '../../review/carry-over.js'
+import { marksForCanvas } from '../../review/carry-marks.js'
 import { buildReviewBody, stateForCanvas, unreviewedLayers } from '../../review/review-body.js'
 import { isLocalKey, keyLabel, type ReviewKey } from '../../contract/review-key.js'
 import { canvasBelongsTo } from '../../store/canvas-store.js'
@@ -107,7 +109,93 @@ async function canvasForSignOff(
   if (artifact === null) {
     throw new AppError('CANVAS_NOT_FOUND', `no canvas for pull request ${number}`, 404, 'generate one first')
   }
-  return { artifact, state: stateForCanvas(stored, found.headSha) }
+  return { artifact, state: (await marksForCanvas(ctx, artifact, found.headSha, stored)).state }
+}
+
+/**
+ * The marks the state should start from when the next write keys it to `canvasSha`: none when the
+ * marks already describe that canvas, otherwise the ones that may follow it from its basis. The
+ * same rule the bundle showed the reviewer, recomputed here rather than taken from the page.
+ */
+async function adoptedMarks(
+  ctx: AppContext,
+  key: ReviewKey,
+  canvasSha: string
+): Promise<Record<string, true> | undefined> {
+  const stored = await ctx.state.read(key)
+  if (stored.reviewedCanvasSha === canvasSha) {
+    return undefined
+  }
+  const artifact = await ctx.canvases.readArtifact(canvasSha)
+  if (artifact === null) {
+    return undefined
+  }
+  return (await marksForCanvas(ctx, artifact, canvasSha, stored)).state.reviewed
+}
+
+/**
+ * The diff of this head as it is stored locally, which every inline target is checked against.
+ * Without it the line a comment names cannot be checked, so the comment is refused rather than
+ * sent to a coordinate nobody verified.
+ */
+async function requireDerived(ctx: AppContext, headSha: string): Promise<Derived> {
+  const derived = await ctx.derived.read(headSha)
+  if (derived === null) {
+    throw new AppError(
+      'NOT_FOUND',
+      'the diff of this head is not available locally, so the line cannot be checked',
+      404,
+      'fetch the PR head and reload'
+    )
+  }
+  return derived
+}
+
+/** Refuses a line the diff on screen does not show. */
+function requireInlineTarget(diff: Derived, target: Parameters<typeof checkInlineTarget>[1]): void {
+  const problem = checkInlineTarget(diff.files, target)
+  if (problem !== null) {
+    throw new AppError('COMMENT_LINE_NOT_IN_DIFF', problem, 422, 'comment on a line the diff shows')
+  }
+}
+
+/**
+ * The `posted` entries for drafts that came from attention points, found in the comment list the
+ * forge created in this submission. Match the full range and body inside that receipt,
+ * never against historical comments. A failed comment read is reported by the host adapter.
+ */
+export function postedFromPending(
+  pending: ReadonlyArray<PendingComment>,
+  comments: ReadonlyArray<{
+    id: number
+    path: string
+    line: number | null
+    startLine?: number | undefined
+    side: string
+    body: string
+  }>
+): Array<{ commentId: number; pointFingerprint: string }> {
+  const entries: Array<{ commentId: number; pointFingerprint: string }> = []
+  const used = new Set<number>()
+  for (const draft of pending) {
+    if (draft.pointFingerprint === undefined) {
+      continue
+    }
+    const match = comments.find(
+      c =>
+        !used.has(c.id) &&
+        c.path === draft.path &&
+        c.line === draft.line &&
+        (c.startLine ?? c.line) === (draft.startLine ?? draft.line) &&
+        c.side === draft.side &&
+        c.body === draft.body
+    )
+    if (match !== undefined) {
+      used.add(match.id)
+      entries.push({ commentId: match.id, pointFingerprint: draft.pointFingerprint })
+    }
+  }
+  return entries
 }
 
 export function reviewRoutes(ctx: AppContext, loader: PrLoader): Hono {
@@ -160,7 +248,10 @@ export function reviewRoutes(ctx: AppContext, loader: PrLoader): Hono {
     if (canvasSha !== pr.headSha) {
       await requireCanvasOf(ctx, key, canvasSha)
     }
-    return c.json(stateBody(key, await ctx.state.setReviewed(key, id, body.reviewed, canvasSha)))
+    // The first mark on a canvas adopts the marks that followed it from the canvas it descends
+    // from, so the page's carried ticks survive the write instead of being replaced.
+    const carried = await adoptedMarks(ctx, key, canvasSha)
+    return c.json(stateBody(key, await ctx.state.setReviewed(key, id, body.reviewed, { canvasSha, carried })))
   })
 
   api.put('/prs/:n/points/:fingerprint/dismissed', async c => {
@@ -197,23 +288,11 @@ export function reviewRoutes(ctx: AppContext, loader: PrLoader): Hono {
     requireSameHead(input.headSha, pr.headSha)
     let diff: Derived = { files: [], patches: {} }
     if (input.kind === 'inline') {
-      const derived = await ctx.derived.read(pr.headSha)
-      if (derived === null) {
-        throw new AppError(
-          'NOT_FOUND',
-          'the diff of this head is not available locally, so the line cannot be checked',
-          404,
-          'fetch the PR head and reload'
-        )
-      }
-      const problem = checkInlineTarget(derived.files, input)
-      if (problem !== null) {
-        throw new AppError('COMMENT_LINE_NOT_IN_DIFF', problem, 422, 'comment on a line the diff shows')
-      }
-      diff = derived
+      diff = await requireDerived(ctx, pr.headSha)
+      requireInlineTarget(diff, input)
     }
     const posted = await ctx.config.host.postComment(ctx.gh, ctx.config.repo, number, pr.headSha, input, diff)
-    await appendComment(ctx, number, posted)
+    await appendComments(ctx, number, [posted])
     const entry =
       input.kind === 'inline' && input.pointFingerprint !== undefined
         ? { commentId: posted.comment.id, pointFingerprint: input.pointFingerprint }
@@ -222,6 +301,42 @@ export function reviewRoutes(ctx: AppContext, loader: PrLoader): Hono {
     return c.json({ ...posted, state }, 201)
   })
 
+  // The pending review: comments the reviewer wrote and has not submitted. They are kept here,
+  // never on the forge, until a review carries them out in one go.
+  api.post('/prs/:n/pending', async c => {
+    const number = requirePrNumber(parseTargetKey(c.req.param('n')), 'a pending review comment')
+    const input = await readBody(c.req.raw, AddPendingInputSchema, 'a comment on a line of the diff')
+    const pr = await loader.currentPr(number)
+    requireSameHead(input.headSha, pr.headSha)
+    // A draft is checked against the diff when it is written, so a line that cannot take a comment
+    // is refused while the reviewer is still looking at it, not when the review is submitted.
+    requireInlineTarget(await requireDerived(ctx, pr.headSha), input)
+    const state = await ctx.state.addPending(number, input, pr.headSha)
+    return c.json(stateBody(number, state), 201)
+  })
+
+  api.patch('/prs/:n/pending/:id', async c => {
+    const number = requirePrNumber(parseTargetKey(c.req.param('n')), 'a pending review comment')
+    const id = c.req.param('id')
+    const { body } = await readBody(c.req.raw, EditPendingInputSchema, '{ "body": "…" }')
+    const current = await ctx.state.read(number)
+    if (!current.pending.some(p => p.id === id)) {
+      throw new AppError('NOT_FOUND', `no pending comment ${id}`, 404, 'reload the page')
+    }
+    return c.json(stateBody(number, await ctx.state.editPending(number, id, body)))
+  })
+
+  api.delete('/prs/:n/pending/:id', async c => {
+    const number = requirePrNumber(parseTargetKey(c.req.param('n')), 'a pending review comment')
+    return c.json(stateBody(number, await ctx.state.removePending(number, c.req.param('id'))))
+  })
+
+  /** Discards the whole pending review. Nothing was on the forge, so nothing is withdrawn. */
+  api.delete('/prs/:n/pending', async c => {
+    const number = requirePrNumber(parseTargetKey(c.req.param('n')), 'a pending review')
+    return c.json(stateBody(number, await ctx.state.clearPending(number)))
+  })
+
   api.get('/prs/:n/review/body', async c => {
     const number = requirePrNumber(parseTargetKey(c.req.param('n')), 'the sign-off summary')
     const pr = await loader.currentPr(number)
@@ -231,6 +346,7 @@ export function reviewRoutes(ctx: AppContext, loader: PrLoader): Hono {
       headSha: pr.headSha,
       body: buildReviewBody({ artifact, state, comments, headSha: pr.headSha }),
       unreviewed: unreviewedLayers(artifact, state).map(l => l.title),
+      pending: state.pending.length,
     }
     return c.json(body)
   })
@@ -255,11 +371,54 @@ export function reviewRoutes(ctx: AppContext, loader: PrLoader): Hono {
     }
     const comments = (await ctx.prs.readComments(number)) ?? (await loader.refreshComments(number)).comments
     const body = input.body ?? buildReviewBody({ artifact, state, comments, headSha: pr.headSha })
-    const review = await ctx.config.host.postReview(ctx.gh, ctx.config.repo, number, pr.headSha, {
-      event: input.event,
-      body,
-    })
-    return c.json({ review }, 201)
+    // The drafts read here are the ones that go out. A draft written after this read stays in the
+    // pending review instead of being dropped by the clear below.
+    const pending = input.includePending ? (await ctx.state.read(number)).pending : []
+    // GitLab needs the diff to position its draft notes.
+    const diff = pending.length === 0 ? { files: [], patches: {} } : await requireDerived(ctx, pr.headSha)
+    for (const head of new Set(pending.map(p => p.headSha))) {
+      if (head === pr.headSha) continue
+      const original = await ctx.derived.read(head)
+      if (
+        !ctx.projectConfig.config.canvas.keepForIdenticalDiff ||
+        original === null ||
+        !samePatches(original, diff)
+      ) {
+        throw new AppError(
+          'CANVAS_STALE',
+          'pending comments were written on a different diff',
+          409,
+          'copy or delete the earlier-commit drafts in the pending review, then comment on the current code'
+        )
+      }
+    }
+    const {
+      comments: submittedComments,
+      warnings,
+      ...review
+    } = await ctx.config.host.postReview(
+      ctx.gh,
+      ctx.config.repo,
+      number,
+      pr.headSha,
+      { event: input.event, body, comments: pending },
+      diff
+    )
+    const next =
+      pending.length === 0
+        ? await ctx.state.read(number)
+        : await ctx.state.completePending(number, pending, postedFromPending(pending, submittedComments))
+    if (submittedComments.length > 0) {
+      await appendComments(
+        ctx,
+        number,
+        submittedComments.map(comment => ({ kind: 'review', comment }))
+      )
+    }
+    return c.json(
+      { review, submitted: pending.length, state: next, comments: submittedComments, warnings },
+      201
+    )
   })
 
   return api
@@ -268,8 +427,12 @@ export function reviewRoutes(ctx: AppContext, loader: PrLoader): Hono {
 /** One append at a time per PR, so two posts that land together do not overwrite each other. */
 const appendChains = new Map<number, Promise<unknown>>()
 
-function appendComment(ctx: AppContext, number: number, posted: PostCommentResult): Promise<void> {
-  const run = () => writeAppendedComment(ctx, number, posted)
+function appendComments(
+  ctx: AppContext,
+  number: number,
+  posted: ReadonlyArray<PostCommentResult>
+): Promise<void> {
+  const run = () => writeAppendedComments(ctx, number, posted)
   const chained = (appendChains.get(number) ?? Promise.resolve()).then(run, run)
   appendChains.set(
     number,
@@ -282,30 +445,27 @@ function appendComment(ctx: AppContext, number: number, posted: PostCommentResul
  * Keeps the cached comments in step with what was just posted, so a reload shows it once. With
  * nothing cached there is nothing to keep in step: the next read fetches the list from GitHub.
  */
-async function writeAppendedComment(
+async function writeAppendedComments(
   ctx: AppContext,
   number: number,
-  posted: PostCommentResult
+  posted: ReadonlyArray<PostCommentResult>
 ): Promise<void> {
   const comments = await ctx.prs.readComments(number)
   if (comments === null) {
     return
   }
-  if (posted.kind === 'review') {
-    if (comments.reviewComments.some(c => c.id === posted.comment.id)) {
-      return
-    }
-    await ctx.prs.writeComments(number, {
-      ...comments,
-      reviewComments: [...comments.reviewComments, posted.comment],
-    })
-    return
+  const reviewComments = [...comments.reviewComments]
+  const issueComments = [...comments.issueComments]
+  for (const entry of posted) {
+    const list = entry.kind === 'review' ? reviewComments : issueComments
+    if (list.some(c => c.id === entry.comment.id)) continue
+    if (entry.kind === 'review') reviewComments.push(entry.comment)
+    else issueComments.push(entry.comment)
   }
-  if (comments.issueComments.some(c => c.id === posted.comment.id)) {
-    return
+  if (
+    reviewComments.length !== comments.reviewComments.length ||
+    issueComments.length !== comments.issueComments.length
+  ) {
+    await ctx.prs.writeComments(number, { ...comments, reviewComments, issueComments })
   }
-  await ctx.prs.writeComments(number, {
-    ...comments,
-    issueComments: [...comments.issueComments, posted.comment],
-  })
 }

package/src/store/canvas-store.ts

@@ -148,6 +148,9 @@ export function createCanvasStore(repoRoot: string, git: Git): CanvasStore {
       if (artifact.importedAt !== undefined) {
         entry.importedAt = artifact.importedAt
       }
+      if (artifact.basisCanvasSha !== undefined) {
+        entry.basisCanvasSha = artifact.basisCanvasSha
+      }
       if (flags?.worktree === true) {
         entry.worktree = true
       }

package/src/store/settings-store.ts

@@ -11,11 +11,15 @@ export const SETTINGS_TEMPLATE = `# Personal pr-review settings. Gitignored: thi
 version: 1
 
 # The look of the page: terminal or github.
-skin: terminal
+skin: ${DEFAULT_SETTINGS.skin}
 
 # Light or dark: auto follows the operating system, light and dark pin one.
 theme: auto
 
+# How much code a review hides when it opens: light, moderate, or aggressive. The Hide code
+# control on the page changes it for that page only.
+foldLevel: light
+
 # Which agent answers in the AI Chat pane: claude or codex.
 agent: claude
 
@@ -121,6 +125,7 @@ export function applySettings(text: string, input: SettingsInput): { text: strin
   doc.set('version', 1)
   doc.set('skin', settings.skin)
   doc.set('theme', settings.theme)
+  doc.set('foldLevel', settings.foldLevel)
   doc.set('agent', settings.agent)
   doc.set('model', settings.model)
   doc.set('chatTimeoutSec', settings.chatTimeoutSec)
@@ -136,6 +141,9 @@ function stripUndefined(input: SettingsInput): Partial<Settings> {
   if (input.theme !== undefined) {
     out.theme = input.theme
   }
+  if (input.foldLevel !== undefined) {
+    out.foldLevel = input.foldLevel
+  }
   if (input.agent !== undefined) {
     out.agent = input.agent
   }

package/src/store/state-store.ts

@@ -1,6 +1,7 @@
 import path from 'node:path'
 import type { ReviewKey } from '../contract/review-key.js'
 import { emptyState, type PrState, PrStateSchema } from '../contract/state.js'
+import type { AddPendingInput, PendingComment } from '../contract/pending.js'
 import { readJsonOrDefault, writeJsonAtomic } from './atomic-json.js'
 import type { PrStore } from './pr-store.js'
 
@@ -22,12 +23,33 @@ export interface StateStore {
   /**
    * Marks one layer or file. `canvasSha` is the commit of the canvas the page was showing: when it
    * differs from the one the marks describe, the old marks are dropped, because they were about
-   * other code.
+   * other code, and `carried` takes their place — the marks the caller worked out may follow that
+   * canvas from the one it was generated from.
    */
-  setReviewed(key: ReviewKey, id: string, reviewed: boolean, canvasSha?: string): Promise<PrState>
+  setReviewed(key: ReviewKey, id: string, reviewed: boolean, opts?: SetReviewedOptions): Promise<PrState>
   setDismissed(key: ReviewKey, fingerprint: string, dismissed: boolean, reason?: string): Promise<PrState>
   setThreadHidden(key: ReviewKey, rootCommentId: number, hidden: boolean): Promise<PrState>
   addPosted(key: ReviewKey, entry: PostedEntry): Promise<PrState>
+  /** Adds one comment to the pending review and returns the state that holds it. */
+  addPending(key: ReviewKey, input: AddPendingInput, headSha: string): Promise<PrState>
+  /** Rewrites one draft's body. A draft that is no longer there leaves the state alone. */
+  editPending(key: ReviewKey, id: string, body: string): Promise<PrState>
+  removePending(key: ReviewKey, id: string): Promise<PrState>
+  /** Discards every draft at the reviewer's request. */
+  clearPending(key: ReviewKey): Promise<PrState>
+  /** Acknowledge submitted versions, preserving drafts added or edited while posting. */
+  completePending(
+    key: ReviewKey,
+    submitted: ReadonlyArray<PendingComment>,
+    posted: PostedEntry[]
+  ): Promise<PrState>
+}
+
+export interface SetReviewedOptions {
+  /** The commit of the canvas the page was showing. */
+  canvasSha?: string | undefined
+  /** Marks that follow `canvasSha` from the canvas it was generated from; used on the first write. */
+  carried?: Readonly<Record<string, true>> | undefined
 }
 
 /** `layer:<id>` or `layer:<id>/file:<key>`, with the ids and keys the artifact uses. */
@@ -43,7 +65,13 @@ function layerOf(id: string): string {
   return at === -1 ? id : id.slice(0, at)
 }
 
+/** Ids only have to be unique inside one state file; the clock and the counter make them so. */
+function pendingId(now: () => Date, seq: number): string {
+  return `p${now().getTime().toString(36)}-${seq.toString(36)}`
+}
+
 export function createStateStore(prs: PrStore, now: () => Date): StateStore {
+  let pendingSeq = 0
   const file = (key: ReviewKey): string => path.join(prs.prDir(key), 'state.json')
   const read = (key: ReviewKey): Promise<PrState> =>
     readJsonOrDefault(file(key), PrStateSchema, () => emptyState(now().toISOString()))
@@ -71,13 +99,14 @@ export function createStateStore(prs: PrStore, now: () => Date): StateStore {
   return {
     read,
     update,
-    setReviewed: (key, id, reviewed, canvasSha) =>
+    setReviewed: (key, id, reviewed, opts) =>
       update(key, state => {
+        const canvasSha = opts?.canvasSha
         const sameCanvas =
           canvasSha === undefined ||
           state.reviewedCanvasSha === undefined ||
           state.reviewedCanvasSha === canvasSha
-        const next = sameCanvas ? { ...state.reviewed } : {}
+        const next = sameCanvas ? { ...state.reviewed } : { ...opts?.carried }
         if (reviewed) {
           next[id] = true
         } else {
@@ -122,5 +151,41 @@ export function createStateStore(prs: PrStore, now: () => Date): StateStore {
         const posted = { ...entry, at: now().toISOString() }
         return { ...state, posted: [...state.posted, posted] }
       }),
+    addPending: (key, input, headSha) => {
+      pendingSeq += 1
+      const at = now().toISOString()
+      const draft: PendingComment = {
+        id: pendingId(now, pendingSeq),
+        path: input.path,
+        line: input.line,
+        side: input.side,
+        ...(input.startLine === undefined ? {} : { startLine: input.startLine }),
+        body: input.body,
+        ...(input.pointFingerprint === undefined ? {} : { pointFingerprint: input.pointFingerprint }),
+        headSha,
+        createdAt: at,
+        updatedAt: at,
+      }
+      return update(key, state => ({ ...state, pending: [...state.pending, draft] }))
+    },
+    editPending: (key, id, body) =>
+      update(key, state => ({
+        ...state,
+        pending: state.pending.map(p => (p.id === id ? { ...p, body, updatedAt: now().toISOString() } : p)),
+      })),
+    removePending: (key, id) =>
+      update(key, state => ({ ...state, pending: state.pending.filter(p => p.id !== id) })),
+    clearPending: key => update(key, state => ({ ...state, pending: [] })),
+    completePending: (key, submitted, posted) =>
+      update(key, state => ({
+        ...state,
+        pending: state.pending.filter(p => !submitted.some(s => s.id === p.id && s.body === p.body)),
+        posted: [
+          ...state.posted,
+          ...posted
+            .filter(p => !state.posted.some(s => s.commentId === p.commentId))
+            .map(p => ({ ...p, at: now().toISOString() })),
+        ],
+      })),
   }
 }