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

package/dist/commands/sync.js

@@ -0,0 +1,192 @@
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { git, gitTry, GitError, NOTES_REF } from '../git.js';
+import { carryNew } from '../origins.js';
+import { carry } from './carry.js';
+export const usage = 'sync [<remote>]   fetch, merge and push glosses (default remote: origin)';
+const MAX_ATTEMPTS = 3;
+// Map of annotated object → note blob for a notes ref, or empty if it doesn't exist.
+function noteList(ref) {
+    const out = gitTry(['notes', '--ref', ref, 'list']) ?? '';
+    return new Map(out.split('\n').filter(Boolean).map((line) => {
+        const [blob, object] = line.split(' ');
+        return [object, blob];
+    }));
+}
+// created_at from a note, or null if the note isn't JSON we can read (for
+// example one written by a newer git-gloss). Notes are never validated or
+// rewritten here, so sync passes through formats it doesn't understand.
+function createdAt(blob) {
+    try {
+        const value = JSON.parse(git(['cat-file', 'blob', blob]))?.created_at;
+        return typeof value === 'string' ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+// The notes at a commit of a notes ref, e.g. the merge base. Notes trees fan
+// paths out (ab/cdef…), so joining the path gives the annotated object.
+function notesAt(commit) {
+    const out = git(['ls-tree', '-r', '--full-tree', commit]);
+    return new Map(out.split('\n').filter(Boolean).map((line) => {
+        const [meta, path] = line.split('\t');
+        return [path.replaceAll('/', ''), meta.split(' ')[2]];
+    }));
+}
+// Commits whose glosses may be shared with the remote: those it already has
+// (reachable from its remote-tracking branches) and, from the pre-push hook,
+// those being pushed now. Glosses of other commits (private branches, local
+// work) stay local.
+function shareable(remote, pushing) {
+    const tips = (gitTry(['for-each-ref', '--format=%(objectname)', `refs/remotes/${remote}/`]) ?? '').split('\n').filter(Boolean);
+    const starts = [...tips, ...pushing];
+    if (!starts.length)
+        return new Set();
+    return new Set(git(['rev-list', ...starts, '--']).split('\n').filter(Boolean));
+}
+const PUSH_REF = 'refs/notes/gloss-sync-tmp';
+// One fetch → merge → push round. Returns null if the push lost a race with
+// someone else's push and the round should be retried.
+function round(remote, pushing, carried) {
+    const tracking = `refs/notes/remotes/${remote}/gloss`;
+    const remoteHas = gitTry(['ls-remote', '--exit-code', remote, NOTES_REF]) !== null;
+    if (remoteHas)
+        git(['fetch', '-q', remote, `+${NOTES_REF}:${tracking}`]);
+    const local = noteList(NOTES_REF);
+    const theirs = remoteHas ? noteList(tracking) : new Map();
+    // The last state both sides shared. A gloss changed on one side only is
+    // simply taken from that side (as the merge below does); only a gloss
+    // changed on both sides since then is a conflict.
+    const hasLocal = gitTry(['rev-parse', '-q', '--verify', NOTES_REF]) !== null;
+    const baseCommit = remoteHas && hasLocal ? gitTry(['merge-base', NOTES_REF, tracking])?.trim() : null;
+    const base = baseCommit ? notesAt(baseCommit) : new Map();
+    let fetched = 0;
+    const conflicts = [];
+    const takeTheirs = [];
+    for (const object of new Set([...local.keys(), ...theirs.keys()])) {
+        const [mine, other, was] = [local.get(object), theirs.get(object), base.get(object)];
+        if (mine === other)
+            continue;
+        if (mine === was) {
+            if (other !== undefined)
+                fetched++;
+            continue;
+        } // only they changed it
+        if (other === was)
+            continue; // only we changed it: pushed below if shareable
+        // Deleted on one side, changed on the other: keep the gloss rather than
+        // lose a correction. (-s ours alone would keep a local deletion.)
+        if (mine === undefined) {
+            takeTheirs.push([object, other]);
+            fetched++;
+            conflicts.push(`${object.slice(0, 10)}: kept theirs (you deleted it, they changed it)`);
+            continue;
+        }
+        if (other === undefined) {
+            conflicts.push(`${object.slice(0, 10)}: kept yours (they deleted it, you changed it)`);
+            continue;
+        }
+        // Both sides changed it: keep the newer gloss, since a re-gloss with
+        // --force is normally a correction. Ties and unreadable notes keep yours.
+        const [a, b] = [createdAt(mine), createdAt(other)];
+        const theirsNewer = a !== null && b !== null && b > a;
+        if (theirsNewer) {
+            takeTheirs.push([object, other]);
+            fetched++;
+        }
+        conflicts.push(`${object.slice(0, 10)}: kept ${theirsNewer ? 'theirs' : 'yours'}` +
+            (a === null || b === null ? " (couldn't read both glosses' dates)" : ' (newer)'));
+    }
+    if (remoteHas) {
+        if (!hasLocal) {
+            git(['update-ref', NOTES_REF, tracking]);
+        }
+        else {
+            // -s ours makes the remote history an ancestor of ours, so the push
+            // below fast-forwards; the newer-wins choices are applied on top.
+            git(['notes', '--ref', NOTES_REF, 'merge', '-q', '-s', 'ours', tracking]);
+        }
+        for (const [object, blob] of takeTheirs)
+            git(['notes', '--ref', NOTES_REF, 'add', '-f', '-C', blob, object]);
+    }
+    // Commits made on the remote by squash or rebase merges (or being pushed
+    // after a local squash or cherry-pick) get the gloss of the commits they
+    // came from, so it goes out with the rest.
+    const tips = (gitTry(['for-each-ref', '--format=%(objectname)', `refs/remotes/${remote}/`]) ?? '').split('\n').filter(Boolean);
+    carried.push(...carryNew([...tips, ...pushing], carry));
+    // What to send: glosses that differ from the remote's, of commits it may
+    // see. They are added on top of the remote's notes history in a scratch
+    // ref, so the push fast-forwards and carries nothing else; local history
+    // (with any withheld glosses) never leaves the machine.
+    const allowed = shareable(remote, pushing);
+    const merged = noteList(NOTES_REF);
+    const toPush = [...merged].filter(([object, blob]) => allowed.has(object) && theirs.get(object) !== blob);
+    const withheld = [...merged.keys()].filter((o) => !allowed.has(o) && !theirs.has(o)).length;
+    if (!toPush.length)
+        return { fetched, pushed: 0, withheld, conflicts };
+    try {
+        if (remoteHas)
+            git(['update-ref', PUSH_REF, tracking]);
+        else
+            gitTry(['update-ref', '-d', PUSH_REF]);
+        for (const [object, blob] of toPush)
+            git(['notes', '--ref', PUSH_REF, 'add', '-f', '-C', blob, object]);
+        try {
+            // --no-verify: don't run the pre-push hook for the notes push itself,
+            // which would call sync again.
+            git(['push', '-q', '--no-verify', remote, `${PUSH_REF}:${NOTES_REF}`]);
+        }
+        catch (err) {
+            if (/\(fetch first\)|non-fast-forward/.test(err.message))
+                return null;
+            throw err;
+        }
+        // Record what the remote now has, so the next sync's merge base is right.
+        git(['notes', '--ref', NOTES_REF, 'merge', '-q', '-s', 'ours', PUSH_REF]);
+    }
+    finally {
+        gitTry(['update-ref', '-d', PUSH_REF]);
+    }
+    return { fetched, pushed: toPush.length, withheld, conflicts };
+}
+export function run(argv) {
+    // --pushing (from the pre-push hook): read the refs being pushed from stdin,
+    // as git gives them to the hook, so glosses of those commits go too.
+    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { pushing: { type: 'boolean' } } });
+    if (values.pushing && process.stdin.isTTY)
+        console.error('note: --pushing reads the refs being pushed from stdin, as the pre-push hook gives them; ignoring it here');
+    const pushing = values.pushing && !process.stdin.isTTY
+        ? readFileSync(0, 'utf8').split('\n').map((l) => l.split(' ')[1]).filter((sha) => sha && !/^0+$/.test(sha))
+        : [];
+    const remote = positionals[0] ?? 'origin';
+    // Only configured remotes: the name becomes part of a ref and an argument,
+    // and a URL has no stable place to keep the remote's glosses.
+    const remotes = (gitTry(['remote']) ?? '').split('\n').filter(Boolean);
+    if (!remotes.includes(remote)) {
+        throw new GitError(`no remote named "${remote}"${remotes.length ? `; remotes are ${remotes.join(', ')}` : ''}`);
+    }
+    const carried = [];
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        const outcome = round(remote, pushing, carried);
+        if (!outcome)
+            continue;
+        const parts = [`fetched ${outcome.fetched}`, `pushed ${outcome.pushed}`];
+        if (!outcome.fetched && !outcome.pushed && !outcome.conflicts.length) {
+            console.log(`glosses already in sync with ${remote}`);
+        }
+        else {
+            console.log(`synced glosses with ${remote}: ${parts.join(', ')}` +
+                (outcome.conflicts.length ? `, ${outcome.conflicts.length} glossed on both sides` : ''));
+            for (const c of outcome.conflicts)
+                console.log(`  ${c}`);
+        }
+        for (const c of carried)
+            console.log(c);
+        if (outcome.withheld) {
+            console.log(`  kept ${outcome.withheld} gloss${outcome.withheld === 1 ? '' : 'es'} local: their commits aren't on ${remote} yet`);
+        }
+        return 0;
+    }
+    throw new GitError(`gave up after ${MAX_ATTEMPTS} attempts: others kept pushing glosses to ${remote}; try again`);
+}

