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

package/dist/html/data.js

@@ -0,0 +1,134 @@
+import { commitDiff, commitSubject, git } from '../git.js';
+import { parseDiff } from '../diff.js';
+import { loadGloss } from '../loader.js';
+import { bodyLines, changedCount, gapText, isGap, refLabel, slice, sliceStats } from '../selection.js';
+import { NECESSITY, NECESSITY_HELP, servesOf } from '../schema.js';
+// The lines to show for a selection: the @@ header, then the slice, with
+// changed lines that belong to other groups collapsed into gap rows.
+export function pageLines(h, selected) {
+    const body = bodyLines(h);
+    if (body.every((l) => l.kind === 'meta'))
+        return body.map((l) => ({ kind: 'meta', old: null, new: null, text: l.raw }));
+    const header = { kind: 'meta', old: null, new: null, text: h.text.split('\n')[0] };
+    return [header, ...slice(body, selected).map((l) => isGap(l)
+            ? { kind: 'gap', old: null, new: null, text: gapText(l.gap) }
+            : { kind: l.kind, old: l.oldNo, new: l.newNo, text: l.kind === 'meta' ? l.raw : l.raw.slice(1) })];
+}
+// A glossed hunk that is no longer in the commit: shown as a placeholder so
+// the reader can see what the gloss refers to, rather than it vanishing.
+function missingHunk(h) {
+    const s = h.stored;
+    return {
+        id: h.id,
+        ref: refLabel(h.id, h.lines),
+        file: s?.file ?? '?',
+        oldFile: s?.oldFile && s.oldFile !== s.file ? s.oldFile : null,
+        range: s && (s.newLines || s.oldLines) ? `-${s.oldStart},${s.oldLines} +${s.newStart},${s.newLines}` : '',
+        status: 'missing',
+        added: 0,
+        removed: 0,
+        alsoIn: [],
+        lines: [],
+    };
+}
+function pageHunk(h, lines, status, alsoIn) {
+    const counts = sliceStats(h, lines);
+    return {
+        id: h.id,
+        ref: refLabel(h.id, lines),
+        file: h.file,
+        oldFile: h.oldFile && h.oldFile !== h.file ? h.oldFile : null,
+        range: h.newLines || h.oldLines ? `-${h.oldStart},${h.oldLines} +${h.newStart},${h.newLines}` : 'file header',
+        status,
+        added: counts.added,
+        removed: counts.removed,
+        alsoIn,
+        lines: pageLines(h, lines),
+    };
+}
+const allLines = (h) => Array.from({ length: changedCount(h) }, (_, i) => i + 1);
+export function commitData(gloss) {
+    const [author, date] = git(['log', '-1', '--format=%an%x00%aI', gloss.sha]).trim().split('\0');
+    const a = gloss.note.annotation;
+    // Which groups claim each changed line, so shared lines are split between
+    // their groups in the bar and each hunk can link to the groups it shares
+    // lines with. A header-only hunk counts as one shared unit.
+    const owners = new Map();
+    const claimed = (h, lines) => (changedCount(h) ? [...(lines ?? allLines(h))] : [0]);
+    for (const g of gloss.groups) {
+        for (const h of g.hunks) {
+            if (!h.current)
+                continue;
+            const byLine = owners.get(h.current) ?? new Map();
+            for (const i of claimed(h.current, h.lines))
+                byLine.set(i, [...(byLine.get(i) ?? []), g.group.id]);
+            owners.set(h.current, byLine);
+        }
+    }
+    const groups = gloss.groups
+        .map(({ group: g, hunks }) => {
+        const live = hunks.filter((h) => h.current !== null);
+        const counts = live.map((h) => sliceStats(h.current, h.lines));
+        const shares = (h) => claimed(h.current, h.lines).map((i) => owners.get(h.current).get(i));
+        return {
+            id: g.id,
+            intent: g.intent,
+            necessity: g.necessity,
+            serves: servesOf(g),
+            removal_impact: g.removal_impact,
+            evidence: g.evidence,
+            notes: g.notes,
+            stale: hunks.filter((h) => h.status !== 'ok').length,
+            total: hunks.length,
+            added: counts.reduce((n, c) => n + c.added, 0),
+            removed: counts.reduce((n, c) => n + c.removed, 0),
+            weight: live.reduce((n, h) => n + (changedCount(h.current) ? shares(h).reduce((w, o) => w + 1 / o.length, 0) : 0), 0),
+            hunks: hunks.map((h) => h.current
+                ? pageHunk(h.current, h.lines, h.status, [...new Set(shares(h).flat())].filter((id) => id !== g.id))
+                : missingHunk(h)),
+        };
+    })
+        .sort((x, y) => NECESSITY.indexOf(x.necessity) - NECESSITY.indexOf(y.necessity));
+    return {
+        sha: gloss.sha,
+        subject: gloss.subject,
+        author,
+        date,
+        glossed: true,
+        task: a.task,
+        summary: a.summary,
+        warnings: gloss.warnings,
+        groups,
+        unannotated: gloss.unannotated.map((u) => pageHunk(u.hunk, u.lines, 'unannotated', [])),
+        alternatives: a.alternatives ?? [],
+        risks: a.risks ?? [],
+    };
+}
+function unglossedData(sha) {
+    const [author, date] = git(['log', '-1', '--format=%an%x00%aI', sha]).trim().split('\0');
+    return {
+        sha,
+        subject: commitSubject(sha),
+        author,
+        date,
+        glossed: false,
+        task: '',
+        warnings: [],
+        groups: [],
+        unannotated: parseDiff(commitDiff(sha)).map((h) => pageHunk(h, null, 'unannotated', [])),
+        alternatives: [],
+        risks: [],
+    };
+}
+export function buildPageData(shas, range = null, merges = []) {
+    return {
+        range,
+        merges: merges.map((sha) => ({ sha, subject: commitSubject(sha) })),
+        necessity: NECESSITY.map((name) => ({ name, help: NECESSITY_HELP[name] })),
+        commits: shas.map((sha) => {
+            const gloss = loadGloss(sha);
+            return gloss ? commitData(gloss) : unglossedData(sha);
+        }),
+        generated: new Date().toISOString(),
+    };
+}

