@vintasoftware/pr-review-canvas 0.1.0

package/static/js/dom.js

@@ -0,0 +1,145 @@
+// @ts-check
+// Small DOM helpers. Everything that builds HTML from data goes through esc().
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function esc(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}
+
+/**
+ * The `>` chevron before a card title is its collapse toggle. It points right while the card is
+ * closed and turns down while it is open (CSS reads aria-expanded). The delegated click handler
+ * in interactions.js reads `data-act` and toggles the card this button belongs to.
+ * @param {string} label
+ * @param {boolean} [expanded]
+ * @param {{ act?: string }} [opts] `act` is omitted inside a <details>, which toggles itself
+ */
+export function chevronHtml(label, expanded = true, opts = {}) {
+  const act = opts.act === undefined ? '' : ` data-act="${esc(opts.act)}"`
+  return `<button class="chev" type="button"${act} aria-expanded="${expanded ? 'true' : 'false'}" aria-label="${esc(label)}">&gt;</button>`
+}
+
+/**
+ * The <summary> of a collapsible <details> block: a chevron, then the title. The block relies on the
+ * native <details> toggle, so a click anywhere on the summary opens or closes it. Pass `open` when
+ * the <details> carries the `open` attribute so the chevron reports the same state.
+ * @param {string} titleHtml already escaped
+ * @param {string} label the chevron's accessible name
+ * @param {{ open?: boolean }} [opts]
+ */
+export function detailsSummaryHtml(titleHtml, label, opts = {}) {
+  return `<summary>${chevronHtml(label, opts.open === true)}${titleHtml}</summary>`
+}
+
+/**
+ * Parses an HTML string into a fragment. Only for strings built with esc().
+ * @param {string} html
+ * @returns {DocumentFragment}
+ */
+export function fragment(html) {
+  const t = document.createElement('template')
+  t.innerHTML = html
+  return t.content
+}
+
+/**
+ * @template {Element} T
+ * @param {string} selector
+ * @param {ParentNode} [root]
+ * @returns {T | null}
+ */
+export function qs(selector, root = document) {
+  return /** @type {T | null} */ (root.querySelector(selector))
+}
+
+/**
+ * Highlights an element for two seconds by toggling `.is-target`.
+ * @param {Element} el
+ * @param {number} [ms]
+ */
+export function flash(el, ms = 2000) {
+  el.classList.add('is-target')
+  setTimeout(() => el.classList.remove('is-target'), ms)
+}
+
+/**
+ * scrollIntoView without throwing in environments that lack it.
+ * @param {Element} el
+ */
+export function scrollIntoViewSafe(el) {
+  el.dispatchEvent(new Event('reveal-code', { bubbles: true }))
+  if (typeof el.scrollIntoView === 'function') {
+    el.scrollIntoView({ block: 'center' })
+  }
+}
+
+/**
+ * "3 min ago" style text for a timestamp.
+ * @param {string} iso
+ * @param {Date} [now]
+ * @returns {string}
+ */
+export function timeAgo(iso, now = new Date()) {
+  const t = Date.parse(iso)
+  if (Number.isNaN(t)) {
+    return ''
+  }
+  const s = Math.max(0, Math.round((now.getTime() - t) / 1000))
+  if (s < 60) {
+    return 'just now'
+  }
+  const m = Math.round(s / 60)
+  if (m < 60) {
+    return `${m} min ago`
+  }
+  const hrs = Math.round(m / 60)
+  if (hrs < 48) {
+    return `${hrs} h ago`
+  }
+  return `${Math.round(hrs / 24)} d ago`
+}
+
+/**
+ * Two-letter initials for the avatar square.
+ * @param {string} login
+ */
+export function initials(login) {
+  const parts = login
+    .replace(/\[bot\]$/, '')
+    .split(/[-_.\s]+/)
+    .filter(Boolean)
+  const a = parts[0]?.[0] ?? '?'
+  const b = parts[1]?.[0] ?? parts[0]?.[1] ?? ''
+  return (a + b).toUpperCase()
+}
+
+/**
+ * Writes text to the clipboard. Throws when the page has no clipboard access (plain http on a
+ * non-localhost origin, or an old browser), so the command shows the failure inline.
+ * @param {string} text
+ * @param {Clipboard | null} [clipboard] defaults to the page's; null means none
+ */
+export async function copyToClipboard(text, clipboard) {
+  const target = clipboard === undefined ? globalThis.navigator?.clipboard : clipboard
+  if (!target || typeof target.writeText !== 'function') {
+    throw new Error('clipboard is not available; copy the command by hand')
+  }
+  await target.writeText(text)
+}
+
+/** @param {{ author: string, avatarUrl?: string | undefined }} comment */
+export function avatarHtml(comment) {
+  const url = comment.avatarUrl
+  if (url && /^https:\/\/avatars\.githubusercontent\.com\//i.test(url)) {
+    return `<img class="av" src="${esc(url)}" alt="${esc(comment.author)} avatar" width="24" height="24" loading="lazy" referrerpolicy="no-referrer">`
+  }
+  return `<span class="av" aria-hidden="true">${esc(initials(comment.author))}</span>`
+}