package/dist/commands/versions.js

@@ -0,0 +1,132 @@
+import { parseArgs } from 'node:util';
+import { commitDiff, git, gitTry, GlossError, NOTES_REF, resolveCommit, WIP_NOTES_REF, WIP_REF, writeNote } from '../git.js';
+import { location, parseDiff } from '../diff.js';
+import { mergeGlosses } from '../merge.js';
+import { noteFormat } from '../schema.js';
+import { refLabel } from '../selection.js';
+export const usage = 'versions [<commit> | wip] [--show <n> | --restore <n>]   every gloss a commit has had (replaced, carried, merged), newest first; wip: every gloss of uncommitted work, including dropped groups';
+// Every change to the notes in `ref`, newest first: a note's history is the
+// notes ref's history, so a replaced or removed gloss is still there. Merges
+// are skipped; each side's own commits carry the versions they brought.
+function history(ref, only) {
+    if (!gitTry(['rev-parse', '-q', '--verify', ref]))
+        return [];
+    const out = [];
+    // One notes commit's changes, per object. When git reorganises the notes
+    // tree (ab/cdef… directories once there are many notes), each note shows
+    // as removed from one path and added at another; that pair is one entry,
+    // and none at all if the gloss itself didn't change.
+    let at = '', how = '', changes = new Map();
+    const flush = () => {
+        for (const [object, c] of changes) {
+            if (c.removed && c.added && c.removed === c.added)
+                continue;
+            out.push({ object, blob: c.added ?? null, at, how });
+        }
+        changes = new Map();
+    };
+    for (const line of git(['log', '--no-merges', '--raw', '--no-abbrev', '--no-renames', '--format=%x00%cI%x00%s', ref, '--']).split('\n')) {
+        if (line.startsWith('\0')) {
+            flush();
+            [, at, how] = line.split('\0');
+            continue;
+        }
+        const m = /^:\d+ \d+ ([0-9a-f]+) ([0-9a-f]+) (\w)\t(.+)$/.exec(line);
+        if (!m)
+            continue;
+        // Notes are stored under the object's id, possibly split into directories.
+        const object = m[4].replaceAll('/', '');
+        if (only && object !== only)
+            continue;
+        const c = changes.get(object) ?? {};
+        if (m[3] === 'D')
+            c.removed = m[1];
+        else {
+            c.added = m[2];
+            if (m[3] === 'M')
+                c.removed = m[1];
+        }
+        changes.set(object, c);
+    }
+    flush();
+    return out;
+}
+function summary(blob) {
+    try {
+        const note = JSON.parse(git(['cat-file', 'blob', blob]));
+        const a = note.annotation;
+        const from = note.sources ? `carried from ${note.sources.map((s) => s.slice(0, 7)).join(', ')}; ` : '';
+        return `${from}${a.groups.length} group${a.groups.length === 1 ? '' : 's'}: ${a.groups.map((g) => g.id).join(', ')}\n       task: ${JSON.stringify(a.task)}`;
+    }
+    catch {
+        return '(not a readable gloss: joined notes from a squash, or not JSON)';
+    }
+}
+const when = (iso) => iso.slice(0, 16).replace('T', ' ');
+export function run(argv) {
+    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { show: { type: 'string' }, restore: { type: 'string' } } });
+    const wip = positionals[0] === 'wip';
+    const ref = wip ? WIP_NOTES_REF : NOTES_REF;
+    const sha = wip ? null : resolveCommit(positionals[0] ?? 'HEAD');
+    const versions = history(ref, sha ?? undefined);
+    const label = sha ? sha.slice(0, 7) : 'uncommitted work';
+    if (!versions.length) {
+        console.log(`no glosses recorded for ${label}`);
+        return 0;
+    }
+    const pick = (arg, flag) => {
+        const n = Number(arg);
+        const v = versions[n - 1];
+        if (!Number.isInteger(n) || !v)
+            throw new GlossError(`${flag} takes a version number from 1 to ${versions.length}`);
+        if (!v.blob)
+            throw new GlossError(`version ${n} records the gloss being removed; pick a version with a gloss`);
+        return { n, v: v };
+    };
+    if (values.show !== undefined) {
+        process.stdout.write(git(['cat-file', 'blob', pick(values.show, '--show').v.blob]));
+        return 0;
+    }
+    if (values.restore !== undefined) {
+        const { n, v } = pick(values.restore, '--restore');
+        if (!wip) {
+            git(['notes', '--ref', ref, 'add', '-f', '-C', v.blob, sha]);
+            console.log(`restored version ${n} as the gloss of ${label}`);
+            return 0;
+        }
+        // A wip version was written for the snapshot of its time. Carry it onto
+        // the current snapshot line by line, as `carry` does, so it describes the
+        // work as it is now; copy it as is only if that old snapshot is gone.
+        const onto = gitTry(['rev-parse', '-q', '--verify', WIP_REF])?.trim();
+        if (!onto)
+            throw new GlossError('there is no snapshot of uncommitted work to restore onto; run git gloss hunks wip first');
+        const note = JSON.parse(git(['cat-file', 'blob', v.blob]));
+        if (v.object === onto || gitTry(['cat-file', '-e', `${v.object}^{commit}`]) === null) {
+            git(['notes', '--ref', ref, 'add', '-f', '-C', v.blob, onto]);
+            console.log(`restored version ${n} onto the wip snapshot ${onto.slice(0, 7)}` +
+                (v.object === onto ? '' : `; its snapshot ${v.object.slice(0, 7)} is gone, so hunk references may not match: check with git gloss show wip`));
+            return 0;
+        }
+        const current = parseDiff(commitDiff(onto));
+        const merged = mergeGlosses([{ sha: v.object, note, hunks: parseDiff(commitDiff(v.object)) }], current);
+        if (!merged.annotation)
+            throw new GlossError(`none of version ${n}'s glossed changes are in the uncommitted work any more; read it with --show ${n}`);
+        writeNote(onto, {
+            gloss: noteFormat(merged.annotation), commit: onto, created_at: new Date().toISOString(),
+            annotation: merged.annotation, hunks: current.map(location), carried_from: v.object,
+        }, WIP_NOTES_REF);
+        console.log(`restored ${merged.annotation.groups.length} group${merged.annotation.groups.length === 1 ? '' : 's'} of version ${n} onto the wip snapshot ${onto.slice(0, 7)}` +
+            (merged.dropped.length ? `\n  not restored (their changes are no longer in the work): ${merged.dropped.map((d) => d.split(':')[1]).join(', ')}` : '') +
+            (merged.gaps.length ? `\n  changes it doesn't explain: ${merged.gaps.map((u) => refLabel(u.hunk.id, u.lines)).join(', ')}` : ''));
+        return 0;
+    }
+    console.log(`glosses of ${label}, newest first:`);
+    versions.forEach((v, i) => {
+        const head = `${String(i + 1).padStart(3)}  ${when(v.at)}  ${v.how}${wip ? `  (snapshot ${v.object.slice(0, 7)})` : ''}`;
+        console.log(`${head}${i === 0 && v.blob && !wip ? '  [current]' : ''}`);
+        console.log(`       ${v.blob ? summary(v.blob) : 'removed'}`);
+    });
+    const arg = positionals[0] ?? 'HEAD';
+    console.log(`\nread one: git gloss versions ${arg} --show <n>   bring one back: git gloss versions ${arg} --restore <n>`);
+    return 0;
+}

