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

package/dist/render.js

@@ -0,0 +1,131 @@
+import { spawnSync } from 'node:child_process';
+import { styleText } from 'node:util';
+import { gitTry } from './git.js';
+import { refLabel, sliceStats } from './selection.js';
+import { servesOf } from './schema.js';
+export const style = (s, text) => styleText(s, text);
+const NECESSITY_STYLE = {
+    required: 'green',
+    supporting: 'cyan',
+    mechanical: 'gray',
+    incidental: 'yellow',
+    defensive: 'blue',
+    speculative: 'magenta',
+};
+export function necessityTag(n) {
+    return style(['bold', NECESSITY_STYLE[n]], `[${n}]`);
+}
+export function necessityWord(n, pad = 0) {
+    return style(NECESSITY_STYLE[n], n.padEnd(pad));
+}
+export const termWidth = () => Math.min(process.stdout.columns || 100, 120);
+// Word-wrap plain text to `width` columns.
+export function wrap(text, width) {
+    const lines = [];
+    let line = '';
+    for (const word of text.split(/\s+/).filter(Boolean)) {
+        if (line && line.length + 1 + word.length > width) {
+            lines.push(line);
+            line = word;
+        }
+        else
+            line = line ? `${line} ${word}` : word;
+    }
+    lines.push(line);
+    return lines;
+}
+// "label text" with continuation lines hanging under the text.
+export function field(label, text, indent = 2) {
+    const hang = indent + label.length + 1;
+    const [first, ...rest] = wrap(text, Math.max(20, termWidth() - hang));
+    return [' '.repeat(indent) + style('dim', label) + ' ' + first, ...rest.map((l) => ' '.repeat(hang) + l)];
+}
+// "h6:5-12  src/x.ts  -10,20 +10,25  +6 -2", with counts for the selected lines.
+export function hunkLabel(h, lines = null) {
+    const range = h.newLines || h.oldLines
+        ? `-${h.oldStart},${h.oldLines} +${h.newStart},${h.newLines}`
+        : 'file header';
+    const file = h.oldFile && h.oldFile !== h.file ? `${h.oldFile} → ${h.file}` : h.file;
+    const s = sliceStats(h, lines);
+    return `${style('bold', refLabel(h.id, lines))}  ${file}  ${style('dim', range)}  ${style('green', `+${s.added}`)} ${style('red', `-${s.removed}`)}`;
+}
+export function colorDiff(text, indent = '') {
+    return text
+        .split('\n')
+        .map((l) => {
+        const s = l.startsWith('@@') ? 'cyan'
+            : l.startsWith('+') ? 'green'
+                : l.startsWith('-') ? 'red'
+                    : l.startsWith('diff ') || l.startsWith('index ') || l.startsWith('⋯') ? 'dim'
+                        : null;
+        return indent + (s ? style(s, l) : l);
+    })
+        .join('\n');
+}
+export function groupHeader(g) {
+    const prefix = `■ [${g.necessity}] `;
+    const out = wrap(g.intent, termWidth() - prefix.length).map((l, i) => (i === 0 ? `${style('bold', '■')} ${necessityTag(g.necessity)} ` : ' '.repeat(prefix.length)) + style('bold', l));
+    out[out.length - 1] += ' ' + style('dim', `(${g.id})`);
+    const serves = servesOf(g);
+    if (serves[0] !== 'task')
+        out.push(...field('serves:', serves.join(', ')));
+    out.push(...field('if removed:', g.removal_impact));
+    if (g.evidence)
+        out.push(...field('evidence:', g.evidence));
+    if (g.notes)
+        out.push(...field('notes:', g.notes));
+    return out;
+}
+export function risksBlock(note) {
+    const risks = note.annotation.risks ?? [];
+    return risks.length ? ['', style('bold', 'Risks'), ...risks.flatMap((r) => field('•', r))] : [];
+}
+export function noteFooter(note) {
+    const out = [];
+    const a = note.annotation;
+    if (a.alternatives?.length) {
+        out.push('', style('bold', 'Alternatives considered'));
+        for (const alt of a.alternatives)
+            out.push(...field('•', `${alt.option}: ${alt.rejected_because}`));
+    }
+    return [...out, ...risksBlock(note)];
+}
+// The pager git would use for `git gloss`: pager.gloss if set (false turns it
+// off), else GIT_PAGER, core.pager, PAGER, less. `git --no-pager` reaches us
+// as GIT_PAGER=cat.
+export function pagerCommand() {
+    if (process.env.GIT_PAGER_IN_USE)
+        return null;
+    const own = gitTry(['config', 'pager.gloss'])?.trim();
+    if (own !== undefined && own !== '') {
+        const off = gitTry(['config', '--type=bool', 'pager.gloss'])?.trim();
+        if (off === 'false')
+            return null;
+        if (off !== 'true')
+            return own;
+    }
+    const pager = gitTry(['var', 'GIT_PAGER'])?.trim();
+    return !pager || pager === 'cat' ? null : pager;
+}
+// Run the pager; print directly only if it could not run at all. Quitting the
+// pager early makes our write fail with EPIPE, which is not a reason to dump
+// the rest of the output on the terminal.
+export function runPager(pager, text) {
+    const r = spawnSync('sh', ['-c', pager], {
+        input: text + '\n',
+        stdio: ['pipe', 'inherit', 'inherit'],
+        env: { LESS: 'FRX', LV: '-c', ...process.env, GIT_PAGER_IN_USE: 'true' },
+    });
+    const code = r.error?.code;
+    if ((r.error && code !== 'EPIPE') || r.status === 127)
+        console.log(text);
+}
+// Page output that won't fit on screen, as git does.
+export function page(text) {
+    const rows = process.stdout.rows;
+    const pager = process.stdout.isTTY && rows && text.split('\n').length >= rows ? pagerCommand() : null;
+    if (pager)
+        runPager(pager, text);
+    else
+        console.log(text);
+}

