@ok-ggwp/git-gloss 0.2.0 → 0.4.0

package/README.md

@@ -12,8 +12,11 @@ git gloss init [--hooks]              follow amends/rebases; fetch origin's glos
 git gloss sync [<remote>]             fetch, merge and push glosses (default: origin)
 git gloss hunks [<commit>|wip]        list hunks, numbering changed lines for h3:2-5 references;
                                       wip snapshots your uncommitted work instead
+git gloss signals [<commit>|<range>|wip] [--json]
+                                      what the diff itself says about attention: path classes, pattern
+                                      hits, dependency bumps and the computed floor
 git gloss adopt [<commit>]            move the gloss of uncommitted work onto the commit made from it
-git gloss add [<commit>] -f a.json    attach an annotation (validated against the diff)
+git gloss add [<commit>] -f a.json    attach an annotation (validated against the diff; --allow-underrate)
 git gloss carry <source>... [--to <c>] gloss a commit from the glosses of the commits its changes came from
                                       (a squash, cherry-pick or rebase): git gloss carry main..feature --to <squash>
       --find [--squash] [<commit>...] ...working out which commits those are
@@ -21,8 +24,10 @@ git gloss show [<commit>|<range>]     summary: one line per group, alternatives,
       -g <group>                      ...expand groups, with their code
       --full                          ...every group's details
       --diff                          ...every group's details and code
-      --only speculative,incidental   ...just the parts you might cut
+      --only speculative,incidental   ...just the parts you might cut (impact values work too: --only contract,sensitive; naming both kinds needs both to match)
+      --sort impact                   ...most consequential groups first
 git gloss html [<commit>|<range>]     self-contained HTML view, of one commit or a branch (--open, -o <file>)
+git gloss ary [--port <n>] [--no-open] browse branches, commits and wip in a local web page (see "Browsing")
 git gloss why <file>:<line>[-<end>]   explain why code exists (via blame), looking past mechanical edits
       --history                       ...every commit that changed the lines, newest first
       --json                          ...for agents, with risks and rejected alternatives
