@ok-ggwp/git-gloss 0.3.0 → 0.5.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,7 +24,8 @@ 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
@@ -31,7 +35,10 @@ git gloss review [<commit>|<range>]   print a review prompt: git gloss review ma
       --material                      ...only the gloss and code, for a reviewer with its own instructions
                                       (which must tell it the author's text is untrusted)
 git gloss versions [<commit>|wip]     every gloss a commit has had, newest first (--show <n>, --restore <n>)
-git gloss reviews [<commit>|<range>]  the reviews recorded for commits, with their findings
+git gloss reviews [<commit>|<range>]  the reviews recorded for commits, with their findings and decisions
+      --decide <review-id> --finding <text> --outcome fixed|follow-up|rejected|accepted [--note <text>]
+                                      record what was decided about one finding
+      --decide <review-id> --complete  the arbiter has finished with that review
 git gloss schema                      print the annotation JSON Schema
 ```
 
@@ -155,8 +162,69 @@ reviews: honesty: no issues (claude, 2026-10-18) · bugs: defects found (claude,
 
 A review says that something was checked, not that it passed. Each review ends with a verdict (`VERDICT: CLEAN` or `VERDICT: ISSUES`). For each part of the commit, the latest review that saw it decides, and a clean result that followed one with issues says so.
 
+### Decisions
+
+A review holds a report and a verdict, so by itself it cannot tell "3 fixed, 2 deferred" from "5 ignored". Whoever arbitrates a review (the `gg-deliver` arbiter, or a person) records **decisions** about it, in the same notes ref and on the same commits as the review. A decision is one JSON line:
+
+```
+{"decision":1,"review":"<review id>","at":"…","by":"…","finding":"1","outcome":"fixed","note":"…"}
+{"decision":1,"review":"<review id>","at":"…","by":"…","complete":true}
+```
+
+`finding` is free text naming the finding (reports are free text, so git-gloss doesn't parse findings out of them); `outcome` is `fixed`, `follow-up`, `rejected` or `accepted`; `note` is optional. The second line says the arbiter has finished and no more decisions are coming, which is what separates "all arbitrated" from "5 ignored". The marker is advisory: decisions added after it are still accepted and counted. A review whose verdict is clean needs none.
+
+```bash
+git gloss reviews wip --decide <review-id> --finding "Rework: wip rule claim" --outcome follow-up --note "next release"
+git gloss reviews wip --decide <review-id> --complete
+```
+
+The target (`wip`, a commit, a range) is as for `reviews`; the decision is added to every commit there that holds that review, and an unknown review id is an error. `by` is `--by <name>`, else `git config user.name`, else "unknown". `reviews` prints each review's id in its header line (the id `--decide` takes) and lists its decisions under it with a summary ("3 fixed, 2 follow-up · complete", or "4 decided · not marked complete"), and `show` carries the same summary on its reviews line. The HTML view does not show decisions yet. Decisions follow their reviews through `adopt` (so decisions made on `wip` survive committing), `carry`, rebases and `sync`. Text from notes (decisions and review records) and commit subjects is shown with control characters and escape sequences removed, since it can arrive from a remote; decision lines over 16 KB are skipped silently, and review lines over 8 MiB or with findings text over 256 KiB are skipped with a warning; unknown outcomes and decisions for a review that is not on the commit are ignored.
+
+Known cost: decisions share the review note, and a git-gloss without this feature ignores decision lines when reading but does not know to keep them: when it copies review records onto another commit (`adopt` and `carry`), it writes only the review records, so the decisions are lost on that copy (git's own note rewriting on an amend or rebase copies whole notes, so that path keeps them). Keep everyone who arbitrates on the same version.
+
 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.
@@ -167,7 +235,7 @@ All gloss and diff text is rendered as text, and a Content-Security-Policy with
 
 ## 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).
+`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. The page is the review desk that `git gloss html` writes, with the pickers in its top bar: choose 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. With a base, the desk's own sidebar lists the commits of the range; with "none" (or when there is nothing beyond the base, or more than 200 commits) the page shows just the branch's newest commit and its groups. 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, which is what opens first once it has been snapshotted (`git gloss hunks wip`); to view a branch or tag called `wip`, type `heads/wip` or `tags/wip`. Every choice loads a new page (`/?rev=…&head=…&base=…`), regenerated from the repo each time, so reloading picks up new glosses and reviews, and the address keeps the selection (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.
 

package/dist/ary/browse.js

@@ -1,80 +1,23 @@
 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]));