package/dist/reviews.js

@@ -0,0 +1,205 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { commitDiff, git, gitTry, GlossError, readNote } from './git.js';
+import { parseDiff } from './diff.js';
+import { bodyLines } from './selection.js';
+// Reviews of commits (by git-gud, or anything else that records them), kept
+// beside the glosses so a reader can see whether a gloss was checked. One JSON
+// record per line: notes from different people and machines combine by taking
+// every line (git's cat_sort_uniq), with no conflicts.
+export const REVIEWS_REF = 'refs/notes/gloss-reviews';
+// The report's VERDICT line, which has to be a line of its own among the
+// last three, so a verdict quoted in the body can't stand in for it.
+export function verdictOf(findings) {
+    const tail = findings.trim().split('\n').filter((l) => l.trim()).slice(-3).reverse();
+    for (const line of tail) {
+        // The whole line, give or take markdown: not a sentence that starts so.
+        const m = /^\W*VERDICT:\W*(CLEAN|ISSUES)\W*$/i.exec(line.trim());
+        if (m)
+            return m[1].toLowerCase();
+    }
+    return undefined;
+}
+const key = (s) => createHash('sha256').update(s).digest('hex').slice(0, 16);
+// One key per changed line, repeated for repeated lines (a second "}" is a
+// second key), so adding another copy of a reviewed line isn't "seen". A
+// change with no lines (a binary file, a mode change, a pure rename) is keyed
+// by its file and content hash.
+export const lineKeys = (hunks) => hunks.flatMap((h) => {
+    const lines = bodyLines(h).filter((l) => l.idx !== null);
+    return lines.length ? lines.map((l) => key(`${h.file}\0${l.raw}`)) : [key(`meta\0${h.file}\0${h.hash}`)];
+}).sort();
+// A group's meaning, without its id or hunk references (which change when a
+// gloss is carried or adopted) and without the notes carrying adds.
+export function groupKey(g) {
+    const notes = (g.notes ?? '').replace(/\s*\((?:from [0-9a-f]{7,}|also served [^)]*)\)/g, '').trim();
+    const serves = (Array.isArray(g.serves) ? g.serves : [g.serves]).slice().sort();
+    return key(JSON.stringify([g.intent, g.necessity, serves, g.removal_impact, g.evidence ?? '', notes]));
+}
+// The gloss's parts a reviewer checks: each group, each risk and each
+// rejected alternative (keyed one by one, so a squash that combines several
+// glosses' risks still matches the reviews of each). The task and summary
+// are left out: carrying joins them.
+export function glossKeys(a) {
+    return [
+        ...a.groups.map(groupKey),
+        ...(a.risks ?? []).map((r) => key(`risk\0${r}`)),
+        ...(a.alternatives ?? []).map((x) => key(`alternative\0${x.option}\0${x.rejected_because}`)),
+    ];
+}
+// What a reviewer of `sha` sees now: its changed lines and its gloss's groups.
+export function stamp(sha) {
+    let groups = [];
+    try {
+        const note = readNote(sha);
+        groups = note ? glossKeys(note.annotation) : [];
+    }
+    catch { /* an unreadable gloss: nothing to stamp */ }
+    return { lines: lineKeys(parseDiff(commitDiff(sha))), groups };
+}
+export function readReviews(sha) {
+    const raw = gitTry(['notes', '--ref', REVIEWS_REF, 'show', sha]);
+    if (!raw)
+        return [];
+    // A rebase can join a note onto one with the same lines; each counts once.
+    return [...new Set(raw.split('\n'))].flatMap((line) => {
+        try {
+            const r = JSON.parse(line);
+            // Records arrive from other machines; skip any that aren't whole.
+            const ok = r?.review === 1 && Array.isArray(r.lines) && Array.isArray(r.groups) &&
+                ['id', 'at', 'stage', 'agent', 'target', 'findings'].every((k) => typeof r[k] === 'string') &&
+                ['model', 'mode'].every((k) => r[k] === undefined || typeof r[k] === 'string') &&
+                (r.verdict === undefined || r.verdict === 'clean' || r.verdict === 'issues');
+            return ok ? [r] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+// Adds records to a commit's reviews, keeping each line once. Several
+// reviews can finish at once, so the write is a compare-and-swap: the new
+// notes commit is built under a private ref, and the reviews ref moves to it
+// only if nobody else moved it meanwhile; otherwise it starts again.
+export function addReviews(sha, records) {
+    const mine = records.map((r) => JSON.stringify(r));
+    // git notes needs it under refs/notes; named so the refs/notes/gloss*
+    // fetch glob never matches it.
+    const tmp = `refs/notes/tmp-gloss-reviews-${process.pid}-${randomUUID().slice(0, 8)}`;
+    try {
+        for (let attempt = 0; attempt < 50; attempt++) {
+            const old = gitTry(['rev-parse', '-q', '--verify', REVIEWS_REF])?.trim() ?? null;
+            if (old)
+                git(['update-ref', tmp, old]);
+            else
+                gitTry(['update-ref', '-d', tmp]);
+            const existing = (gitTry(['notes', '--ref', tmp, 'show', sha]) ?? '').split('\n').filter(Boolean);
+            const lines = [...new Set([...existing, ...mine])].sort();
+            git(['notes', '--ref', tmp, 'add', '-f', '-F', '-', sha], lines.join('\n') + '\n');
+            const next = git(['rev-parse', tmp]).trim();
+            // An empty old value means "must not exist yet".
+            if (gitTry(['update-ref', REVIEWS_REF, next, old ?? '']) !== null)
+                return;
+        }
+        throw new GlossError(`couldn't record the review on ${sha.slice(0, 10)}: other processes kept writing reviews at the same time`);
+    }
+    finally {
+        gitTry(['update-ref', '-d', tmp]);
+    }
+}
+// Reviews follow a gloss onto commits made from the reviewed ones (adopt,
+// carry); their keys decide what they still cover there.
+export function copyReviews(from, to) {
+    const records = from.flatMap(readReviews);
+    if (records.length)
+        addReviews(to, records);
+}
+// Whether reviews saw every changed line, counting repeats: each distinct
+// stamp (reviews of different commits, as for a squash) contributes its
+// lines; reviews of the same stamp count once.
+function covers(reviews, lines) {
+    const seen = new Map();
+    const stamps = new Set();
+    for (const r of reviews) {
+        const id = r.lines.join(',');
+        if (stamps.has(id))
+            continue;
+        stamps.add(id);
+        const counts = new Map();
+        for (const l of r.lines)
+            counts.set(l, (counts.get(l) ?? 0) + 1);
+        for (const [l, n] of counts)
+            seen.set(l, (seen.get(l) ?? 0) + n);
+    }
+    const need = new Map();
+    for (const l of lines)
+        need.set(l, (need.get(l) ?? 0) + 1);
+    return [...need].every(([l, n]) => (seen.get(l) ?? 0) >= n);
+}
+// Per stage: whether the commit as it is now was reviewed. A commit squashed
+// from several reviewed ones is covered when their reviews together saw all
+// of it.
+export function reviewStatus(sha, current = stamp(sha)) {
+    const byStage = new Map();
+    for (const r of readReviews(sha))
+        byStage.set(r.stage, [...(byStage.get(r.stage) ?? []), r]);
+    return [...byStage].map(([stage, reviews]) => {
+        const groups = new Set(reviews.flatMap((r) => r.groups));
+        return {
+            stage,
+            now: current,
+            reviews: reviews.sort((a, b) => b.at.localeCompare(a.at)),
+            code: covers(reviews, current.lines) ? 'seen' : 'changed',
+            gloss: current.groups.length ? (current.groups.every((g) => groups.has(g)) ? 'seen' : 'changed') : null,
+        };
+    });
+}
+// Whether this stage's reviews still apply to the commit as it is now.
+export const current = (s) => s.code === 'seen' && !((s.stage === 'honesty' || s.stage === 'improve') && s.gloss === 'changed');
+// What the reviews concluded about the commit as it is now. Each part of it
+// (a gloss group for honesty and improve, else a changed line) takes the
+// verdict of the latest review that saw it, so fixing a gloss and having it
+// reviewed again replaces the earlier verdict for the parts it saw. Issues
+// if any part's latest review found some; clean if every part's said clean.
+export function verdict(s) {
+    const v = latestVerdicts(s);
+    return v.includes('issues') ? 'issues' : v.length && v.every((x) => x === 'clean') ? 'clean' : 'unknown';
+}
+function latestVerdicts(s) {
+    const byGroups = (s.stage === 'honesty' || s.stage === 'improve') && s.now.groups.length;
+    const parts = byGroups ? s.now.groups : s.now.lines;
+    // s.reviews is newest first.
+    const latest = new Set();
+    for (const part of parts) {
+        // A review without a verdict line says nothing either way, so it doesn't
+        // replace an earlier one's.
+        const r = s.reviews.find((r) => r.verdict && (byGroups ? r.groups : r.lines).includes(part));
+        if (r)
+            latest.add(r);
+    }
+    return [...latest].map((r) => r.verdict);
+}
+// Whether a review older than the ones deciding the verdict found issues:
+// a clean result is then shown as following an earlier one with issues.
+export const earlierIssues = (s) => verdict(s) !== 'issues' && s.reviews.some((r) => r.verdict === 'issues');
+// What a verdict means for each stage: improve's "issues" are suggestions.
+const WORDS = {
+    bugs: { clean: 'no defects found', issues: 'defects found' },
+    improve: { clean: 'nothing to improve', issues: 'suggestions' },
+    default: { clean: 'no issues', issues: 'issues found' },
+};
+// One short phrase per stage, for summaries: "honesty: issues found (claude,
+// 2026-10-18)". A review says the commit was checked, not that it passed.
+export function statusPhrase(s) {
+    const latest = s.reviews[0];
+    const who = `${latest.agent}${latest.model ? `:${latest.model}` : ''}, ${latest.at.slice(0, 10)}${s.reviews.length > 1 ? `, ${s.reviews.length} reviews` : ''}`;
+    if (s.code === 'changed')
+        return `${s.stage}: code changed since review (${who})`;
+    if (!current(s)) {
+        const never = s.reviews.every((r) => !r.groups.length);
+        return `${s.stage}: ${never ? 'reviewed before it was glossed' : 'gloss changed since review'} (${who})`;
+    }
+    const v = verdict(s);
+    const words = WORDS[s.stage] ?? WORDS.default;
+    return `${s.stage}: ${v === 'clean' ? words.clean : v === 'issues' ? words.issues : 'reviewed'} (${who}` +
+        `${earlierIssues(s) ? '; an earlier review found issues' : ''})`;
+}

package/dist/schema.js

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { REF_PATTERN } from './selection.js';
+// In the order `show` lists groups: what the task needs, then what a reviewer
+// might cut, then edits with no design content.
+export const NECESSITY = [
+    'required',
+    'supporting',
+    'defensive',
+    'incidental',
+    'speculative',
+    'mechanical',
+];
+export const NECESSITY_HELP = {
+    required: 'The task cannot be done without this change',
+    supporting: 'Needed only because other groups need it (name them in `serves`)',
+    mechanical: 'Follow-on edits with no design content: renames, imports, formatting, lockfiles',
+    incidental: 'Drive-by cleanup or refactor the task did not ask for',
+    defensive: 'Guards edge cases or failures nobody asked about',
+    speculative: 'Added because it might be useful later',
+};
+export const Group = z.object({
+    id: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9-]*$/, 'use lowercase kebab-case')
+        .describe('Short unique id for this group, e.g. "retry-core"'),
+    intent: z.string().min(1).describe('What this group of changes does, in one short sentence (under ~80 characters)'),
+    necessity: z.enum(NECESSITY).describe('How necessary the change is to the task'),
+    serves: z
+        .union([z.string(), z.array(z.string()).min(1)])
+        .describe('"task" if it serves the task directly, otherwise the id of the group it supports, or a list of ids when it supports several (e.g. tests)'),
+    removal_impact: z
+        .string()
+        .min(1)
+        .describe('What concretely breaks or is lost if this group is removed'),
+    evidence: z
+        .string()
+        .optional()
+        .describe('A test, requirement or task line that demonstrates the need'),
+    hunks: z
+        .array(z.string().regex(REF_PATTERN, 'use a hunk id like "h3", or changed lines of one like "h3:2-5" or "h3:1,4-6"'))
+        .min(1)
+        .describe('Hunks from `git gloss hunks` that belong to this group: "h3" for a whole hunk, "h3:2-5" for its changed lines 2 to 5'),
+    notes: z.string().optional(),
+});
+export const Annotation = z.object({
+    version: z.literal(1).default(1),
+    task: z.string().min(1).describe('The task or request these changes were made for'),
+    summary: z.string().optional().describe('One or two sentences on the overall change'),
+    groups: z.array(Group).min(1),
+    alternatives: z
+        .array(z.object({ option: z.string(), rejected_because: z.string() }))
+        .optional()
+        .describe('Approaches considered and why they were not taken'),
+    risks: z.array(z.string()).optional().describe('Known risks or open questions'),
+    author: z
+        .object({
+        agent: z.string().optional(),
+        model: z.string().optional(),
+        session: z.string().optional(),
+    })
+        .optional(),
+});
+// A group's serves targets as a list, whichever form the gloss used.
+export const servesOf = (g) => (Array.isArray(g.serves) ? g.serves : [g.serves]);
+// Note formats: 1 whole-hunk references only; 2 line ranges ("h3:2-5");
+// 3 serves lists. A note is written with the lowest format that can hold it,
+// so older readers only refuse notes that use something they can't read.
+export const NOTE_FORMAT = 3;
+export function noteFormat(a) {
+    if (a.groups.some((g) => servesOf(g).length > 1))
+        return 3;
+    if (a.groups.some((g) => g.hunks.some((ref) => ref.includes(':'))))
+        return 2;
+    return 1;
+}

package/dist/selection.js

@@ -0,0 +1,147 @@
+export const REF_PATTERN = /^(h\d+)(?::(\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*))?$/;
+export function parseRef(ref) {
+    const m = REF_PATTERN.exec(ref);
+    if (!m)
+        return null;
+    if (!m[2])
+        return { hunk: m[1], ranges: null };
+    const ranges = m[2].split(',').map((part) => {
+        const [a, b] = part.split('-').map(Number);
+        return [a, b ?? a];
+    });
+    return { hunk: m[1], ranges };
+}
+export function formatRanges(lines) {
+    const sorted = [...new Set(lines)].sort((x, y) => x - y);
+    const parts = [];
+    for (let i = 0; i < sorted.length; i++) {
+        let j = i;
+        while (j + 1 < sorted.length && sorted[j + 1] === sorted[j] + 1)
+            j++;
+        parts.push(i === j ? `${sorted[i]}` : `${sorted[i]}-${sorted[j]}`);
+        i = j;
+    }
+    return parts.join(',');
+}
+export const refLabel = (id, lines) => (lines ? `${id}:${formatRanges(lines)}` : id);
+const HUNK_HEADER = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/;
+// Parsed bodies are cached per hunk: callers ask for the same hunk's lines
+// many times (counts, slices, coverage), and re-parsing made splitting a large
+// hunk quadratic.
+const parsed = new WeakMap();
+// The hunk's lines after its @@ header, with changed-line numbers and file
+// line numbers. A header-only change (binary, rename) is all 'meta'.
+export function bodyLines(h) {
+    let lines = parsed.get(h);
+    if (!lines)
+        parsed.set(h, (lines = parseBody(h)));
+    return lines;
+}
+function parseBody(h) {
+    const [header, ...body] = h.text.split('\n');
+    const m = HUNK_HEADER.exec(header);
+    if (!m)
+        return h.text.split('\n').map((raw) => ({ raw, kind: 'meta', idx: null, oldNo: null, newNo: null }));
+    let oldNo = Number(m[1]), newNo = Number(m[2]), idx = 0;
+    return body.map((raw) => {
+        if (raw[0] === '+')
+            return { raw, kind: 'add', idx: ++idx, oldNo: null, newNo: newNo++ };
+        if (raw[0] === '-')
+            return { raw, kind: 'del', idx: ++idx, oldNo: oldNo++, newNo: null };
+        if (raw[0] === '\\')
+            return { raw, kind: 'meta', idx: null, oldNo: null, newNo: null };
+        return { raw, kind: 'ctx', idx: null, oldNo: oldNo++, newNo: newNo++ };
+    });
+}
+export const changedCount = (h) => bodyLines(h).filter((l) => l.idx !== null).length;
+export const isGap = (l) => 'gap' in l;
+// The part of a hunk a selection covers: selected changed lines, context
+// within `context` lines of them, and a gap marker for each run of changed
+// lines that belong elsewhere. A null selection is the whole hunk.
+export function slice(lines, selected, context = 3) {
+    if (!selected)
+        return lines;
+    const keep = lines.map((l) => l.idx !== null && selected.has(l.idx));
+    const near = lines.map((_, i) => keep.slice(Math.max(0, i - context), i + context + 1).some(Boolean));
+    const out = [];
+    lines.forEach((l, i) => {
+        if (keep[i] || (l.kind === 'meta' && near[i]))
+            out.push(l);
+        else if (l.idx !== null) {
+            const last = out[out.length - 1];
+            if (last && isGap(last))
+                last.gap++;
+            else
+                out.push({ gap: 1 });
+        }
+        else if (l.kind === 'ctx' && near[i])
+            out.push(l);
+    });
+    return out;
+}
+// Lines a group's view leaves out: claimed by other groups, or (under --partial) by none.
+export const gapText = (n) => `⋯ ${n} changed line${n === 1 ? '' : 's'} not in this group`;
+// Text form of a slice for terminal and prompt output: the @@ header, kept
+// lines verbatim, gaps as marker lines that can't be read as diff lines.
+export function sliceText(h, selected) {
+    if (!selected)
+        return h.text;
+    const header = h.text.split('\n')[0];
+    return [header, ...slice(bodyLines(h), selected).map((l) => (isGap(l) ? gapText(l.gap) : l.raw))].join('\n');
+}
+export function sliceStats(h, selected) {
+    if (!selected)
+        return { added: h.added, removed: h.removed };
+    const lines = bodyLines(h).filter((l) => l.idx !== null && selected.has(l.idx));
+    return { added: lines.filter((l) => l.kind === 'add').length, removed: lines.filter((l) => l.kind === 'del').length };
+}
+// One selection per hunk for a group's refs, in order of first mention. A
+// whole-hunk ref wins over ranges for the same hunk. Ranges are clamped to the
+// hunk's changed-line count, so an oversized range (from a typo, a stale or a
+// hand-edited note) can't build an enormous set; refs to unknown hunks keep
+// an empty selection.
+export function selections(refs, changedOf) {
+    const out = new Map();
+    for (const ref of refs) {
+        const r = parseRef(ref);
+        if (!r)
+            continue;
+        const prev = out.get(r.hunk);
+        if (prev === null)
+            continue;
+        if (!r.ranges) {
+            out.set(r.hunk, null);
+            continue;
+        }
+        const set = prev ?? new Set();
+        const n = changedOf(r.hunk) ?? 0;
+        for (const [a, b] of r.ranges)
+            for (let i = Math.max(1, a); i <= Math.min(b, n); i++)
+                set.add(i);
+        out.set(r.hunk, set);
+    }
+    return out;
+}
+// Changed lines that no claim covers. A hunk with no claims at all is
+// uncovered whole (lines: null); a header-only hunk is covered by any claim.
+export function uncovered(hunks, claims) {
+    const out = [];
+    for (const h of hunks) {
+        const mine = claims.filter((c) => c.hunk === h);
+        if (!mine.length) {
+            out.push({ hunk: h, lines: null });
+            continue;
+        }
+        if (mine.some((c) => c.lines === null))
+            continue;
+        const covered = new Set(mine.flatMap((c) => [...c.lines]));
+        const missing = new Set();
+        const n = changedCount(h);
+        for (let i = 1; i <= n; i++)
+            if (!covered.has(i))
+                missing.add(i);
+        if (missing.size)
+            out.push({ hunk: h, lines: missing });
+    }
+    return out;
+}

package/dist/validate.js

@@ -0,0 +1,85 @@
+import { servesOf } from './schema.js';
+import { changedCount, parseRef, refLabel, selections, uncovered } from './selection.js';
+export function validate(annotation, hunks) {
+    const errors = [];
+    const groupIds = new Set();
+    for (const g of annotation.groups) {
+        if (groupIds.has(g.id))
+            errors.push(`duplicate group id "${g.id}"`);
+        groupIds.add(g.id);
+    }
+    const byHunkId = new Map(hunks.map((h) => [h.id, h]));
+    const claims = [];
+    for (const g of annotation.groups) {
+        for (const ref of g.hunks) {
+            const r = parseRef(ref);
+            const h = byHunkId.get(r.hunk);
+            if (!h) {
+                errors.push(`group "${g.id}" references unknown hunk "${r.hunk}"`);
+                continue;
+            }
+            const n = changedCount(h);
+            if (r.ranges && n === 0)
+                errors.push(`group "${g.id}": ${r.hunk} has no changed lines to select; reference it whole`);
+            else if (r.ranges?.some(([a, b]) => b < a)) {
+                errors.push(`group "${g.id}": "${ref}" runs backwards; write ranges low to high, e.g. ${r.hunk}:3-5`);
+            }
+            else if (r.ranges?.some(([a, b]) => a < 1 || b > n)) {
+                errors.push(`group "${g.id}": "${ref}" is out of range; ${r.hunk} has changed lines 1-${n}`);
+            }
+        }
+        for (const [id, lines] of selections(g.hunks, (id) => { const h = byHunkId.get(id); return h && changedCount(h); })) {
+            const h = byHunkId.get(id);
+            if (h)
+                claims.push({ hunk: h, lines });
+        }
+        const targets = servesOf(g);
+        for (const t of targets) {
+            if (t !== 'task' && !groupIds.has(t))
+                errors.push(`group "${g.id}" serves unknown group "${t}" (use "task" or group ids)`);
+            if (t === g.id)
+                errors.push(`group "${g.id}" cannot serve itself`);
+        }
+        if (targets.length > 1 && targets.includes('task')) {
+            errors.push(`group "${g.id}" serves "task" and groups; use "task" alone or list only groups`);
+        }
+        if (new Set(targets).size < targets.length)
+            errors.push(`group "${g.id}" lists a serves target twice`);
+        if (g.necessity === 'supporting' && targets.includes('task')) {
+            errors.push(`group "${g.id}" is "supporting" but serves "task"; name the group(s) it supports`);
+        }
+    }
+    // A group is in a cycle if it can reach itself by following serves links.
+    const byId = new Map(annotation.groups.map((g) => [g.id, g]));
+    for (const g of annotation.groups) {
+        const seen = new Set();
+        const queue = servesOf(g).filter((t) => t !== 'task');
+        while (queue.length) {
+            const id = queue.shift();
+            if (id === g.id) {
+                errors.push(`group "${g.id}" is in a serves cycle; every chain must end at "task"`);
+                break;
+            }
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            queue.push(...servesOf(byId.get(id) ?? { serves: 'task' }).filter((t) => t !== 'task'));
+        }
+    }
+    return { errors, uncovered: uncovered(hunks, claims).map((u) => refLabel(u.hunk.id, u.lines)) };
+}
+// The note a carried group gets when groups it served didn't come along, so
+// it serves the task instead; carriedErrors recognises it by this prefix.
+const ALSO_SERVED = '(also served ';
+export const alsoServed = (lost, why) => `${ALSO_SERVED}${lost.join(', ')}, ${why})`;
+// Errors in a gloss moved onto another commit (by adopt or carry). A group
+// whose supported groups didn't come along serves the task instead, with
+// "(also served …)" in its notes; that isn't an error for such a group, but
+// is for any other.
+export function carriedErrors(annotation, hunks) {
+    const repointed = new Set(annotation.groups.filter((g) => g.notes?.includes(ALSO_SERVED)).map((g) => g.id));
+    return validate(annotation, hunks).errors.filter((e) => {
+        const m = /^group "([^"]+)" is "supporting" but serves "task"/.exec(e);
+        return !(m && repointed.has(m[1]));
+    });
+}