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

package/dist/origins.js

@@ -0,0 +1,156 @@
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { commitDiff, diffBetween, EMPTY_TREE, git, gitTry, NOTES_REF } from './git.js';
+import { parseDiff } from './diff.js';
+import { bodyLines } from './selection.js';
+// Commits that have a gloss and are in this repository (a teammate's gloss
+// can arrive before, or without, the commit it describes).
+export function glossedCommits() {
+    const shas = (gitTry(['notes', '--ref', NOTES_REF, 'list']) ?? '').split('\n').filter(Boolean).map((l) => l.split(' ')[1]);
+    if (!shas.length)
+        return [];
+    return git(['cat-file', '--batch-check=%(objectname) %(objecttype)'], shas.join('\n') + '\n')
+        .split('\n').filter((l) => l.endsWith(' commit')).map((l) => l.split(' ')[0]);
+}
+const diffs = new Map();
+const diffOf = (sha) => {
+    let d = diffs.get(sha);
+    if (!d)
+        diffs.set(sha, (d = parseDiff(commitDiff(sha))));
+    return d;
+};
+// git's patch-id: the same for two commits that make the same changes,
+// wherever they sit in history.
+function patchId(sha) {
+    const diff = gitTry(['show', '--format=', '--no-color', '--no-ext-diff', sha]);
+    return diff ? git(['patch-id', '--stable'], diff).split(' ')[0] || null : null;
+}
+// Where a commit's changes came from, among commits with a gloss:
+// 1. its message: "(cherry picked from commit X)" (cherry-pick -x), or the
+//    "Squashed commit of the following:" list git merge --squash writes;
+// 2. a commit with the same author, author date and patch-id: a cherry-pick
+//    or a rebase (both keep the author date), including GitHub's
+//    "Rebase and merge";
+// 3. with `squash`, a branch not merged into the commit whose combined diff is
+//    at least 80% the same as the commit's: a squash merge, including
+//    GitHub's "Squash and merge", whatever its message says.
+// Returns the source commits, oldest first, or null.
+export function findOrigins(target, opts = {}) {
+    const glossed = new Set(opts.glossed ?? glossedCommits());
+    glossed.delete(target);
+    if (!glossed.size)
+        return null;
+    const message = git(['log', '-1', '--format=%B', target]);
+    const named = [
+        ...[...message.matchAll(/\(cherry picked from commit ([0-9a-f]{7,64})\)/g)].map((m) => m[1]),
+        ...(/^Squashed commit of the following:/m.test(message) ? [...message.matchAll(/^commit ([0-9a-f]{40,64})$/gm)].map((m) => m[1]) : []),
+    ].map((s) => gitTry(['rev-parse', '-q', '--verify', `${s}^{commit}`])?.trim()).filter((s) => !!s && glossed.has(s));
+    // git lists squashed commits newest first.
+    if (named.length)
+        return [...new Set(named)].reverse();
+    const ident = (sha) => git(['log', '-1', '--format=%an%x00%ae%x00%ad', '--date=raw', sha]).trim();
+    const mine = ident(target);
+    const same = git(['log', '--no-walk=unsorted', '--stdin', '--format=%H%x00%an%x00%ae%x00%ad', '--date=raw'], [...glossed].join('\n'))
+        .split('\n').filter(Boolean).filter((l) => l.slice(l.indexOf('\0') + 1) === mine).map((l) => l.slice(0, l.indexOf('\0')));
+    if (same.length) {
+        const id = patchId(target);
+        const match = id && same.find((s) => patchId(s) === id);
+        if (match)
+            return [match];
+    }
+    if (!opts.squash)
+        return null;
+    return squashSources(target, [...glossed]);
+}
+// Changed lines as a multiset of "file, +/- text".
+function changedLines(hunks) {
+    const out = new Map();
+    for (const h of hunks)
+        for (const l of bodyLines(h)) {
+            if (l.idx === null)
+                continue;
+            const key = `${h.file}\0${l.raw}`;
+            out.set(key, (out.get(key) ?? 0) + 1);
+        }
+    return out;
+}
+// How alike two diffs are: the changed lines they share, as a share of the
+// larger one. A squash's diff is (nearly) its branch's combined diff, so this
+// is near 1; an unrelated commit that happens to repeat a few of a branch's
+// lines scores low, however small it is.
+function similarity(a, b) {
+    const [x, y] = [changedLines(a), changedLines(b)];
+    let shared = 0, nx = 0, ny = 0;
+    for (const n of x.values())
+        nx += n;
+    for (const n of y.values())
+        ny += n;
+    for (const [k, n] of x)
+        shared += Math.min(n, y.get(k) ?? 0);
+    return Math.max(nx, ny) ? shared / Math.max(nx, ny) : 0;
+}
+// The unmerged branch the target is a squash of: the one whose combined
+// diff (from where it left the target's parent to its tip) is at least 80%
+// the same as the target's, best first.
+function squashSources(target, glossed) {
+    const parent = gitTry(['rev-parse', '-q', '--verify', `${target}^1`])?.trim();
+    if (!parent)
+        return null;
+    // Branch history the target doesn't contain, from glossed commits and
+    // branch heads; its tips are the candidate squashed branches.
+    const heads = (gitTry(['for-each-ref', '--format=%(objectname)', 'refs/heads/', 'refs/remotes/']) ?? '').split('\n').filter(Boolean);
+    const when = Number(git(['log', '-1', '--format=%ct', target]).trim());
+    const rows = git(['rev-list', '--parents', ...new Set([...glossed, ...heads]), '--not', target, '--'])
+        .split('\n').filter(Boolean).map((l) => l.split(' '));
+    const hasChild = new Set(rows.flatMap(([, ...parents]) => parents));
+    const tips = rows.map(([c]) => c).filter((c) => !hasChild.has(c))
+        .filter((c) => Number(git(['log', '-1', '--format=%ct', c]).trim()) <= when);
+    const glossedSet = new Set(glossed);
+    const mine = diffOf(target);
+    let best = null;
+    for (const tip of tips) {
+        const base = gitTry(['merge-base', tip, parent])?.trim();
+        const shas = git(['rev-list', '--reverse', '--no-merges', base ? `${base}..${tip}` : tip, '--']).split('\n').filter((s) => glossedSet.has(s));
+        if (!shas.length)
+            continue;
+        const score = similarity(mine, parseDiff(diffBetween(base || EMPTY_TREE, tip)));
+        if (score >= 0.8 && (!best || score > best.score))
+            best = { sources: shas, score };
+    }
+    return best?.sources ?? null;
+}
+// Unglossed commits on `starts` (a remote's branches, commits being pushed)
+// that may have been made from glossed ones by a squash or rebase merge, a
+// cherry-pick: each is glossed from its origins when they are found. Checks
+// are remembered in .git/gloss-checked with how many glossed commits there
+// were, so a commit is checked again only once more glosses have arrived (its
+// origins' glosses may come later, from a teammate). Returns what was carried.
+export function carryNew(starts, carry) {
+    if (!starts.length)
+        return [];
+    const glossed = glossedCommits();
+    if (!glossed.length)
+        return [];
+    const memo = git(['rev-parse', '--git-path', 'gloss-checked']).trim();
+    const checked = new Map((existsSync(memo) ? readFileSync(memo, 'utf8').split('\n').filter(Boolean) : [])
+        .map((l) => { const [sha, n] = l.split(' '); return [sha, Number(n) || 0]; }));
+    // A commit made from glossed ones is newer than the oldest of them.
+    const oldest = Math.min(...git(['log', '--no-walk=unsorted', '--stdin', '--format=%ct'], glossed.join('\n'))
+        .split('\n').filter(Boolean).map(Number));
+    const glossedSet = new Set(glossed);
+    const targets = git(['rev-list', '--no-merges', `--since=${oldest}`, ...starts, '--']).split('\n')
+        .filter((s) => s && !glossedSet.has(s) && (checked.get(s) ?? -1) < glossed.length);
+    const out = [];
+    for (const target of targets.reverse()) {
+        const origins = findOrigins(target, { squash: true, glossed });
+        if (origins) {
+            const res = carry(origins, target);
+            if (res.written) {
+                out.push(res.message);
+                glossed.push(target);
+                glossedSet.add(target);
+            }
+        }
+        appendFileSync(memo, `${target} ${glossed.length}\n`);
+    }
+    return out;
+}

package/dist/render.js

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

package/dist/schema.js

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

package/dist/selection.js

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

package/dist/validate.js

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

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@ok-ggwp/git-gloss",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Annotate agent-written diffs with intent and necessity, stored in git notes",
+  "license": "MIT",
+  "keywords": [
+    "git",
+    "notes",
+    "code-review",
+    "ai",
+    "agents",
+    "annotations"
+  ],
+  "homepage": "https://github.com/ok-ggwp/git-gloss#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ok-ggwp/git-gloss.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ok-ggwp/git-gloss/issues"
+  },
+  "type": "module",
+  "bin": {
+    "git-gloss": "bin/git-gloss.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.12"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepare": "npm run build",
+    "test": "node --test 'test/**/*.test.ts'",
+    "typecheck": "tsc"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2"
+  }
+}