@@ -63,10 +68,25 @@ npm install -D @ok-ggwp/git-gloss
 npx git-gloss init --hooks
 ```
 
-The hooks run `git gloss`, so it must be on PATH wherever git runs; with a project install, that means running git from a shell where `node_modules/.bin` is on PATH, or installing it globally as well.
+The hooks run `git gloss`, so it must be on PATH wherever git runs. A project install isn't, by default: a GUI git client, or a shell that didn't run `pnpm`/`npm` scripts, won't find it. See [Project installs](#project-installs) for how to keep the team on one version anyway.
 
 To work on git-gloss itself: clone it, `npm install`, `npm link`, `npm test`. From a checkout, on Node 22.18+, the TypeScript source runs directly; on older versions the launcher runs `dist/`, which `npm install` builds (and `npm run build` rebuilds after changes). The tests need Node 23.6+.
 
+### Project installs
+
+A project install (`npm install -D`) keeps every teammate on the same version, which matters because glosses and reviews are shared git notes that each copy reads and writes. The cost is that `git gloss` is then on PATH only inside a shell that has `node_modules/.bin` on it. Two ways to deal with that:
+
+- **Put it on PATH in the hooks.** Add one line near the top of each hook that calls `git gloss` (`pre-push`, `post-commit`, `post-rewrite`), with the hooks kept in a tracked folder (for example, `.githooks/`, set with `git config core.hooksPath .githooks`):
+
+  ```sh
+  PATH="$PWD/node_modules/.bin:$PATH"
+  ```
+
+  Git runs hooks from the top of the working tree, so `$PWD` is that directory. In a monorepo where the install lives in a subfolder (`web/node_modules/.bin`), use that path instead. On Windows, use `$PWD` rather than `git rev-parse --show-toplevel`, which returns a `C:/…` path that Git for Windows' shell can't put on PATH.
+- **Run the setup from `prepare`.** A `prepare` script in the package that owns `node_modules` can set `core.hooksPath` and run `git gloss init --hooks` on every install, so nobody has to remember it in each clone. Skip it in CI, and make it never fail the install. Note that pnpm doesn't run `prepare` when `node_modules` is already up to date, so an existing clone needs `pnpm run prepare` once.
+
+Either way, the hooks never block a commit or push. Without `git gloss` on PATH they print an error and glosses aren't adopted, carried or synced, so check that `git gloss init` prints no warning after changing it. The Claude Code skill can run the tool through the project install too; see "Calling git-gloss" in the skill.
+
 ### Setting up a repo
 
 In each repo you use it in:
@@ -141,6 +161,47 @@ A review says that something was checked, not that it passed. Each review ends w
 
 Like glosses, reviews follow rebased commits in repos set up with `git gloss init`. Reviews are shared by `git gloss sync` (and so by every push with the hooks) like glosses, for commits the remote has. They never conflict: everyone's reviews are kept. Other tools can record reviews too: `git gloss reviews --stamp <rev>` before the review, then `git gloss reviews --record` with the stamp and the report as JSON on stdin.
 
+## Impact and attention
+
+Necessity and consequence are separate: a `required` one-line fix to a login helper matters more than a `required` rename in a leaf component. Two optional fields say so. Each group may have `impact` (`local < module < shared < contract < sensitive`, the farthest its effect reaches if it is wrong) and an `impact_reason` of up to 120 characters. The annotation may have `attention`: `level` (`skim`, `look`, `careful` or `must-read`), one to three `focus` group ids to read first, `reasons`, and an optional `override_reason`. `git gloss schema` lists them all.
+
+`show` leads with `attention: CAREFUL (declared) · floor: careful · focus: a, b` and the reasons, and badges each group with its impact; `html` shows the same as a banner whose focus links jump to the groups. Where nothing is declared, `show` and `html` show a value computed from the diff and mark it, as in `attention: LOOK (derived)` (a group's derived impact is in parentheses); a gloss reads as `attention: unrated` only where no signals can be computed. When glosses are combined (`carry`, a squash, a rebase) the attention level is the highest of them and the focus groups are the most impactful three, with the reasons joined; if any of them declared none, the combined gloss declares none and shows a derived one.
+
+Notes using these fields are format 4; a git-gloss that predates them refuses such a note ("written by a newer git-gloss") rather than silently dropping the fields. A gloss that doesn't use them is still written in its old format. Derived values and floors are computed on every read and never stored in a note.
+
+### Computed signals and the floor
+
+`git gloss signals [<commit>|<range>|wip] [--json]` reports, per hunk, file and change: the path classes (`sensitive`, `shared`, `contract`, `generated`, `test`, `docs`, plus `lockfile` and `manifest`), pattern hits, stats (files, hunks, lines, test files, share of hunks in tests), dependency changes, and the floor. `wip` is the working tree as it is now (no snapshot is taken). `hunks` ends with a short summary of the same, so read it before writing a gloss. Signals are cheap heuristics from globs and regexes, not a security scanner.
+
+- **Pattern hits** are regexes (case-insensitive unless the pattern sets `flags`) matched against the *added and removed* lines of a hunk only: never unchanged context lines, never the `@@` header. In test, docs and lockfile paths they are *damped*: still reported, but they don't count towards the floor (a `password` in a test file is not sensitive).
+- **Dependencies.** Edits to manifests and lockfiles are listed. `package-lock.json` and `pnpm-lock.yaml` are parsed from their changed lines for version bumps, and a bump of a package that no `package.json` change names is flagged as transitive. Other lockfiles are `contract` with no version detail.
+- **Floor of a hunk**: the highest of its path class (`sensitive`, `contract`, `shared`; lockfiles and manifests are at least `contract`; otherwise `module`) and its undamped pattern hits. Test, docs and generated files cap at `local` (a pattern hit in generated code still counts). A group's floor is the highest floor of its hunks; for a group that claims only some lines of a hunk, only the hits on those lines count.
+- **Floor of the change**: skim for `local`, look for `module`, careful for `shared` and `contract`, must-read for `sensitive`, and at least careful when more than `attention.largeChangeFiles` (default 50) files changed.
+- **Derived attention** (when the gloss declares none): start from the highest group impact (declared, else the group's floor) with the same mapping, then raise it one step (capped at must-read, once however many apply) for a behaviour-changing group that no test group serves, for a speculative or defensive group outside tests, or for more than `largeChangeFiles` files; never below the floor. A group is *behaviour-changing* when its necessity is not `mechanical` and not all its hunks are tests, docs, generated files or lockfiles. It is *served by tests* when a group made only of test-file hunks names it in `serves`, directly or through groups it serves; a test group serving `"task"` doesn't count.
+
+`add` checks a gloss against the floor. A group whose declared `impact` is below its floor (above plain `module`) is a warning naming the signal. A declared `attention.level` below the floor is an error unless `attention.override_reason` says why; `--allow-underrate` turns that error into a warning. Leaving `impact` or `attention` out is always allowed. An `override_reason` is shown by `show` and `html` next to the floor, flagged as a mismatch.
+
+### Config
+
+The built-in defaults name no language, framework or tool, only common file names. A repo adds to them with `.gloss/config.json`, committed in that repo. The file is read from the base branch (the merge base of the checked-out `HEAD` and `origin/main`, `main`, `origin/master` or `master`, so a long-lived branch sees the config as of where it forked; a commit on the base branch itself reads its own config, flagged `sensitive` if it edits the file), never from the working tree, so a change cannot reclassify its own paths; a config edit only takes effect once it is on the base branch. With none of those branches the defaults apply, with a warning. Editing the file is itself always a `sensitive` path. A pattern that takes over 250 ms on a hunk is cut off and from then on counts as matching every changed line (with a warning), so a slow or padded line raises the floor and never lowers it:
+
+```json
+{
+  "attention": { "largeChangeFiles": 80 },
+  "paths": {
+    "shared": ["packages/shared/**", "tsconfig.base.json"],
+    "sensitive": ["src/devices/**"],
+    "test": { "extends": false, "globs": ["**/*.spec.*", "e2e/**"] }
+  },
+  "patterns": {
+    "sensitive": [{ "regex": "\\bdevice\\.write\\(", "name": "device write" }],
+    "contract": ["<regex for the repo's public-API markers>"]
+  }
+}
+```
+
+A class is a list that extends the default list, or `{ "extends": false, "globs": [...] }` (`"regexes"` for patterns) to replace it. Path classes: `sensitive`, `shared`, `contract`, `generated`, `test`, `docs`, `lockfile`, `manifest`; pattern classes: `sensitive`, `contract`, `shared`. Globs support `**`, `*`, `?` and `{a,b}`; a glob without a `/` matches that name at any depth. `git config gloss.attention.largeChangeFiles <n>` overrides the file. A malformed config is an error naming the file and key (`add` and `signals` stop; `show` falls back to declared values and "unrated").
+
 ## HTML view
 
 `git gloss html --open` writes a single HTML file (no network access, works offline) and opens it. It shows the task and summary, a bar of how the changed lines split across necessity categories, and a card per group with its rationale; code is collapsed until you ask for it. Click categories to filter, use the sidebar to jump between groups, or press `j`/`k` to move, `o` to show code, and `e`/`c` to expand or collapse everything. `#g-<group>` in the URL opens that group.