package/static/js/download.js

@@ -0,0 +1,52 @@
+// @ts-check
+// Handing a file to the browser. The export command fetches the zip itself, so it can show a
+// pending state and an error; this module only does the save at the end.
+import { fetchCanvasZip } from './api.js'
+
+/**
+ * @typedef {{ doc?: Document, urls?: { createObjectURL: (b: Blob) => string, revokeObjectURL: (u: string) => void } }} SaveDeps
+ */
+
+/**
+ * @param {Blob} blob
+ * @param {string} filename
+ * @param {SaveDeps} [deps]
+ */
+export function saveBlob(blob, filename, deps = {}) {
+  const doc = deps.doc ?? document
+  const urls = deps.urls ?? URL
+  const href = urls.createObjectURL(blob)
+  const link = doc.createElement('a')
+  link.href = href
+  link.download = filename
+  doc.body.appendChild(link)
+  link.click()
+  link.remove()
+  urls.revokeObjectURL(href)
+}
+
+/**
+ * @param {number} prNumber
+ * @param {{ headSha?: string, fetchImpl?: typeof fetch } & SaveDeps} [opts]
+ * @returns {Promise<string>} the file name the browser saved
+ */
+export async function exportCanvasZip(prNumber, opts = {}) {
+  /** @type {{ headSha?: string, fetchImpl?: typeof fetch }} */
+  const request = {}
+  if (opts.headSha !== undefined) {
+    request.headSha = opts.headSha
+  }
+  if (opts.fetchImpl !== undefined) {
+    request.fetchImpl = opts.fetchImpl
+  }
+  const { blob, filename } = await fetchCanvasZip(prNumber, request)
+  const deps = {}
+  if (opts.doc !== undefined) {
+    deps.doc = opts.doc
+  }
+  if (opts.urls !== undefined) {
+    deps.urls = opts.urls
+  }
+  saveBlob(blob, filename, deps)
+  return filename
+}

package/static/js/empty-state.js

