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

package/dist/commands/show.js

@@ -0,0 +1,210 @@
+import { parseArgs } from 'node:util';
+import { commitSubject, gitTry, readNote, resolveCommits } from '../git.js';
+import { refLabel, sliceStats, sliceText } from '../selection.js';
+import { loadGloss } from '../loader.js';
+import { NECESSITY } from '../schema.js';
+import { current, reviewStatus, statusPhrase, verdict } from '../reviews.js';
+import { colorDiff, field, groupHeader, hunkLabel, necessityWord, noteFooter, page, style, termWidth, wrap, } from '../render.js';
+export const usage = 'show [<commit> | <range>] [-g <group>]... [--full] [--diff] [--only <necessity,...>]   summarise a gloss, or each commit in a range';
+// Counts over the lines each part selects, not whole hunks, so groups that
+// split a hunk don't both count all of it.
+function stats(parts) {
+    const s = parts.map((p) => sliceStats(p.hunk, p.lines));
+    return {
+        count: parts.length,
+        added: s.reduce((n, x) => n + x.added, 0),
+        removed: s.reduce((n, x) => n + x.removed, 0),
+    };
+}
+const currentParts = (g) => g.hunks.flatMap((h) => (h.current ? [{ hunk: h.current, lines: h.lines }] : []));
+export function run(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            group: { type: 'string', short: 'g', multiple: true },
+            full: { type: 'boolean' },
+            diff: { type: 'boolean' },
+            only: { type: 'string' },
+        },
+    });
+    const only = values.only?.split(',').map((s) => s.trim());
+    const unknown = only?.filter((n) => !NECESSITY.includes(n));
+    if (unknown?.length) {
+        console.error(`error: unknown necessity ${unknown.join(', ')}; expected ${NECESSITY.join(', ')}`);
+        return 2;
+    }
+    const { shas, merges, range } = resolveCommits(positionals[0] ?? 'HEAD');
+    if (!range) {
+        const gloss = loadGloss(shas[0]);
+        if (!gloss) {
+            console.error(`${shas[0].slice(0, 10)} has no gloss (annotate it with \`git gloss add\`)`);
+            return 1;
+        }
+        const sha = shas[0];
+        const ids = gloss.groups.map((g) => g.group.id);
+        const missing = values.group?.filter((id) => !ids.includes(id));
+        if (missing?.length) {
+            // Usually the group is in an earlier commit's gloss, e.g. one shown just
+            // before HEAD moved. Look a little way back for one that has them all.
+            const earlier = (gitTry(['rev-list', '--max-count=30', `${sha}~1`]) ?? '').split('\n').filter(Boolean).find((c) => {
+                try {
+                    const groups = readNote(c)?.annotation.groups.map((g) => g.id) ?? [];
+                    return missing.every((id) => groups.includes(id));
+                }
+                catch {
+                    return false;
+                }
+            });
+            const flags = missing.map((id) => `-g ${id}`).join(' ');
+            console.error(`error: the gloss on ${sha.slice(0, 7)} (${gloss.subject}) has no group ${missing.join(', ')}; its groups are ${ids.join(', ')}` +
+                (earlier ? `\n  found in ${earlier.slice(0, 7)} (${commitSubject(earlier)}): git gloss show ${earlier.slice(0, 7)} ${flags}` : ''));
+            return 2;
+        }
+        const out = renderCommit(sha, gloss, values, only, true);
+        if (!out) {
+            console.error(`no groups match ${[values.group && `-g ${values.group.join(',')}`, only && `--only ${only.join(',')}`].filter(Boolean).join(' and ')}`);
+            return 1;
+        }
+        page(out.join('\n'));
+        return 0;
+    }
+    // A range: each commit in turn, oldest first. Group ids repeat across
+    // commits, so -g is for single commits.
+    if (values.group) {
+        console.error('error: -g needs a single commit; pick one from the range, e.g. git gloss show <commit> -g <group>');
+        return 2;
+    }
+    const glosses = shas.map((sha) => loadGloss(sha));
+    const glossed = glosses.filter(Boolean).length;
+    const stale = glosses.filter((g) => g?.stale).length;
+    // How many glossed commits had their gloss checked: an honesty review that
+    // saw this code and this gloss.
+    const honesty = shas.map((sha, i) => (glosses[i] ? reviewStatus(sha).find((r) => r.stage === 'honesty' && current(r)) : undefined));
+    const vetted = honesty.filter(Boolean).length;
+    const flagged = honesty.filter((r) => r && verdict(r) === 'issues').length;
+    const out = [
+        style('bold', `${range}: ${shas.length} commit${shas.length === 1 ? '' : 's'}, ${glossed} glossed`) +
+            (glossed ? style(vetted === glossed ? 'green' : 'yellow', `, ${vetted} honesty-reviewed`) : '') +
+            (flagged ? style('yellow', ` (${flagged} with issues)`) : '') +
+            (stale ? style('red', ` (${stale} stale)`) : '') +
+            (merges.length ? style('dim', `  (${merges.length} merge${merges.length === 1 ? '' : 's'} not shown)`) : ''),
+    ];
+    shas.forEach((sha, i) => {
+        out.push('', style('dim', '─'.repeat(Math.min(termWidth(), 60))));
+        const gloss = glosses[i];
+        if (!gloss) {
+            out.push(`${style('yellow', sha.slice(0, 10))} ${style('bold', commitSubject(sha))}`, style('dim', 'no gloss for this commit'));
+            return;
+        }
+        // An --only filter can leave a commit with nothing to show; say so and move on.
+        out.push(...(renderCommit(sha, gloss, values, only, false) ??
+            [`${style('yellow', sha.slice(0, 10))} ${style('bold', gloss.subject)}`, style('dim', `no ${only?.join('/')} groups`)]));
+    });
+    if (glossed)
+        out.push('', style('dim', 'One commit in detail: git gloss show <commit> --full   (or -g <group> for its code)'));
+    page(out.join('\n'));
+    return 0;
+}
+// One line on whether the commit as it is now was reviewed, per stage.
+function reviewsLine(sha) {
+    const statuses = reviewStatus(sha);
+    if (!statuses.length)
+        return style('dim', 'reviews: none recorded');
+    const color = (s) => (!current(s) || verdict(s) === 'issues' ? 'yellow' : verdict(s) === 'clean' ? 'green' : 'dim');
+    return `reviews: ${statuses.map((s) => style(color(s), statusPhrase(s))).join(style('dim', ' · '))}` +
+        style('dim', `   (findings: git gloss reviews ${sha.slice(0, 7)})`);
+}
+// One commit's view, or null if no group matches -g/--only. `hints` adds the
+// footer on how to expand, which a range prints once instead.
+function renderCommit(sha, gloss, values, only, hints) {
+    const a = gloss.note.annotation;
+    const short = sha.slice(0, 7);
+    const out = [`${style('yellow', sha.slice(0, 10))} ${style('bold', gloss.subject)}`];
+    out.push(...field('task:', a.task, 0));
+    if (a.summary)
+        out.push(...field('summary:', a.summary, 0));
+    for (const w of gloss.warnings)
+        out.push(...field('⚠', w, 0).map((l) => style('red', l)));
+    out.push(reviewsLine(sha));
+    const groups = gloss.groups
+        .filter((g) => !only || only.includes(g.group.necessity))
+        .filter((g) => !values.group || values.group.includes(g.group.id));
+    if (!groups.length)
+        return null;
+    // -g: chosen groups with their code. --full: every group's details, plus
+    // alternatives and risks. --diff: --full plus code.
+    if (values.group || values.full || values.diff) {
+        const withCode = values.diff || !!values.group;
+        for (const g of groups) {
+            out.push('', ...groupHeader(g.group));
+            if (!withCode)
+                continue;
+            for (const h of g.hunks) {
+                if (!h.current) {
+                    out.push('', style('red', `  ${h.id}: no longer in this commit's diff`));
+                    continue;
+                }
+                if (h.status === 'changed')
+                    out.push('', style('red', `  ${h.id}: content changed since it was glossed`));
+                out.push('', '  ' + hunkLabel(h.current, h.lines), colorDiff(sliceText(h.current, h.lines), '    '));
+            }
+        }
+        if (gloss.unannotated.length && !only && !values.group) {
+            out.push('', style(['bold', 'red'], '■ Unannotated changes'));
+            for (const u of gloss.unannotated) {
+                out.push('  ' + hunkLabel(u.hunk, u.lines));
+                if (withCode)
+                    out.push(colorDiff(sliceText(u.hunk, u.lines), '    '), '');
+            }
+        }
+        if (!values.group)
+            out.push(...noteFooter(gloss.note));
+        return out;
+    }
+    // Summary: one line per group.
+    const sorted = [...groups].sort((x, y) => NECESSITY.indexOf(x.group.necessity) - NECESSITY.indexOf(y.group.necessity));
+    const tally = NECESSITY.map((n) => [n, gloss.groups.filter((g) => g.group.necessity === n).length])
+        .filter(([, c]) => c > 0)
+        .map(([n, c]) => `${c} ${necessityWord(n)}`);
+    const showing = groups.length < gloss.groups.length ? style('dim', `  (showing ${groups.length}: --only ${only?.join(',')})`) : '';
+    out.push('', `${style('bold', `${gloss.groups.length} groups:`)} ${tally.join(style('dim', ' · '))}${showing}`, '');
+    const rows = sorted.map((g) => {
+        const s = stats(currentParts(g));
+        const stale = g.hunks.filter((h) => h.status !== 'ok').length;
+        return {
+            g, stale,
+            stat: `${s.count} hunk${s.count === 1 ? '' : 's'}`, added: `+${s.added}`, removed: `-${s.removed}`,
+        };
+    });
+    const un = stats(gloss.unannotated.map((u) => ({ hunk: u.hunk, lines: u.lines })));
+    const idW = Math.max(...rows.map((r) => r.g.group.id.length));
+    const statW = Math.max(...rows.map((r) => r.stat.length), un.count ? 8 : 0);
+    const addW = Math.max(...rows.map((r) => r.added.length));
+    const remW = Math.max(...rows.map((r) => r.removed.length));
+    const intentCol = 2 + 11 + 2 + idW + 2;
+    const statsW = 2 + statW + 1 + addW + 1 + remW;
+    const intentW = Math.max(20, termWidth() - intentCol - statsW);
+    for (const r of rows) {
+        // Intents wrap within their column rather than being cut off; the stats
+        // stay on the first line so the numbers still line up.
+        const [first, ...rest] = wrap(r.g.group.intent, intentW);
+        out.push(`  ${necessityWord(r.g.group.necessity, 11)}  ${style('bold', r.g.group.id.padEnd(idW))}  ` +
+            `${first.padEnd(intentW)}  ` +
+            style('dim', r.stat.padStart(statW)) + ' ' + style('green', r.added.padStart(addW)) + ' ' + style('red', r.removed.padStart(remW)), ...rest.map((l) => ' '.repeat(intentCol) + l));
+        if (r.stale) {
+            out.push(' '.repeat(intentCol) + style('red', `⚠ ${r.stale} of ${r.g.hunks.length} hunk(s) changed or gone since glossing`));
+        }
+    }
+    if (un.count && !only) {
+        const where = gloss.unannotated.map((u) => refLabel(u.hunk.id, u.lines)).join(', ');
+        out.push(`  ${style(['bold', 'red'], 'unannotated'.padEnd(11))}  ${style('red', `+${un.added} -${un.removed} not in any group: ${where}`)}`);
+    }
+    // Rejected alternatives and risks: short, and often what a reader most
+    // lacks, so they're in the summary rather than only behind --full.
+    out.push(...noteFooter(gloss.note));
+    if (hints) {
+        out.push('', style('dim', `Expand a group:  git gloss show ${short} -g <group>`), style('dim', `Everything:      --full (each group's evidence and notes)   --diff (and code)`));
+    }
+    return out;
+}