package/dist/commands/why.js

@@ -0,0 +1,209 @@
+import { parseArgs } from 'node:util';
+import { blameRange, commitSubject, lineHistory } from '../git.js';
+import { loadGloss } from '../loader.js';
+import { servesOf } from '../schema.js';
+import { field, groupHeader, style } from '../render.js';
+import { bodyLines, formatRanges } from '../selection.js';
+export const usage = 'why <file>:<line>[-<end>] [--history] [--rev <commit>] [--json]   explain why code exists';
+// Glosses are loaded at most once per commit, however many lines or steps
+// refer to it; each load diffs the commit.
+const glossCache = new Map();
+function glossFor(commit) {
+    if (!glossCache.has(commit))
+        glossCache.set(commit, loadGloss(commit));
+    return glossCache.get(commit);
+}
+// Groups in a gloss that own `line` of `file` on the new side of the commit's
+// diff: they claim the whole hunk, or that line's changed-line number.
+function groupsForLine(gloss, file, line) {
+    return (gloss?.groups ?? [])
+        .filter((g) => g.hunks.some(({ current: h, lines }) => {
+        if (!h || h.file !== file || line < h.newStart || line >= h.newStart + h.newLines)
+            return false;
+        if (!lines)
+            return true;
+        const idx = bodyLines(h).find((l) => l.kind === 'add' && l.newNo === line)?.idx;
+        return idx !== undefined && idx !== null && lines.has(idx);
+    }))
+        .map((g) => g.group);
+}
+function step(commit, file, lines) {
+    const gloss = glossFor(commit);
+    const groups = [...new Map(lines.flatMap((l) => groupsForLine(gloss, file, l)).map((g) => [g.id, g])).values()];
+    return { commit, subject: gloss?.subject ?? commitSubject(commit), file, lines, gloss, groups };
+}
+// A change whose only explanation is mechanical (rename, reformat) says
+// nothing about why the code exists, so it is looked through.
+const mechanicalOnly = (s) => s.groups.length > 0 && s.groups.every((g) => g.necessity === 'mechanical');
+// Every group a group serves, directly or through others, nearest first.
+// `add` rejects cycles; the seen set guards glosses written before it did.
+function chain(gloss, g) {
+    const byId = new Map(gloss?.note.annotation.groups.map((x) => [x.id, x]) ?? []);
+    const seen = new Set([g.id]);
+    const out = [];
+    const queue = servesOf(g);
+    while (queue.length) {
+        const next = byId.get(queue.shift());
+        if (!next || seen.has(next.id))
+            continue;
+        seen.add(next.id);
+        out.push(next);
+        queue.push(...servesOf(next));
+    }
+    return out;
+}
+function explain(run, history) {
+    const { commit, origFile } = run[0];
+    const orig = run.map((b) => b.origLine);
+    const latest = step(commit, origFile, orig);
+    const lines = run.map((b) => b.line);
+    // The run is contiguous in the blamed commit, so git log -L tracks exactly
+    // these lines and not others between them.
+    const start = orig[0], end = orig[orig.length - 1];
+    if (!history && !mechanicalOnly(latest)) {
+        // Only whether older history exists, without walking it.
+        const more = (lineHistory(origFile, start, end, commit, 2)?.length ?? 0) > 1;
+        return { lines, latest, before: [], moreHistory: more, note: null };
+    }
+    const trail = lineHistory(origFile, start, end, commit) ?? [];
+    // Normally the trail starts at the blamed commit. If they disagree (blame
+    // can skip commits, e.g. with blame.ignoreRevsFile), keep the trail's older
+    // commits anyway and say so rather than drop them.
+    const at = trail.findIndex((t) => t.commit === commit);
+    const older = at >= 0 ? trail.slice(at + 1) : trail;
+    const note = trail.length && at !== 0 ? 'git log -L traced these lines from a different commit than blame named; the history may be incomplete' : null;
+    const before = [];
+    for (const t of older) {
+        if (!history && !mechanicalOnly(before.at(-1) ?? latest))
+            break;
+        before.push(step(t.commit, t.file, t.lines));
+    }
+    return { lines, latest, before, moreHistory: older.length > before.length, note };
+}
+const stepJson = (s) => ({
+    commit: s.commit,
+    subject: s.subject,
+    file: s.file,
+    lines_in_commit: formatRanges(s.lines),
+    glossed: s.gloss !== null,
+    stale: s.gloss?.stale ?? false,
+    task: s.gloss?.note.annotation.task ?? null,
+    // serves is always a list here, whichever form the gloss used.
+    groups: s.groups.map((g) => ({ ...g, serves: servesOf(g), serves_chain: chain(s.gloss, g).map((c) => c.id) })),
+});
+export function run(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { rev: { type: 'string' }, json: { type: 'boolean' }, history: { type: 'boolean' } },
+    });
+    const m = /^(.+):(\d+)(?:-(\d+))?$/.exec(positionals[0] ?? '');
+    if (!m || Number(m[2]) < 1 || (m[3] && Number(m[3]) < Number(m[2]))) {
+        console.error('usage: git gloss ' + usage);
+        return 2;
+    }
+    const [, file, startStr, endStr] = m;
+    const start = Number(startStr), end = Number(endStr ?? startStr);
+    // One blame for the whole range, then one explanation per contiguous run of
+    // lines (in the blamed commit) that a commit last changed, in the order the
+    // runs appear. A commit's lines can be split by others' changes, and each
+    // run's history has to be traced separately.
+    const blamed = blameRange(file, start, end, values.rev);
+    const uncommitted = [];
+    const byCommit = new Map();
+    for (const b of blamed) {
+        if (/^0+$/.test(b.commit)) {
+            uncommitted.push(b.line);
+            continue;
+        }
+        if (!byCommit.has(b.commit))
+            byCommit.set(b.commit, []);
+        byCommit.get(b.commit).push(b);
+    }
+    const runs = [];
+    for (const group of byCommit.values()) {
+        group.sort((x, y) => x.origLine - y.origLine);
+        for (const b of group) {
+            const last = runs.at(-1);
+            if (last && last[0].commit === b.commit && b.origLine === last[last.length - 1].origLine + 1)
+                last.push(b);
+            else
+                runs.push([b]);
+        }
+    }
+    runs.sort((x, y) => Math.min(...x.map((b) => b.line)) - Math.min(...y.map((b) => b.line)));
+    const explanations = runs.map((run) => explain(run, !!values.history));
+    const short = blamed.length < end - start + 1 ? `the file ends at line ${start + blamed.length - 1}` : null;
+    if (values.json) {
+        console.log(JSON.stringify({
+            file, start, end,
+            explanations: explanations.map((e) => ({
+                lines: formatRanges(e.lines),
+                ...stepJson(e.latest),
+                risks: e.latest.gloss?.note.annotation.risks ?? [],
+                alternatives: e.latest.gloss?.note.annotation.alternatives ?? [],
+                // Older commits: mechanical changes looked through by default, every
+                // change with --history.
+                before: e.before.map(stepJson),
+                more_history: e.moreHistory,
+                note: e.note,
+            })),
+            uncommitted: uncommitted.length ? formatRanges(uncommitted) : null,
+            note: short,
+        }, null, 2));
+        return 0;
+    }
+    const out = [];
+    const span = start === end ? `${start}` : `${start}-${end}`;
+    const renderStep = (s, label, older) => {
+        // Where the lines were in an older commit: after edits or a file rename
+        // that differs from the query.
+        const then = older || s.file !== file ? style('dim', `  (${s.file}:${formatRanges(s.lines)} then)`) : '';
+        out.push(`${label}${style('yellow', s.commit.slice(0, 10))} ${s.subject}${then}`);
+        if (!s.gloss) {
+            out.push(style('dim', '  no gloss for this commit'));
+            return;
+        }
+        out.push(...field('task:', s.gloss.note.annotation.task));
+        for (const w of s.gloss.warnings)
+            out.push(style(['bold', 'red'], `  ⚠ ${w}`));
+        if (!s.groups.length)
+            out.push(style('dim', '  these lines are not in an annotated hunk'));
+        for (const g of s.groups) {
+            out.push(...groupHeader(g).map((l) => '  ' + l));
+            for (const parent of chain(s.gloss, g))
+                out.push(`    ${style('dim', '↳ which serves:')} ${parent.intent} ${style('dim', `(${parent.id})`)}`);
+        }
+    };
+    explanations.forEach((e, i) => {
+        if (i > 0)
+            out.push('');
+        const label = runs.length > 1 || start !== end
+            ? style('bold', `line${e.lines.length === 1 ? '' : 's'} ${formatRanges(e.lines)}  `)
+            : '';
+        renderStep(e.latest, label, false);
+        // Risks and rejected alternatives cover the whole commit, not just these
+        // lines, so text output points at them instead of printing them here.
+        const a = e.latest.gloss?.note.annotation;
+        const extras = [a?.risks?.length && `${a.risks.length} risk${a.risks.length === 1 ? '' : 's'}`,
+            a?.alternatives?.length && `${a.alternatives.length} rejected alternative${a.alternatives.length === 1 ? '' : 's'}`].filter(Boolean);
+        if (extras.length)
+            out.push(style('dim', `  the commit also lists ${extras.join(' and ')}: git gloss show ${e.latest.commit.slice(0, 7)} --full`));
+        e.before.forEach((s, j) => {
+            const prev = j === 0 ? e.latest : e.before[j - 1];
+            out.push(style('dim', mechanicalOnly(prev) ? '  ↓ that change was mechanical; before it:' : '  ↓ before that:'));
+            renderStep(s, '  ', true);
+        });
+        if (e.note)
+            out.push(style('dim', `  ${e.note}`));
+    });
+    if (!values.history && explanations.some((e) => e.moreHistory)) {
+        out.push('', style('dim', `Earlier changes to these lines: git gloss why ${file}:${span}${values.rev ? ` --rev ${values.rev}` : ''} --history`));
+    }
+    if (short)
+        out.push('', style('dim', short));
+    if (uncommitted.length)
+        out.push('', style('dim', `lines ${formatRanges(uncommitted)} are not committed yet`));
+    console.log(out.join('\n'));
+    return 0;
+}

