@vintasoftware/pr-review-canvas 0.4.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

@@ -4,8 +4,10 @@
 import { setDisabledReason } from './composer.js'
 import { esc, timeAgo } from './dom.js'
 import { authorProfileUrl, currentHost, hostLabel } from './host.js'
-import { refreshRail } from './layers.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'
@@ -84,7 +86,23 @@ export function renderHeader(bundle, opts) {
   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) : ''
+  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">' +
@@ -93,7 +111,7 @@ export function renderHeader(bundle, opts) {
     `<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"${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="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>` +
@@ -104,27 +122,36 @@ export function renderHeader(bundle, opts) {
     `<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 ${esc(hostLabel())}" data-act="signoff" data-event="APPROVE" data-needs-post` +
-    `${blocked === null ? ` title="Write and preview an approving review on ${esc(hostLabel())}"` : ` disabled data-disabled-reason="${esc(blocked)}" title="${esc(blocked)}"`}>approve on ${esc(currentHost().kind)}</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 ${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>'
   )
 }