@ok-ggwp/git-gloss 0.6.0 → 0.7.0

package/dist/findings.js

@@ -28,7 +28,20 @@
 // Items are indent-0 `-`, `*`, `+`, `1.` or `1)` lines; indented sub-items and
 // wrapped lines are left alone, as are fenced code blocks, rules and empty
 // items. A numbered heading with no list under it keeps its own number as its
-// ref (`1`) and gets no label. Running it on its own output changes nothing.
+// ref (`1`, or `1/2` when `1` is taken) and its line is not rewritten. A section whose
+// first ref is already taken (a second `1.` heading with items) is labelled `S/N`, see
+// below. Running it on its own output changes nothing.
+// A section label is the section number, `1`. A section is labelled `S/N` (`1/2`, items
+// `1/2.1`, N from 2 to 999) only when a ref it would emit equals one already emitted: the
+// heading ref `1` of a list-less heading, or the first item ref `1.1` of a section with
+// items. Within a section a heading ref and an item ref never collide, so an empty
+// numbered heading, an unnumbered heading or a bold line uses no label up, and no ref the
+// old labeller produced changes. The one new ref: a list-less heading whose bare number
+// equals a loose item's (`- x` then `## 1.`) was unreachable before and now gets `1/2`. Past 999 repeats the label stays `S/999`
+// and the items keep counting on, so item refs stay distinct; only the heading row of such
+// a section without items has no row of its own (its ref is already taken).
+const MAX_REPEAT = 999;
+const repeatLabel = (num, n) => (n === 1 ? String(num) : `${num}/${n}`);
 const isDigit = (c) => c >= '0' && c <= '9';
 const MAXDIG = 6;
 // The section number at the start of a heading's text: up to 3 digits, then `.` or
@@ -129,10 +142,13 @@ function itemText(line) {
         return null;
     return line.slice(j);
 }