package/dist/diff.js

@@ -0,0 +1,144 @@
+import { createHash } from 'node:crypto';
+const HUNK_HEADER = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
+const ESCAPES = { a: 7, b: 8, t: 9, n: 10, v: 11, f: 12, r: 13 };
+// git C-quotes paths with unusual characters: "q\"x.js", "a\tb", and octal
+// bytes such as \303\251 for non-ASCII when core.quotePath is on.
+export function unquote(quoted) {
+    const body = quoted.slice(1, -1);
+    const parts = [];
+    let last = 0;
+    for (const m of body.matchAll(/\\([0-7]{3}|.)/g)) {
+        parts.push(Buffer.from(body.slice(last, m.index), 'utf8'));
+        const e = m[1];
+        parts.push(Buffer.from([e.length === 3 ? parseInt(e, 8) : (ESCAPES[e] ?? e.charCodeAt(0))]));
+        last = m.index + m[0].length;
+    }
+    parts.push(Buffer.from(body.slice(last), 'utf8'));
+    return Buffer.concat(parts).toString('utf8');
+}
+// A path from a "--- a/x" or "+++ b/x" line: null for /dev/null, without the
+// a/ b/ prefix, unquoted, and without the tab git appends to paths that
+// contain spaces.
+export function parsePath(raw) {
+    let p = raw.replace(/\t$/, '');
+    if (p === '/dev/null')
+        return null;
+    if (p.startsWith('"') && p.endsWith('"'))
+        p = unquote(p);
+    return p.replace(/^[ab]\//, '');
+}
+export function parseDiff(diff) {
+    const lines = diff.split('\n');
+    const hunks = [];
+    let file = null;
+    let i = 0;
+    const flush = () => {
+        if (!file)
+            return;
+        if (file.hunks.length === 0) {
+            // Still give header-only changes an id so they can be annotated.
+            hunks.push({
+                id: '',
+                file: file.newFile ?? file.oldFile ?? '?',
+                oldFile: file.oldFile,
+                oldStart: 0, oldLines: 0, newStart: 0, newLines: 0,
+                text: file.meta.join('\n'),
+                hash: '',
+                added: 0, removed: 0,
+            });
+        }
+        hunks.push(...file.hunks);
+        file = null;
+    };
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.startsWith('diff --git ')) {
+            flush();
+            const m = /^diff --git a\/(.*) b\/(.*)$/.exec(line);
+            file = { oldFile: m?.[1] ?? null, newFile: m?.[2] ?? null, meta: [line], hunks: [] };
+            i++;
+            continue;
+        }
+        if (!file) {
+            i++;
+            continue;
+        }
+        if (line.startsWith('--- ')) {
+            file.oldFile = parsePath(line.slice(4));
+            file.meta.push(line);
+            i++;
+            continue;
+        }
+        if (line.startsWith('+++ ')) {
+            file.newFile = parsePath(line.slice(4));
+            file.meta.push(line);
+            i++;
+            continue;
+        }
+        if (line.startsWith('new file mode')) {
+            file.oldFile = null;
+        }
+        if (line.startsWith('deleted file mode')) {
+            file.newFile = null;
+        }
+        if (line.startsWith('rename from '))
+            file.oldFile = line.slice(12);
+        if (line.startsWith('rename to '))
+            file.newFile = line.slice(10);
+        const h = HUNK_HEADER.exec(line);
+        if (!h) {
+            file.meta.push(line);
+            i++;
+            continue;
+        }
+        const oldStart = Number(h[1]), oldLines = h[2] === undefined ? 1 : Number(h[2]);
+        const newStart = Number(h[3]), newLines = h[4] === undefined ? 1 : Number(h[4]);
+        const body = [line];
+        let oldLeft = oldLines, newLeft = newLines, added = 0, removed = 0;
+        i++;
+        // Consume by line counts, not by prefix: a removed line "-- x" looks like a
+        // "--- " file header and would otherwise end the hunk early.
+        while (i < lines.length && (oldLeft > 0 || newLeft > 0 || lines[i].startsWith('\\'))) {
+            const l = lines[i];
+            if (l.startsWith('+')) {
+                newLeft--;
+                added++;
+            }
+            else if (l.startsWith('-')) {
+                oldLeft--;
+                removed++;
+            }
+            else if (l.startsWith('\\')) { /* "" */ }
+            else {
+                oldLeft--;
+                newLeft--;
+            }
+            body.push(l);
+            i++;
+        }
+        file.hunks.push({
+            id: '',
+            file: file.newFile ?? file.oldFile ?? '?',
+            oldFile: file.oldFile,
+            oldStart, oldLines, newStart, newLines,
+            text: body.join('\n'),
+            hash: '',
+            added, removed,
+        });
+    }
+    flush();
+    hunks.forEach((h, n) => {
+        h.id = `h${n + 1}`;
+        // Hash only what the hunk changes, so a rebase that shifts line numbers or
+        // context lines doesn't make an otherwise identical hunk look different.
+        const body = h.text.startsWith('@@')
+            ? h.text.split('\n').slice(1).filter((l) => l[0] === '+' || l[0] === '-' || l[0] === '\\').join('\n')
+            : h.text;
+        h.hash = createHash('sha256').update(h.file + '\0' + body).digest('hex').slice(0, 16);
+    });
+    return hunks;
+}
+export function location(h) {
+    const { id, file, oldFile, oldStart, oldLines, newStart, newLines, hash } = h;
+    return { id, file, oldFile, oldStart, oldLines, newStart, newLines, hash };
+}