@@ -0,0 +1,161 @@
+// @ts-check
+/** @typedef {import('./contract-types.js').PrBundle} PrBundle */
+import { esc } from './dom.js'
+
+export const DROP_ZONE_ID = 'zip'
+
+/**
+ * What the drop zone shows. `over` is a file dragged across it, `busy` an upload in flight, and
+ * `error` the last failure, which stays until the next attempt.
+ * @typedef {{ phase: 'idle' | 'over' | 'busy', progress: number, error: string | null }} DropState
+ */
+
+/** @type {DropState} */
+export const INITIAL_DROP_STATE = { phase: 'idle', progress: 0, error: null }
+
+/**
+ * @typedef {{ type: 'enter' } | { type: 'leave' } | { type: 'start' } | { type: 'progress', fraction: number }
+ *   | { type: 'done' } | { type: 'fail', message: string }} DropEvent
+ */
+
+/**
+ * @param {DropState} state
+ * @param {DropEvent} event
+ * @returns {DropState}
+ */
+export function dropReducer(state, event) {
+  switch (event.type) {
+    case 'enter':
+      return state.phase === 'busy' ? state : { ...state, phase: 'over' }
+    case 'leave':
+      return state.phase === 'busy' ? state : { ...state, phase: 'idle' }
+    case 'start':
+      return { phase: 'busy', progress: 0, error: null }
+    case 'progress':
+      return state.phase === 'busy' ? { ...state, progress: Math.min(Math.max(event.fraction, 0), 1) } : state
+    case 'done':
+      return { phase: 'idle', progress: 1, error: null }
+    case 'fail':
+      return { phase: 'idle', progress: 0, error: event.message }
+  }
+}
+
+/**
+ * The file the user picked has to be a canvas zip. The name is only a first check; the server
+ * reads the zip itself and answers CANVAS_INVALID when it is not one.
+ * @param {string} filename
+ * @returns {string | null} the problem, or null when the name is fine
+ */
+export function validateCanvasFilename(filename) {
+  if (!filename.toLowerCase().endsWith('.zip')) {
+    return 'that is not a zip file'
+  }
+  return filename.toLowerCase().startsWith('pr-review-canvas-') ? null : 'that zip is not a review canvas export'
+}
+
+/**
+ * @param {PrBundle} bundle
+ * @returns {string}
+ */
+export function sharedCanvasCalloutHtml(bundle) {
+  const shared = bundle.sharedCanvas
+  if (!shared) {
+    return ''
+  }
+  const name = `<span class="path">${esc(shared.name)}</span>`
+  if (shared.downloadable) {
+    return `<div class="callout" role="status">A canvas is attached to this PR (${name}) &mdash; importing&hellip;</div>`
+  }
+  return (
+    `<div class="callout warn" role="status">A canvas is attached to this PR (${name}) but could not be downloaded (${esc(shared.reason ?? 'unknown')}). ` +
+    `<a href="${esc(shared.url)}" target="_blank" rel="noopener noreferrer">Download it</a> and drop it here. ` +
+    '<button class="cmd" type="button" id="fetch-shared">fetch again</button></div>'
+  )
+}
+
+/**
+ * @param {PrBundle} bundle
+ * @returns {string}
+ */
+function skillCommandHtml(bundle) {
+  return (
+    '<p class="hint">Run this in Claude Code or Codex from this repo. The page updates when the canvas is published.</p>' +
+    `<div class="cmdbox"><code>${esc(bundle.skillCommand)}</code><button class="cmd fill" type="button" data-copy="${esc(bundle.skillCommand)}">copy</button></div>`
+  )
+}
+
+/** @returns {string} */
+function dropZoneHtml() {
+  return (
+    '<p class="hint">or import a canvas a teammate attached to the PR</p>' +
+    `<label class="drop" for="${DROP_ZONE_ID}">Drop a canvas zip here or <span class="link">choose file</span>` +
+    `<input class="sr" id="${DROP_ZONE_ID}" type="file" accept=".zip"></label>` +
+    '<p class="drop-status" role="status" aria-live="polite"></p>'
+  )
+}
+
+/**
+ * The `missing` screen: the skill command with its copy command, the drop zone, the callout.
+ * @param {PrBundle} bundle
+ * @returns {string}
+ */
+export function renderEmptyState(bundle) {
+  return (
+    '<section class="panel empty" id="empty-state" aria-labelledby="es-h">' +
+    '<div class="panel-h"><h2 id="es-h">No review canvas for this PR yet</h2></div>' +
+    '<div class="body center">' +
+    skillCommandHtml(bundle) +
+    dropZoneHtml() +
+    sharedCanvasCalloutHtml(bundle) +
+    '</div></section>'
+  )
+}
+
+/**
+ * How far the canvas is from the head, in words.
+ * @param {NonNullable<PrBundle['stale']>} stale
+ * @returns {string}
+ */
+export function staleSummary(stale) {
+  const canvas = stale.canvasHeadSha.slice(0, 7)
+  const head = stale.currentHeadSha.slice(0, 7)
+  if (stale.relation === 'unrelated') {
+    return `The canvas is for ${canvas}, which is not in this branch any more; the head is ${head}.`
+  }
+  const behind = stale.commitsBehind ?? 0
+  return `The canvas is for ${canvas}, ${behind} commit${behind === 1 ? '' : 's'} behind the head ${head}.`
+}
+
+/**
+ * The bar that stays on screen while a stale canvas is shown, so the reader is never misled about
+ * which commit the diffs come from.
+ * @param {NonNullable<PrBundle['stale']>} stale
+ * @returns {string}
+ */
+export function staleBarHtml(stale) {
+  return (
+    `<div class="stale-bar" role="status"><strong>Canvas is outdated.</strong> You are reading an older commit. ${esc(staleSummary(stale))} ` +
+    '<button class="cmd" type="button" id="stale-generate" aria-haspopup="dialog">generate for current head</button></div>'
+  )
+}
+
+/**
+ * The `stale` screen: the same card as the empty state, plus the two ways forward.
+ * @param {PrBundle} bundle
+ * @returns {string}
+ */
+export function renderStaleState(bundle) {
+  const stale = bundle.stale
+  return (
+    '<section class="panel empty" id="empty-state" aria-labelledby="es-h">' +
+    '<div class="panel-h"><h2 id="es-h">Canvas is outdated</h2></div>' +
+    '<div class="body center">' +
+    `<p class="hint">${stale ? esc(staleSummary(stale)) : ''}</p>` +
+    '<div class="cmdbox"><button class="cmd fill" type="button" id="view-stale">view stale canvas</button>' +
+    '<button class="cmd" type="button" id="stale-generate" aria-haspopup="dialog">generate for current head</button></div>' +
+    skillCommandHtml(bundle) +
+    dropZoneHtml() +
+    sharedCanvasCalloutHtml(bundle) +
+    '</div></section>'
+  )
+}