package/dist/html/page.js

@@ -0,0 +1,35 @@
+import { randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+const asset = (name) => readFileSync(new URL(name, import.meta.url), 'utf8');
+// JSON inside a <script> element: escape "<" so no string in the data, such as
+// "</script>", can end the element early.
+export function embedJson(data) {
+    return JSON.stringify(data).replace(/</g, '\\u003c');
+}
+const escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+export function renderPage(data) {
+    // The page only runs our own inline script. If escaping ever failed, an
+    // injected script would lack the nonce and the CSP would block it.
+    const nonce = randomBytes(16).toString('base64');
+    const csp = `default-src 'none'; style-src 'nonce-${nonce}'; script-src 'nonce-${nonce}'`;
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="${csp}">
+<title>${data.range ? `gloss ${escapeHtml(data.range)} (${data.commits.length} commit${data.commits.length === 1 ? '' : 's'})` : `gloss ${escapeHtml(data.commits[0].sha.slice(0, 7))}: ${escapeHtml(data.commits[0].subject)}`}</title>
+<style nonce="${nonce}">
+${asset('./style.css')}
+</style>
+</head>
+<body>
+<div id="app"><noscript>This page needs JavaScript to render the gloss.</noscript></div>
+<script type="application/json" id="gloss-data">${embedJson(data)}</script>
+<script nonce="${nonce}">
+${asset('./client.js')}
+</script>
+</body>
+</html>
+`;
+}

package/dist/html/style.css

@@ -0,0 +1,220 @@
+:root {
+  --bg: #f7f7f5;
+  --surface: #ffffff;
+  --surface-2: #f1f1ee;
+  --border: #e2e2dc;
+  --text: #1d1d1b;
+  --muted: #6b6b66;
+  --accent: #3b5bdb;
+  --warn-bg: #fff4e5;
+  --warn-border: #f0b35b;
+  --warn-text: #7a4300;
+  --add-bg: #e6f6ea;
+  --add-mark: #1a7f37;
+  --del-bg: #fcebec;
+  --del-mark: #c62a2f;
+  --meta-bg: #eef1f8;
+  --meta-text: #4a5a85;
+
+  --n-required: #1f8a4c;
+  --n-supporting: #0f7f8f;
+  --n-defensive: #3b5bdb;
+  --n-incidental: #b7791f;
+  --n-speculative: #9c36b5;
+  --n-mechanical: #868e96;
+
+  --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace;
+  --sans: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  color-scheme: light;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #151514;
+    --surface: #1e1e1c;
+    --surface-2: #262624;
+    --border: #34342f;
+    --text: #e8e8e3;
+    --muted: #9a9a92;
+    --accent: #8ea2ff;
+    --warn-bg: #33270f;
+    --warn-border: #a2701e;
+    --warn-text: #f3c77a;
+    --add-bg: #15301e;
+    --add-mark: #5ccf7f;
+    --del-bg: #3a1a1c;
+    --del-mark: #ff7b80;
+    --meta-bg: #20263a;
+    --meta-text: #a3b1dc;
+
+    --n-required: #4cc27a;
+    --n-supporting: #33b5c4;
+    --n-defensive: #7d93ff;
+    --n-incidental: #e0a43e;
+    --n-speculative: #cf7ee4;
+    --n-mechanical: #8d949b;
+    color-scheme: dark;
+  }
+}
+
+* { box-sizing: border-box; }
+html { -webkit-text-size-adjust: 100%; }
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--text);
+  font: 15px/1.55 var(--sans);
+}
+main { min-width: 0; }
+a { color: var(--accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+code, .mono { font-family: var(--mono); font-size: 0.86em; }
+
+.layout {
+  display: grid;
+  /* minmax(0, …) so a wide diff scrolls inside its box instead of widening the page */
+  grid-template-columns: minmax(0, 1fr);
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 24px 16px 64px;
+  gap: 32px;
+}
+@media (min-width: 1100px) {
+  .layout { grid-template-columns: 240px minmax(0, 1fr); padding: 32px 32px 80px; }
+}
+
+/* Sidebar */
+.toc { display: none; }
+@media (min-width: 1100px) {
+  .toc { display: block; position: sticky; top: 24px; align-self: start; max-height: calc(100vh - 48px); overflow: auto; }
+}
+.toc h2 { font-size: 12px; text-transform: uppercase; letter-spacing: 0.06em; color: var(--muted); margin: 0 0 8px; }
+.toc ol { list-style: none; margin: 0 0 24px; padding: 0; }
+.toc li a {
+  display: flex; align-items: center; gap: 8px;
+  padding: 4px 8px; border-radius: 6px; color: var(--text);
+  font-family: var(--mono); font-size: 12.5px;
+}
+.toc li a:hover { background: var(--surface-2); text-decoration: none; }
+.toc li.hidden a { opacity: 0.35; }
+.toc li.active a { background: var(--surface-2); }
+
+.dot { width: 8px; height: 8px; border-radius: 50%; flex: none; background: var(--c); }
+
+/* Header */
+.commit { display: flex; flex-wrap: wrap; align-items: baseline; gap: 4px 12px; color: var(--muted); font-size: 13px; }
+.sha { font-family: var(--mono); background: var(--surface-2); border: 1px solid var(--border); padding: 1px 6px; border-radius: 5px; color: var(--text); }
+h1 { font-size: 24px; line-height: 1.3; margin: 8px 0 16px; letter-spacing: -0.01em; }
+.statement { margin: 0 0 8px; max-width: 75ch; }
+.statement .label { color: var(--muted); font-size: 12px; text-transform: uppercase; letter-spacing: 0.06em; margin-right: 6px; }
+
+.warning {
+  margin: 16px 0; padding: 12px 14px; border-radius: 8px;
+  background: var(--warn-bg); border: 1px solid var(--warn-border); color: var(--warn-text);
+}
+
+/* Necessity overview */
+.overview { margin: 24px 0 8px; }
+.bar { display: flex; height: 10px; border-radius: 5px; overflow: hidden; background: var(--surface-2); }
+.bar span { display: block; height: 100%; background: var(--c); min-width: 2px; }
+.bar span + span { border-left: 2px solid var(--bg); }
+.chips { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 12px; }
+.chip {
+  display: inline-flex; align-items: center; gap: 6px;
+  border: 1px solid var(--border); background: var(--surface); color: var(--text);
+  border-radius: 999px; padding: 4px 10px; font: inherit; font-size: 13px; cursor: pointer;
+}
+.chip .count { color: var(--muted); font-variant-numeric: tabular-nums; }
+.chip[aria-pressed="false"] { opacity: 0.45; }
+.chip[aria-pressed="false"] .dot { background: transparent; border: 1.5px solid var(--c); }
+.overview .note { color: var(--muted); font-size: 12.5px; margin-top: 8px; }
+
+.toolbar { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 8px; margin: 24px 0 12px; }
+.toolbar .shown { color: var(--muted); font-size: 13px; }
+.btn {
+  border: 1px solid var(--border); background: var(--surface); color: var(--text);
+  border-radius: 6px; padding: 4px 10px; font: inherit; font-size: 13px; cursor: pointer;
+}
+.btn:hover { background: var(--surface-2); }
+
+/* Group cards */
+.group {
+  background: var(--surface); border: 1px solid var(--border); border-left: 4px solid var(--c);
+  border-radius: 8px; margin: 0 0 12px; scroll-margin-top: 16px;
+}
+.group:focus-visible, .group.focused { outline: 2px solid var(--accent); outline-offset: 2px; }
+.group.hidden { display: none; }
+.group-head { padding: 14px 16px 4px; }
+.group-title { display: flex; flex-wrap: wrap; align-items: baseline; gap: 4px 10px; }
+.badge {
+  font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em;
+  color: var(--c); border: 1px solid var(--c); border-radius: 4px; padding: 0 5px;
+}
+.intent { font-weight: 600; font-size: 16px; overflow-wrap: anywhere; }
+.gid { font-family: var(--mono); font-size: 12.5px; color: var(--muted); }
+.stats { margin-left: auto; font-family: var(--mono); font-size: 12.5px; color: var(--muted); white-space: nowrap; }
+.plus { color: var(--add-mark); }
+.minus { color: var(--del-mark); }
+.stale { font-size: 12px; color: var(--warn-text); background: var(--warn-bg); border-radius: 4px; padding: 0 6px; }
+
+.facts { margin: 8px 0 0; padding: 0 16px 12px; display: grid; grid-template-columns: max-content 1fr; gap: 4px 12px; font-size: 14px; }
+.facts dt { color: var(--muted); font-size: 12.5px; padding-top: 1px; }
+.facts dd { margin: 0; max-width: 80ch; overflow-wrap: anywhere; }
+@media (max-width: 600px) {
+  .facts { grid-template-columns: 1fr; }
+  .facts dd { margin-bottom: 6px; }
+  .stats { margin-left: 0; }
+}
+
+.code-toggle {
+  display: block; width: 100%; text-align: left; border: 0; border-top: 1px solid var(--border);
+  background: transparent; color: var(--muted); font: inherit; font-size: 13px; padding: 8px 16px; cursor: pointer;
+  border-radius: 0 0 8px 0;
+}
+.code-toggle:hover { background: var(--surface-2); color: var(--text); }
+.code { border-top: 1px solid var(--border); padding: 12px 16px 16px; }
+.code[hidden] { display: none; }
+
+/* Hunks */
+.hunk { border: 1px solid var(--border); border-radius: 6px; overflow: hidden; margin: 0 0 12px; }
+.hunk:last-child { margin-bottom: 0; }
+.hunk-head {
+  display: flex; flex-wrap: wrap; align-items: center; gap: 4px 10px;
+  padding: 6px 10px; background: var(--surface-2); border-bottom: 1px solid var(--border); font-size: 12.5px;
+}
+.hunk-head .file { font-family: var(--mono); font-weight: 600; overflow-wrap: anywhere; }
+.hunk-head .range { font-family: var(--mono); color: var(--muted); }
+.also { color: var(--muted); }
+.also a { font-family: var(--mono); }
+.scroll { overflow-x: auto; }
+table.diff { border-collapse: collapse; width: 100%; font-family: var(--mono); font-size: 12.5px; line-height: 1.5; }
+table.diff td { padding: 0 8px; vertical-align: top; }
+td.ln { width: 1%; min-width: 3.2em; text-align: right; color: var(--muted); user-select: none; opacity: 0.8; }
+td.mark { width: 1%; padding: 0 2px 0 4px; user-select: none; }
+td.text { white-space: pre; }
+tr.add { background: var(--add-bg); }
+tr.add td.mark { color: var(--add-mark); }
+tr.del { background: var(--del-bg); }
+tr.del td.mark { color: var(--del-mark); }
+tr.meta td { background: var(--meta-bg); color: var(--meta-text); }
+tr.gap td { background: var(--surface-2); color: var(--muted); font-style: italic; font-family: var(--sans); padding: 2px 8px; }
+
+/* Unannotated, alternatives, risks */
+.section { margin-top: 40px; }
+.section h2 { font-size: 17px; margin: 0 0 12px; }
+.unannotated { border: 1px dashed var(--del-mark); border-radius: 8px; padding: 12px 16px; background: var(--surface); }
+.list { margin: 0; padding-left: 20px; max-width: 80ch; }
+.list li { margin-bottom: 6px; }
+.list .why { color: var(--muted); }
+
+footer { margin-top: 48px; color: var(--muted); font-size: 12.5px; }
+kbd { font-family: var(--mono); font-size: 11.5px; border: 1px solid var(--border); border-bottom-width: 2px; border-radius: 4px; padding: 0 4px; background: var(--surface); }
+
+/* Range pages */
+.commit-list { list-style: none; margin: 0 0 8px; padding: 0; font-size: 14px; }
+.commit-list li { display: flex; flex-wrap: wrap; align-items: baseline; gap: 4px 8px; padding: 3px 0; }
+.commit-list .sha { font-size: 12px; }
+.commit-section { margin-top: 48px; padding-top: 24px; border-top: 1px solid var(--border); scroll-margin-top: 16px; }
+.commit-section h2 { font-size: 20px; margin: 8px 0 12px; }
+.commit-section .section h3 { font-size: 16px; margin: 0 0 12px; }
+.toc h2.commit-head { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; text-transform: none; letter-spacing: 0; font-family: var(--mono); }

package/dist/loader.js

@@ -0,0 +1,62 @@
+import { commitDiff, commitSubject, readNote } from './git.js';
+import { parseDiff } from './diff.js';
+import { changedCount, selections, uncovered } from './selection.js';
+const locationKey = (h) => [h.file, h.oldFile ?? '', h.oldStart, h.oldLines, h.newStart, h.newLines].join('\0');
+// Pair each stored hunk with a current one: first by the hash of its changes
+// (it may have moved in a rebase), then by location (same place, different
+// changes). Hash matches all go first so a location fallback can't take a
+// hunk that a later stored hunk matches exactly.
+export function matchHunks(stored, current) {
+    const used = new Set();
+    const resolved = new Map();
+    for (const s of stored) {
+        const match = s.hash ? current.find((h) => h.hash === s.hash && !used.has(h)) : undefined;
+        if (match) {
+            used.add(match);
+            resolved.set(s.id, { id: s.id, stored: s, current: match, status: 'ok' });
+        }
+    }
+    const byLocation = new Map(current.map((h) => [locationKey(h), h]));
+    for (const s of stored) {
+        if (resolved.has(s.id))
+            continue;
+        const match = byLocation.get(locationKey(s));
+        if (match && !used.has(match)) {
+            used.add(match);
+            // Glosses written before hashes existed can only be matched by location.
+            resolved.set(s.id, { id: s.id, stored: s, current: match, status: s.hash ? 'changed' : 'ok' });
+        }
+        else {
+            resolved.set(s.id, { id: s.id, stored: s, current: null, status: 'missing' });
+        }
+    }
+    return resolved;
+}
+// Hunks are matched by their stored location and content hash, never by id
+// alone: ids are positional, so any change in diff output would otherwise put
+// the wrong code under a group without anyone noticing.
+export function loadGloss(sha) {
+    const note = readNote(sha);
+    if (!note)
+        return null;
+    const current = parseDiff(commitDiff(sha));
+    const resolved = matchHunks(note.hunks, current);
+    const groups = note.annotation.groups.map((group) => ({
+        group,
+        hunks: [...selections(group.hunks, (id) => { const c = resolved.get(id)?.current; return c ? changedCount(c) : undefined; })].map(([id, lines]) => ({
+            ...(resolved.get(id) ?? { id, stored: null, current: null, status: 'missing' }),
+            lines,
+        })),
+    }));
+    const claims = groups.flatMap((g) => g.hunks.flatMap((h) => (h.current ? [{ hunk: h.current, lines: h.lines }] : [])));
+    const unannotated = uncovered(current, claims);
+    const bad = [...resolved.values()].filter((h) => h.status !== 'ok').length;
+    const matched = new Set([...resolved.values()].map((h) => h.current));
+    const unknown = current.filter((h) => !matched.has(h)).length;
+    const warnings = [];
+    if (bad || unknown) {
+        warnings.push(`this gloss no longer matches the commit (${bad} glossed hunk(s) changed or gone, ${unknown} new); ` +
+            'the commit was probably amended or rebased after glossing. Re-gloss it with `git gloss add --force`.');
+    }
+    return { sha, subject: commitSubject(sha), note, groups, unannotated, stale: warnings.length > 0, warnings };
+}

package/dist/merge.js

@@ -0,0 +1,191 @@
+import { matchHunks } from './loader.js';
+import { servesOf } from './schema.js';
+import { bodyLines, changedCount, formatRanges, selections, uncovered } from './selection.js';
+import { alsoServed } from './validate.js';
+// A changed line is identified by its file and its text with the +/- sign.
+const lineKey = (file, raw) => `${file}\0${raw}`;
+// A header-only hunk (binary, rename, mode change) by its file and content hash.
+const metaKey = (h, file = h.file) => `meta\0${file}\0${h.hash}`;
+// Build one gloss for `target` (the diff of a commit) from the glosses of the
+// commits its changes came from: a squash of several commits, a cherry-pick,
+// a rebase whose diff changed. Each changed line in the target is matched to
+// a source line with the same file and text, and takes that line's group.
+// For an added line the latest source wins (the last commit to write that
+// text); for a removed line, the earliest. Each source line is used once, and
+// a line several groups wrote (such as "}") goes to the group of its nearest
+// neighbour, so repeated lines are shared out sensibly. Groups keep their intent, grade and notes; lines no source explains
+// are left as gaps, never assigned to a guess.
+export function mergeGlosses(sources, target) {
+    const pools = new Map();
+    const add = (key, owner) => {
+        const pool = pools.get(key);
+        if (pool)
+            pool.push(owner);
+        else
+            pools.set(key, [owner]);
+    };
+    // A file renamed by a later source is known in the target by its last name,
+    // so lines written under an earlier name follow the renames.
+    const renames = sources.map((s) => new Map(s.hunks.filter((h) => h.oldFile && h.oldFile !== h.file).map((h) => [h.oldFile, h.file])));
+    const finalName = (file, src) => {
+        for (let i = src + 1; i < sources.length; i++)
+            file = renames[i].get(file) ?? file;
+        return file;
+    };
+    const stale = [];
+    sources.forEach((s, src) => {
+        // Hunk ids are positional, so a stored id is resolved to the source's
+        // current hunk by content; a hunk whose changes differ from what was
+        // glossed is left out rather than read under the wrong group.
+        const byId = new Map();
+        for (const [id, r] of matchHunks(s.note.hunks, s.hunks)) {
+            if (r.status === 'ok' && r.current)
+                byId.set(id, r.current);
+            else
+                stale.push(`${s.sha.slice(0, 7)}:${id}`);
+        }
+        for (const g of s.note.annotation.groups) {
+            for (const [id, sel] of selections(g.hunks, (hid) => { const h = byId.get(hid); return h && changedCount(h); })) {
+                const h = byId.get(id);
+                if (!h)
+                    continue;
+                if (changedCount(h) === 0) {
+                    add(metaKey(h, finalName(h.file, src)), { src, group: g.id });
+                    continue;
+                }
+                for (const l of bodyLines(h)) {
+                    if (l.idx !== null && (sel === null || sel.has(l.idx)))
+                        add(lineKey(finalName(h.file, src), l.raw), { src, group: g.id });
+                }
+            }
+        }
+    });
+    // Takes a source line for one of `keys`: from `prefer`'s group when it has
+    // one, else the latest source (added lines) or the earliest (removed lines).
+    const take = (keys, latest, prefer) => {
+        for (const key of keys) {
+            const pool = pools.get(key);
+            if (!pool?.length)
+                continue;
+            // Pools are filled in source order, so the last entry is the latest.
+            let best = prefer ? pool.findIndex((o) => o.src === prefer.src && o.group === prefer.group) : -1;
+            if (best < 0)
+                best = latest ? pool.length - 1 : 0;
+            return pool.splice(best, 1)[0];
+        }
+        return null;
+    };
+    const owners = (keys) => new Set(keys.flatMap((k) => (pools.get(k) ?? []).map((o) => `${o.src}\0${o.group}`)));
+    // Claimed lines per source group, per target hunk.
+    const claimed = new Map();
+    const claim = (o, h, idx) => {
+        const key = `${o.src}\0${o.group}`;
+        let byHunk = claimed.get(key);
+        if (!byHunk)
+            claimed.set(key, (byHunk = new Map()));
+        if (idx === null) {
+            byHunk.set(h, null);
+            return;
+        }
+        const set = byHunk.get(h);
+        if (set === null)
+            return;
+        byHunk.set(h, (set ?? new Set()).add(idx));
+    };
+    for (const h of target) {
+        if (changedCount(h) === 0) {
+            const o = take([metaKey(h)], true);
+            if (o)
+                claim(o, h, null);
+            continue;
+        }
+        // A line may have been written under the file's earlier name.
+        const files = h.oldFile && h.oldFile !== h.file ? [h.file, h.oldFile] : [h.file];
+        const lines = bodyLines(h).filter((l) => l.idx !== null).map((l) => ({ l, keys: files.map((f) => lineKey(f, l.raw)) }));
+        // First the lines only one group could own; then lines several groups
+        // wrote (such as "}"), which go to the group of the nearest line above,
+        // or else below, that one of them owns.
+        const got = new Map();
+        for (const { l, keys } of lines) {
+            if (owners(keys).size !== 1)
+                continue;
+            const o = take(keys, l.kind === 'add');
+            if (o)
+                got.set(l.idx, o);
+        }
+        lines.forEach(({ l, keys }, i) => {
+            if (got.has(l.idx) || !owners(keys).size)
+                return;
+            const candidates = owners(keys);
+            const near = [...lines.slice(0, i).reverse(), ...lines.slice(i + 1)]
+                .map((x) => got.get(x.l.idx)).find((o) => o && candidates.has(`${o.src}\0${o.group}`));
+            const o = take(keys, l.kind === 'add', near);
+            if (o)
+                got.set(l.idx, o);
+        });
+        for (const [idx, o] of got)
+            claim(o, h, idx);
+    }
+    // The groups that kept a change, in source order then group order. Ids that
+    // clash between sources get the source's position appended.
+    const kept = [];
+    const dropped = [];
+    sources.forEach((s, src) => s.note.annotation.groups.forEach((g) => {
+        const byHunk = claimed.get(`${src}\0${g.id}`);
+        if (byHunk)
+            kept.push({ src, g, byHunk });
+        else
+            dropped.push(`${s.sha.slice(0, 7)}:${g.id}`);
+    }));
+    if (!kept.length)
+        return { annotation: null, used: [], dropped, gaps: [], stale };
+    const used = [...new Set(kept.map((k) => k.src))];
+    const several = used.length > 1;
+    const clash = new Set(kept.map((k) => k.g.id).filter((id, i, all) => all.indexOf(id) !== i));
+    const taken = new Set(kept.map((k) => k.g.id));
+    const newId = new Map(kept.map((k) => {
+        if (!clash.has(k.g.id))
+            return [`${k.src}\0${k.g.id}`, k.g.id];
+        let id = `${k.g.id}-${k.src + 1}`;
+        for (let n = 2; taken.has(id); n++)
+            id = `${k.g.id}-${k.src + 1}-${n}`;
+        taken.add(id);
+        return [`${k.src}\0${k.g.id}`, id];
+    }));
+    const groups = kept.map(({ src, g, byHunk }) => {
+        const hunks = [...byHunk].sort(([a], [b]) => target.indexOf(a) - target.indexOf(b)).map(([h, set]) => set === null || set.size === changedCount(h) ? h.id : `${h.id}:${formatRanges(set)}`);
+        // A group may serve one that kept no change; point it at the task and say
+        // so, rather than leave a reference validation would reject.
+        const targets = servesOf(g);
+        const mapped = targets.map((t) => (t === 'task' ? t : newId.get(`${src}\0${t}`))).filter((t) => !!t);
+        const lost = targets.filter((t) => t !== 'task' && !newId.has(`${src}\0${t}`));
+        const extra = [
+            ...(lost.length ? [alsoServed(lost, 'which has no change left here')] : []),
+            ...(several ? [`(from ${sources[src].sha.slice(0, 7)})`] : []),
+        ].join(' ');
+        return {
+            ...g,
+            id: newId.get(`${src}\0${g.id}`),
+            hunks,
+            serves: mapped.length > 1 ? mapped : mapped[0] ?? 'task',
+            ...(extra ? { notes: g.notes ? `${g.notes} ${extra}` : extra } : {}),
+        };
+    });
+    const notes = used.map((i) => sources[i].note.annotation);
+    const unique = (xs) => [...new Map(xs.map((x) => [JSON.stringify(x), x])).values()];
+    const tasks = unique(notes.map((a) => a.task));
+    const summaries = unique(notes.flatMap((a) => (a.summary ? [a.summary] : [])));
+    const alternatives = unique(notes.flatMap((a) => a.alternatives ?? []));
+    const risks = unique(notes.flatMap((a) => a.risks ?? []));
+    const annotation = {
+        version: 1,
+        task: tasks.join('; '),
+        ...(summaries.length ? { summary: summaries.join(' ') } : {}),
+        groups,
+        ...(alternatives.length ? { alternatives } : {}),
+        ...(risks.length ? { risks } : {}),
+        ...(notes[0].author ? { author: notes[0].author } : {}),
+    };
+    const claims = kept.flatMap(({ byHunk }) => [...byHunk].map(([hunk, lines]) => ({ hunk, lines })));
+    return { annotation, used: used.map((i) => sources[i].sha), dropped, gaps: uncovered(target, claims), stale };
+}