@@ -149,6 +210,12 @@ Give a range (`git gloss html main..feature --open`) for a branch or PR view: ev
 
 All gloss and diff text is rendered as text, and a Content-Security-Policy with a per-page nonce blocks any script the page didn't generate.
 
+## Browsing
+
+`git gloss ary` starts a small web server and opens it in your browser, so you can explore glosses without working out commits, branches and ranges on the command line. Pick a branch and a branch to compare it with (the repo's `main` or `master` by default); each picker has a search box, for repos with many branches. Then click a commit, or "Whole branch" for the range view. Each commit shows its subject (up to two lines) and whether it has a gloss and a review, and a search box above the list finds commits by message or author (case-insensitive, plain text). Searching covers the whole selected branch, not only the commits loaded so far. Your uncommitted work appears at the top once it has been snapshotted (`git gloss hunks wip`). To look at anything else, such as `HEAD~3` or `release..main`, type it into the revision box. As everywhere in git-gloss, `wip` there means the snapshot of uncommitted work, so to view a branch or tag called `wip`, type `heads/wip` or `tags/wip`. Each selection is the page `git gloss html` writes, regenerated on every load, so Reload picks up new glosses and reviews. The address bar keeps the selection, so a reload returns to it (with a random port, a bookmark lasts only until you stop the server; pass `--port` for a stable address).
+
+It serves one repository, the one you run it in, until you press Ctrl-C. It listens on 127.0.0.1 only, on a free port (or `--port`), only answers requests addressed to that host name, and never writes anything: it doesn't take snapshots or change notes. A page shows at most 200 commits; pick a narrower range for more. `--no-open` doesn't launch a browser.
+
 ## Caveats
 
 - Carrying a gloss onto a server-side squash needs the original commits in your repository; usually the author has them. If a squash merge resolved conflicts or changed much of the code, it may not reach the 80% match; run `git gloss carry <branch commits> --to <squash>`.

package/dist/ary/browse.js

@@ -0,0 +1,80 @@
+import { basename } from 'node:path';
+import { NOTES_REF, WIP_NOTES_REF, WIP_REF, git, gitTry, wipStaleness } from '../git.js';
+import { REVIEWS_REF } from '../reviews.js';
+// The commits a notes ref has notes on ("<note> <commit>" per line). A missing
+// ref is no notes.
+function notedCommits(ref) {
+    const lines = (gitTry(['notes', '--ref', ref, 'list']) ?? '').split('\n');
+    return new Set(lines.filter(Boolean).map((l) => l.split(' ')[1]));
+}
+function refList(namespace) {
+    return git(['for-each-ref', '--sort=-committerdate', '--format=%(refname)%00%(refname:short)%00%(committerdate:relative)%00%(subject)', namespace])
+        .split('\n')
+        .filter(Boolean)
+        .map((l) => l.split('\0'))
+        // refs/remotes/<remote>/HEAD is a pointer to another branch, not a branch.
+        .filter(([full]) => !full.endsWith('/HEAD'))
+        .map(([, name, date, subject]) => ({ name, date, subject }));
+}
+export function listRefs() {
+    const branches = refList('refs/heads');
+    const remotes = refList('refs/remotes');
+    const names = new Set([...branches, ...remotes].map((b) => b.name));
+    const wipSha = gitTry(['rev-parse', '--verify', '--quiet', WIP_REF])?.trim();
+    let stale = null;
+    if (wipSha) {
+        try {
+            stale = wipStaleness(wipSha);
+        }
+        catch {
+            // Staleness is advice; the snapshot is still viewable without it.
+        }
+    }
+    return {
+        repo: basename(git(['rev-parse', '--show-toplevel']).trim()),
+        current: gitTry(['symbolic-ref', '--short', '--quiet', 'HEAD'])?.trim() || null,
+        branches,
+        remotes,
+        defaultBase: ['main', 'master', 'origin/main', 'origin/master'].find((n) => names.has(n)) ?? null,
+        wip: wipSha ? { sha: wipSha, glossed: notedCommits(WIP_NOTES_REF).has(wipSha), stale } : null,
+    };
+}
+// Newest first: the commits of `head`, or only those not in `base` when given.
+// `query` keeps the commits whose message or author contains it (any case).
+export function listLog(head, base, limit, skip, query = '') {
+    const range = base ? `${base}..${head}` : head;
+    const format = '--format=%H%x00%an%x00%aI%x00%s%x00%P';
+    let out;
+    if (query) {
+        // git ANDs --grep with --author, so ask for each on its own and merge, then
+        // list the union by commit date (what --no-walk=sorted gives, which can
+        // differ from the order of an unfiltered log when dates are skewed).
+        const shas = new Set();
+        for (const filter of ['--grep', '--author']) {
+            const found = git(['log', '--format=%H', '--regexp-ignore-case', '--fixed-strings', `${filter}=${query}`, '--end-of-options', range, '--']);
+            for (const sha of found.split('\n').filter(Boolean))
+                shas.add(sha);
+        }
+        // No -n or --skip here: git then walks on to the parents, so page by hand.
+        out = shas.size
+            ? git(['log', '--no-walk=sorted', '--stdin', format], [...shas].join('\n') + '\n').split('\n').slice(skip, skip + limit + 1).join('\n')
+            : '';
+    }
+    else {
+        // One more than asked for, to know whether there are more.
+        out = git(['log', format, '-n', String(limit + 1), '--skip', String(skip), '--end-of-options', range, '--']);
+    }
+    const glossed = notedCommits(NOTES_REF);
+    const reviewed = notedCommits(REVIEWS_REF);
+    const rows = out.split('\n').filter(Boolean).map((l) => l.split('\0'));
+    return {
+        commits: rows.slice(0, limit).map(([sha, author, date, subject, parents]) => ({
+            sha, author, date, subject,
+            merge: parents.includes(' '),
+            glossed: glossed.has(sha),
+            reviewed: reviewed.has(sha),
+        })),
+        more: rows.length > limit,
+        total: base && !query ? Number(git(['rev-list', '--count', '--end-of-options', range, '--']).trim()) : null,
+    };
+}

package/dist/ary/client.js

@@ -0,0 +1,401 @@
+// The ary shell: pick a branch, a base to compare it with, and a commit (or the
+// whole branch), and the chosen view loads in the frame. Text only goes
+// through textContent; nothing from the repo is parsed as HTML.
+(function () {
+  'use strict'
+  var app = document.getElementById('app')
+  var PAGE = 100
+
+  // What is selected. head/base choose which commits are listed; rev is what
+  // the frame shows (a sha, "wip", a range, or anything typed in).
+  var state = { head: null, base: null, rev: null, q: '' }
+  var refs = null
+  var log = { commits: [], more: false, total: null }
+  var logError = null
+  var parts = {}
+
+  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 plural(n, word) { return n + ' ' + word + (n === 1 ? '' : 's') }
+  function api(path) {
+    return fetch(path).then(function (r) {
+      return r.json().then(function (body) {
+        if (!r.ok) throw new Error(body.error || r.statusText)
+        return body
+      })
+    })
+  }
+
+  // ---- location: the selection is kept in the hash, so reload and links work ----
+  function saveHash() {
+    var p = new URLSearchParams()
+    if (state.rev) p.set('rev', state.rev)
+    if (state.head) p.set('head', state.head)
+    if (state.base) p.set('base', state.base)
+    history.replaceState(null, '', '#' + p.toString())
+  }
+  function readHash() {
+    var p = new URLSearchParams(location.hash.slice(1))
+    return { rev: p.get('rev'), head: p.get('head'), base: p.get('base') }
+  }
+
+  // ---- sidebar ----
+  // A branch picker with a search box: a repo can have hundreds of branches,
+  // too many to scan in a <select>. Matching is case-insensitive and every
+  // space-separated word must appear in the name.
+  var SHOWN = 200
+  function picker(onPick) {
+    var root = el('div', 'combo')
+    var button = el('button', 'combo-btn')
+    button.type = 'button'
+    button.setAttribute('aria-haspopup', 'listbox')
+    var panel = el('div', 'combo-panel')
+    panel.hidden = true
+    var input = el('input')
+    input.type = 'search'
+    input.spellcheck = false
+    input.placeholder = 'Search branches…'
+    input.setAttribute('aria-label', 'Search branches')
+    var list = el('div', 'combo-list')
+    list.setAttribute('role', 'listbox')
+    add(panel, input, list)
+    add(root, button, panel)
+
+    var groups = []
+    var noneLabel = null
+    var value = null
+    var items = [] // the rows now shown: { value, node }
+    var active = 0
+
+    function matches(name, words) {
+      var n = name.toLowerCase()
+      return words.every(function (w) { return n.indexOf(w) >= 0 })
+    }
+    function paint() {
+      items.forEach(function (it, i) { it.node.classList.toggle('active', i === active) })
+      if (items[active]) items[active].node.scrollIntoView({ block: 'nearest' })
+    }
+    function render() {
+      var words = input.value.toLowerCase().split(/\s+/).filter(Boolean)
+      list.textContent = ''
+      items = []
+      var shown = 0
+      var hidden = 0
+      function item(label, v) {
+        var node = el('button', 'combo-item', label)
+        node.type = 'button'
+        node.setAttribute('role', 'option')
+        node.setAttribute('aria-selected', String(v === value))
+        node.addEventListener('click', function () { pick(v) })
+        items.push({ value: v, node: node })
+        return node
+      }
+      if (noneLabel && !words.length) list.appendChild(item(noneLabel, null))
+      groups.forEach(function (g) {
+        var found = g.names.filter(function (n) { return matches(n, words) })
+        var room = found.slice(0, Math.max(0, SHOWN - shown))
+        hidden += found.length - room.length
+        shown += room.length
+        if (!room.length) return
+        add(list, add(el('div', 'combo-group', g.label), el('span', 'count', found.length)))
+        room.forEach(function (n) { list.appendChild(item(n, n)) })
+      })
+      if (hidden) add(list, el('div', 'combo-more', hidden + ' more: keep typing to narrow the list'))
+      if (!items.length) add(list, el('div', 'combo-more', 'No branches match.'))
+      // Start on the current value, or on the first match when searching.
+      var at = words.length ? -1 : items.findIndex(function (it) { return it.value === value })
+      active = at >= 0 ? at : 0
+      paint()
+    }
+    function open() {
+      panel.hidden = false
+      button.setAttribute('aria-expanded', 'true')
+      input.value = ''
+      render()
+      input.focus()
+    }
+    function close() {
+      panel.hidden = true
+      button.setAttribute('aria-expanded', 'false')
+    }
+    function pick(v) {
+      close()
+      button.focus()
+      if (v !== value) onPick(v)
+    }
+    button.addEventListener('click', function () { if (panel.hidden) open(); else close() })
+    input.addEventListener('input', render)
+    input.addEventListener('keydown', function (ev) {
+      if (ev.key === 'ArrowDown' || ev.key === 'ArrowUp') {
+        ev.preventDefault()
+        if (items.length) active = (active + (ev.key === 'ArrowDown' ? 1 : items.length - 1)) % items.length
+        paint()
+      } else if (ev.key === 'Enter') {
+        ev.preventDefault()
+        if (items[active]) pick(items[active].value)
+      } else if (ev.key === 'Escape') {
+        ev.preventDefault()
+        close()
+        button.focus()
+      }
+    })
+    document.addEventListener('mousedown', function (ev) { if (!panel.hidden && !root.contains(ev.target)) close() })
+
+    return {
+      root: root,
+      // Local and remote branches, and what choosing "no branch" is called (if allowed).
+      setOptions: function (g, none) { groups = g; noneLabel = none },
+      setValue: function (v) {
+        value = v
+        button.textContent = v || noneLabel || 'choose a branch'
+        button.title = button.textContent
+      },
+    }
+  }
+
+  function branchGroups() {
+    return [
+      { label: 'Local branches', names: refs.branches.map(function (b) { return b.name }) },
+      { label: 'Remote branches', names: refs.remotes.map(function (b) { return b.name }) },
+    ]
+  }
+
+  // One entry in the list: the title gets the full width (two lines at most),
+  // with the details and status marks on a line below it.
+  function row(title, details, marks, current, onClick) {
+    var b = el('button', 'row')
+    b.type = 'button'
+    b.setAttribute('aria-current', String(current))
+    b.title = title
+    add(b, el('div', 'subject', title))
+    var meta = el('div', 'meta')
+    details.forEach(function (d) { meta.appendChild(d) })
+    add(meta, add(el('span', 'marks'), marks[0], marks[1], marks[2]))
+    add(b, meta)
+    b.addEventListener('click', onClick)
+    return b
+  }
+  function mark(kind, text, tip) {
+    var m = el('span', 'mark ' + kind, text)
+    if (tip) m.title = tip
+    return m
+  }
+  function glossMark(glossed) {
+    return glossed ? mark('glossed', '● glossed', 'This commit has a gloss') : mark('none', '○ no gloss', 'This commit has no gloss')
+  }
+
+  function renderList() {
+    var list = parts.list
+    list.textContent = ''
+    if (refs.wip) {
+      add(list, el('h2', null, 'Uncommitted work'))
+      var w = refs.wip
+      add(list, row('wip snapshot', [el('span', null, w.stale || 'the latest snapshot of your working tree')],
+        [glossMark(w.glossed), w.stale ? mark('warn', 'stale', w.stale) : null], state.rev === 'wip', function () { select('wip') }))
+    }
+    add(list, el('h2', null, state.head ? 'Commits on ' + state.head : 'Commits'))
+    if (logError) { add(list, el('p', 'error', logError)); return }
+    // A search narrows the list to some commits, so it isn't the whole branch.
+    if (state.base && state.head && log.commits.length && !state.q) {
+      var range = state.base + '..' + state.head
+      add(list, row('Whole branch', [el('span', null, range + ' · ' + plural(log.total === null ? log.commits.length : log.total, 'commit'))], [], state.rev === range, function () { select(range) }))
+    }
+    if (!log.commits.length) {
+      add(list, el('p', 'empty', state.q ? 'No commits match “' + state.q + '”.' : state.base ? 'No commits beyond ' + state.base + '.' : 'No commits.'))
+    }
+    log.commits.forEach(function (c) {
+      add(list, row(c.subject,
+        [el('span', 'sha', c.sha.slice(0, 7)), el('span', null, ' · ' + c.author + ' · ' + new Date(c.date).toLocaleDateString())],
+        c.merge ? [mark('none', 'merge')] : [glossMark(c.glossed), c.reviewed ? mark('reviewed', '✓ reviewed', 'This commit has a recorded review') : null],
+        state.rev === c.sha, function () { select(c.sha) }))
+    })
+    if (log.more) {
+      var more = el('button', 'btn more', 'Load more')
+      more.type = 'button'
+      more.addEventListener('click', function () { loadLog(true) })
+      add(list, more)
+    }
+  }
+
+  function renderSide() {
+    parts.head.setOptions(branchGroups(), null)
+    parts.head.setValue(state.head)
+    parts.base.setOptions(branchGroups(), '(none: all of the branch’s history)')
+    parts.base.setValue(state.base)
+    parts.rev.value = state.rev && state.rev !== 'wip' ? state.rev : ''
+    renderList()
+  }
+
+  // ---- viewer ----
+  function renderViewer() {
+    var v = parts.viewer
+    v.textContent = ''
+    if (!state.rev) {
+      add(v, el('div', 'placeholder', 'Pick a commit, a whole branch, or type any revision or range.'))
+      return
+    }
+    var src = '/view?rev=' + encodeURIComponent(state.rev)
+    var open = el('a', null, 'open in a tab ↗')
+    open.href = src
+    open.target = '_blank'
+    open.rel = 'noopener'
+    var reload = el('button', 'btn', 'Reload')
+    reload.type = 'button'
+    var frame = el('iframe')
+    frame.title = 'gloss of ' + state.rev
+    frame.src = src
+    // So the page's keys (j, k, o, e, c) work without clicking into it first.
+    frame.addEventListener('load', function () { frame.contentWindow.focus() })
+    reload.addEventListener('click', function () { frame.src = src })
+    add(v, add(el('div', 'viewer-bar'), el('span', 'what', state.rev === 'wip' ? 'uncommitted work (wip)' : state.rev), reload, open), frame)
+  }
+
+  // ---- actions ----
+  function select(rev) {
+    state.rev = rev
+    saveHash()
+    renderList()
+    parts.rev.value = rev === 'wip' ? '' : rev
+    renderViewer()
+  }
+
+  function loadLog(append) {
+    if (!state.head) { log = { commits: [], more: false, total: null }; renderList(); return Promise.resolve() }
+    var q = new URLSearchParams({ head: state.head, limit: PAGE, skip: append ? log.commits.length : 0 })
+    if (state.base) q.set('base', state.base)
+    if (state.q) q.set('q', state.q)
+    var asked = state.head + '..' + state.base + '?' + state.q
+    return api('/api/log?' + q).then(function (data) {
+      if (asked !== state.head + '..' + state.base + '?' + state.q) return // the selection moved on
+      logError = null
+      log = append ? { commits: log.commits.concat(data.commits), more: data.more, total: data.total } : data
+      renderList()
+    }).catch(function (err) {
+      logError = err.message
+      log = { commits: [], more: false, total: null }
+      renderList()
+    })
+  }
+
+  function pickHead(name) {
+    state.head = name
+    // A feature branch is most useful against the usual base; the base itself
+    // is listed whole.
+    state.base = name === refs.defaultBase ? null : refs.defaultBase
+    saveHash()
+    renderSide()
+    loadLog(false)
+  }
+
+  function load() {
+    return api('/api/refs').then(function (data) {
+      parts.error.hidden = true
+      refs = data
+      var h = readHash()
+      // A link or bookmark may name a branch that has since been deleted or
+      // renamed: use the usual choice instead, and say so.
+      var known = {}
+      refs.branches.concat(refs.remotes).forEach(function (b) { known[b.name] = true })
+      var head = h.head && known[h.head] ? h.head : null
+      state.head = head || refs.current || refs.defaultBase || (refs.branches[0] && refs.branches[0].name) || null
+      var notice = null
+      if (h.head && !head) {
+        // The default base goes with the default branch.
+        state.base = state.head === refs.defaultBase ? null : refs.defaultBase
+        notice = 'Branch “' + h.head + '” no longer exists; showing ' + (state.head || 'the default') + ' instead.'
+      } else if (h.base && !known[h.base]) {
+        state.base = null
+        notice = 'The branch to compare with, “' + h.base + '”, no longer exists; showing all of ' + state.head + '’s history.'
+      } else if (head) {
+        state.base = h.base || null
+      } else {
+        state.base = state.head === refs.defaultBase ? null : refs.defaultBase
+      }
+      if (notice) {
+        parts.error.textContent = notice
+        parts.error.hidden = false
+      }
+      state.rev = h.rev || (refs.wip ? 'wip' : null)
+      parts.title.textContent = refs.repo
+      renderSide()
+      renderViewer()
+      return loadLog(false).then(function () {
+        // With nothing chosen, show the whole branch, or its newest commit.
+        if (!state.rev && state.head) select(state.base && log.commits.length ? state.base + '..' + state.head : log.commits.length ? log.commits[0].sha : null)
+      })
+    })
+  }
+
+  function build() {
+    parts.title = el('span', 'repo')
+    var refresh = el('button', 'btn', 'Refresh')
+    refresh.type = 'button'
+    refresh.title = 'Re-read branches and commits'
+    refresh.addEventListener('click', function () { load().catch(fail) })
+
+    parts.head = picker(pickHead)
+    parts.base = picker(function (name) {
+      state.base = name
+      parts.base.setValue(name)
+      saveHash()
+      loadLog(false)
+    })
+
+    parts.rev = el('input')
+    parts.rev.type = 'text'
+    parts.rev.spellcheck = false
+    parts.rev.placeholder = 'HEAD~3, abc123, main..feature'
+    var go = el('button', 'btn', 'View')
+    go.type = 'submit'
+    var form = add(el('form', 'rev-row'), parts.rev, go)
+    form.addEventListener('submit', function (ev) {
+      ev.preventDefault()
+      var v = parts.rev.value.trim()
+      if (v) select(v)
+    })
+
+    parts.search = el('input')
+    parts.search.type = 'search'
+    parts.search.spellcheck = false
+    parts.search.placeholder = 'Search commit messages and authors…'
+    parts.search.setAttribute('aria-label', 'Search commits')
+    var searching = null
+    parts.search.addEventListener('input', function () {
+      // Wait for a pause in typing: each search asks git.
+      clearTimeout(searching)
+      searching = setTimeout(function () {
+        state.q = parts.search.value.trim()
+        loadLog(false)
+      }, 250)
+    })
+
+    parts.error = el('p', 'error')
+    parts.error.hidden = true
+    parts.list = el('div', 'list')
+    parts.viewer = el('section', 'viewer')
+
+    var top = add(el('div', 'side-top'),
+      add(el('div', 'title'), el('strong', null, 'git gloss ary'), parts.title, refresh),
+      parts.error,
+      add(el('div', 'field'), el('span', null, 'Branch'), parts.head.root),
+      add(el('div', 'field'), el('span', null, 'Compare with'), parts.base.root),
+      add(el('label', 'field'), document.createTextNode('Any revision or range'), form))
+    add(app, add(el('div', 'shell'), add(el('aside', 'side'), top, add(el('div', 'search-bar'), parts.search), parts.list), parts.viewer))
+  }
+
+  function fail(err) {
+    parts.error.textContent = 'Could not read the repository: ' + err.message
+    parts.error.hidden = false
+  }
+
+  build()
+  load().catch(fail)
+})()

package/dist/ary/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>git gloss ary</title>
+<link rel="stylesheet" href="/ary.css">
+</head>
+<body>
+<div id="app"><noscript>This page needs JavaScript.</noscript></div>
+<script src="/ary.js"></script>
+</body>
+</html>