@vintasoftware/pr-review-canvas 0.1.0

package/static/js/app.js

@@ -0,0 +1,418 @@
+// @ts-check
+// Boot: read the bootstrap JSON, fetch the bundle and the patches together, render the screen for
+// the bundle's status, and keep the page current: the empty screen polls until a canvas is
+// published, and the regenerate dialog polls until a newer canvas replaces the one on screen.
+/** @typedef {import('./contract-types.js').PrBundle} PrBundle */
+import {
+  ApiError,
+  fetchBundle,
+  fetchPatches,
+  fetchSharedCanvas,
+  importCanvas,
+  pollBundle,
+  saveAppearance,
+} from './api.js'
+import { setChatEnabled } from './ask.js'
+import { readChatWidth, renderChatShell, wireChat } from './chat.js'
+import { runCommand, wireCopyCommands } from './commands.js'
+import { initDeepLinks } from './deep-link.js'
+import { initDiagrams } from './diagram.js'
+import { esc, qs } from './dom.js'
+import { exportCanvasZip } from './download.js'
+import { renderEmptyState, renderStaleState, staleBarHtml } from './empty-state.js'
+import { errorCardHtml } from './errors.js'
+import { renderHeader } from './header.js'
+import { wireDropZone } from './import-zone.js'
+import { toast, wireReview } from './interactions.js'
+import { defineLayerElements, pathSet, renderLayers, renderRail, setRenderContext } from './layers.js'
+import { renderOverview } from './overview.js'
+import { wireQuickQuestions } from './quick-questions.js'
+import { canvasChanged, openRegenerateDialog } from './regenerate.js'
+import { createReviewSession } from './review-session.js'
+import { initScrollSpy } from './scroll-spy.js'
+import { openSettingsDialog } from './settings.js'
+import { applySkin, nextSkin, readSkin, skinLabel } from './skin.js'
+import { applyTheme, nextTheme, readTheme, themeLabel } from './theme.js'
+
+/** @typedef {{ prNumber: number, owner: string, repo: string, version: string }} Bootstrap */
+
+/** @returns {Bootstrap | null} */
+function readBootstrap() {
+  const el = document.getElementById('bootstrap')
+  if (!el?.textContent) {
+    return null
+  }
+  try {
+    return /** @type {Bootstrap} */ (JSON.parse(el.textContent))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * @param {string} version
+ * @param {PrBundle} [bundle]
+ */
+function footerHtml(version, bundle) {
+  const canvas = bundle?.canvas
+    ? `<span>canvas <span class="mono">${esc(bundle.canvas.headSha.slice(0, 7))}</span> · ${esc(bundle.canvas.source)}</span>`
+    : ''
+  return `<footer><span>pr-review ${esc(version)}</span>${canvas}<span>localhost only · nothing leaves this machine except GitHub posts you confirm</span></footer>`
+}
+
+/** @param {ReadonlyArray<string>} warnings */
+function bannerHtml(warnings) {
+  return warnings.length === 0 ? '' : `<div class="banner" role="status">${warnings.map(w => esc(w)).join(' · ')}</div>`
+}
+
+/**
+ * @param {unknown} err
+ * @returns {import('./contract-types.js').ErrorEnvelope['error']}
+ */
+function toEnvelopeError(err) {
+  if (!(err instanceof ApiError)) {
+    return { code: 'INTERNAL', message: String(err) }
+  }
+  return err.hint === undefined
+    ? { code: err.code, message: err.message }
+    : { code: err.code, message: err.message, hint: err.hint }
+}
+
+/**
+ * The patches for the bundle. The first visit builds derived/ while the bundle resolves, so the
+ * parallel fetch can land before the patches exist; one more try after the bundle is enough.
+ * @param {number} prNumber
+ * @param {Promise<Record<string, string> | null>} started
+ * @param {string} [headSha] the canvas commit, when it is not the PR head
+ */
+async function settlePatches(prNumber, started, headSha) {
+  const first = await started
+  if (first !== null) {
+    return first
+  }
+  const retry = headSha === undefined ? {} : { headSha }
+  return fetchPatches(prNumber, retry).then(
+    r => r.patches,
+    () => null
+  )
+}
+
+export class PrAppElement extends HTMLElement {
+  /** @type {{ stop: () => void } | null} */
+  poller = null
+  /** @type {Bootstrap | null} */
+  bootstrap = null
+  /** @type {import('./theme.js').Theme} */
+  theme = 'auto'
+  /** @type {import('./skin.js').Skin} */
+  skin = 'terminal'
+  /** @type {{ stop: () => void } | null} */
+  diagrams = null
+  /** @type {{ stop: () => void } | null} */
+  deepLinks = null
+  /** @type {{ stop: () => void } | null} */
+  scrollSpy = null
+  /** @type {{ stop: () => void } | null} */
+  interactions = null
+  /** @type {ReturnType<typeof wireChat>} */
+  chat = null
+  /** @type {{ stop: () => void } | null} */
+  quickQuestions = null
+  /** The reader asked to read the canvas of the older commit. */
+  viewStale = false
+
+  connectedCallback() {
+    // Once per element: the content is re-rendered on every flip, the element itself is not.
+    wireCopyCommands(this)
+    void this.boot()
+  }
+
+  disconnectedCallback() {
+    this.stopPolling()
+    this.diagrams?.stop()
+    this.diagrams = null
+    this.deepLinks?.stop()
+    this.deepLinks = null
+    this.scrollSpy?.stop()
+    this.scrollSpy = null
+    this.interactions?.stop()
+    this.interactions = null
+    this.stopChat()
+  }
+
+  stopChat() {
+    this.chat?.stop()
+    this.chat = null
+    this.quickQuestions?.stop()
+    this.quickQuestions = null
+  }
+
+  async boot() {
+    this.bootstrap = readBootstrap()
+    if (!this.bootstrap) {
+      this.innerHTML = errorCardHtml({ code: 'INTERNAL', message: 'missing bootstrap data' })
+      return
+    }
+    this.theme = readTheme(document.documentElement)
+    this.skin = readSkin(document.documentElement)
+    const patchesPromise = fetchPatches(this.bootstrap.prNumber).then(
+      r => r.patches,
+      () => null
+    )
+    /** @type {PrBundle} */
+    let bundle
+    try {
+      bundle = await fetchBundle(this.bootstrap.prNumber)
+    } catch (err) {
+      this.innerHTML = errorCardHtml(toEnvelopeError(err)) + footerHtml(this.bootstrap.version)
+      qs('#retry', this)?.addEventListener('click', () => void this.boot())
+      return
+    }
+    await this.render(bundle, patchesPromise)
+  }
+
+  /**
+   * @param {PrBundle} bundle
+   * @param {Promise<Record<string, string> | null>} [patchesPromise]
+   */
+  async render(bundle, patchesPromise) {
+    const boot = this.bootstrap
+    if (!boot) {
+      return
+    }
+    this.stopPolling()
+    this.diagrams?.stop()
+    this.diagrams = null
+    this.deepLinks?.stop()
+    this.deepLinks = null
+    this.scrollSpy?.stop()
+    this.scrollSpy = null
+    this.interactions?.stop()
+    this.interactions = null
+    this.stopChat()
+    const now = new Date()
+    const header = renderHeader(bundle, { host: location.host, theme: this.theme, skin: this.skin, now })
+    const chatEnabled = bundle.chat.enabled
+    const storage = typeof localStorage === 'undefined' ? null : localStorage
+    // The renderers read this while they build the cards, so it is set before the first one.
+    setChatEnabled(chatEnabled)
+    const showsCanvas = bundle.artifact !== undefined && (bundle.status === 'ready' || this.viewStale)
+    if (bundle.artifact && showsCanvas) {
+      const { artifact } = bundle
+      // A stale canvas describes its own commit, so its files and diffs come from that sha.
+      const staleSha = bundle.status === 'stale' ? bundle.stale?.canvasHeadSha : undefined
+      const files = staleSha === undefined ? bundle.files : artifact.files
+      const paths = pathSet(files)
+      const patches = await settlePatches(
+        boot.prNumber,
+        patchesPromise ??
+          fetchPatches(boot.prNumber, staleSha === undefined ? {} : { headSha: staleSha }).then(
+            r => r.patches,
+            () => null
+          ),
+        staleSha
+      )
+      // The context is set before any <pr-file> connects, so each card renders once, when visible.
+      setRenderContext({
+        artifact,
+        files,
+        patches,
+        comments: bundle.comments.reviewComments,
+        state: bundle.state,
+        now,
+      })
+      defineLayerElements()
+      const staleBar = bundle.status === 'stale' && bundle.stale ? staleBarHtml(bundle.stale) : ''
+      this.innerHTML =
+        header +
+        bannerHtml(bundle.warnings) +
+        `<div class="layout${chatEnabled ? '' : ' no-chat'}">${renderRail(artifact, bundle.state)}<main id="main">${staleBar}${renderOverview(bundle, { paths, now })}${renderLayers(artifact, files, bundle.state, bundle.comments.reviewComments)}</main>${renderChatShell({ enabled: chatEnabled, width: readChatWidth(storage) })}</div>` +
+        footerHtml(boot.version, bundle)
+      // The screen is interactive from here: reviewed state, dismissals, threads, and posting.
+      // A stale canvas shows the diff of an older commit, so nothing is posted from it: a line
+      // number of that commit means something else on the head a comment would land on.
+      const capabilities =
+        bundle.status === 'stale'
+          ? {
+              canComment: /** @type {const} */ (false),
+              tokenKind: bundle.capabilities.tokenKind,
+              login: bundle.capabilities.login,
+              reason: 'this canvas is for an older commit; generate one for the current head to post',
+            }
+          : bundle.capabilities
+      const session = createReviewSession({
+        prNumber: boot.prNumber,
+        artifact,
+        files,
+        state: bundle.state,
+        capabilities,
+        headSha: bundle.pr.headSha,
+      })
+      const interactions = wireReview(this, session, {
+        chat: () => this.chat,
+        openSettings: el => void openSettingsDialog(this, el),
+      })
+      this.interactions = interactions
+      if (chatEnabled) {
+        this.chat = wireChat({
+          root: this,
+          prNumber: boot.prNumber,
+          session,
+          onProposed: (what, comment, el) => interactions.onProposedComment(what, comment, el),
+        })
+        this.quickQuestions = wireQuickQuestions(this, {
+          onPick: (context, question) => {
+            if (question === null) {
+              this.chat?.ask(context)
+            } else {
+              this.chat?.askQuestion(context, question)
+            }
+          },
+        })
+      }
+      if (bundle.status === 'stale') {
+        this.startPolling(next => next.status === 'ready')
+      }
+    } else {
+      const screen = bundle.status === 'stale' ? renderStaleState(bundle) : renderEmptyState(bundle)
+      this.innerHTML =
+        header +
+        bannerHtml(bundle.warnings) +
+        `<div class="layout no-chat"><nav class="rail" aria-label="Review layers"><ul class="tree"><li><a href="#empty-state" aria-current="location"><span class="t">Overview</span><span class="m">no canvas yet</span></a></li></ul></nav><main id="main">${screen}</main></div>` +
+        footerHtml(boot.version, bundle)
+      // A canvas published from the harness shows up here without a reload.
+      this.startPolling(next => next.status === 'ready')
+    }
+    // Mermaid is fetched only when this screen holds a diagram, and again on a theme flip.
+    this.diagrams = initDiagrams(this)
+    // The cards are in the page now, so a link in the URL has something to land on.
+    this.deepLinks = initDeepLinks(this)
+    this.scrollSpy = initScrollSpy(this)
+    this.wireCommands(bundle)
+  }
+
+  /**
+   * Writes the skin or the theme to `.pr-review/settings.yml`.
+   * @param {import('./contract-types.js').AppearanceInput} input
+   * @param {string} what the word the failure message names
+   */
+  save(input, what) {
+    void saveAppearance(input).catch(() => toast(this, `could not save the ${what} to settings.yml`))
+  }
+
+  /** @param {PrBundle} bundle */
+  wireCommands(bundle) {
+    // The review screen routes this through the delegated handler; the empty and stale screens
+    // have no such handler, so the command is wired here for every screen.
+    const settings = qs('#settings', this)
+    if (settings instanceof HTMLElement && this.interactions === null) {
+      settings.addEventListener('click', () => void openSettingsDialog(this, settings))
+    }
+    // Both repaint the page under the click; the settings file catches up after the round trip,
+    // and each says so when it cannot, because the next load would come back in the old one.
+    const toggle = qs('#theme-toggle', this)
+    toggle?.addEventListener('click', () => {
+      this.theme = nextTheme(this.theme)
+      applyTheme(this.theme, document.documentElement)
+      toggle.textContent = themeLabel(this.theme)
+      this.save({ theme: this.theme }, 'theme')
+    })
+    const skinToggle = qs('#skin-toggle', this)
+    skinToggle?.addEventListener('click', () => {
+      this.skin = nextSkin(this.skin)
+      applySkin(this.skin, document.documentElement)
+      skinToggle.textContent = skinLabel(this.skin)
+      this.save({ skin: this.skin }, 'skin')
+    })
+    const openDialog = () => {
+      openRegenerateDialog(this, bundle.skillCommand)
+      this.startPolling(next => canvasChanged(bundle, next))
+    }
+    qs('#regenerate', this)?.addEventListener('click', openDialog)
+    qs('#stale-generate', this)?.addEventListener('click', openDialog)
+    const boot = this.bootstrap
+    if (!boot) {
+      return
+    }
+    const exportZip = qs('#export-zip', this)
+    if (exportZip instanceof HTMLElement) {
+      exportZip.addEventListener('click', () => {
+        // The canvas on screen is the one to export, which is the older one on the stale screen.
+        const headSha = bundle.canvas?.headSha
+        void runCommand(exportZip, () => exportCanvasZip(boot.prNumber, headSha ? { headSha } : {}), {
+          pendingLabel: 'exporting…',
+        })
+      })
+    }
+    const fetchShared = qs('#fetch-shared', this)
+    if (fetchShared instanceof HTMLElement) {
+      fetchShared.addEventListener('click', () => {
+        void runCommand(
+          fetchShared,
+          async () => {
+            // Imported or not, the answer changes the callout, so the screen is drawn again.
+            await fetchSharedCanvas(boot.prNumber)
+            await this.reload()
+          },
+          { pendingLabel: 'fetching…' }
+        )
+      })
+    }
+    const refresh = qs('#refresh', this)
+    if (refresh instanceof HTMLElement) {
+      refresh.addEventListener('click', () => {
+        void runCommand(refresh, () => this.reload({ refresh: true }), { pendingLabel: 'refreshing…' })
+      })
+    }
+    const viewStale = qs('#view-stale', this)
+    viewStale?.addEventListener('click', () => {
+      this.viewStale = true
+      void this.render(bundle)
+    })
+    wireDropZone(this, { prNumber: boot.prNumber, importImpl: importCanvas, onImported: () => void this.reload() })
+  }
+
+  /**
+   * Re-reads the bundle and re-renders, after an import changed what the server holds. With
+   * `refresh` the server asks GitHub again instead of answering from its caches.
+   * @param {{ refresh?: boolean }} [opts]
+   */
+  async reload(opts = {}) {
+    const boot = this.bootstrap
+    if (!boot) {
+      return
+    }
+    const next = await fetchBundle(boot.prNumber, opts.refresh === true ? { refresh: true } : {})
+    await this.render(next)
+  }
+
+  /**
+   * One poller at a time. When `until` holds, the new bundle replaces the screen.
+   * @param {(bundle: PrBundle) => boolean} until
+   */
+  startPolling(until) {
+    const boot = this.bootstrap
+    if (!boot) {
+      return
+    }
+    this.stopPolling()
+    this.poller = pollBundle(boot.prNumber, {
+      until,
+      onBundle: next => {
+        if (until(next)) {
+          this.poller = null
+          void this.render(next)
+        }
+      },
+    })
+  }
+
+  stopPolling() {
+    this.poller?.stop()
+    this.poller = null
+  }
+}
+
+if (!customElements.get('pr-app')) {
+  customElements.define('pr-app', PrAppElement)
+}

package/static/js/ask.js

@@ -0,0 +1,35 @@
+// @ts-check
+// The `[ ask ]` command that sets the AI Chat context. One builder, so a layer card, a file
+// card, an attention point, and the selection toolbar all carry the same attributes and the
+// quick-question menu finds them all.
+import { chatContextAttrs } from './chat-context.js'
+import { esc } from './dom.js'
+
+/**
+ * Whether the AI Chat pane is on for this screen. The renderers read it rather than threading a
+ * flag through every card; `app.js` sets it once per render.
+ */
+let chatEnabled = false
+
+/** @param {boolean} on */
+export function setChatEnabled(on) {
+  chatEnabled = on
+}
+
+export function isChatEnabled() {
+  return chatEnabled
+}
+
+/**
+ * The command, or nothing at all when the pane is off: a page without a chat shows no way to ask.
+ * @param {import('./chat-context.js').ChatContext} context
+ * @param {{ label?: string, enabled?: boolean }} [opts]
+ * @returns {string}
+ */
+export function askButtonHtml(context, opts = {}) {
+  if (!(opts.enabled ?? chatEnabled)) {
+    return ''
+  }
+  const label = opts.label ?? 'ask'
+  return `<button class="cmd" type="button" data-act="ask" data-ask${chatContextAttrs(context)}>${esc(label)}</button>`
+}

package/static/js/chat-context.js

@@ -0,0 +1,137 @@
+// @ts-check
+// The one thing a chat message is about. One value per message, set-not-toggle: asking about the
+// same target again leaves the context as it is. Both sides use this file: the browser through a
+// module import, the server through src/contract/chat.ts.
+
+/**
+ * @typedef {{ kind: 'pr' }
+ *   | { kind: 'layer', layerId: string }
+ *   | { kind: 'file', path: string }
+ *   | { kind: 'lines', path: string, side: 'new' | 'old', start: number, end: number }
+ *   | { kind: 'point', fingerprint: string }} ChatContext
+ */
+
+/** @type {ChatContext} */
+export const WHOLE_PR = { kind: 'pr' }
+
+/**
+ * True when two contexts name the same target, so setting the second one changes nothing.
+ * @param {ChatContext} a
+ * @param {ChatContext} b
+ */
+export function sameChatContext(a, b) {
+  if (a.kind !== b.kind) {
+    return false
+  }
+  if (a.kind === 'pr') {
+    return true
+  }
+  if (a.kind === 'layer' && b.kind === 'layer') {
+    return a.layerId === b.layerId
+  }
+  if (a.kind === 'file' && b.kind === 'file') {
+    return a.path === b.path
+  }
+  if (a.kind === 'lines' && b.kind === 'lines') {
+    return a.path === b.path && a.side === b.side && a.start === b.start && a.end === b.end
+  }
+  if (a.kind === 'point' && b.kind === 'point') {
+    return a.fingerprint === b.fingerprint
+  }
+  return false
+}
+
+/**
+ * What the chip says. The label names the target exactly, so a reader always knows what the next
+ * message is about.
+ * @param {ChatContext} context
+ * @param {(layerId: string) => string | undefined} [layerTitle]
+ * @param {(fingerprint: string) => string | undefined} [pointTitle]
+ * @returns {string}
+ */
+export function chatContextLabel(context, layerTitle, pointTitle) {
+  switch (context.kind) {
+    case 'pr':
+      return 'whole PR'
+    case 'layer': {
+      const title = layerTitle?.(context.layerId)
+      return title === undefined ? `layer ${context.layerId}` : `layer · ${title}`
+    }
+    case 'file':
+      return context.path
+    case 'lines': {
+      const side = context.side === 'old' ? ' (old side)' : ''
+      return context.start === context.end
+        ? `${context.path} line ${context.start}${side}`
+        : `${context.path} lines ${context.start}–${context.end}${side}`
+    }
+    case 'point': {
+      const title = pointTitle?.(context.fingerprint)
+      return title === undefined ? 'attention point' : `point · ${title}`
+    }
+  }
+}
+
+/**
+ * The context a `[ ask ]` element names, read from its data attributes. Returns the whole-PR
+ * context for an element that names nothing.
+ * @param {Element} el
+ * @returns {ChatContext}
+ */
+export function chatContextFromElement(el) {
+  const fingerprint = el.getAttribute('data-ask-point')
+  if (fingerprint !== null && fingerprint !== '') {
+    return { kind: 'point', fingerprint }
+  }
+  const layerId = el.getAttribute('data-ask-layer')
+  if (layerId !== null && layerId !== '') {
+    return { kind: 'layer', layerId }
+  }
+  const path = el.getAttribute('data-ask-path')
+  if (path === null || path === '') {
+    return WHOLE_PR
+  }
+  const start = Number(el.getAttribute('data-ask-start'))
+  const end = Number(el.getAttribute('data-ask-end'))
+  if (!Number.isInteger(start) || start <= 0 || !Number.isInteger(end) || end < start) {
+    return { kind: 'file', path }
+  }
+  return { kind: 'lines', path, side: el.getAttribute('data-ask-side') === 'old' ? 'old' : 'new', start, end }
+}
+
+/**
+ * The data attributes an `[ ask ]` element carries, ready to put in a template string.
+ * @param {ChatContext} context
+ * @returns {string}
+ */
+export function chatContextAttrs(context) {
+  switch (context.kind) {
+    case 'pr':
+      return ''
+    case 'layer':
+      return ` data-ask-layer="${escapeAttr(context.layerId)}"`
+    case 'file':
+      return ` data-ask-path="${escapeAttr(context.path)}"`
+    case 'lines':
+      return (
+        ` data-ask-path="${escapeAttr(context.path)}" data-ask-side="${context.side}"` +
+        ` data-ask-start="${context.start}" data-ask-end="${context.end}"`
+      )
+    case 'point':
+      return ` data-ask-point="${escapeAttr(context.fingerprint)}"`
+  }
+}
+
+/**
+ * Attribute-safe text. `dom.js` is the browser-only escaper; this file also runs on the server,
+ * so it escapes the five characters an attribute value can break on itself.
+ * @param {string} value
+ */
+function escapeAttr(value) {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}