package/static/js/errors.js

@@ -0,0 +1,135 @@
+// @ts-check
+// Error cards for the review page, keyed by the server's error code. Each card says what happened,
+// what to do, and offers a retry. Every code in the server's list has one; errors.test.js checks
+// that, so a new code cannot ship without its card.
+/** @typedef {import('./contract-types.js').ErrorEnvelope} ErrorEnvelope */
+import { esc } from './dom.js'
+
+/** @typedef {{ title: string, action: string }} ErrorCard */
+
+/** @type {ErrorCard} */
+const FALLBACK = {
+  title: 'Something went wrong',
+  action: 'Retry. If it keeps failing, check the server log in the terminal running pr-review.',
+}
+
+/** @type {Record<string, ErrorCard>} */
+export const ERROR_CARDS = {
+  BAD_REQUEST: {
+    title: 'The page asked for something the server could not read',
+    action: 'Check the URL. If you got here from a link inside the page, retry and report it.',
+  },
+  NOT_FOUND: {
+    title: 'Not found',
+    action: 'Retry. A missing diff usually means the PR head is not in this clone yet.',
+  },
+  FORBIDDEN_HOST: {
+    title: 'This server only answers to localhost',
+    action: 'Open the page as http://localhost:3010 or http://127.0.0.1:3010.',
+  },
+  CROSS_ORIGIN: {
+    title: 'The request did not come from this page',
+    action: 'Reload the page and try again. Do not drive this server from another site.',
+  },
+  NOT_A_REPO: {
+    title: 'Not a git repository',
+    action: 'Start pr-review from a clone, or pass --repo <dir>.',
+  },
+  NO_ORIGIN: {
+    title: 'No GitHub origin',
+    action: 'Add an origin remote that points at github.com, then restart the server.',
+  },
+  GIT_ERROR: {
+    title: 'A git command failed',
+    action: 'Check the message, then retry. Fetching the PR head by hand often clears it.',
+  },
+  GH_MISSING: {
+    title: 'GitHub CLI is not installed',
+    action: 'Install gh from https://cli.github.com and log in, then retry.',
+  },
+  GH_UNAUTHENTICATED: {
+    title: 'GitHub CLI is not logged in',
+    action: 'Run gh auth login in a terminal, then retry.',
+  },
+  GITHUB_API_ERROR: {
+    title: 'GitHub refused the request',
+    action: 'Retry in a moment. A rate limit or an outage both read like this.',
+  },
+  PR_NOT_FOUND: {
+    title: 'Pull request not found',
+    action: 'Check the number, and that this clone’s origin is the right repository.',
+  },
+  CANVAS_NOT_FOUND: {
+    title: 'No canvas for this pull request',
+    action: 'Generate one with the pr-review-canvas skill, or import a zip a teammate attached.',
+  },
+  CANVAS_INVALID: {
+    title: 'That canvas could not be read',
+    action: 'Generate the canvas again for the current head, or import another zip.',
+  },
+  CANVAS_REPO_MISMATCH: {
+    title: 'That canvas belongs to another repository',
+    action: 'Import a canvas exported from this repository.',
+  },
+  CANVAS_TOO_LARGE: {
+    title: 'That canvas is too large',
+    action: 'A canvas zip holds two JSON files and stays under 20 MB. Export it again.',
+  },
+  CANVAS_STALE: {
+    title: 'The pull request moved on',
+    action: 'Reload the page: the head commit changed since this page was drawn.',
+  },
+  MODEL_INVALID: {
+    title: 'The generated canvas did not pass validation',
+    action: 'Run the pr-review-canvas skill again; it prints one line per problem.',
+  },
+  SKILL_DIR_EXISTS: {
+    title: 'The skill directory is already taken',
+    action: 'Remove it, or run pr-review install-skill --force.',
+  },
+  COMMENT_FORBIDDEN: {
+    title: 'This GitHub login cannot post here',
+    action: 'Run gh auth refresh -h github.com -s repo, then retry.',
+  },
+  COMMENT_LINE_NOT_IN_DIFF: {
+    title: 'GitHub takes comments only on lines the diff shows',
+    action: 'Pick a line inside a hunk of this pull request.',
+  },
+  SIGNOFF_INCOMPLETE: {
+    title: 'Some layers are not reviewed yet',
+    action: 'Mark every layer outside Other as reviewed, then approve.',
+  },
+  CHAT_BUSY: {
+    title: 'The chat is answering another message',
+    action: 'Wait for the answer, or stop it, then send again.',
+  },
+  NOT_IMPLEMENTED: {
+    title: 'That part is not built yet',
+    action: 'Nothing to do here; the feature is not in this version.',
+  },
+  INTERNAL: FALLBACK,
+}
+
+/**
+ * @param {ErrorEnvelope['error']} error
+ * @returns {ErrorCard}
+ */
+export function errorCardFor(error) {
+  return ERROR_CARDS[error.code] ?? FALLBACK
+}
+
+/**
+ * @param {ErrorEnvelope['error']} error
+ * @returns {string}
+ */
+export function errorCardHtml(error) {
+  const card = errorCardFor(error)
+  return (
+    '<main id="main" class="home">' +
+    `<section class="panel error-card" data-code="${esc(error.code)}" aria-labelledby="err-h">` +
+    `<div class="panel-h"><h2 id="err-h">${esc(card.title)} <span class="mono muted">${esc(error.code)}</span></h2></div>` +
+    `<div class="body"><p>${esc(error.message)}</p>${error.hint ? `<p class="muted">${esc(error.hint)}</p>` : ''}` +
+    `<p>${esc(card.action)}</p>` +
+    '<p><button class="cmd fill" type="button" id="retry">retry</button></p></div></section></main>'
+  )
+}