-// Drop a label this function wrote before: `**[1.2]** `.
+// Drop a label this function wrote before: `**[1.2]** ` or `**[1/2.2]** `.
 function stripLabel(t) {
     if (!t.startsWith('**['))
         return t;
+    const m = /^\*\*\[\d{1,3}\/\d{1,3}\.\d{1,6}\]\*\* */.exec(t.slice(0, 40));
+    if (m)
+        return t.slice(m[0].length);
     let i = 3;
     while (i < 20 && (isDigit(t[i] ?? '') || t[i] === '.'))
         i++;
@@ -148,9 +164,51 @@ function scan(text) {
     const lines = text.split('\n');
     // Each ref with its text (an item's, or a numbered heading's line); the first wins.
     const found = new Map();
-    const add = (ref, t) => { if (!found.has(ref))
-        found.set(ref, t); };
-    let section = 0, count = 0;
+    // The rows of a decision template: one per ref that was added, marked heading or item.
+    const rows = [];
+    // Refs a heading row could not take because another row has them (a template row lost, or a
+    // heading whose ref a decision would give to the other finding).
+    const clashes = new Set();
+    // `lost` marks a heading row that would have been listed: only then is a lost ref a clash.
+    const add = (ref, t, heading, lost = false) => {
+        if (found.has(ref)) {
+            if (lost)
+                clashes.add(ref);
+            return null;
+        }
+        found.set(ref, t);
+        const row = { ref, text: t, heading, hasItems: false };
+        rows.push(row);
+        return row;
+    };
+    // How many items each label has.
+    const counts = new Map();
+    // The first label of `num` whose first ref is not taken: the heading's own ref, or `.1`.
+    // Refs only get added, so a label found taken stays taken: each (number, kind) resumes
+    // from where it stopped, which keeps this linear in the number of sections.
+    const resume = new Map();
+    const pick = (num, forHeading) => {
+        const key = `${num}:${forHeading}`;
+        let k = resume.get(key) ?? 1;
+        while (k < MAX_REPEAT && found.has(forHeading ? repeatLabel(num, k) : `${repeatLabel(num, k)}.1`))
+            k++;
+        resume.set(key, k);
+        return repeatLabel(num, k);
+    };
+    // A numbered heading waits for its first item: with items it only names the section
+    // (the items are the findings), without it is a row of its own.
+    let pending = null;
+    const flush = (withItems = false) => {
+        if (!pending)
+            return;
+        const lab = pick(pending.num, true);
+        const row = add(lab, pending.text, true, !withItems);
+        if (row && withItems)
+            row.hasItems = true;
+        pending = null;
+    };
+    let section = 0;
+    let label = null;
     let sawHeading = false, sawNumbered = false, sawItem = false;
     let fence = null;
     for (let n = 0; n < lines.length; n++) {
@@ -167,18 +225,19 @@ function scan(text) {
             continue;
         const h = headingText(line) ?? boldOnly(line) ?? (plainTitle(lines, n) ? line : null);
         if (h !== null) {
+            flush();
             const num = leadingNumber(h);
             if (num !== null) {
                 section = num;
                 sawNumbered = true;
-                add(String(num), line.replace(/^[\s#*_]+/, '').replace(/^\d{1,3}[.)]?\s*/, '').replace(/[\s*_:]+$/, ''));
+                pending = { num, text: line.replace(/^[\s#*_]+/, '').replace(/^\d{1,3}[.)]?\s*/, '').replace(/[\s*_:]+$/, '') };
             }
             else if (!sawItem && !sawNumbered)
                 section = 0;
             else
                 section += 1;
+            label = null;
             sawHeading = true;
-            count = 0;
             continue;
         }
         const item = itemText(line);
@@ -186,13 +245,28 @@ function scan(text) {
             continue;
         if (section === 0 && sawHeading)
             section = 1;
+        // A heading numbered 0 keeps its own ref: it is not the section its items fall in.
+        if (pending && pending.num !== section)
+            flush(true);
         sawItem = true;
-        count++;
-        const ref = sawHeading ? `${section}.${count}` : String(count);
-        add(ref, stripLabel(item));
+        if (sawHeading && label === null) {
+            label = pick(section, false);
+            if (pending) {
+                const row = add(label, pending.text, true);
+                if (row)
+                    row.hasItems = true;
+                pending = null;
+            }
+        }
+        const key = label ?? '';
+        const k = (counts.get(key) ?? 0) + 1;
+        counts.set(key, k);
+        const ref = sawHeading ? `${label}.${k}` : String(k);
+        add(ref, stripLabel(item), false);
         lines[n] = `- **[${ref}]** ${stripLabel(item)}`;
     }
-    return { out: lines.join('\n'), found };
+    flush();
+    return { out: lines.join('\n'), found, rows, clashes: [...clashes] };
 }
 export function labelFindings(text) {
     return scan(text).out;
@@ -201,41 +275,62 @@ export function labelFindings(text) {
 export function findingRefs(text) {
     return new Set(scan(text).found.keys());
 }
-// Each ref a report carries, once, with the text of its finding (raw, for the caller to clean).
+// What a decision template lists: each finding's ref once, with its text (raw, for the
+// caller to clean). A numbered heading is listed only when no items sit under it; its
+// ref stays valid for a decision (findingRefs has it) but is not suggested.
+// Refs that more than one finding of a report claims, so a decision naming one is ambiguous.
+export function findingClashes(text) {
+    return scan(text).clashes;
+}
 export function findingTexts(text) {
-    return [...scan(text).found];
+    return scan(text).rows.filter((r) => !(r.heading && r.hasItems)).map((r) => [r.ref, r.text]);
 }
 // A decision's finding names a finding by starting with its ref: `1.2 wording nit`,
 // `1.2: ...`, or a bare section number only with a delimiter (`3: ...`, `3) ...`,
 // `3. ...`). Numbers are up to 3 digits, so `2024 migration` and `3 files` are text.
 export function refOf(finding) {
-    let i = 0;
-    while (i < 4 && isDigit(finding[i] ?? ''))
-        i++;
-    if (i === 0 || i > 3)
+    // The end of the digit run at `from` (1 to `max` digits), or null if there is none or it is longer.
+    const digits = (from, max) => {
+        let e = from;
+        while (e < from + max && isDigit(finding[e] ?? ''))
+            e++;
+        return e === from || isDigit(finding[e] ?? '') ? null : e;
+    };
+    let s = digits(0, 3);
+    if (s === null)
         return null;
-    if (finding[i] === '.') {
-        let j = i + 1;
-        while (j < i + 5 && isDigit(finding[j] ?? ''))
+    // The Nth occurrence of a section number: `1/2`, N from 2 to 999.
+    if (finding[s] === '/') {
+        const e = digits(s + 1, 3);
+        if (e === null || Number(finding.slice(s + 1, e)) < 2)
+            return null;
+        s = e;
+    }
+    if (finding[s] === '.') {
+        let j = s + 1;
+        while (j < s + 5 && isDigit(finding[j] ?? ''))
             j++;
-        if (j > i + 1 && j <= i + 4) {
+        if (j > s + 1 && j <= s + 4) {
             const c = finding[j];
             if (c === undefined || c === ' ' || c === '\t' || c === ':')
                 return finding.slice(0, j);
         }
     }
-    const c = finding[i];
+    const c = finding[s];
     if (c === ':' || c === ')')
-        return finding.slice(0, i);
-    if (c === '.' && (finding[i + 1] === undefined || finding[i + 1] === ' '))
-        return finding.slice(0, i);
+        return finding.slice(0, s);
+    if (c === '.' && (finding[s + 1] === undefined || finding[s + 1] === ' '))
+        return finding.slice(0, s);
     return null;
 }
-function compareRefs(a, b) {
-    const [a1, a2 = '-1'] = a.split('.');
-    const [b1, b2 = '-1'] = b.split('.');
-    return Number(a1) - Number(b1) || Number(a2) - Number(b2);
-}
+// `1` < `1.1` < `1.10` < `1/2` < `1/2.1` < `2`: section number, then repeat, then item.
+// Only refs from refOf reach this.
+const refKey = (r) => {
+    const [sec, item = '-1'] = r.split('.');
+    const [num, rep = '1'] = sec.split('/');
+    return { num: Number(num), rep: Number(rep), item: Number(item) };
+};
+const compareKeys = (x, y) => x.num - y.num || x.rep - y.rep || x.item - y.item;
 // Finding order: decisions whose finding starts with a ref, by ref (1.2 before
 // 1.10, ties by time); the rest after them in time order.
 export function orderDecisions(input) {
@@ -247,8 +342,8 @@ export function orderDecisions(input) {
         if (r === null)
             rest.push(d);
         else
-            withRef.push([r, d]);
+            withRef.push([refKey(r), d]);
     }
-    withRef.sort((a, b) => compareRefs(a[0], b[0]));
+    withRef.sort((a, b) => compareKeys(a[0], b[0]));
     return [...withRef.map((x) => x[1]), ...rest];
 }

package/dist/git.js

@@ -1,8 +1,8 @@
 import { execFileSync } from 'node:child_process';
-import { copyFileSync, existsSync, mkdtempSync, rmSync, statSync, utimesSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, 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 { Annotation, MAX_NOTE_BYTES, NOTE_FORMAT } from './schema.js';
 import { parsePath, unquote } from './diff.js';
 import { plain } from './plain.js';
 export const NOTES_REF = 'refs/notes/gloss';
@@ -21,10 +21,33 @@ export class GlossError extends Error {
 export class GitError extends GlossError {
     // git's exit code, when it ran and failed (1 is often "no", 128 a real failure).
     status;
+    // The call was killed at GIT_GLOSS_GIT_TIMEOUT: unlike a failure, not an answer.
+    timedOut = false;
 }
-export function git(args, input, env = {}) {
+// How long one git call may run before it is killed (ms; 0 = no limit). A
+// hung git (a stuck filesystem, a credential helper, a lock) would otherwise
+// hang git-gloss for good. Read once at load: GIT_GLOSS_GIT_TIMEOUT overrides;
+// a value that is not a non-negative number is ignored.
+// A timed-out git gets SIGTERM, not SIGKILL: git removes its lock files
+// (index.lock, a ref's .lock) on SIGTERM, while SIGKILL would leave one that
+// fails every later command. A git that ignores SIGTERM is waited for, with
+// no second-stage kill (execFileSync only returns when the child ends), so
+// such a git still hangs git-gloss.
+// Network calls (fetch, push, ls-remote) get NETWORK_TIMEOUT (600 s) instead:
+// a slow link would otherwise fail at 120 s and every retry would fail again.
+// GIT_GLOSS_NETWORK_TIMEOUT (ms, 0 = none) sets that limit alone; failing it,
+// GIT_GLOSS_GIT_TIMEOUT, when set, applies to both.
+export function parseGitTimeout(raw, fallback = 120_000) {
+    const n = raw === undefined || raw.trim() === '' ? NaN : Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+const GIT_TIMEOUT = parseGitTimeout(process.env.GIT_GLOSS_GIT_TIMEOUT);
+export const NETWORK_TIMEOUT = parseGitTimeout(process.env.GIT_GLOSS_NETWORK_TIMEOUT, parseGitTimeout(process.env.GIT_GLOSS_GIT_TIMEOUT, 600_000));
+export function git(args, input, env = {}, limit = GIT_TIMEOUT) {
     try {
         return execFileSync('git', args, {
+            timeout: limit,
+            killSignal: 'SIGTERM',
             encoding: 'utf8',
             input,
             // Untranslated messages: readNote recognises "no note found" by its text.
@@ -34,17 +57,45 @@ export function git(args, input, env = {}) {
         });
     }
     catch (err) {
+        if (err.code === 'ETIMEDOUT') {
+            const what = plain(args.slice(0, 3).join(' ')).slice(0, 80);
+            const t = new GitError(`git ${what} timed out after ${limit / 1000} s (set GIT_GLOSS_GIT_TIMEOUT to change the limit)`);
+            t.timedOut = true;
+            throw t;
+        }
         const stderr = err.stderr?.trim();
         const e = new GitError(stderr || `git ${args.join(' ')} failed`);
         e.status = typeof err.status === 'number' ? err.status : undefined;
         throw e;
     }
 }
-export function gitTry(args, input) {
+// For a catch that turns a git failure into a value ("no gloss", "unreadable",
+// "use the defaults"): a git killed at the time limit gave no answer, so the
+// timeout goes on to the caller rather than become that value.
+export function rethrowTimeout(err) {
+    if (err instanceof GitError && err.timedOut)
+        throw err;
+}
+// Best-effort cleanup (a temporary ref in a `finally`, or after success): never
+// throws, not even on a timeout, so it can't fail a finished job or replace the
+// first error. A timeout leaves one warning line.
+export function gitCleanup(args) {
     try {
-        return git(args, input);
+        git(args);
     }
-    catch {
+    catch (err) {
+        if (err instanceof GitError && err.timedOut)
+            process.stderr.write(`warning: cleanup timed out, a temporary ref may be left (git ${args.join(' ')})\n`);
+    }
+}
+export function gitTry(args, input, limit = GIT_TIMEOUT) {
+    try {
+        return git(args, input, {}, limit);
+    }
+    catch (err) {
+        // Any failure is "no" (callers probe with this), but a git killed at the
+        // time limit gave no answer: say so rather than let it read as "no".
+        rethrowTimeout(err);
         return null;
     }
 }
@@ -59,11 +110,30 @@ const looksSensitive = (path) => SENSITIVE.some((re) => re.test(path.split('/').
 // 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 READ_ONLY_MAX_UNTRACKED = 5000;
+// One deadline for the whole read-only check, every git call in it included.
+const READ_ONLY_TOTAL_MS = 10_000;
+class TooBig extends Error {
+}
+// A git runner for the read-only check: every call gets what is left of one total deadline
+// (none left: TooBig), and never more than the usual limit.
+function deadlineRun(totalMs) {
+    const end = Date.now() + totalMs;
+    return (args, env = {}) => {
+        const left = end - Date.now();
+        if (left <= 0)
+            throw new TooBig();
+        return git(args, undefined, env, GIT_TIMEOUT ? Math.min(left, GIT_TIMEOUT) : left);
+    };
+}
+// `bounded`: the read-only check (see wipStaleness): its runner, and nothing is written to the repo.
+function workingTree(bounded) {
     const dir = mkdtempSync(join(tmpdir(), 'git-gloss-index-'));
+    const readOnly = !!bounded;
+    const run = bounded ?? ((args, env = {}) => git(args, undefined, env));
     try {
         const index = join(dir, 'index');
-        const real = git(['rev-parse', '--path-format=absolute', '--git-path', 'index']).trim();
+        const real = run(['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
@@ -73,12 +143,20 @@ function workingTree() {
             utimesSync(index, atime, mtime);
         }
         const env = { GIT_INDEX_FILE: index };
-        const untracked = git(['ls-files', '--others', '--exclude-standard', '-z', '--', ':/']).split('\0').filter(Boolean);
+        const untracked = run(['ls-files', '--others', '--exclude-standard', '-z', '--', ':/']).split('\0').filter(Boolean);
         const excluded = untracked.filter(looksSensitive);
-        git(['add', '-A', '--', ':/'], undefined, env);
+        if (readOnly) {
+            if (untracked.length > READ_ONLY_MAX_UNTRACKED)
+                throw new TooBig();
+            // New objects go to the temporary directory (removed below); the repo's own are only read.
+            mkdirSync(join(dir, 'objects'));
+            env.GIT_OBJECT_DIRECTORY = join(dir, 'objects');
+            env.GIT_ALTERNATE_OBJECT_DIRECTORIES = run(['rev-parse', '--path-format=absolute', '--git-path', 'objects']).trim();
+        }
+        run(['add', '-A', '--', ':/'], env);
         if (excluded.length)
-            git(['rm', '-q', '--cached', '--', ...excluded.map((p) => `:/${p}`)], undefined, env);
-        return { tree: git(['write-tree'], undefined, env).trim(), excluded };
+            run(['rm', '-q', '--cached', '--', ...excluded.map((p) => `:/${p}`)], env);
+        return { tree: run(['write-tree'], env).trim(), excluded };
     }
     finally {
         rmSync(dir, { recursive: true, force: true });
@@ -139,13 +217,35 @@ export function archiveSnapshot(sha) {
 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;
+// `readOnly` (the ary server): writes nothing to the repository (the check's objects go to a
+// temporary directory), and ONE total deadline covers every git call in it. If that runs out, or
+// git fails, or the tree is too big, the answer is undefined ("could not check"): it is advisory.
+export function wipStaleness(sha, readOnly = false) {
+    if (!readOnly) {
+        const s = treeAndParent(sha);
+        if (s.parent !== headSha())
+            return 'HEAD has moved since this snapshot was taken';
+        return workingTree().tree !== s.tree ? 'the working tree has changed since this snapshot was taken' : null;
+    }
+    try {
+        const run = deadlineRun(READ_ONLY_TOTAL_MS);
+        const [tree, parent] = run(['log', '-1', '--format=%T %P', sha]).trim().split(' ');
+        let head = null; // no commits yet: no HEAD
+        try {
+            head = run(['rev-parse', '--verify', '--quiet', 'HEAD']).trim();
+        }
+        catch (err) {
+            rethrowTimeout(err);
+            if (err instanceof TooBig)
+                throw err;
+        }
+        if ((parent || null) !== (head || null))
+            return 'HEAD has moved since this snapshot was taken';
+        return workingTree(run).tree !== tree ? 'the working tree has changed since this snapshot was taken' : null;
+    }
+    catch {
+        return undefined;
+    }
 }
 // The diff of uncommitted work against HEAD, as a snapshot would have it,
 // without taking a snapshot: no ref is written (only objects). Hunk ids match
@@ -185,19 +285,28 @@ export function resolveCommit(rev) {
 // 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) {
+// `newest`: keep only the newest that many non-merge commits (and the merges since the oldest of
+// them); `total` is how many there were. The rev-list still walks the whole range.
+export function resolveCommits(arg, newest = Infinity) {
     if (!arg.includes('..'))
-        return { shas: [resolveCommit(arg)], merges: [], range: null };
+        return { shas: [resolveCommit(arg)], merges: [], range: null, total: 1 };
     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)
+    const plain = list('--no-merges');
+    let merges = list('--merges');
+    if (!plain.length && !merges.length)
         throw new GitError(`no commits in ${arg}`);
-    return { shas, merges, range: arg };
+    const shas = plain.slice(-newest);
+    if (shas.length < plain.length) {
+        // Keep the merges after the oldest shown commit, in the order of the whole range.
+        const all = list();
+        const keep = new Set(all.slice(all.indexOf(shas[0])));
+        merges = merges.filter((c) => keep.has(c));
+    }
+    return { shas, merges, range: arg, total: plain.length };
 }
 export function commitSubject(sha) {
     return git(['log', '-1', '--format=%s', sha]).trim();
@@ -238,12 +347,22 @@ function cleanStrings(v) {
         return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, cleanStrings(x)]));
     return v;
 }
+// A note's total size, which no other cap bounds (each cost is linear in it, but
+// 60 MB took seconds, and the hunk records are not capped by count).
+export const noteSizeProblem = (bytes) => bytes > MAX_NOTE_BYTES ? `${(bytes / 1024 / 1024).toFixed(1)} MiB, over the size limit of ${MAX_NOTE_BYTES / 1024 / 1024} MiB (MAX_NOTE_BYTES in src/schema.ts)` : null;
 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)}`;
+    return parseNote(raw, `the gloss on ${sha.slice(0, 10)}`);
+}
+// A stored gloss's text as a note, or a GlossError saying why it can't be one
+// (`at` names it in the message). Also used for glosses read from the notes history.
+export function parseNote(raw, at) {
+    const big = noteSizeProblem(Buffer.byteLength(raw));
+    if (big)
+        throw new GlossError(`${at} is ${big}; replace it with \`git gloss add --force\``);
     let data;
     try {
         data = JSON.parse(raw);
@@ -268,7 +387,12 @@ export function readNote(sha) {
     return { ...data, annotation: cleanStrings(annotation.data) };
 }
 export function writeNote(sha, note, ref = NOTES_REF) {
-    git(['notes', '--ref', ref, 'add', '-f', '-F', '-', sha], JSON.stringify(note, null, 2) + '\n');
+    const text = JSON.stringify(note, null, 2) + '\n';
+    // Readers refuse a bigger note, so it is not written.
+    const big = noteSizeProblem(Buffer.byteLength(text));
+    if (big)
+        throw new GlossError(`the gloss is ${big}; write less text, or fewer or smaller groups`);
+    git(['notes', '--ref', ref, 'add', '-f', '-F', '-', sha], text);
 }
 // The commits that changed lines start..end of `file`, newest first, starting
 // from `commit`, following them through edits, moves within the file and

package/dist/html/client.js

@@ -492,8 +492,10 @@
     if (!multi && state.kind === 'group' && dir < 0 && !neighbor(-1)) { selectKind(0, 'overview'); return }
     if (multi && state.kind !== 'group') {
       var order = commitOrder()
-      var next = order[order.indexOf(state.ci) + dir]
-      if (next !== undefined) selectKind(next, 'overview')
+      // The nearest commit the filter shows, not one it hides.
+      for (var j = order.indexOf(state.ci) + dir; j >= 0 && j < order.length; j += dir) {
+        if (!commitHidden(order[j])) { selectKind(order[j], 'overview'); break }
+      }
       return
     }
     var id = neighbor(dir)
@@ -653,6 +655,7 @@
   function unannotatedBox(c) {
     var box = add(el('div', 'unannotated'), el('p', null, c.glossed
       ? 'These changes are in the commit but no group explains them.'
+      : c.glossRefused ? 'This commit\'s gloss was refused, so nothing explains these changes.'
       : 'This commit has no gloss, so nothing explains these changes.'))
     c.unannotated.forEach(function (h) { box.appendChild(hunkView(c, h, 'un')) })
     return box
@@ -714,9 +717,10 @@
     if (multi) add(pane, el('div', 'eyebrow', 'Commit ' + (ci + 1) + ' of ' + commits.length + ' · ' + new Date(c.date).toLocaleDateString()))
     add(pane, el('h1', 'title', c.subject), commitMeta(c))
     if (!c.glossed) {
-      var w = add(el('section', 'warnbox'), el('div', 't', 'No gloss on this commit'),
+      var w = add(el('section', 'warnbox'), el('div', 't', c.glossRefused ? 'Gloss refused on this commit' : 'No gloss on this commit'),
+        c.glossRefused ? el('p', null, 'The gloss on this commit was refused: ' + c.glossRefused) : null,
         el('p', null, 'Its whole diff is unannotated, so there is no attention level, no groups and no reasons to read.'),
-        el('p', 'cmd', 'git gloss add ' + sha7(c)))
+        el('p', 'cmd', 'git gloss add ' + sha7(c) + (c.glossRefused ? ' --force' : '')))
       add(pane, w)
       add(pane, changesHead('Changes (' + c.unannotated.length + ')'), unannotatedBox(c))
       return pane
@@ -953,7 +957,7 @@
     })
     var box = add(el('div', 'sum'), el('div', 'eyebrow', 'Range at a glance'), strip, line)
     var top = commits[order[0]]
-    if (levelOf(top).level) {
+    if (top && levelOf(top).level) {
       var link = el('a', null, sha7(top) + ' ' + top.subject)
       link.href = '#c-' + sha7(top)
       link.addEventListener('click', function (ev) { ev.preventDefault(); selectKind(order[0], 'overview') })
@@ -962,13 +966,51 @@
     return box
   }
 
+  // The box above a range's commit list. Matching is plain text (lower-cased `includes` on the
+  // short sha, subject and author), never a pattern or markup. The one input is kept across
+  // re-renders so what was typed stays; it is not saved anywhere, so a reload clears it.
+  var railRows = []
+  var filterBox = null
+  var noMatch = el('div', 'emptyrows', 'No commits match.')
+  function commitHidden(ci) {
+    return railRows.some(function (r) { return r.ci === ci && r.node.hidden })
+  }
+  function applyCommitFilter() {
+    var q = filterBox.value.trim().toLowerCase()
+    var shown = 0
+    railRows.forEach(function (r) {
+      var hit = !q || r.text.indexOf(q) >= 0
+      r.node.hidden = !hit
+      if (hit) shown++
+    })
+    noMatch.hidden = !q || !!shown
+  }
+  function commitFilter() {
+    if (!filterBox) {
+      filterBox = el('input')
+      filterBox.type = 'search'
+      filterBox.spellcheck = false
+      filterBox.placeholder = 'Filter commits'
+      filterBox.setAttribute('aria-label', 'Filter commits by message, author or sha')
+      filterBox.addEventListener('input', applyCommitFilter)
+    }
+    return add(el('div', 'cfilter'), filterBox, noMatch)
+  }
+
   function renderRail() {
     railEl.textContent = ''
     if (multi) {
       add(railEl, railSummary(), add(el('div', 'railhead'), el('div', 'eyebrow', state.hot ? 'Hottest first, then newest' : 'Newest first')))
       var list = el('div', 'commits')
-      commitOrder().forEach(function (ci) { list.appendChild(commitRow(ci)) })
-      add(railEl, list)
+      railRows = []
+      commitOrder().forEach(function (ci) {
+        var row = commitRow(ci)
+        var c = commits[ci]
+        railRows.push({ ci: ci, node: row, text: (sha7(c) + ' ' + c.subject + ' ' + c.author).toLowerCase() })
+        list.appendChild(row)
+      })
+      add(railEl, commitFilter(), list)
+      applyCommitFilter()
       if (data.merges.length) {
         var ml = add(el('div', 'mergelist'), el('div', 'eyebrow', 'Merges, not reviewed'))
         data.merges.forEach(function (m) { ml.appendChild(add(el('div'), el('span', 'mono', m.sha.slice(0, 7)), text(' ' + m.subject))) })