-}
+import { git, gitTry } from '../git.js';
 function refList(namespace) {
-    return git(['for-each-ref', '--sort=-committerdate', '--format=%(refname)%00%(refname:short)%00%(committerdate:relative)%00%(subject)', namespace])
+    return git(['for-each-ref', '--sort=-committerdate', '--format=%(refname)%00%(refname:short)', 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 }));
+        .map(([, name]) => name);
 }
 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.
-        }
-    }
+    const names = new Set([...branches, ...remotes]);
     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/picker.js

@@ -0,0 +1,163 @@
+// The branch pickers and revision box in the desk's top bar when served by
+// `git gloss ary`. Included by page.ts only in that mode, ahead of the desk's
+// script, in the same nonce'd <script>; `el` and `add` are the desk's helpers. It makes no requests: the branches
+// arrive in the page data. Choosing something loads the URL for it, and the
+// server renders that page. Text only goes through textContent.
+function aryBar(ary, el, add) {
+  'use strict'
+  // 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: ary.branches },
+      { label: 'Remote branches', names: ary.remotes },
+    ]
+  }
+  function go(head, base, rev) {
+    var p = new URLSearchParams()
+    if (rev) p.set('rev', rev)
+    if (head) p.set('head', head)
+    if (base) p.set('base', base)
+    location.assign('/?' + p.toString())
+  }
+
+  var headPicker = picker(function (name) {
+    // A feature branch is most useful against the usual base; the base itself is listed whole.
+    go(name, name === ary.defaultBase ? null : ary.defaultBase, null)
+  })
+  headPicker.setOptions(branchGroups(), null)
+  headPicker.setValue(ary.head)
+  var basePicker = picker(function (name) { go(ary.head, name, null) })
+  basePicker.setOptions(branchGroups(), '(none: just the newest commit)')
+  basePicker.setValue(ary.base)
+
+  var input = el('input')
+  input.type = 'text'
+  input.spellcheck = false
+  input.placeholder = 'HEAD~3, abc123, main..feature, wip'
+  input.setAttribute('aria-label', 'Any revision or range')
+  input.value = ary.rev || ''
+  var form = add(el('form', 'ary-rev'), input)
+  form.addEventListener('submit', function (ev) {
+    ev.preventDefault()
+    var v = input.value.trim()
+    if (v) go(ary.head, ary.base, v)
+  })
+
+  function field(label, node) { return add(el('div', 'ary-field'), el('span', null, label), node) }
+  var bar = add(el('div', 'ary-bar'), el('span', 'ary-repo', ary.repo),
+    field('Branch', headPicker.root), field('Compare with', basePicker.root), field('Revision', form))
+  if (ary.notice) bar.appendChild(el('p', 'ary-notice', ary.notice))
+  return bar
+}

package/dist/ary/server.js

@@ -1,16 +1,11 @@
-import { readFileSync } from 'node:fs';
 import { createServer } from 'node:http';
-import { GlossError, WIP_REF, gitTry, resolveCommits } from '../git.js';
+import { GlossError, WIP_REF, git, gitTry, resolveCommits } from '../git.js';
 import { buildPageData } from '../html/data.js';
 import { escapeHtml, renderPage } from '../html/page.js';
-import { listLog, listRefs } from './browse.js';
-const asset = (name) => readFileSync(new URL(name, import.meta.url), 'utf8');
+import { listRefs } from './browse.js';
 // A range page loads and lays out every commit in it, so a huge one would hang
 // the browser. Narrowing it is a better answer than a spinner.
 export const MAX_RANGE_COMMITS = 200;
-// The shell page loads only its own script and style, and may frame only
-// /view pages. Those carry their own policy: an inline script with a nonce.
-const SHELL_CSP = "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; frame-src 'self'; base-uri 'none'; form-action 'none'";
 class BadRequest extends GlossError {
 }
 // A revision, branch or range typed by the user or taken from the sidebar. An