package/static/js/fences.js

@@ -0,0 +1,90 @@
+// @ts-check
+// Splits a markdown text around fenced blocks with one info string. Two callers: mermaid
+// diagrams and the chat's proposed-comment cards.
+
+/** @typedef {{ type: 'markdown' | 'block', text: string }} FenceSegment */
+
+/** A fence line: up to three spaces, the marker, then the info string. */
+const FENCE_RE = /^([ \t]{0,3})(`{3,}|~{3,})[ \t]*(.*)$/
+
+/**
+ * The fence a line opens or closes, or null when the line is ordinary text. A backtick fence
+ * carries no backtick in its info string, which is what tells a fence from inline code.
+ * @param {string} line
+ * @returns {{ marker: string, info: string } | null}
+ */
+function fenceOf(line) {
+  const match = FENCE_RE.exec(line)
+  if (match === null) {
+    return null
+  }
+  const marker = match[2] ?? ''
+  const info = (match[3] ?? '').trim()
+  if (marker.startsWith('`') && info.includes('`')) {
+    return null
+  }
+  return { marker, info }
+}
+
+/**
+ * The pieces of a markdown text in order: prose and the blocks whose info string is `info`. A
+ * fence inside another fence is plain code, and an unclosed block is prose again, opening line
+ * and all, because the reader never sees it as a block either.
+ * @param {string} markdown
+ * @param {string} info the info string to pick out, compared case-insensitively
+ * @returns {FenceSegment[]}
+ */
+export function splitFences(markdown, info) {
+  const wanted = info.toLowerCase()
+  /** @type {FenceSegment[]} */
+  const out = []
+  /** @type {string[]} */
+  let prose = []
+  /** @type {string[]} */
+  let block = []
+  /** @type {{ marker: string, wanted: boolean, line: string } | null} */
+  let open = null
+  const flushProse = () => {
+    if (prose.length > 0) {
+      out.push({ type: 'markdown', text: prose.join('\n') })
+      prose = []
+    }
+  }
+  // CRLF text is read as LF, so a fence is found the same way whatever wrote the markdown.
+  for (const line of markdown.replace(/\r\n/g, '\n').split('\n')) {
+    const fence = fenceOf(line)
+    if (open === null) {
+      if (fence !== null) {
+        open = { marker: fence.marker, wanted: fence.info.toLowerCase() === wanted, line }
+        if (open.wanted) {
+          block = []
+          continue
+        }
+      }
+      prose.push(line)
+      continue
+    }
+    const closer = fence !== null && fence.info === '' ? fence.marker : ''
+    const closes = closer.length >= open.marker.length && closer[0] === open.marker[0]
+    if (closes) {
+      if (open.wanted) {
+        flushProse()
+        out.push({ type: 'block', text: block.join('\n') })
+      } else {
+        prose.push(line)
+      }
+      open = null
+      continue
+    }
+    if (open.wanted) {
+      block.push(line)
+    } else {
+      prose.push(line)
+    }
+  }
+  if (open?.wanted === true) {
+    prose.push(open.line, ...block)
+  }
+  flushProse()
+  return out
+}