package/dist/commands/sync.js

@@ -0,0 +1,245 @@
+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 { REVIEWS_REF } from '../reviews.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 };
+}
+const REVIEWS_PUSH_REF = 'refs/notes/gloss-reviews-sync-tmp';
+// Reviews are shared like glosses, but never conflict: each review is a line,
+// and both sides' lines are kept (git's cat_sort_uniq). Only reviews of
+// commits the remote may see are sent. Returns null if the push lost a race.
+function syncReviews(remote, pushing) {
+    const tracking = `refs/notes/remotes/${remote}/gloss-reviews`;
+    const remoteHas = gitTry(['ls-remote', '--exit-code', remote, REVIEWS_REF]) !== null;
+    if (remoteHas)
+        git(['fetch', '-q', remote, `+${REVIEWS_REF}:${tracking}`]);
+    const before = noteList(REVIEWS_REF);
+    const theirs = remoteHas ? noteList(tracking) : new Map();
+    if (remoteHas) {
+        if (gitTry(['rev-parse', '-q', '--verify', REVIEWS_REF]) === null)
+            git(['update-ref', REVIEWS_REF, tracking]);
+        else
+            git(['notes', '--ref', REVIEWS_REF, 'merge', '-q', '-s', 'cat_sort_uniq', tracking]);
+    }
+    const merged = noteList(REVIEWS_REF);
+    const fetched = [...merged].filter(([object, blob]) => before.get(object) !== blob).length;
+    const allowed = shareable(remote, pushing);
+    const toPush = [...merged].filter(([object, blob]) => allowed.has(object) && theirs.get(object) !== blob);
+    if (!toPush.length)
+        return { fetched, pushed: 0 };
+    try {
+        if (remoteHas)
+            git(['update-ref', REVIEWS_PUSH_REF, tracking]);
+        else
+            gitTry(['update-ref', '-d', REVIEWS_PUSH_REF]);
+        for (const [object, blob] of toPush)
+            git(['notes', '--ref', REVIEWS_PUSH_REF, 'add', '-f', '-C', blob, object]);
+        try {
+            git(['push', '-q', '--no-verify', remote, `${REVIEWS_PUSH_REF}:${REVIEWS_REF}`]);
+        }
+        catch (err) {
+            if (/\(fetch first\)|non-fast-forward/.test(err.message))
+                return null;
+            throw err;
+        }
+        git(['notes', '--ref', REVIEWS_REF, 'merge', '-q', '-s', 'cat_sort_uniq', REVIEWS_PUSH_REF]);
+    }
+    finally {
+        gitTry(['update-ref', '-d', REVIEWS_PUSH_REF]);
+    }
+    return { fetched, pushed: toPush.length };
+}
+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);
+        let reviews = null;
+        for (let tries = 0; tries < MAX_ATTEMPTS && !reviews; tries++)
+            reviews = syncReviews(remote, pushing);
+        if (!reviews)
+            console.log(`  reviews not synced: others kept pushing reviews to ${remote}; run git gloss sync again`);
+        else if (reviews.fetched || reviews.pushed)
+            console.log(`  reviews: fetched ${reviews.fetched}, pushed ${reviews.pushed}`);
+        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;
+}