@vintasoftware/pr-review-canvas 0.3.0 → 0.5.0

package/static/js/fold-levels.js

@@ -0,0 +1,176 @@
+// @ts-check
+// How aggressively the canvas hides code. One implementation for the server (re-exported by
+// src/contract/review-artifact.ts) and the browser, so the validator and the page agree on what
+// a level hides.
+
+/**
+ * The levels, from the least hiding to the most. They nest: a fold hides at its own level and at
+ * every level above it, so `light` folds are hidden in all three modes. The page opens at the
+ * level saved in the settings file, `light` until the reader picks another, and a change from
+ * the control holds for the session only.
+ */
+export const FOLD_LEVELS = /** @type {const} */ (['light', 'moderate', 'aggressive'])
+
+/** @typedef {(typeof FOLD_LEVELS)[number]} FoldLevel */
+
+/** The level a review opens at until the reader saves another, and the level of an older canvas's folds. */
+export const DEFAULT_FOLD_LEVEL = 'light'
+
+/**
+ * @param {unknown} value
+ * @returns {value is FoldLevel}
+ */
+export function isFoldLevel(value) {
+  return FOLD_LEVELS.some(level => level === value)
+}
+
+/**
+ * Where a level sits in the order, so two levels can be compared.
+ * @param {FoldLevel} level
+ * @returns {number}
+ */
+export function foldLevelRank(level) {
+  return FOLD_LEVELS.indexOf(level)
+}
+
+/**
+ * Whether code marked with `level` is hidden while the reader is at `current`.
+ * @param {FoldLevel} level
+ * @param {FoldLevel} current
+ * @returns {boolean}
+ */
+export function hidesAt(level, current) {
+  return foldLevelRank(level) <= foldLevelRank(current)
+}
+
+/**
+ * The level after `level`, back to the first after the last, so one key can step through them.
+ * @param {FoldLevel} level
+ * @returns {FoldLevel}
+ */
+export function nextFoldLevel(level) {
+  return FOLD_LEVELS[(foldLevelRank(level) + 1) % FOLD_LEVELS.length] ?? DEFAULT_FOLD_LEVEL
+}
+
+/**
+ * @typedef {{ side: 'new' | 'old', startLine: number, endLine: number }} Span
+ * @typedef {Span & { level: FoldLevel }} Range
+ * @typedef {{
+ *   collapsed?: FoldLevel | undefined,
+ *   annotations: readonly Span[],
+ *   folds?: readonly Range[] | undefined,
+ *   hunks: readonly string[],
+ * }} FoldedFile
+ */
+
+/**
+ * Whether `inner` sits wholly inside `outer` without being the same range. The validator allows
+ * this only when the inner fold has the lower level; the page then draws the outer one alone.
+ * @param {Span} outer
+ * @param {Span} inner
+ */
+export function contains(outer, inner) {
+  return (
+    outer !== inner &&
+    outer.side === inner.side &&
+    outer.startLine <= inner.startLine &&
+    inner.endLine <= outer.endLine &&
+    (outer.startLine < inner.startLine || inner.endLine < outer.endLine)
+  )
+}
+
+/**
+ * The folds that hide at `level`, with every fold nested inside another kept fold dropped. Only
+ * the outermost fold is drawn, so raising the level replaces a set of small titles with one.
+ * @template {Range} T
+ * @param {readonly T[]} folds
+ * @param {FoldLevel} level
+ * @returns {T[]}
+ */
+export function foldsForLevel(folds, level) {
+  const applicable = folds.filter(fold => hidesAt(fold.level, level))
+  return applicable.filter(fold => !applicable.some(other => contains(other, fold)))
+}
+
+/**
+ * Whether a file's whole body starts hidden at this level. An annotated file never collapses: a
+ * fold over an annotation still shows the annotation's text, a collapsed file shows only its path.
+ * @param {FoldedFile} file
+ * @param {FoldLevel} level
+ * @returns {boolean}
+ */
+export function collapsesAt(file, level) {
+  return file.collapsed !== undefined && hidesAt(file.collapsed, level) && file.annotations.length === 0
+}
+
+/**
+ * Rows a set of ranges covers, each row counted once where ranges nest or touch. The one count
+ * the page's counters and the validator's thresholds share.
+ * @param {readonly Span[]} ranges
+ * @returns {number}
+ */
+export function coveredRows(ranges) {
+  let total = 0
+  for (const side of /** @type {const} */ (['new', 'old'])) {
+    const sorted = ranges
+      .filter(range => range.side === side)
+      .map(range => ({ start: range.startLine, end: range.endLine }))
+      .sort((a, b) => a.start - b.start)
+    /** @type {{ start: number, end: number } | null} */
+    let current = null
+    for (const range of sorted) {
+      if (current !== null && range.start <= current.end + 1) {
+        current.end = Math.max(current.end, range.end)
+        continue
+      }
+      total += current === null ? 0 : current.end - current.start + 1
+      current = { ...range }
+    }
+    total += current === null ? 0 : current.end - current.start + 1
+  }
+  return total
+}
+
+/**
+ * Rows a file's hunks draw, near enough for a counter: context lines are shared by both sides,
+ * so the longer side is the row count when nothing else is known about the patch.
+ * @param {FoldedFile} file
+ * @param {ReadonlyArray<{ id: string, oldLines: number, newLines: number }>} hunks every hunk of the file
+ * @returns {number}
+ */
+export function fileRows(file, hunks) {
+  return hunks
+    .filter(hunk => file.hunks.includes(hunk.id))
+    .reduce((sum, hunk) => sum + Math.max(hunk.oldLines, hunk.newLines), 0)
+}
+
+/**
+ * What the review's discussion keeps open in one file card: `keepsOpen` when a comment or an
+ * attention point stops the card collapsing, `discussed` when a thread or a pending draft in its
+ * chunks stops every fold. The page decides both once per card, and the card and its counter read
+ * the answer.
+ * @typedef {{ keepsOpen: boolean, discussed: boolean }} Discussion
+ */
+
+/** A file nobody has discussed yet, as the validator sees every file of a fresh generation. */
+export const UNDISCUSSED = /** @type {Discussion} */ ({ keepsOpen: false, discussed: false })
+
+/**
+ * How many diff lines a file shows, and how many of them `level` hides. Measured from the model,
+ * so the counter reads the same before and after a card draws its diff.
+ * @param {FoldedFile} file
+ * @param {ReadonlyArray<{ id: string, oldLines: number, newLines: number }>} hunks every hunk of the file
+ * @param {FoldLevel} level
+ * @param {Discussion} discussion
+ * @returns {{ total: number, hidden: number }}
+ */
+export function hiddenLines(file, hunks, level, discussion) {
+  const total = fileRows(file, hunks)
+  if (collapsesAt(file, level) && !discussion.keepsOpen) {
+    return { total, hidden: total }
+  }
+  if (discussion.discussed) {
+    return { total, hidden: 0 }
+  }
+  return { total, hidden: coveredRows(foldsForLevel(file.folds ?? [], level)) }
+}

