@ok-ggwp/git-gloss 0.0.0-stage → 0.1.0

package/dist/git.js

@@ -0,0 +1,315 @@
+import { execFileSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdtempSync, rmSync, statSync, utimesSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Annotation, NOTE_FORMAT } from './schema.js';
+import { parsePath, unquote } from './diff.js';
+export const NOTES_REF = 'refs/notes/gloss';
+// Glosses of uncommitted work (wip snapshots) live in their own notes ref,
+// which sync never pushes, and the latest snapshot in a private ref that
+// keeps it from being garbage-collected. refs/worktree/ refs are per
+// worktree, so each linked worktree has its own snapshot.
+export const WIP_NOTES_REF = 'refs/notes/gloss-wip';
+export const WIP_REF = 'refs/worktree/gloss/wip';
+const WIP_MESSAGE = 'git-gloss wip snapshot';
+export const REMOTE_NOTES_REF = 'refs/notes/remotes/origin/gloss';
+export const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+// Errors whose message is fit to show the user without a stack trace.
+export class GlossError extends Error {
+}
+export class GitError extends GlossError {
+}
+export function git(args, input, env = {}) {
+    try {
+        return execFileSync('git', args, {
+            encoding: 'utf8',
+            input,
+            // Untranslated messages: readNote recognises "no note found" by its text.
+            env: { ...process.env, ...env, LC_ALL: 'C' },
+            maxBuffer: 256 * 1024 * 1024,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        const stderr = err.stderr?.trim();
+        throw new GitError(stderr || `git ${args.join(' ')} failed`);
+    }
+}
+export function gitTry(args, input) {
+    try {
+        return git(args, input);
+    }
+    catch {
+        return null;
+    }
+}
+// Untracked files that look like secrets. A snapshot is shown and sent to
+// reviewers, so these are left out unless the user stages them.
+const SENSITIVE = [
+    /^\.env(\..*)?$/, /\.(pem|key|p12|pfx|jks|keystore|kdbx)$/, /^id_(rsa|dsa|ecdsa|ed25519)$/,
+    /(^|[-_.])(secrets?|credentials?|tokens?|passwords?)([-_.]|$)/i, /^\.(netrc|npmrc|pypirc)$/,
+];
+const looksSensitive = (path) => SENSITIVE.some((re) => re.test(path.split('/').pop()));
+// The working tree as a tree object: tracked files, staged files, and
+// untracked files except ignored ones and ones that look like secrets. Built
+// in a temporary index so the real index is untouched. `excluded` lists the
+// untracked files left out as possible secrets.
+function workingTree() {
+    const dir = mkdtempSync(join(tmpdir(), 'git-gloss-index-'));
+    try {
+        const index = join(dir, 'index');
+        const real = git(['rev-parse', '--path-format=absolute', '--git-path', 'index']).trim();
+        if (existsSync(real)) {
+            copyFileSync(real, index);
+            // Keep the index's timestamps: git compares them with file mtimes to
+            // spot files edited in the same second as the index was written
+            // ("racily clean"), and a fresh mtime would hide such edits.
+            const { atime, mtime } = statSync(real);
+            utimesSync(index, atime, mtime);
+        }
+        const env = { GIT_INDEX_FILE: index };
+        const untracked = git(['ls-files', '--others', '--exclude-standard', '-z', '--', ':/']).split('\0').filter(Boolean);
+        const excluded = untracked.filter(looksSensitive);
+        git(['add', '-A', '--', ':/'], undefined, env);
+        if (excluded.length)
+            git(['rm', '-q', '--cached', '--', ...excluded.map((p) => `:/${p}`)], undefined, env);
+        return { tree: git(['write-tree'], undefined, env).trim(), excluded };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+const headSha = () => gitTry(['rev-parse', '--verify', '--quiet', 'HEAD'])?.trim() ?? null;
+const treeAndParent = (sha) => {
+    const [tree, parent] = git(['log', '-1', '--format=%T %P', sha]).trim().split(' ');
+    return { tree, parent: parent || null };
+};
+// Record uncommitted changes as a commit on top of HEAD without touching the
+// branch, index or files, and point WIP_REF at it. Reuses the current
+// snapshot if nothing has changed, so its gloss stays attached.
+// `replaced` is the previous snapshot when this one replaces it, so the
+// caller can carry its gloss over.
+export function snapshotWorkingTree() {
+    const { tree, excluded } = workingTree();
+    const head = headSha();
+    if (head && git(['rev-parse', `${head}^{tree}`]).trim() === tree) {
+        throw new GlossError('there are no uncommitted changes to snapshot');
+    }
+    const current = gitTry(['rev-parse', '--verify', '--quiet', WIP_REF])?.trim();
+    if (current) {
+        const c = treeAndParent(current);
+        if (c.tree === tree && c.parent === head)
+            return { sha: current, excluded, replaced: null };
+    }
+    const sha = git(['commit-tree', tree, ...(head ? ['-p', head] : []), '-m', WIP_MESSAGE], undefined, commitIdentity()).trim();
+    if (current)
+        archiveSnapshot(current);
+    git(['update-ref', WIP_REF, sha]);
+    return { sha, excluded, replaced: current ?? null };
+}
+// Snapshots and archive entries are commit objects, which need an identity;
+// fall back to a placeholder where git has none configured rather than fail.
+function commitIdentity() {
+    const ident = (v) => gitTry(['var', v]) !== null;
+    const env = {};
+    if (!ident('GIT_AUTHOR_IDENT'))
+        Object.assign(env, { GIT_AUTHOR_NAME: 'git-gloss', GIT_AUTHOR_EMAIL: 'git-gloss@localhost' });
+    if (!ident('GIT_COMMITTER_IDENT'))
+        Object.assign(env, { GIT_COMMITTER_NAME: 'git-gloss', GIT_COMMITTER_EMAIL: 'git-gloss@localhost' });
+    return env;
+}
+// A glossed snapshot that is being replaced or cleared stays reachable from
+// this ref, so git gc keeps it: its old gloss, which the notes history keeps,
+// still has the changes it describes (`versions wip` reads and restores them).
+// Each entry is an empty commit whose parents are the previous entry and the
+// snapshot. Per worktree, like WIP_REF.
+export const ARCHIVE_REF = 'refs/worktree/gloss/archive';
+export function archiveSnapshot(sha) {
+    if (rawNote(WIP_NOTES_REF, sha) === null)
+        return;
+    const prev = gitTry(['rev-parse', '-q', '--verify', ARCHIVE_REF])?.trim();
+    const entry = git(['commit-tree', EMPTY_TREE, ...(prev ? ['-p', prev] : []), '-p', sha, '-m', 'git-gloss: earlier glossed wip snapshot'], undefined, commitIdentity()).trim();
+    git(['update-ref', ARCHIVE_REF, entry]);
+}
+export const dropWipNote = (sha) => gitTry(['notes', '--ref', WIP_NOTES_REF, 'remove', '--ignore-missing', sha]);
+export const isWipSnapshot = (sha) => gitTry(['log', '-1', '--format=%s', sha])?.trim() === WIP_MESSAGE;
+// Why the latest snapshot no longer matches the working tree, or null.
+export function wipStaleness(sha) {
+    const s = treeAndParent(sha);
+    if (s.parent !== headSha())
+        return 'HEAD has moved since this snapshot was taken';
+    if (workingTree().tree !== s.tree)
+        return 'the working tree has changed since this snapshot was taken';
+    return null;
+}
+export function resolveCommit(rev) {
+    // "wip": the latest snapshot of uncommitted work (made by `hunks wip`). A
+    // branch or tag named wip still works when there is no snapshot, and can be
+    // reached as heads/wip or tags/wip when there is.
+    const named = gitTry(['rev-parse', '--verify', '--quiet', `${rev}^{commit}`])?.trim();
+    if (rev === 'wip') {
+        const sha = gitTry(['rev-parse', '--verify', '--quiet', WIP_REF])?.trim();
+        if (sha) {
+            if (named)
+                console.error('note: "wip" means the snapshot of uncommitted work; for the branch or tag, use heads/wip or tags/wip');
+            const stale = wipStaleness(sha);
+            if (stale)
+                console.error(`warning: ${stale}; run \`git gloss hunks wip\` to snapshot again, then re-gloss`);
+            return sha;
+        }
+        if (!named)
+            throw new GlossError('no snapshot of uncommitted work yet; run `git gloss hunks wip` first');
+    }
+    const sha = named;
+    if (!sha)
+        throw new GitError(`not a commit: ${rev}`);
+    return sha.trim();
+}
+// A commit, or the commits in a range such as "main..feature", oldest first.
+// Merges are not reviewed (their first-parent diff repeats the merged
+// commits) but are returned so views can say they were skipped: a merge can
+// still carry conflict resolutions or edits of its own.
+export function resolveCommits(arg) {
+    if (!arg.includes('..'))
+        return { shas: [resolveCommit(arg)], merges: [], range: null };
+    if (arg.includes('...')) {
+        throw new GitError(`${arg}: "..." includes commits from both sides; use A..B for the commits on B since A`);
+    }
+    // --end-of-options: the argument is a revision range, never an option.
+    const list = (...flags) => git(['rev-list', '--reverse', ...flags, '--end-of-options', arg, '--']).split('\n').filter(Boolean);
+    const shas = list('--no-merges');
+    const merges = list('--merges');
+    if (!shas.length && !merges.length)
+        throw new GitError(`no commits in ${arg}`);
+    return { shas, merges, range: arg };
+}
+export function commitSubject(sha) {
+    return git(['log', '-1', '--format=%s', sha]).trim();
+}
+// Diff of a commit against its first parent (or the empty tree for a root
+// commit). Every option that changes which hunks git produces, or their order,
+// is pinned so hunk ids are the same regardless of the user's diff config.
+export function commitDiff(sha) {
+    return diffBetween(gitTry(['rev-parse', '--verify', '--quiet', `${sha}^1`])?.trim() || EMPTY_TREE, sha);
+}
+// The diff between two commits (or trees), with the same pinned options.
+export function diffBetween(from, to) {
+    return git([
+        '-c', 'core.quotePath=false', '-c', 'diff.suppressBlankEmpty=false',
+        'diff', '--no-color', '--no-ext-diff', '--no-textconv', '--find-renames',
+        '--src-prefix=a/', '--dst-prefix=b/', '-U3',
+        '-O/dev/null', '--diff-algorithm=myers', '--indent-heuristic',
+        '--inter-hunk-context=0', '--no-relative', '--submodule=short', '-l1000',
+        from, to,
+    ]);
+}
+function rawNote(ref, sha) {
+    try {
+        return git(['notes', '--ref', ref, 'show', sha]);
+    }
+    catch (err) {
+        if (/no note found/i.test(err.message))
+            return null;
+        throw err;
+    }
+}
+export function readNote(sha) {
+    // A commit's gloss, or a wip snapshot's (they are never the same object).
+    const raw = rawNote(NOTES_REF, sha) ?? rawNote(WIP_NOTES_REF, sha);
+    if (raw === null)
+        return null;
+    const at = `the gloss on ${sha.slice(0, 10)}`;
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        // notes.rewriteMode=concatenate joins two notes when a rebase squashes
+        // glossed commits together.
+        if (/}\s*\n\s*{/.test(raw)) {
+            throw new GlossError(`${at} holds several glosses joined together (from a squash or fixup); re-gloss it with \`git gloss add --force\``);
+        }
+        throw new GlossError(`${at} is not valid JSON; replace it with \`git gloss add --force\``);
+    }
+    if (typeof data?.gloss === 'number' && data.gloss > NOTE_FORMAT) {
+        throw new GlossError(`${at} was written by a newer git-gloss (format ${data.gloss}); upgrade to read it`);
+    }
+    const annotation = Annotation.safeParse(data?.annotation);
+    if (![1, 2, 3].includes(data?.gloss) || !Array.isArray(data.hunks) || !annotation.success) {
+        throw new GlossError(`${at} is malformed; replace it with \`git gloss add --force\``);
+    }
+    return { ...data, annotation: annotation.data };
+}
+export function writeNote(sha, note, ref = NOTES_REF) {
+    git(['notes', '--ref', ref, 'add', '-f', '-F', '-', sha], JSON.stringify(note, null, 2) + '\n');
+}
+// The commits that changed lines start..end of `file`, newest first, starting
+// from `commit`, following them through edits, moves within the file and
+// renames. Each step gives the file's path in that commit and the lines' new
+// numbers in its diff. `max` stops after that many commits (to check whether
+// any older history exists without walking it). Uses git log -L, so it is
+// approximate when lines are heavily rewritten. Null if git can't trace them.
+export function lineHistory(file, start, end, commit, max) {
+    const out = gitTry([
+        // showSignature would print signature checks between the commits.
+        '-c', 'core.quotePath=false', '-c', 'log.showSignature=false', 'log', '--no-color', '--no-ext-diff',
+        '--src-prefix=a/', '--dst-prefix=b/', `-L${start},${end}:${file}`, '--format=%x00%H',
+        ...(max ? [`--max-count=${max}`] : []), commit,
+    ]);
+    if (out === null)
+        return null;
+    return out.split('\0').filter((chunk) => chunk.trim()).map((chunk) => {
+        const [first, ...rest] = chunk.split('\n');
+        let path = file, newNo = 0, inHunk = false;
+        const lines = [];
+        for (const l of rest) {
+            if (l.startsWith('diff --git ')) {
+                inHunk = false;
+                continue;
+            }
+            // Inside a hunk, decide by position, not prefix: an added line whose
+            // text starts with "++ " would otherwise look like a "+++" header.
+            if (!inHunk && l.startsWith('+++ ')) {
+                path = parsePath(l.slice(4)) ?? path;
+                continue;
+            }
+            const h = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(l);
+            if (h) {
+                newNo = Number(h[1]);
+                inHunk = true;
+                continue;
+            }
+            if (!inHunk)
+                continue;
+            if (l.startsWith('+'))
+                lines.push(newNo++);
+            else if (l.startsWith(' '))
+                newNo++;
+        }
+        return { commit: first.trim(), file: path, lines };
+    });
+}
+// Blame lines start..end in one call (one record per line).
+export function blameRange(file, start, end, rev) {
+    const args = ['blame', '--line-porcelain', '-L', `${start},${end}`];
+    if (rev)
+        args.push(rev);
+    args.push('--', file);
+    const out = [];
+    let cur = null;
+    for (const l of git(args).split('\n')) {
+        // 40 hex digits for SHA-1 repositories, 64 for SHA-256.
+        const head = /^([0-9a-f]{40}(?:[0-9a-f]{24})?) (\d+) (\d+)/.exec(l);
+        if (head) {
+            cur = { commit: head[1], origLine: Number(head[2]), line: Number(head[3]), origFile: file };
+            out.push(cur);
+            continue;
+        }
+        // Porcelain C-quotes unusual file names, like diff headers do.
+        if (cur && l.startsWith('filename ')) {
+            const raw = l.slice(9);
+            cur.origFile = raw.startsWith('"') ? unquote(raw) : raw;
+        }
+    }
+    return out;
+}

package/dist/html/client.js

@@ -0,0 +1,354 @@
+// Renders the gloss page from the embedded JSON. All text goes through
+// textContent; nothing from the data is ever parsed as HTML.
+(function () {
+  'use strict'
+  var data = JSON.parse(document.getElementById('gloss-data').textContent)
+  var app = document.getElementById('app')
+  var hidden = new Set() // necessity values filtered out
+  var multi = data.commits.length > 1 || data.range !== null
+  // Group ids are unique within a commit, not across a range, so a range page
+  // keys cards by commit too: #g-<sha7>-<group>.
+  function key(c, id) { return multi ? c.sha.slice(0, 7) + '-' + id : id }
+
+  function el(tag, cls, text) {
+    var e = document.createElement(tag)
+    if (cls) e.className = cls
+    if (text !== undefined && text !== null) e.textContent = String(text)
+    return e
+  }
+  function add(parent) {
+    for (var i = 1; i < arguments.length; i++) if (arguments[i]) parent.appendChild(arguments[i])
+    return parent
+  }
+  function color(e, necessity) {
+    e.style.setProperty('--c', 'var(--n-' + necessity + ')')
+    return e
+  }
+  function plural(n, word) { return n + ' ' + word + (n === 1 ? '' : 's') }
+  function stats(added, removed) {
+    return add(el('span', 'stats'), el('span', 'plus', '+' + added), document.createTextNode(' '), el('span', 'minus', '−' + removed))
+  }
+  function groupLink(c, id) {
+    var a = el('a', null, id)
+    a.href = '#g-' + key(c, id)
+    a.addEventListener('click', function (ev) { ev.preventDefault(); focusGroup(key(c, id), true) })
+    return a
+  }
+
+  // ---- diff rendering ----
+  function hunkView(c, h) {
+    var head = add(el('div', 'hunk-head'),
+      el('span', 'range', h.ref),
+      el('span', 'file', h.oldFile ? h.oldFile + ' → ' + h.file : h.file),
+      el('span', 'range', h.range),
+      stats(h.added, h.removed))
+    if (h.status === 'changed') add(head, el('span', 'stale', 'changed since glossed'))
+    if (h.status === 'missing') {
+      add(head, el('span', 'stale', 'no longer in this commit'))
+      return add(el('div', 'hunk'), head)
+    }
+    if (h.alsoIn.length) {
+      var also = add(el('span', 'also'), document.createTextNode('shares lines with '))
+      h.alsoIn.forEach(function (id, i) { if (i) also.appendChild(document.createTextNode(', ')); also.appendChild(groupLink(c, id)) })
+      add(head, also)
+    }
+    var table = el('table', 'diff')
+    h.lines.forEach(function (l) {
+      var tr = el('tr', l.kind)
+      if (l.kind === 'meta' || l.kind === 'gap') {
+        var td = el('td', 'text', l.text)
+        td.colSpan = 4
+        add(tr, td)
+      } else {
+        add(tr,
+          el('td', 'ln', l.old === null ? '' : l.old),
+          el('td', 'ln', l.new === null ? '' : l.new),
+          el('td', 'mark', l.kind === 'add' ? '+' : l.kind === 'del' ? '−' : ' '),
+          el('td', 'text', l.text))
+      }
+      table.appendChild(tr)
+    })
+    return add(el('div', 'hunk'), head, add(el('div', 'scroll'), table))
+  }
+
+  // ---- group cards ----
+  var cards = []
+  function groupCard(c, g) {
+    var card = color(el('article', 'group'), g.necessity)
+    card.id = 'g-' + key(c, g.id)
+    card.tabIndex = -1
+    card.dataset.necessity = g.necessity
+
+    var title = add(el('div', 'group-title'),
+      el('span', 'badge', g.necessity),
+      el('span', 'intent', g.intent),
+      el('span', 'gid', g.id))
+    if (g.stale) add(title, el('span', 'stale', g.stale + ' of ' + plural(g.total, 'hunk') + ' changed or gone'))
+    add(title, stats(g.added, g.removed))
+
+    var facts = el('dl', 'facts')
+    function fact(label, value) {
+      if (!value) return
+      add(facts, el('dt', null, label), typeof value === 'string' ? el('dd', null, value) : add(el('dd'), value))
+    }
+    if (g.serves[0] !== 'task') {
+      var links = el('span')
+      g.serves.forEach(function (id, i) { if (i) links.appendChild(document.createTextNode(', ')); links.appendChild(groupLink(c, id)) })
+      fact('serves', links)
+    }
+    fact('if removed', g.removal_impact)
+    fact('evidence', g.evidence)
+    fact('notes', g.notes)
+
+    add(card, add(el('div', 'group-head'), title), facts)
+
+    if (g.hunks.length) {
+      var code = el('div', 'code')
+      code.hidden = true
+      var toggle = el('button', 'code-toggle')
+      toggle.type = 'button'
+      var rendered = false
+      function setOpen(open) {
+        if (open && !rendered) { g.hunks.forEach(function (h) { code.appendChild(hunkView(c, h)) }); rendered = true }
+        code.hidden = !open
+        toggle.textContent = (open ? '▾ Hide code' : '▸ Show code') + ' · ' + plural(g.hunks.length, 'hunk')
+        toggle.setAttribute('aria-expanded', String(open))
+      }
+      toggle.addEventListener('click', function () { setOpen(code.hidden) })
+      setOpen(false)
+      card.setOpen = setOpen
+      card.isOpen = function () { return !code.hidden }
+      add(card, toggle, code)
+    }
+    cards.push(card)
+    return card
+  }
+
+  // ---- page ----
+  function statement(parent, label, text) {
+    if (text) add(parent, add(el('p', 'statement'), el('span', 'label', label), document.createTextNode(text)))
+  }
+  function commitMeta(c) {
+    return add(el('div', 'commit'), el('span', 'sha', c.sha.slice(0, 10)),
+      el('span', null, c.author), el('span', null, new Date(c.date).toLocaleString()))
+  }
+
+  // One commit's groups, unannotated changes, risks and alternatives, with its
+  // entries in the sidebar.
+  function commitBody(c, main) {
+    var tocList = el('ol')
+    var groupsEl = el('section', 'groups')
+    c.groups.forEach(function (g) {
+      groupsEl.appendChild(groupCard(c, g))
+      var li = el('li')
+      li.dataset.necessity = g.necessity
+      li.dataset.key = key(c, g.id)
+      var a = add(el('a'), color(el('span', 'dot'), g.necessity), el('span', null, g.id))
+      a.href = '#g-' + key(c, g.id)
+      a.title = g.intent
+      a.addEventListener('click', function (ev) { ev.preventDefault(); focusGroup(key(c, g.id), false) })
+      tocList.appendChild(add(li, a))
+    })
+    add(main, groupsEl)
+
+    var h = multi ? 'h3' : 'h2'
+    if (c.unannotated.length) {
+      var unId = 'unannotated' + (multi ? '-' + c.sha.slice(0, 7) : '')
+      var un = add(el('section', 'section'), el(h, null, (c.glossed ? 'Unannotated changes' : 'Changes') + ' (' + c.unannotated.length + ')'))
+      var box = add(el('div', 'unannotated'), el('p', null, c.glossed
+        ? 'These changes are in the commit but no group explains them.'
+        : 'This commit has no gloss, so nothing explains these changes.'))
+      c.unannotated.forEach(function (hk) { box.appendChild(hunkView(c, hk)) })
+      un.id = unId
+      add(main, add(un, box))
+      var ua = add(el('a'), el('span', null, c.glossed ? 'unannotated' : 'unglossed diff'))
+      ua.href = '#' + unId
+      tocList.appendChild(add(el('li'), ua))
+    }
+    if (c.risks.length) {
+      var rl = el('ul', 'list')
+      c.risks.forEach(function (r) { rl.appendChild(el('li', null, r)) })
+      add(main, add(el('section', 'section'), el(h, null, 'Risks'), rl))
+    }
+    if (c.alternatives.length) {
+      var al = el('ul', 'list')
+      c.alternatives.forEach(function (x) {
+        al.appendChild(add(el('li'), el('strong', null, x.option), el('span', 'why', ' — ' + x.rejected_because)))
+      })
+      add(main, add(el('section', 'section'), el(h, null, 'Alternatives considered'), al))
+    }
+    return tocList
+  }
+
+  function render() {
+    var layout = el('div', 'layout')
+    var toc = el('nav', 'toc')
+    var main = el('main')
+    add(layout, toc, main)
+    var allGroups = []
+    data.commits.forEach(function (c) { allGroups = allGroups.concat(c.groups) })
+
+    // Header: the commit itself, or the range and its commits.
+    if (multi) {
+      var glossed = data.commits.filter(function (c) { return c.glossed }).length
+      add(main, add(el('div', 'commit'), el('span', 'sha', data.range),
+        el('span', null, plural(data.commits.length, 'commit') + ', ' + glossed + ' glossed')))
+      add(main, el('h1', null, 'Branch ' + data.range))
+      var list = el('ol', 'commit-list')
+      data.commits.forEach(function (c) {
+        var a = add(el('a'), el('span', 'sha', c.sha.slice(0, 7)), document.createTextNode(' ' + c.subject))
+        a.href = '#c-' + c.sha.slice(0, 7)
+        var li = add(el('li'), a)
+        if (!c.glossed) add(li, el('span', 'stale', 'no gloss'))
+        else if (c.warnings.length) add(li, el('span', 'stale', 'stale gloss'))
+        list.appendChild(li)
+      })
+      data.merges.forEach(function (m) {
+        list.appendChild(add(el('li'), el('span', 'sha', m.sha.slice(0, 7)), document.createTextNode(' ' + m.subject),
+          el('span', 'stale', 'merge, not reviewed')))
+      })
+      add(main, list)
+    } else {
+      var only = data.commits[0]
+      add(main, commitMeta(only), el('h1', null, only.subject))
+      statement(main, 'Task', only.task)
+      statement(main, 'Summary', only.summary)
+      only.warnings.forEach(function (w) { add(main, el('div', 'warning', '⚠ ' + w)) })
+    }
+
+    // Necessity overview across every commit: bar weighted by changed lines,
+    // chips filter groups.
+    var present = data.necessity.filter(function (n) { return allGroups.some(function (g) { return g.necessity === n.name }) })
+    var total = allGroups.reduce(function (s, g) { return s + g.weight }, 0) || 1
+    var bar = el('div', 'bar')
+    var chips = el('div', 'chips')
+    present.forEach(function (n) {
+      var groups = allGroups.filter(function (g) { return g.necessity === n.name })
+      var weight = groups.reduce(function (s, g) { return s + g.weight }, 0)
+      var seg = color(el('span'), n.name)
+      seg.style.width = (100 * weight / total) + '%'
+      seg.title = n.name + ': ' + Math.round(100 * weight / total) + '% of changed lines'
+      bar.appendChild(seg)
+
+      var chip = color(el('button', 'chip'), n.name)
+      chip.type = 'button'
+      chip.title = n.help + ' (click to show or hide)'
+      chip.setAttribute('aria-pressed', 'true')
+      add(chip, el('span', 'dot'), el('span', null, n.name), el('span', 'count', groups.length))
+      chip.dataset.necessity = n.name
+      chip.addEventListener('click', function () {
+        if (hidden.has(n.name)) hidden.delete(n.name); else hidden.add(n.name)
+        chip.setAttribute('aria-pressed', String(!hidden.has(n.name)))
+        applyFilter()
+      })
+      chips.appendChild(chip)
+    })
+    add(main, add(el('section', 'overview'), bar, chips,
+      el('div', 'note', 'Bar shows each category’s share of changed lines' + (multi ? ' across the range' : '') +
+        '. Click a category to hide or show its groups.')))
+
+    // Toolbar
+    var shown = el('span', 'shown')
+    var expand = el('button', 'btn', 'Expand all code')
+    var collapse = el('button', 'btn', 'Collapse all')
+    expand.type = collapse.type = 'button'
+    expand.addEventListener('click', function () { setAll(true) })
+    collapse.addEventListener('click', function () { setAll(false) })
+    add(main, add(el('div', 'toolbar'), shown, add(el('span'), expand, document.createTextNode(' '), collapse)))
+
+    // Commits, each with its groups; the sidebar groups them by commit.
+    data.commits.forEach(function (c) {
+      var target = main
+      if (multi) {
+        target = el('section', 'commit-section')
+        target.id = 'c-' + c.sha.slice(0, 7)
+        add(target, commitMeta(c), el('h2', null, c.subject))
+        statement(target, 'Task', c.task)
+        statement(target, 'Summary', c.summary)
+        c.warnings.forEach(function (w) { add(target, el('div', 'warning', '⚠ ' + w)) })
+        add(main, target)
+      }
+      var tocList = commitBody(c, target)
+      var heading = multi ? c.sha.slice(0, 7) + ' ' + c.subject : 'Groups'
+      var tocHead = el('h2', multi ? 'commit-head' : null, heading)
+      if (multi) tocHead.title = c.subject
+      add(toc, tocHead, tocList)
+    })
+
+    var foot = el('footer')
+    add(foot, document.createTextNode('Keys: '), el('kbd', null, 'j'), document.createTextNode(' / '), el('kbd', null, 'k'),
+      document.createTextNode(' next / previous group · '), el('kbd', null, 'o'), document.createTextNode(' show or hide code · '),
+      el('kbd', null, 'e'), document.createTextNode(' expand all · '), el('kbd', null, 'c'),
+      document.createTextNode(' collapse all.'))
+    add(foot, el('p', null, 'A snapshot generated by git-gloss ' + new Date(data.generated).toLocaleString() +
+      '. It does not update if the gloss or commit changes; regenerate with git gloss html ' +
+      (data.range || data.commits[0].sha.slice(0, 10)) + '.'))
+    add(main, foot)
+
+    app.textContent = ''
+    app.appendChild(layout)
+
+    function applyFilter() {
+      var visible = 0
+      cards.forEach(function (c) {
+        var off = hidden.has(c.dataset.necessity)
+        c.classList.toggle('hidden', off)
+        if (!off) visible++
+      })
+      toc.querySelectorAll('li[data-necessity]').forEach(function (li) { li.classList.toggle('hidden', hidden.has(li.dataset.necessity)) })
+      shown.textContent = visible === cards.length
+        ? plural(cards.length, 'group')
+        : 'Showing ' + visible + ' of ' + plural(cards.length, 'group')
+    }
+    applyFilter()
+    showNecessity = function (n) {
+      hidden.delete(n)
+      chips.querySelectorAll('.chip').forEach(function (c) { if (c.dataset.necessity === n) c.setAttribute('aria-pressed', 'true') })
+      applyFilter()
+    }
+  }
+  var showNecessity = function () {}
+
+  function setAll(open) {
+    cards.forEach(function (c) { if (c.setOpen && !c.classList.contains('hidden')) c.setOpen(open) })
+  }
+
+  var current = -1
+  function focusGroup(k, openCode, instant) {
+    var i = cards.findIndex(function (c) { return c.id === 'g-' + k })
+    if (i < 0) return
+    var card = cards[i]
+    // Following a link to a filtered-out group turns its category back on.
+    if (card.classList.contains('hidden')) showNecessity(card.dataset.necessity)
+    cards.forEach(function (c) { c.classList.remove('focused') })
+    card.classList.add('focused')
+    current = i
+    if (openCode && card.setOpen) card.setOpen(true)
+    card.scrollIntoView({ block: 'start', behavior: instant ? 'auto' : 'smooth' })
+    document.querySelectorAll('.toc li').forEach(function (li) { li.classList.toggle('active', li.dataset.key === k) })
+    history.replaceState(null, '', '#g-' + k)
+  }
+  function step(dir) {
+    var visible = cards.filter(function (c) { return !c.classList.contains('hidden') })
+    if (!visible.length) return
+    var pos = visible.indexOf(cards[current])
+    var next = visible[Math.min(visible.length - 1, Math.max(0, pos + dir))] || visible[0]
+    focusGroup(next.id.slice(2), false)
+  }
+
+  document.addEventListener('keydown', function (ev) {
+    if (ev.metaKey || ev.ctrlKey || ev.altKey) return
+    var t = ev.target
+    if (t && (/^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName) || t.isContentEditable)) return
+    if (ev.key === 'j') step(1)
+    else if (ev.key === 'k') step(-1)
+    else if (ev.key === 'o' && cards[current] && cards[current].setOpen) cards[current].setOpen(!cards[current].isOpen())
+    else if (ev.key === 'e') setAll(true)
+    else if (ev.key === 'c') setAll(false)
+  })
+
+  render()
+  if (location.hash.indexOf('#g-') === 0) {
+    try { focusGroup(decodeURIComponent(location.hash.slice(3)), true, true) } catch (e) { /* malformed hash */ }
+  }
+})()