@@ -26,10 +21,6 @@ function revParam(url, name, required = true) {
         throw new BadRequest(`not a revision: ${v.slice(0, 80)}`);
     return v;
 }
-const intParam = (url, name, fallback, min, max) => {
-    const n = Number(url.searchParams.get(name) ?? fallback);
-    return Number.isInteger(n) && n >= min ? Math.min(n, max) : fallback;
-};
 function send(res, status, type, body, headers = {}) {
     res.writeHead(status, {
         'content-type': `${type}; charset=utf-8`,
@@ -41,9 +32,74 @@ function send(res, status, type, body, headers = {}) {
     });
     res.end(body);
 }
-const sendJson = (res, data) => send(res, 200, 'application/json', JSON.stringify(data));
-function viewPage(url) {
-    const rev = revParam(url, 'rev');
+// The page may not be framed by anyone: it shows the code of your commits.
+const PAGE_HEADERS = { 'content-security-policy': "frame-ancestors 'none'" };
+function errorPage(res, status, message) {
+    send(res, status, 'text/html', `<!doctype html><meta charset="utf-8"><meta name="color-scheme" content="light dark"><pre style="white-space:pre-wrap;font:14px/1.5 system-ui;padding:16px">${escapeHtml(message)}</pre><p style="font:14px/1.5 system-ui;padding:0 16px"><a href="/">Back to the default view</a></p>`, { 'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'" });
+}
+// The commits of `head` the page shows when nothing else is chosen: those
+// beyond `base` (when a page can show them all), or else the newest one (as a sha, so a branch called "wip"
+// doesn't mean the snapshot).
+function defaultRev(head, base) {
+    if (!head)
+        return null;
+    if (base) {
+        // A range beyond what a page shows would only be an error page: show the newest commit.
+        const n = Number(git(['rev-list', '--count', '--end-of-options', `${base}..${head}`, '--']).trim());
+        if (n > 0 && n <= MAX_RANGE_COMMITS)
+            return `${base}..${head}`;
+    }
+    return gitTry(['rev-parse', '--verify', '--quiet', `${head}^{commit}`])?.trim() || null;
+}
+// The page for ?rev=&head=&base=. head and base only fill the pickers and
+// choose the default rev; the rev alone decides which commits are shown.
+function deskPage(url, res) {
+    const refs = listRefs();
+    const known = new Set([...refs.branches, ...refs.remotes]);
+    const wantHead = revParam(url, 'head', false);
+    const wantBase = revParam(url, 'base', false);
+    let rev = revParam(url, 'rev', false);
+    // The default base goes with the default branch.
+    const baseFor = (head) => (head === refs.defaultBase ? null : refs.defaultBase);
+    // A link or bookmark may name a branch that has since been deleted or
+    // renamed: use the usual choice instead, and say so.
+    let head = wantHead && known.has(wantHead) ? wantHead : null;
+    const fallback = refs.current || refs.defaultBase || refs.branches[0] || null;
+    let base;
+    let notice = null;
+    if (wantHead && !head) {
+        head = fallback;
+        base = baseFor(head);
+        notice = `Branch \u201c${wantHead}\u201d no longer exists; showing ${head ?? 'the default'} instead.`;
+    }
+    else if (wantBase && !known.has(wantBase)) {
+        head ??= fallback;
+        base = null;
+        notice = `The branch to compare with, \u201c${wantBase}\u201d, no longer exists; showing the newest commit of ${head ?? 'the default'}.`;
+    }
+    else if (head) {
+        base = wantBase;
+    }
+    else {
+        head = fallback;
+        base = wantBase ?? baseFor(head);
+    }
+    if (!rev) {
+        // Opening with nothing chosen shows the uncommitted work, if snapshotted;
+        // choosing a branch shows that branch.
+        const wip = !wantHead && !wantBase && gitTry(['rev-parse', '--verify', '--quiet', WIP_REF]);
+        rev = wip ? 'wip' : defaultRev(head, base);
+        if (!rev)
+            throw new GlossError(head ? `${head} has no commits to show` : 'there are no branches to show; pass ?rev= to view a commit');
+        if (!notice) {
+            const p = new URLSearchParams({ rev });
+            if (head)
+                p.set('head', head);
+            if (base)
+                p.set('base', base);
+            return send(res, 302, 'text/plain', 'redirecting', { location: `/?${p}` });
+        }
+    }
     // "wip" is the latest snapshot of uncommitted work. The server never takes
     // one (that is `git gloss hunks wip`): browsing doesn't change anything.
     const target = rev === 'wip' ? gitTry(['rev-parse', '--verify', '--quiet', WIP_REF])?.trim() : rev;
@@ -53,22 +109,14 @@ function viewPage(url) {
     if (shas.length > MAX_RANGE_COMMITS) {
         throw new GlossError(`${rev} has ${shas.length} commits; a page shows at most ${MAX_RANGE_COMMITS}. Pick a narrower range.`);
     }
-    return renderPage(buildPageData(shas, range, merges));
+    const data = buildPageData(shas, range, merges);
+    data.ary = { repo: refs.repo, branches: refs.branches, remotes: refs.remotes, defaultBase: refs.defaultBase, head, base, rev, notice };
+    send(res, 200, 'text/html', renderPage(data), PAGE_HEADERS);
 }
-function route(req, res, url) {
-    const shell = (name, type) => send(res, 200, type, asset(name), type === 'text/html' ? { 'content-security-policy': SHELL_CSP } : {});
-    switch (url.pathname) {
-        case '/': return shell('./index.html', 'text/html');
-        case '/ary.js': return shell('./client.js', 'text/javascript');
-        case '/ary.css': return shell('./style.css', 'text/css');
-        case '/api/refs': return sendJson(res, listRefs());
-        case '/api/log':
-            return sendJson(res, listLog(revParam(url, 'head'), revParam(url, 'base', false), intParam(url, 'limit', 100, 1, 500), intParam(url, 'skip', 0, 0, 1e6), (url.searchParams.get('q') ?? '').slice(0, 200)));
-        case '/view':
-            // The page may only be framed by the shell, not by another site.
-            return send(res, 200, 'text/html', viewPage(url), { 'content-security-policy': "frame-ancestors 'self'" });
-        default: return send(res, 404, 'text/plain', 'not found');
-    }
+function route(res, url) {
+    if (url.pathname === '/')
+        return deskPage(url, res);
+    send(res, 404, 'text/plain', 'not found');
 }
 export function createAry(port) {
     return createServer((req, res) => {
@@ -80,9 +128,16 @@ export function createAry(port) {
             return send(res, 403, 'text/plain', `forbidden host: this server answers to ${allowed.join(' and ')} (it listens on this machine only; through an SSH tunnel, forward the same port number)`);
         if (req.method !== 'GET' && req.method !== 'HEAD')
             return send(res, 405, 'text/plain', 'read-only', { allow: 'GET, HEAD' });
-        const url = new URL(req.url ?? '/', 'http://localhost');
         try {
-            route(req, res, url);
+            // A request target need not be a URL ("//[" is not), and a throw here would end the process.
+            let url;
+            try {
+                url = new URL(req.url ?? '/', 'http://localhost');
+            }
+            catch {
+                throw new BadRequest('not a valid request target');
+            }
+            route(res, url);
         }
         catch (err) {
             if (!(err instanceof GlossError)) {
@@ -90,12 +145,7 @@ export function createAry(port) {
                 return send(res, 500, 'text/plain', 'internal error');
             }
             const status = err instanceof BadRequest ? 400 : 422;
-            if (url.pathname === '/view') {
-                send(res, status, 'text/html', `<!doctype html><meta charset="utf-8"><meta name="color-scheme" content="light dark"><pre style="white-space:pre-wrap;font:14px/1.5 system-ui;padding:16px">${escapeHtml(err.message)}</pre>`, { 'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'self'" });
-            }
-            else {
-                send(res, status, 'application/json', JSON.stringify({ error: err.message }));
-            }
+            errorPage(res, status, err.message);
         }
     });
 }

package/dist/attention.js

@@ -0,0 +1,34 @@
+import { ATTENTION, IMPACT } from './schema.js';
+// Rank of a group's impact; a group with none is below every level.
+export const impactRank = (i) => (i ? IMPACT.indexOf(i) : -1);
+export const maxImpact = (a, b) => (impactRank(b) > impactRank(a) ? b : a);
+export const attentionRank = (a) => (a ? ATTENTION.indexOf(a) : -1);
+export const maxAttention = (a, b) => (attentionRank(b) > attentionRank(a) ? b : a);
+// One step up, capped at must-read.
+export const raise = (a) => ATTENTION[Math.min(ATTENTION.length - 1, ATTENTION.indexOf(a) + 1)];
+// The attention a given impact calls for, before any raising.
+const ATTENTION_FOR_IMPACT = {
+    local: 'skim', module: 'look', shared: 'careful', contract: 'careful', sensitive: 'must-read',
+};
+export const attentionForImpact = (i) => ATTENTION_FOR_IMPACT[i];
+// What the reviewer should do when glosses are combined (a squash, a rebase):
+// the highest level of any of them. Focus groups of all of them, renamed to
+// their new ids (`rename` returns undefined for a group that is gone), most
+// impactful first, without repeats, at most three. Reasons are unioned.
+export function combineAttention(parts, rename, groups) {
+    if (!parts.length)
+        return undefined;
+    const level = parts.map((p) => p.level).reduce((a, b) => (ATTENTION.indexOf(b) > ATTENTION.indexOf(a) ? b : a));
+    const impactOf = new Map(groups.map((g) => [g.id, g.impact]));
+    const focus = [...new Set(parts.flatMap((p, i) => (p.focus ?? []).flatMap((id) => rename(i, id) ?? [])))]
+        .sort((a, b) => impactRank(impactOf.get(b)) - impactRank(impactOf.get(a)))
+        .slice(0, 3);
+    const reasons = [...new Set(parts.flatMap((p) => p.reasons ?? []))];
+    const overrides = [...new Set(parts.flatMap((p) => (p.override_reason && p.level === level ? [p.override_reason] : [])))];
+    return {
+        level,
+        ...(focus.length ? { focus } : {}),
+        ...(reasons.length ? { reasons } : {}),
+        ...(overrides.length ? { override_reason: overrides.join('; ') } : {}),
+    };
+}

package/dist/carry.js

@@ -52,5 +52,8 @@ export function carryGloss(note, current, previous = []) {
     const byId = new Map(current.map((h) => [h.id, h]));
     const claims = groups.flatMap((g) => [...selections(g.hunks, (id) => { const h = byId.get(id); return h && changedCount(h); })]
         .flatMap(([id, lines]) => { const h = byId.get(id); return h ? [{ hunk: h, lines }] : []; }));
-    return { annotation: { ...a, groups }, kept: groups.length, total: a.groups.length, dropped, gaps: uncovered(current, claims), partialMatch };
+    // Focus groups that were left behind can't be pointed at.
+    const focus = a.attention?.focus?.filter((id) => keptIds.has(id));
+    const attention = a.attention && { ...a.attention, focus: focus?.length ? focus : undefined };
+    return { annotation: { ...a, groups, ...(attention ? { attention } : {}) }, kept: groups.length, total: a.groups.length, dropped, gaps: uncovered(current, claims), partialMatch };
 }

package/dist/cli.js

@@ -10,11 +10,12 @@ import * as review from './commands/review.js';
 import * as reviews from './commands/reviews.js';
 import * as schema from './commands/schema.js';
 import * as show from './commands/show.js';
+import * as signals from './commands/signals.js';
 import * as sync from './commands/sync.js';
 import * as versions from './commands/versions.js';
 import * as why from './commands/why.js';
 const COMMANDS = {
-    init, hunks, add, adopt, carry, show, html, ary, why, review, reviews, sync, versions, schema,
+    init, hunks, signals, add, adopt, carry, show, html, ary, why, review, reviews, sync, versions, schema,
 };
 function help() {
     return 'usage: git gloss <command> [options]\n\n' +