@ok-ggwp/git-gloss 0.0.0-stage → 0.2.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 };
+}

package/dist/git.js

@@ -0,0 +1,315 @@
+import { execFileSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdtempSync, rmSync, statSync, utimesSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Annotation, NOTE_FORMAT } from './schema.js';
+import { parsePath, unquote } from './diff.js';
+export const NOTES_REF = 'refs/notes/gloss';
+// Glosses of uncommitted work (wip snapshots) live in their own notes ref,
+// which sync never pushes, and the latest snapshot in a private ref that
+// keeps it from being garbage-collected. refs/worktree/ refs are per
+// worktree, so each linked worktree has its own snapshot.
+export const WIP_NOTES_REF = 'refs/notes/gloss-wip';
+export const WIP_REF = 'refs/worktree/gloss/wip';
+const WIP_MESSAGE = 'git-gloss wip snapshot';
+export const REMOTE_NOTES_REF = 'refs/notes/remotes/origin/gloss';
+export const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+// Errors whose message is fit to show the user without a stack trace.
+export class GlossError extends Error {
+}
+export class GitError extends GlossError {
+}
+export function git(args, input, env = {}) {
+    try {
+        return execFileSync('git', args, {
+            encoding: 'utf8',
+            input,
+            // Untranslated messages: readNote recognises "no note found" by its text.
+            env: { ...process.env, ...env, LC_ALL: 'C' },
+            maxBuffer: 256 * 1024 * 1024,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        const stderr = err.stderr?.trim();
+        throw new GitError(stderr || `git ${args.join(' ')} failed`);
+    }
+}
+export function gitTry(args, input) {
+    try {
+        return git(args, input);
+    }
+    catch {
+        return null;
+    }
+}
+// Untracked files that look like secrets. A snapshot is shown and sent to
+// reviewers, so these are left out unless the user stages them.
+const SENSITIVE = [
+    /^\.env(\..*)?$/, /\.(pem|key|p12|pfx|jks|keystore|kdbx)$/, /^id_(rsa|dsa|ecdsa|ed25519)$/,
+    /(^|[-_.])(secrets?|credentials?|tokens?|passwords?)([-_.]|$)/i, /^\.(netrc|npmrc|pypirc)$/,
+];
+const looksSensitive = (path) => SENSITIVE.some((re) => re.test(path.split('/').pop()));
+// The working tree as a tree object: tracked files, staged files, and
+// untracked files except ignored ones and ones that look like secrets. Built
+// in a temporary index so the real index is untouched. `excluded` lists the
+// untracked files left out as possible secrets.
+function workingTree() {
+    const dir = mkdtempSync(join(tmpdir(), 'git-gloss-index-'));
+    try {
+        const index = join(dir, 'index');
+        const real = git(['rev-parse', '--path-format=absolute', '--git-path', 'index']).trim();
+        if (existsSync(real)) {
+            copyFileSync(real, index);
+            // Keep the index's timestamps: git compares them with file mtimes to
+            // spot files edited in the same second as the index was written
+            // ("racily clean"), and a fresh mtime would hide such edits.
+            const { atime, mtime } = statSync(real);
+            utimesSync(index, atime, mtime);
+        }
+        const env = { GIT_INDEX_FILE: index };
+        const untracked = git(['ls-files', '--others', '--exclude-standard', '-z', '--', ':/']).split('\0').filter(Boolean);
+        const excluded = untracked.filter(looksSensitive);
+        git(['add', '-A', '--', ':/'], undefined, env);
+        if (excluded.length)
+            git(['rm', '-q', '--cached', '--', ...excluded.map((p) => `:/${p}`)], undefined, env);
+        return { tree: git(['write-tree'], undefined, env).trim(), excluded };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+const headSha = () => gitTry(['rev-parse', '--verify', '--quiet', 'HEAD'])?.trim() ?? null;
+const treeAndParent = (sha) => {
+    const [tree, parent] = git(['log', '-1', '--format=%T %P', sha]).trim().split(' ');
+    return { tree, parent: parent || null };
+};
+// Record uncommitted changes as a commit on top of HEAD without touching the
+// branch, index or files, and point WIP_REF at it. Reuses the current
+// snapshot if nothing has changed, so its gloss stays attached.
+// `replaced` is the previous snapshot when this one replaces it, so the
+// caller can carry its gloss over.
+export function snapshotWorkingTree() {
+    const { tree, excluded } = workingTree();
+    const head = headSha();
+    if (head && git(['rev-parse', `${head}^{tree}`]).trim() === tree) {
+        throw new GlossError('there are no uncommitted changes to snapshot');
+    }
+    const current = gitTry(['rev-parse', '--verify', '--quiet', WIP_REF])?.trim();
+    if (current) {
+        const c = treeAndParent(current);
+        if (c.tree === tree && c.parent === head)
+            return { sha: current, excluded, replaced: null };
+    }
+    const sha = git(['commit-tree', tree, ...(head ? ['-p', head] : []), '-m', WIP_MESSAGE], undefined, commitIdentity()).trim();
+    if (current)
+        archiveSnapshot(current);
+    git(['update-ref', WIP_REF, sha]);
+    return { sha, excluded, replaced: current ?? null };
+}
+// Snapshots and archive entries are commit objects, which need an identity;
+// fall back to a placeholder where git has none configured rather than fail.
+function commitIdentity() {
+    const ident = (v) => gitTry(['var', v]) !== null;
+    const env = {};
+    if (!ident('GIT_AUTHOR_IDENT'))
+        Object.assign(env, { GIT_AUTHOR_NAME: 'git-gloss', GIT_AUTHOR_EMAIL: 'git-gloss@localhost' });
+    if (!ident('GIT_COMMITTER_IDENT'))
+        Object.assign(env, { GIT_COMMITTER_NAME: 'git-gloss', GIT_COMMITTER_EMAIL: 'git-gloss@localhost' });
+    return env;
+}
+// A glossed snapshot that is being replaced or cleared stays reachable from
+// this ref, so git gc keeps it: its old gloss, which the notes history keeps,
+// still has the changes it describes (`versions wip` reads and restores them).
+// Each entry is an empty commit whose parents are the previous entry and the
+// snapshot. Per worktree, like WIP_REF.
+export const ARCHIVE_REF = 'refs/worktree/gloss/archive';
+export function archiveSnapshot(sha) {
+    if (rawNote(WIP_NOTES_REF, sha) === null)
+        return;
+    const prev = gitTry(['rev-parse', '-q', '--verify', ARCHIVE_REF])?.trim();
+    const entry = git(['commit-tree', EMPTY_TREE, ...(prev ? ['-p', prev] : []), '-p', sha, '-m', 'git-gloss: earlier glossed wip snapshot'], undefined, commitIdentity()).trim();
+    git(['update-ref', ARCHIVE_REF, entry]);
+}
+export const dropWipNote = (sha) => gitTry(['notes', '--ref', WIP_NOTES_REF, 'remove', '--ignore-missing', sha]);
+export const isWipSnapshot = (sha) => gitTry(['log', '-1', '--format=%s', sha])?.trim() === WIP_MESSAGE;
+// Why the latest snapshot no longer matches the working tree, or null.
+export function wipStaleness(sha) {
+    const s = treeAndParent(sha);
+    if (s.parent !== headSha())
+        return 'HEAD has moved since this snapshot was taken';
+    if (workingTree().tree !== s.tree)
+        return 'the working tree has changed since this snapshot was taken';
+    return null;
+}
+export function resolveCommit(rev) {
+    // "wip": the latest snapshot of uncommitted work (made by `hunks wip`). A
+    // branch or tag named wip still works when there is no snapshot, and can be
+    // reached as heads/wip or tags/wip when there is.
+    const named = gitTry(['rev-parse', '--verify', '--quiet', `${rev}^{commit}`])?.trim();
+    if (rev === 'wip') {
+        const sha = gitTry(['rev-parse', '--verify', '--quiet', WIP_REF])?.trim();
+        if (sha) {
+            if (named)
+                console.error('note: "wip" means the snapshot of uncommitted work; for the branch or tag, use heads/wip or tags/wip');
+            const stale = wipStaleness(sha);
+            if (stale)
+                console.error(`warning: ${stale}; run \`git gloss hunks wip\` to snapshot again, then re-gloss`);
+            return sha;
+        }
+        if (!named)
+            throw new GlossError('no snapshot of uncommitted work yet; run `git gloss hunks wip` first');
+    }
+    const sha = named;
+    if (!sha)
+        throw new GitError(`not a commit: ${rev}`);
+    return sha.trim();
+}
+// A commit, or the commits in a range such as "main..feature", oldest first.
+// Merges are not reviewed (their first-parent diff repeats the merged
+// commits) but are returned so views can say they were skipped: a merge can
+// still carry conflict resolutions or edits of its own.
+export function resolveCommits(arg) {
+    if (!arg.includes('..'))
+        return { shas: [resolveCommit(arg)], merges: [], range: null };
+    if (arg.includes('...')) {
+        throw new GitError(`${arg}: "..." includes commits from both sides; use A..B for the commits on B since A`);
+    }
+    // --end-of-options: the argument is a revision range, never an option.
+    const list = (...flags) => git(['rev-list', '--reverse', ...flags, '--end-of-options', arg, '--']).split('\n').filter(Boolean);
+    const shas = list('--no-merges');
+    const merges = list('--merges');
+    if (!shas.length && !merges.length)
+        throw new GitError(`no commits in ${arg}`);
+    return { shas, merges, range: arg };
+}
+export function commitSubject(sha) {
+    return git(['log', '-1', '--format=%s', sha]).trim();
+}
+// Diff of a commit against its first parent (or the empty tree for a root
+// commit). Every option that changes which hunks git produces, or their order,
+// is pinned so hunk ids are the same regardless of the user's diff config.
+export function commitDiff(sha) {
+    return diffBetween(gitTry(['rev-parse', '--verify', '--quiet', `${sha}^1`])?.trim() || EMPTY_TREE, sha);
+}
+// The diff between two commits (or trees), with the same pinned options.
+export function diffBetween(from, to) {
+    return git([
+        '-c', 'core.quotePath=false', '-c', 'diff.suppressBlankEmpty=false',
+        'diff', '--no-color', '--no-ext-diff', '--no-textconv', '--find-renames',
+        '--src-prefix=a/', '--dst-prefix=b/', '-U3',
+        '-O/dev/null', '--diff-algorithm=myers', '--indent-heuristic',
+        '--inter-hunk-context=0', '--no-relative', '--submodule=short', '-l1000',
+        from, to,
+    ]);
+}
+function rawNote(ref, sha) {
+    try {
+        return git(['notes', '--ref', ref, 'show', sha]);
+    }
+    catch (err) {
+        if (/no note found/i.test(err.message))
+            return null;
+        throw err;
+    }
+}
+export function readNote(sha) {
+    // A commit's gloss, or a wip snapshot's (they are never the same object).
+    const raw = rawNote(NOTES_REF, sha) ?? rawNote(WIP_NOTES_REF, sha);
+    if (raw === null)
+        return null;
+    const at = `the gloss on ${sha.slice(0, 10)}`;
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        // notes.rewriteMode=concatenate joins two notes when a rebase squashes
+        // glossed commits together.
+        if (/}\s*\n\s*{/.test(raw)) {
+            throw new GlossError(`${at} holds several glosses joined together (from a squash or fixup); re-gloss it with \`git gloss add --force\``);
+        }
+        throw new GlossError(`${at} is not valid JSON; replace it with \`git gloss add --force\``);
+    }
+    if (typeof data?.gloss === 'number' && data.gloss > NOTE_FORMAT) {
+        throw new GlossError(`${at} was written by a newer git-gloss (format ${data.gloss}); upgrade to read it`);
+    }
+    const annotation = Annotation.safeParse(data?.annotation);
+    if (![1, 2, 3].includes(data?.gloss) || !Array.isArray(data.hunks) || !annotation.success) {
+        throw new GlossError(`${at} is malformed; replace it with \`git gloss add --force\``);
+    }
+    return { ...data, annotation: annotation.data };
+}
+export function writeNote(sha, note, ref = NOTES_REF) {
+    git(['notes', '--ref', ref, 'add', '-f', '-F', '-', sha], JSON.stringify(note, null, 2) + '\n');
+}
+// The commits that changed lines start..end of `file`, newest first, starting
+// from `commit`, following them through edits, moves within the file and
+// renames. Each step gives the file's path in that commit and the lines' new
+// numbers in its diff. `max` stops after that many commits (to check whether
+// any older history exists without walking it). Uses git log -L, so it is
+// approximate when lines are heavily rewritten. Null if git can't trace them.
+export function lineHistory(file, start, end, commit, max) {
+    const out = gitTry([
+        // showSignature would print signature checks between the commits.
+        '-c', 'core.quotePath=false', '-c', 'log.showSignature=false', 'log', '--no-color', '--no-ext-diff',
+        '--src-prefix=a/', '--dst-prefix=b/', `-L${start},${end}:${file}`, '--format=%x00%H',
+        ...(max ? [`--max-count=${max}`] : []), commit,
+    ]);
+    if (out === null)
+        return null;
+    return out.split('\0').filter((chunk) => chunk.trim()).map((chunk) => {
+        const [first, ...rest] = chunk.split('\n');
+        let path = file, newNo = 0, inHunk = false;
+        const lines = [];
+        for (const l of rest) {
+            if (l.startsWith('diff --git ')) {
+                inHunk = false;
+                continue;
+            }
+            // Inside a hunk, decide by position, not prefix: an added line whose
+            // text starts with "++ " would otherwise look like a "+++" header.
+            if (!inHunk && l.startsWith('+++ ')) {
+                path = parsePath(l.slice(4)) ?? path;
+                continue;
+            }
+            const h = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(l);
+            if (h) {
+                newNo = Number(h[1]);
+                inHunk = true;
+                continue;
+            }
+            if (!inHunk)
+                continue;
+            if (l.startsWith('+'))
+                lines.push(newNo++);
+            else if (l.startsWith(' '))
+                newNo++;
+        }
+        return { commit: first.trim(), file: path, lines };
+    });
+}
+// Blame lines start..end in one call (one record per line).
+export function blameRange(file, start, end, rev) {
+    const args = ['blame', '--line-porcelain', '-L', `${start},${end}`];
+    if (rev)
+        args.push(rev);
+    args.push('--', file);
+    const out = [];
+    let cur = null;
+    for (const l of git(args).split('\n')) {
+        // 40 hex digits for SHA-1 repositories, 64 for SHA-256.
+        const head = /^([0-9a-f]{40}(?:[0-9a-f]{24})?) (\d+) (\d+)/.exec(l);
+        if (head) {
+            cur = { commit: head[1], origLine: Number(head[2]), line: Number(head[3]), origFile: file };
+            out.push(cur);
+            continue;
+        }
+        // Porcelain C-quotes unusual file names, like diff headers do.
+        if (cur && l.startsWith('filename ')) {
+            const raw = l.slice(9);
+            cur.origFile = raw.startsWith('"') ? unquote(raw) : raw;
+        }
+    }
+    return out;
+}