package/static/js/header.js

@@ -3,8 +3,11 @@
 /** @typedef {import('./contract-types.js').RiskTag} RiskTag */
 import { setDisabledReason } from './composer.js'
 import { esc, timeAgo } from './dom.js'
-import { refreshRail } from './layers.js'
+import { authorProfileUrl, currentHost, hostLabel } from './host.js'
+import { canvasHiddenLines, getFoldLevel, refreshRail } from './layers.js'
+import { pendingBarHtml, pendingCount } from './pending.js'
 import { progressSummary } from './progress.js'
+import { foldLevelControlHtml } from './reading-level.js'
 import { approveBlockedReason } from './signoff.js'
 import { skinLabel } from './skin.js'
 import { themeLabel } from './theme.js'
@@ -41,6 +44,19 @@ export function largePrNoticeHtml(bundle) {
   )
 }
 
+/**
+ * The author, linked to their page on the forge. A local review's author is the name this clone
+ * commits as, which is no forge login, so it stays plain text.
+ * @param {string} author
+ * @param {boolean} local
+ * @returns {string}
+ */
+function authorHtml(author, local) {
+  return local
+    ? esc(author)
+    : `<a href="${esc(authorProfileUrl(author))}" target="_blank" rel="noopener noreferrer">${esc(author)}</a>`
+}
+
 /** @param {PrBundle['pr']} pr */
 export function statePill(pr) {
   const state = pr.state === 'open' && pr.draft ? 'draft' : pr.state
@@ -61,47 +77,81 @@ export function renderHeader(bundle, opts) {
     ? `<span class="pill agent">${esc(artifact.generator.agent)}${artifact.generator.model ? ` · ${esc(artifact.generator.model)}` : ''} · ${esc(artifact.generator.harness)}</span><span>generated ${esc(timeAgo(artifact.generatedAt, opts.now))}</span>`
     : ''
   const number = pr.number === null ? '' : `<span class="mono num">#${pr.number}</span>`
-  const progress = ready ? progressHtml(artifact, bundle.state) : ''
+  // Work that is not pushed has no page on the forge, and nothing to refresh from it either.
+  const local = bundle.local !== undefined
+  const forgeLink =
+    pr.url === ''
+      ? ''
+      : `<a class="cmd" href="${esc(pr.url)}" target="_blank" rel="noopener noreferrer">${esc(currentHost().kind)}</a>`
+  const refreshTitle = local
+    ? 'Snapshot the working tree again and redraw'
+    : `Fetch the latest PR, comments, and shared canvas from ${esc(hostLabel())}`
+  const progress = ready ? progressHtml(artifact, bundle.state, pr.headSha) : ''
+  const level = getFoldLevel()
+  const reading = ready
+    ? foldLevelControlHtml(
+        level,
+        canvasHiddenLines(
+          {
+            artifact,
+            files: bundle.files,
+            comments: bundle.comments.reviewComments,
+            state: bundle.state,
+            headSha: pr.headSha,
+          },
+          level
+        )
+      )
+    : ''
   const risk = ready ? riskLineHtml(artifact.risk) : ''
   return (
     '<header class="hdr">' +
     `<div class="hdr-bar"><div class="brand"><span class="brand-wordmark"><img class="brand-icon" src="/static/brand.svg" width="32" height="32" alt="">PR review canvas</span><span class="mono muted">${esc(opts.host)}</span></div>` +
     '<div class="hdr-actions" role="group" aria-label="Canvas actions">' +
-    `<button class="cmd" type="button" id="regenerate" title="Generate a new canvas for this PR" aria-haspopup="dialog"${hasCanvas ? '' : ' disabled'}>regenerate</button>` +
-    `<button class="cmd" type="button" id="export-zip" title="Download this canvas as a zip to share on GitHub"${hasCanvas ? '' : ' disabled'}>export zip</button>` +
-    '<button class="cmd" type="button" id="refresh" title="Fetch the latest PR, comments, and shared canvas from GitHub">refresh</button>' +
-    `<button class="cmd" type="button" id="settings" data-act="settings" aria-haspopup="dialog"${bundle.chat.enabled || bundle.chat.acpx ? ' title="Configure the AI chat agent, model, and limits"' : ' disabled title="acpx is not installed"'}>settings</button>` +
+    `<button class="cmd" type="button" id="regenerate" title="Generate a new canvas for ${local ? 'this local work' : 'this PR'}" aria-haspopup="dialog"${hasCanvas ? '' : ' disabled'}>regenerate</button>` +
+    `<button class="cmd" type="button" id="export-zip" title="Download this canvas as a zip to share on ${esc(hostLabel())}"${hasCanvas ? '' : ' disabled'}>export zip</button>` +
+    `<button class="cmd" type="button" id="refresh" title="${refreshTitle}">refresh</button>` +
+    '<button class="cmd" type="button" id="settings" data-act="settings" aria-haspopup="dialog" title="Configure the default reading level and the AI chat agent, model, and limits">settings</button>' +
     '<button class="cmd" type="button" data-act="help" title="Show keyboard shortcuts and review help" aria-haspopup="dialog">help</button>' +
     `<button class="cmd" type="button" id="skin-toggle" title="Switch between Terminal and GitHub styling">${esc(skinLabel(opts.skin))}</button>` +
     `<button class="cmd" type="button" id="theme-toggle" title="Switch between Light, Dark, and Auto themes">${esc(themeLabel(opts.theme))}</button>` +
     '</div></div>' +
     '<div class="stripe" aria-hidden="true"></div>' +
     '<div class="hdr-title">' +
-    `<div class="title"><h1>${number}${esc(pr.title)}</h1><a class="cmd" href="${esc(pr.url)}" target="_blank" rel="noopener noreferrer">github</a></div>` +
-    `<p class="meta"><span>by <a href="https://github.com/${esc(pr.author)}" target="_blank" rel="noopener noreferrer">${esc(pr.author)}</a></span>` +
+    `<div class="title"><h1>${number}${esc(pr.title)}</h1>${forgeLink}</div>` +
+    `<p class="meta"><span>by ${authorHtml(pr.author, local)}</span>` +
     `<span class="mono">${esc(pr.headRef)} &rarr; ${esc(pr.baseRef)}</span>${statePill(pr)}` +
     `<span class="diffstat"><span class="ok">+${pr.additions}</span> <span class="bad">&minus;${pr.deletions}</span></span>${agent}</p>` +
-    `${largePrNoticeHtml(bundle)}${risk}${progress}</div></header>`
+    `${largePrNoticeHtml(bundle)}${risk}${reading}${progress}</div></header>`
   )
 }
 
 /**
- * The thin line, its text, and the two sign-off commands. Approve stays disabled with the
- * reason until every layer that is not Other has been marked reviewed.
+ * The thin line, its text, the pending-review bar, and the three sign-off commands. Approve stays
+ * disabled with the reason until every layer that is not Other has been marked reviewed; a
+ * comment-only review and a request for changes are always allowed, since neither claims the
+ * change set was read in full.
  * @param {import('./contract-types.js').ReviewArtifact} artifact
  * @param {import('./contract-types.js').PrState} state
  */
-export function progressHtml(artifact, state) {
+export function progressHtml(artifact, state, headSha = artifact.pr.headSha) {
   const p = progressSummary(artifact, state)
   const blocked = approveBlockedReason(artifact, state)
+  const approveTitle = `Write and preview an approving review on ${esc(hostLabel())}`
   const approve =
-    `<button class="cmd" type="button" id="approve" data-tooltip="Write and preview an approving review on GitHub" data-act="signoff" data-event="APPROVE" data-needs-post` +
-    `${blocked === null ? ' title="Write and preview an approving review on GitHub"' : ` disabled data-disabled-reason="${esc(blocked)}" title="${esc(blocked)}"`}>approve on github</button>`
+    `<button class="cmd" type="button" id="approve" data-tooltip="${approveTitle}" data-act="signoff" data-event="APPROVE" data-needs-post` +
+    `${blocked === null ? ` title="${approveTitle}"` : ` disabled data-disabled-reason="${esc(blocked)}" title="${esc(blocked)}"`}>approve on ${esc(currentHost().kind)}</button>`
+  const commentTitle = `Write and preview a review with no verdict on ${esc(hostLabel())}`
   return (
     `<div class="progress"><div class="pline" role="progressbar" aria-valuenow="${p.done}" aria-valuemin="0" aria-valuemax="${p.total}" aria-label="Layers reviewed"><span style="width:${p.percent}%"></span></div>` +
     `<span class="ptext">${p.done} of ${p.total} layers reviewed</span></div>` +
+    `<div class="pending-bar-host${pendingCount(state) > 0 ? ' has-pending' : ''}">${pendingBarHtml(
+      pendingCount(state),
+      state.pending.filter(draft => draft.headSha !== headSha)
+    )}</div>` +
     `<div class="signoff">${approve}` +
-    '<button class="cmd" type="button" id="request-changes" data-tooltip="Write and preview a review requesting changes on GitHub" title="Write and preview a review requesting changes on GitHub" data-act="signoff" data-event="REQUEST_CHANGES" data-needs-post>request changes</button>' +
+    `<button class="cmd" type="button" id="request-changes" data-tooltip="Write and preview a review requesting changes on ${esc(hostLabel())}" title="Write and preview a review requesting changes on ${esc(hostLabel())}" data-act="signoff" data-event="REQUEST_CHANGES" data-needs-post>request changes</button>` +
+    `<button class="cmd" type="button" id="comment-review" data-tooltip="${commentTitle}" title="${commentTitle}" data-act="signoff" data-event="COMMENT" data-needs-post>comment</button>` +
     '<span class="capability-note" role="status"></span></div>'
   )
 }

package/static/js/host.js

@@ -0,0 +1,40 @@
+// @ts-check
+// The forge this server talks to, as the page shell's bootstrap names it. One server serves one
+// host, so the words and links that depend on it are read from here rather than threaded through
+// every renderer.
+/** @typedef {import('./contract-types.js').PublicHost} PublicHost */
+
+/** @type {PublicHost} */
+const DEFAULT_HOST = { kind: 'github', label: 'GitHub', webBase: 'https://github.com' }
+
+/** @type {PublicHost} */
+let current = DEFAULT_HOST
+
+/** @param {PublicHost | undefined} host */
+export function setHost(host) {
+  current = host ?? DEFAULT_HOST
+}
+
+export function currentHost() {
+  return current
+}
+
+/** `GitHub` or `GitLab`, for sentences. */
+export function hostLabel() {
+  return current.label
+}
+
+/** `post to github` / `post to gitlab`, the command label. */
+export function postToLabel() {
+  return `post to ${current.kind}`
+}
+
+/** What a command says when this login may not post. */
+export function noPostingTitle() {
+  return `this ${current.label} login cannot post on this repository`
+}
+
+/** @param {string} author */
+export function authorProfileUrl(author) {
+  return `${current.webBase}/${author}`
+}

package/static/js/import-zone.js

@@ -56,7 +56,7 @@ export function wireDropZone(root, opts) {
     }
   }
   const send = async (/** @type {File} */ file) => {
-    const problem = validateCanvasFilename(file.name)
+    const problem = validateCanvasFilename(file.name, opts.prNumber)
     if (problem !== null) {
       apply({ type: 'fail', message: problem })
       return