@vintasoftware/pr-review-canvas 0.3.0 → 0.4.0

package/src/server/html.ts

@@ -1,7 +1,9 @@
 import { html, raw } from 'hono/html'
 import type { HtmlEscapedString } from 'hono/utils/html'
 import type { ErrorEnvelope, HomeData } from '../contract/api.js'
+import { keyLabel, keyToString, type LocalKey, type ReviewKey } from '../contract/review-key.js'
 import type { Appearance } from '../contract/settings.js'
+import { type Host, publicHost } from '../host/host.js'
 
 type Html = HtmlEscapedString | Promise<HtmlEscapedString>
 
@@ -68,29 +70,42 @@ ${opts.app ? html`<script type="module" src="/static/js/app.js"></script>` : ''}
 }
 
 export function reviewPage(
-  bootstrap: { prNumber: number; owner: string; repo: string; version: string },
+  page: { prNumber: ReviewKey; owner: string; repo: string; version: string; host: Host },
   nonce: string,
   appearance: Appearance
 ): Html {
+  const bootstrap = { ...page, host: publicHost(page.host) }
+  const key = keyToString(bootstrap.prNumber)
+  const what =
+    typeof bootstrap.prNumber === 'number' ? `${page.host.nounShort} #${key}` : keyLabel(bootstrap.prNumber)
   return pageShell({
-    title: `PR #${bootstrap.prNumber} · ${bootstrap.owner}/${bootstrap.repo} · review canvas`,
+    title: `${what} · ${bootstrap.owner}/${bootstrap.repo} · review canvas`,
     bootstrap,
     nonce,
     appearance,
     app: true,
     body: html`<a class="skip" href="#main">Skip to content</a>
-<pr-app class="page" data-pr="${String(bootstrap.prNumber)}"><div class="loading">Loading PR #${String(bootstrap.prNumber)}…</div></pr-app>`,
+<pr-app class="page" data-pr="${key}"><div class="loading">Loading ${what}…</div></pr-app>`,
   })
 }
 
 export function homePage(
-  data: HomeData & { owner: string; repo: string; version: string; port: number },
+  data: HomeData & {
+    owner: string
+    repo: string
+    version: string
+    port: number
+    host: Host
+    /** The local reviews prepared here, so the home page can link straight to them. */
+    localReviews: readonly LocalKey[]
+  },
   nonce: string,
   appearance: Appearance
 ): Html {
+  const { noun, nounShort, label } = data.host
   return pageShell({
     title: 'PR review canvas',
-    bootstrap: { owner: data.owner, repo: data.repo, version: data.version },
+    bootstrap: { owner: data.owner, repo: data.repo, version: data.version, host: publicHost(data.host) },
     nonce,
     appearance,
     app: false,
@@ -100,18 +115,27 @@ export function homePage(
 <div class="hdr-actions"><a class="cmd" href="/api/health">health</a></div></div>
 <div class="stripe" aria-hidden="true"></div>
 <div class="hdr-title"><div class="title"><h1>${data.owner}/${data.repo}</h1></div>
-<p class="meta"><span>Open a pull request by number. Diffs come from your local clone; the canvas from a published review.</span></p></div>
+<p class="meta"><span>Open a ${noun} by number. Diffs come from your local clone; the canvas from a published review.</span></p></div>
 </header>
 <main id="main" class="home">
-<section class="panel"><div class="panel-h"><h2>Open a pull request</h2></div>
+<section class="panel"><div class="panel-h"><h2>Open a ${noun}</h2></div>
 <form class="body home-form" method="get" action="/review">
-<label>PR number <input name="n" type="number" min="1" required inputmode="numeric"></label>
+<label>${nounShort} number <input name="n" type="number" min="1" required inputmode="numeric"></label>
 <button class="cmd fill" type="submit">open</button>
 </form></section>
+<section class="panel"><div class="panel-h"><h2>Before the ${noun}</h2></div>
+<div class="body">${
+      data.localReviews.length === 0
+        ? html`<p class="muted">Nothing reviewed here yet. Run <code>/pr-review-canvas branch</code> to read the current branch against the default one, or <code>/pr-review-canvas uncommitted</code> to read it with your working-tree edits on top, before opening a ${noun}.</p>`
+        : html`<ul class="plain">${data.localReviews.map(
+            key =>
+              html`<li><a href="/review/${key}">${keyLabel(key)}</a> <span class="muted">/review/${key}</span></li>`
+          )}</ul>`
+    }</div></section>
 <section class="panel"><div class="panel-h"><h2>Recent</h2></div>
 ${
   data.recentPrs.length === 0
-    ? html`<div class="body muted">No pull requests opened yet.</div>`
+    ? html`<div class="body muted">No ${noun}s opened yet.</div>`
     : html`<ul class="plain body">${data.recentPrs.map(
         p =>
           html`<li><a href="/review/${String(p.number)}"><span class="mono num">#${String(p.number)}</span> ${p.title}</a></li>`
@@ -119,7 +143,7 @@ ${
 }
 </section>
 </main>
-<footer><span>pr-review ${data.version}</span><span>localhost only · nothing leaves this machine except GitHub posts you confirm</span></footer>
+<footer><span>pr-review ${data.version}</span><span>localhost only · nothing leaves this machine except ${label} posts you confirm</span></footer>
 </div>`,
   })
 }

package/src/server/routes/api.ts

@@ -9,22 +9,45 @@ import type {
   PatchesResponse,
   SharedCanvasFetchResponse,
 } from '../../contract/api.js'
+import { isLocalKey, parseReviewKey, type ReviewKey } from '../../contract/review-key.js'
 import { AppearanceInputSchema, type AppearanceResponse } from '../../contract/settings.js'
-import { createPrLoader, resolveBundle, runDiscovery } from '../bundle.js'
+import { publicHost } from '../../host/host.js'
+import { lookupCanvas } from '../../review/carry-over.js'
+import { createPrLoader, resolveBundle, resolveLocalBundle, runDiscovery } from '../bundle.js'
 import { BodyTooLargeError, readCappedBody } from '../capped-body.js'
 import type { AppContext } from '../context.js'
 import { AppError } from '../errors.js'
 import { chatRoutes } from './chat-routes.js'
 import { reviewRoutes } from './review-routes.js'
 
-export const PrNumberSchema = z.coerce.number().int().positive()
+/** The target a route's `:n` names: a pull request number, or `local` for work with no PR yet. */
+export function parseTargetKey(raw: string): ReviewKey {
+  const key = parseReviewKey(raw)
+  if (key === null) {
+    throw new AppError(
+      'BAD_REQUEST',
+      `not a review target: ${raw}`,
+      400,
+      'use a PR number, `branch`, or `uncommitted`'
+    )
+  }
+  return key
+}
 
-export function parsePrNumber(raw: string): number {
-  const parsed = PrNumberSchema.safeParse(raw)
-  if (!parsed.success) {
-    throw new AppError('BAD_REQUEST', `not a pull request number: ${raw}`, 400)
+/**
+ * The pull request behind a key, for the routes that talk to the forge. Local work has none, and
+ * saying so is better than letting the call fail somewhere inside the host client.
+ */
+export function requirePrNumber(key: ReviewKey, what: string): number {
+  if (isLocalKey(key)) {
+    throw new AppError(
+      'BAD_REQUEST',
+      `${what} needs a pull request, and this canvas describes work that has none yet`,
+      400,
+      'open the pull request, then review it at /review/<number>'
+    )
   }
-  return parsed.data
+  return key
 }
 
 const ContextQuerySchema = z.object({
@@ -74,12 +97,14 @@ function parseHeadShaQuery(raw: string | undefined): string | undefined {
 async function currentCanvasSha(
   ctx: AppContext,
   loader: ReturnType<typeof createPrLoader>,
-  number: number
+  key: ReviewKey
 ): Promise<string> {
-  const pr = await loader.currentPr(number)
-  const found = await ctx.canvases.findForPr(number, pr.headSha)
+  const pr = await loader.currentTarget(key)
+  const found = isLocalKey(key)
+    ? await ctx.canvases.findForLocal(key, pr.headSha)
+    : await lookupCanvas(ctx, key, pr)
   if (found.status === 'missing') {
-    throw new AppError('CANVAS_NOT_FOUND', `no canvas for pull request ${number}`, 404, 'generate one first')
+    throw new AppError('CANVAS_NOT_FOUND', `no canvas for ${String(key)}`, 404, 'generate one first')
   }
   return found.headSha
 }
@@ -156,6 +181,7 @@ export function apiRoutes(ctx: AppContext): Hono {
           : {}),
       },
       repo: ctx.config.repo,
+      host: publicHost(ctx.config.host),
       dataDir: ctx.config.dataDir,
       chat: {
         enabled: chatEnabled,
@@ -167,15 +193,24 @@ export function apiRoutes(ctx: AppContext): Hono {
   })
 
   api.get('/prs/:n', async c => {
-    const number = parsePrNumber(c.req.param('n'))
-    const bundle = await resolveBundle(ctx, loader, number, { refresh: c.req.query('refresh') === '1' })
+    const key = parseTargetKey(c.req.param('n'))
+    const opts = { refresh: c.req.query('refresh') === '1', poll: c.req.query('poll') === '1' }
+    const bundle = isLocalKey(key)
+      ? await resolveLocalBundle(ctx, loader, key, opts)
+      : await resolveBundle(ctx, loader, key, opts)
     return c.json(bundle)
   })
 
   api.get('/prs/:n/patches', async c => {
-    const number = parsePrNumber(c.req.param('n'))
-    const headSha = parseHeadShaQuery(c.req.query('headSha')) ?? (await loader.currentPr(number)).headSha
-    const derived = await ctx.derived.read(headSha)
+    const key = parseTargetKey(c.req.param('n'))
+    const pr = await loader.currentTarget(key)
+    const headSha = parseHeadShaQuery(c.req.query('headSha')) ?? pr.headSha
+    // Only the target's own head has a merge base to build from; any other sha the page names is
+    // an older canvas, whose diffs were written when that canvas was drawn.
+    const derived = await ctx.derived.readOrBuild(
+      headSha,
+      headSha === pr.headSha ? pr.mergeBaseSha : undefined
+    )
     if (derived === null) {
       throw new AppError(
         'NOT_FOUND',
@@ -189,13 +224,13 @@ export function apiRoutes(ctx: AppContext): Hono {
   })
 
   api.get('/prs/:n/comments', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const number = requirePrNumber(parseTargetKey(c.req.param('n')), 'reading comments')
     const { comments } = await loader.refreshComments(number)
     return c.json(comments)
   })
 
   api.get('/prs/:n/context', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const key = parseTargetKey(c.req.param('n'))
     const parsed = ContextQuerySchema.safeParse(c.req.query())
     if (!parsed.success) {
       throw new AppError('BAD_REQUEST', 'context needs path, side (new|old), from, to', 400)
@@ -204,7 +239,7 @@ export function apiRoutes(ctx: AppContext): Hono {
     if (q.to < q.from || q.to - q.from + 1 > CONTEXT_MAX_LINES) {
       throw new AppError('BAD_REQUEST', `request between 1 and ${CONTEXT_MAX_LINES} lines`, 400)
     }
-    const pr = await loader.currentPr(number)
+    const pr = await loader.currentTarget(key)
     const lines = await ctx.derived.readLines(
       pr.headSha,
       q.side === 'new' ? 'head' : 'base',
@@ -226,10 +261,12 @@ export function apiRoutes(ctx: AppContext): Hono {
   })
 
   api.get('/prs/:n/export', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const key = parseTargetKey(c.req.param('n'))
     const requested = parseHeadShaQuery(c.req.query('headSha'))
-    const headSha = requested ?? (await currentCanvasSha(ctx, loader, number))
-    const zip = await buildCanvasZipFor(ctx, headSha, number)
+    const headSha = requested ?? (await currentCanvasSha(ctx, loader, key))
+    // A local canvas is exported without a number, which is what makes it importable on the
+    // pull request once that exists.
+    const zip = await buildCanvasZipFor(ctx, headSha, isLocalKey(key) ? undefined : key)
     // The name is built from the repo slug, the PR number, and the sha, so it holds no user text.
     return new Response(new Blob([zip.bytes]), {
       headers: {
@@ -240,7 +277,7 @@ export function apiRoutes(ctx: AppContext): Hono {
   })
 
   api.post('/prs/:n/import', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const number = requirePrNumber(parseTargetKey(c.req.param('n')), 'importing a shared canvas')
     const { file, force } = await readUpload(c.req.raw)
     if (!(file instanceof File)) {
       throw new AppError('BAD_REQUEST', 'send the zip as the multipart field `file`', 400)
@@ -255,18 +292,18 @@ export function apiRoutes(ctx: AppContext): Hono {
     const result = await importCanvas(ctx, {
       bytes: new Uint8Array(await file.arrayBuffer()),
       prNumber: number,
-      currentHeadSha: (await loader.currentPr(number)).headSha,
+      currentHead: await loader.currentPr(number),
       force: force === '1',
     })
     return c.json(result)
   })
 
   api.post('/prs/:n/shared-canvas/fetch', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const number = requirePrNumber(parseTargetKey(c.req.param('n')), 'looking for a shared canvas')
     // Looking again means looking at the pull request as it is now, not at the cached copy.
     const { pr, comments } = await loader.load(number, { refresh: true })
     const discovery = await runDiscovery(ctx, pr, comments, { refresh: true })
-    const found = await ctx.canvases.findForPr(number, pr.headSha)
+    const found = await lookupCanvas(ctx, number, pr)
     const body: SharedCanvasFetchResponse = {
       imported: discovery.imported,
       status: found.status,

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

@@ -10,11 +10,14 @@ import { ChatSendSchema } from '../../contract/chat.js'
 import type { Pr, ReviewArtifact } from '../../contract/review-artifact.js'
 import type { SettingsResponse } from '../../contract/settings.js'
 import { isChatAgent, SettingsInputSchema } from '../../contract/settings.js'
+import { lookupCanvas } from '../../review/carry-over.js'
+import type { Derived } from '../../store/derived-store.js'
 import type { PrLoader } from '../bundle.js'
 import type { AppContext } from '../context.js'
 import { AppError, logRequestError } from '../errors.js'
 import { SSE_HEADERS, sseStream } from '../sse.js'
-import { parsePrNumber } from './api.js'
+import { isLocalKey, type ReviewKey } from '../../contract/review-key.js'
+import { parseTargetKey } from './api.js'
 
 async function readJsonBody<T>(
   request: Request,
@@ -53,28 +56,72 @@ function settingsResponse(ctx: AppContext, settings: SettingsResponse['settings'
       maxRepairRounds: project.generation.maxRepairRounds,
       inlineDiffMaxLines: project.generation.inlineDiffMaxLines,
       smallPrHunks: project.generation.smallPrHunks,
+      keepForIdenticalDiff: project.canvas.keepForIdenticalDiff,
       layers: project.layers.length,
       highRisk: project.highRisk.length,
     },
   }
 }
 
-/** The canvas the chat talks about: the one written for the pull request's current head. */
-async function artifactForChat(ctx: AppContext, number: number, pr: Pr): Promise<ReviewArtifact> {
+/** What the chat talks about: the canvas on screen, and the diff that canvas is shown with. */
+interface ChatSubject {
+  artifact: ReviewArtifact
+  /** The head for a current canvas; the canvas's own commit for an outdated one, as the page shows it. */
+  headSha: string
+  files: Derived['files']
+  patches: Derived['patches']
+}
+
+/**
+ * The canvas the chat talks about. A current canvas is read with the head's diff. An outdated one
+ * is still a canvas: the page shows it with the diff of its own commit, so the chat quotes that.
+ */
+async function subjectForChat(ctx: AppContext, key: ReviewKey, pr: Pr): Promise<ChatSubject> {
   if (ctx.fixtureArtifact !== null) {
-    return { ...ctx.fixtureArtifact, pr }
+    return withDiff({ ...ctx.fixtureArtifact, pr }, pr.headSha, await ctx.derived.read(pr.headSha))
   }
-  const found = await ctx.canvases.findForPr(number, pr.headSha)
-  const artifact = found.status === 'ready' ? await ctx.canvases.readArtifact(found.headSha) : null
-  if (artifact === null) {
+  const found = isLocalKey(key)
+    ? await ctx.canvases.findForLocal(key, pr.headSha)
+    : await lookupCanvas(ctx, key, pr)
+  const artifact = found.status === 'missing' ? null : await ctx.canvases.readArtifact(found.headSha)
+  if (found.status === 'missing' || artifact === null) {
     throw new AppError(
       'CANVAS_NOT_FOUND',
-      'there is no canvas for this commit, so the chat has nothing to talk about',
+      'there is no canvas for this pull request, so the chat has nothing to talk about',
       404,
       'generate a canvas for the current head first'
     )
   }
-  return artifact
+  if (found.status === 'stale') {
+    // The diff is the canvas's own commit's, so the stored artifact, which names that commit,
+    // is already the one that describes it.
+    const manifest = await ctx.canvases.readManifest(found.headSha)
+    return withDiff(
+      artifact,
+      found.headSha,
+      await ctx.derived.readOrBuild(found.headSha, manifest?.mergeBaseSha)
+    )
+  }
+  // A carried-over canvas was generated for an earlier commit but is read with the head's diff,
+  // so the live pull request is stamped on it: the seed's header names the commit whose diff the
+  // agent is given, with that commit's file and line counts.
+  return withDiff({ ...artifact, pr }, pr.headSha, await ctx.derived.read(pr.headSha))
+}
+
+/**
+ * The subject with its diff, or the 404 that says the diff is not on this machine. The artifact
+ * passed in names `headSha` as its own commit, so the seed header and the diff agree.
+ */
+function withDiff(artifact: ReviewArtifact, headSha: string, derived: Derived | null): ChatSubject {
+  if (derived === null) {
+    throw new AppError(
+      'NOT_FOUND',
+      'the diff of this head is not available locally, so the chat cannot quote it',
+      404,
+      'fetch the PR head and reload'
+    )
+  }
+  return { artifact, headSha, files: derived.files, patches: derived.patches }
 }
 
 /** Every path this file serves, so the chat-disabled check covers all of them and nothing else. */
@@ -122,56 +169,47 @@ export function chatRoutes(ctx: AppContext, loader: PrLoader): Hono {
     return c.json(await ctx.agents.probe(id, { refresh: c.req.query('refresh') === '1' }))
   })
 
-  api.get('/prs/:n/chat/threads', async c => c.json(await ctx.chat.threads(parsePrNumber(c.req.param('n')))))
+  api.get('/prs/:n/chat/threads', async c => c.json(await ctx.chat.threads(parseTargetKey(c.req.param('n')))))
 
   api.post('/prs/:n/chat/threads', async c => {
-    const number = parsePrNumber(c.req.param('n'))
-    const thread = await ctx.chat.createThread(number)
-    return c.json({ thread, ...(await ctx.chat.threads(number)) }, 201)
+    const key = parseTargetKey(c.req.param('n'))
+    const thread = await ctx.chat.createThread(key)
+    return c.json({ thread, ...(await ctx.chat.threads(key)) }, 201)
   })
 
   api.get('/prs/:n/chat/threads/:name/history', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const key = parseTargetKey(c.req.param('n'))
     const name = c.req.param('name')
-    if (!isThreadNameFor(name, number)) {
-      throw new AppError('NOT_FOUND', `no chat thread named ${name} on this pull request`, 404)
+    if (!isThreadNameFor(name, key)) {
+      throw new AppError('NOT_FOUND', `no chat thread named ${name} on this review`, 404)
     }
-    const body: ChatHistoryResponse = { name, turns: await ctx.transcripts.read(number, name) }
+    const body: ChatHistoryResponse = { name, turns: await ctx.transcripts.read(key, name) }
     return c.json(body)
   })
 
   api.post('/prs/:n/chat/cancel', async c => {
-    const number = parsePrNumber(c.req.param('n'))
-    return c.json({ cancelled: await ctx.chat.cancel(number) })
+    const key = parseTargetKey(c.req.param('n'))
+    return c.json({ cancelled: await ctx.chat.cancel(key) })
   })
 
   api.post('/prs/:n/chat', async c => {
-    const number = parsePrNumber(c.req.param('n'))
+    const key = parseTargetKey(c.req.param('n'))
     const input = await readJsonBody(
       c.req.raw,
       ChatSendSchema,
       '{ "message": "…", "context": { "kind": "pr" } }'
     )
-    const pr = await loader.currentPr(number)
-    const artifact = await artifactForChat(ctx, number, pr)
-    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 chat cannot quote it',
-        404,
-        'fetch the PR head and reload'
-      )
-    }
+    const pr = await loader.currentTarget(key)
+    const { artifact, headSha, files, patches } = await subjectForChat(ctx, key, pr)
     const events = ctx.chat.send(
       {
-        prNumber: number,
-        headSha: pr.headSha,
+        key,
+        headSha,
         artifact,
-        files: derived.files,
-        patches: derived.patches,
-        derivedDir: ctx.derived.derivedDir(pr.headSha),
-        readLines: (side, filePath, from, to) => ctx.derived.readLines(pr.headSha, side, filePath, from, to),
+        files,
+        patches,
+        derivedDir: ctx.derived.derivedDir(headSha),
+        readLines: (side, filePath, from, to) => ctx.derived.readLines(headSha, side, filePath, from, to),
       },
       { message: input.message, context: input.context, thread: input.thread }
     )
@@ -190,7 +228,7 @@ export function chatRoutes(ctx: AppContext, loader: PrLoader): Hono {
         replayFrom(first, iterator),
         undefined,
         () => {
-          void ctx.chat.cancel(number)
+          void ctx.chat.cancel(key)
         },
         err => logRequestError(ctx.log, c.req, err)
       ),

package/src/server/routes/pages.ts

@@ -3,8 +3,8 @@ import { type Appearance, type AppearanceQuery, appearanceForRequest } from '../
 import type { AppContext } from '../context.js'
 import type { AppEnv } from '../env.js'
 import { AppError } from '../errors.js'
+import { LOCAL_KEYS, parseReviewKey } from '../../contract/review-key.js'
 import { homePage, reviewPage } from '../html.js'
-import { parsePrNumber } from './api.js'
 
 /** How the page is painted, rendered onto the tag so nothing flashes before the app module runs. */
 export async function appearanceFor(ctx: AppContext, query: AppearanceQuery): Promise<Appearance> {
@@ -22,15 +22,20 @@ export function pageRoutes(ctx: AppContext): Hono<AppEnv> {
   const app = new Hono<AppEnv>()
 
   app.get('/', async c => {
-    const recentPrs = await ctx.prs.listRecent(10)
+    const [recentPrs, ...localPrs] = await Promise.all([
+      ctx.prs.listRecent(10),
+      ...LOCAL_KEYS.map(key => ctx.prs.readPr(key)),
+    ])
     return c.html(
       homePage(
         {
           recentPrs,
+          localReviews: LOCAL_KEYS.filter((_, i) => localPrs[i] !== null && localPrs[i] !== undefined),
           owner: ctx.config.repo.owner,
           repo: ctx.config.repo.name,
           version: ctx.version,
           port: ctx.config.port,
+          host: ctx.config.host,
         },
         c.get('cspNonce'),
         await appearanceFor(ctx, appearanceQuery(c))
@@ -47,15 +52,24 @@ export function pageRoutes(ctx: AppContext): Hono<AppEnv> {
 
   app.get('/review/:n', async c => {
     const raw = c.req.param('n')
-    let prNumber: number
-    try {
-      prNumber = parsePrNumber(raw)
-    } catch {
-      throw new AppError('BAD_REQUEST', `"${raw}" is not a pull request number`, 400, 'use /review/<number>')
+    const prNumber = parseReviewKey(raw)
+    if (prNumber === null) {
+      throw new AppError(
+        'BAD_REQUEST',
+        `"${raw}" is not a review target`,
+        400,
+        'use /review/<number>, /review/branch, or /review/uncommitted'
+      )
     }
     return c.html(
       reviewPage(
-        { prNumber, owner: ctx.config.repo.owner, repo: ctx.config.repo.name, version: ctx.version },
+        {
+          prNumber,
+          owner: ctx.config.repo.owner,
+          repo: ctx.config.repo.name,
+          version: ctx.version,
+          host: ctx.config.host,
+        },
         c.get('cspNonce'),
         await appearanceFor(ctx, appearanceQuery(c))
       )