@ok-ggwp/git-gloss 0.5.0 → 0.7.0

package/dist/batch.js

@@ -0,0 +1,184 @@
+import { closeSync, openSync, readSync } from 'node:fs';
+import { GlossError } from './git.js';
+import { addReviews, checkDecision, MAX_DECISION_LINE, readDecisions, resolveBy } from './reviews.js';
+import { findingTexts } from './findings.js';
+import { plain } from './plain.js';
+// Limits for `reviews --decide-file`, checked before anything is parsed or written.
+export const MAX_BATCH_ENTRIES = 500;
+export const MAX_BATCH_BYTES = 1024 * 1024;
+export const TEMPLATE_TEXT = 80;
+// What one --decide-file may write to a commit (bytes of its record lines): the 1 MiB input
+// cap alone would still let a file add about 1 MiB to every commit of a range. Honest
+// decisions are a few hundred bytes each; this is a guard against bloat, not against unreadable data.
+export const MAX_BATCH_WRITE_BYTES = 512 * 1024;
+// Reads a file, or stdin for "-", never more than MAX_BATCH_BYTES: a read that
+// goes past it is refused without holding the rest (also for a pipe or /dev/zero).
+export function readBounded(src) {
+    const what = src === '-' ? 'stdin' : plain(src);
+    const fail = (e) => new GlossError(`--decide-file: can't read ${what}: ${e.code ?? 'error'}`);
+    const buf = Buffer.allocUnsafe(MAX_BATCH_BYTES + 1);
+    let fd = 0, total = 0;
+    try {
+        if (src !== '-')
+            fd = openSync(src, 'r');
+        // Until end of input; a full buffer means the input is over the limit.
+        while (total < buf.length) {
+            let n;
+            try {
+                n = readSync(fd, buf, total, buf.length - total, null);
+            }
+            catch (e) {
+                // A non-blocking pipe with nothing yet: wait a little (no busy spin) and ask again.
+                if (e.code !== 'EAGAIN')
+                    throw e;
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+                continue;
+            }
+            if (n === 0)
+                break;
+            total += n;
+        }
+    }
+    catch (e) {
+        throw fail(e);
+    }
+    finally {
+        if (fd !== 0)
+            closeSync(fd);
+    }
+    if (total > MAX_BATCH_BYTES)
+        throw new GlossError(`--decide-file: the input is over ${MAX_BATCH_BYTES / 1024 / 1024} MiB; split the decisions into several files`);
+    return buf.toString('utf8', 0, total);
+}
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// Accepts a bare array of {finding, outcome, note?}, or {review?, complete?: boolean,
+// decisions: [...]}. Unknown keys are ignored. Everything is checked here; nothing is written.
+export function parseBatch(text, reviewId) {
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch (e) {
+        throw new GlossError(`--decide-file: not valid JSON (${e instanceof RangeError ? 'nested too deeply' : plain(e.message).slice(0, 120)})`);
+    }
+    let list;
+    let complete = false;
+    if (Array.isArray(data))
+        list = data;
+    else if (isObject(data)) {
+        const d = data.decisions;
+        const c = data.complete;
+        if (c !== undefined && typeof c !== 'boolean')
+            throw new GlossError('--decide-file: "complete" must be true or false');
+        complete = c === true;
+        const r = data.review;
+        if (r !== undefined && r !== '' && r !== reviewId)
+            throw new GlossError(`--decide-file: the file is for review ${plain(String(r)).slice(0, 80)}, not ${plain(reviewId)}`);
+        if (!Array.isArray(d))
+            throw new GlossError('--decide-file: the object needs a "decisions" array');
+        list = d;
+    }
+    else
+        throw new GlossError('--decide-file: expected an array of {finding, outcome, note?}, or an object with a "decisions" array');
+    if (list.length > MAX_BATCH_ENTRIES)
+        throw new GlossError(`--decide-file: ${list.length} entries; at most ${MAX_BATCH_ENTRIES} per file`);
+    if (!list.length && !complete)
+        throw new GlossError('--decide-file: no decisions in the file');
+    // addReviews keeps a repeated line once, so a repeated finding would be counted but not written.
+    const firstAt = new Map();
+    const entries = list.map((e, i) => {
+        const at = `--decide-file: entry ${i + 1}`;
+        if (!isObject(e))
+            throw new GlossError(`${at} is not an object`);
+        const finding = e.finding, outcome = e.outcome, note = e.note;
+        if (typeof finding !== 'string')
+            throw new GlossError(`${at} has no "finding" text`);
+        const label = `${at} ("${plain(finding).slice(0, 40)}")`;
+        if (outcome === undefined || outcome === '')
+            throw new GlossError(`${label} has an empty outcome; fill it in or delete the row`);
+        if (typeof outcome !== 'string')
+            throw new GlossError(`${label}: "outcome" must be a string`);
+        if (note !== undefined && typeof note !== 'string')
+            throw new GlossError(`${label}: "note" must be a string`);
+        try {
+            checkDecision({ finding, outcome, note });
+        }
+        catch (err) {
+            if (err instanceof GlossError)
+                throw new GlossError(`${label}: ${err.message.replace(/^--/, '')}`);
+            throw err;
+        }
+        const seen = firstAt.get(finding.trim());
+        if (seen !== undefined)
+            throw new GlossError(`${label} repeats entry ${seen}`);
+        firstAt.set(finding.trim(), i + 1);
+        return { finding: finding.trim(), outcome: outcome, ...(note ? { note } : {}) };
+    });
+    return { entries, complete };
+}
+// A record that, as written, is a line readers would skip (escapes make control characters longer).
+export function checkLength(record, what) {
+    if (JSON.stringify(record).length > MAX_DECISION_LINE)
+        throw new GlossError(`${what} is too long to record: the finding and note, as written, exceed what readers accept; shorten them`);
+}
+// The skeleton `--decide-template` prints: one row per ref, outcome left empty.
+export function template(reviewId, findings) {
+    const rows = findingTexts(findings);
+    if (rows.length > MAX_BATCH_ENTRIES)
+        throw new GlossError(`review ${plain(reviewId)} has ${rows.length} findings; --decide-file takes at most ${MAX_BATCH_ENTRIES}`);
+    return {
+        review: reviewId, complete: false,
+        decisions: rows.map(([ref, text]) => ({ finding: `${ref}${ref.includes('.') ? '' : ':'} ${[...plain(text).replace(/\s+/g, ' ').trim()].slice(0, TEMPLATE_TEXT).join('')}`.trim(), outcome: '', note: '' })),
+    };
+}
+// Everything `reviews --decide-file` needs before it writes: the checked entries, the
+// holders of the review, and the records (with the complete marker last). Nothing is written.
+export function prepareBatch(src, id, byArg, holdersOf) {
+    const batch = parseBatch(readBounded(src), id);
+    const holders = holdersOf(id);
+    const by = resolveBy(byArg);
+    const at = new Date().toISOString();
+    const records = batch.entries.map((e, i) => {
+        const r = { decision: 1, review: id, at, by, finding: e.finding, outcome: e.outcome, ...(e.note ? { note: e.note } : {}) };
+        checkLength(r, `--decide-file: entry ${i + 1}`);
+        return r;
+    });
+    if (batch.complete)
+        records.push({ decision: 1, review: id, at, by, complete: true });
+    const bytes = records.reduce((n, r) => n + Buffer.byteLength(JSON.stringify(r)) + 1, 0);
+    if (bytes > MAX_BATCH_WRITE_BYTES) {
+        throw new GlossError(`--decide-file: the ${records.length} records come to ${Math.ceil(bytes / 1024)} KiB as written; at most ${MAX_BATCH_WRITE_BYTES / 1024} KiB per file; shorten the findings and notes or split the file`);
+    }
+    return { batch, holders, records };
+}
+// The same decision, whenever it was made: what a re-run must not record twice.
+const sameDecision = (r) => JSON.stringify([r.review, r.finding ?? null, r.outcome ?? null, r.note ?? null, r.by, r.complete ?? null]);
+// The records not yet on that commit: one equal to the LATEST decision for its finding
+// there is left out, but not one equal to an earlier decision that a later one reversed.
+// A re-run of a file after a partly failed write adds only what is missing (each run has
+// its own `at`).
+export function newRecords(sha, records) {
+    const latest = new Map();
+    for (const r of [...readDecisions(sha)].sort((a, b) => a.at.localeCompare(b.at)))
+        latest.set(JSON.stringify([r.review, r.finding ?? null]), sameDecision(r));
+    return records.filter((r) => latest.get(JSON.stringify([r.review, r.finding ?? null])) !== sameDecision(r));
+}
+// Write the records to each holder, one write per commit, leaving out what it has. Counts
+// as it goes: decisions written (the most any one commit got, so a range counts a file once),
+// whether the complete marker was written, commits written, records skipped.
+export function applyBatch(holders, records) {
+    let decisions = 0, written = 0, skipped = 0, marked = false;
+    for (const sha of holders) {
+        const todo = newRecords(sha, records);
+        skipped += records.length - todo.length;
+        if (!todo.length)
+            continue;
+        addReviews(sha, todo);
+        written++;
+        const fresh = todo.filter((r) => !r.complete).length;
+        decisions = Math.max(decisions, fresh);
+        if (todo.some((r) => r.complete))
+            marked = true;
+    }
+    return { decisions, marked, written, skipped };
+}

package/dist/cli.js

@@ -7,6 +7,7 @@ import * as html from './commands/html.js';
 import * as hunks from './commands/hunks.js';
 import * as init from './commands/init.js';
 import * as review from './commands/review.js';
+import * as lint from './commands/lint.js';
 import * as reviews from './commands/reviews.js';
 import * as schema from './commands/schema.js';
 import * as show from './commands/show.js';
@@ -15,7 +16,7 @@ import * as sync from './commands/sync.js';
 import * as versions from './commands/versions.js';
 import * as why from './commands/why.js';
 const COMMANDS = {
-    init, hunks, signals, add, adopt, carry, show, html, ary, why, review, reviews, sync, versions, schema,
+    init, hunks, signals, lint, add, adopt, carry, show, html, ary, why, review, reviews, sync, versions, schema,
 };
 function help() {
     return 'usage: git gloss <command> [options]\n\n' +

package/dist/commands/add.js

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync, readSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 import { z } from 'zod';
 import { commitDiff, isWipSnapshot, NOTES_REF, readNote, resolveCommit, WIP_NOTES_REF, writeNote } from '../git.js';
@@ -7,6 +7,32 @@ import { Annotation, noteFormat } from '../schema.js';
 import { validate } from '../validate.js';
 import { loadConfig } from '../config.js';
 import { analyzeGroups, groupInputsFor, ratingProblems } from '../floor.js';
+// readFileSync(0) throws EAGAIN when the pipe is non-blocking and momentarily empty
+// (a big gloss from a slower writer): wait a moment and read on.
+function readStdin() {
+    const chunks = [];
+    const buf = Buffer.alloc(1 << 20);
+    for (;;) {
+        let n;
+        try {
+            n = readSync(0, buf);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'EAGAIN') {
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+                continue;
+            }
+            if (code === 'EOF')
+                break;
+            throw err;
+        }
+        if (n === 0)
+            break;
+        chunks.push(Buffer.from(buf.subarray(0, n)));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
 export const usage = 'add [<commit>] [-f <file>] [--force] [--partial] [--allow-underrate] [--dry-run]   attach an annotation (JSON from file or stdin)';
 export function run(argv) {
     const { values, positionals } = parseArgs({
@@ -25,7 +51,7 @@ export function run(argv) {
         console.error('error: pipe annotation JSON on stdin or pass -f <file> (see `git gloss schema`)');
         return 2;
     }
-    const raw = readFileSync(values.file ?? 0, 'utf8');
+    const raw = values.file ? readFileSync(values.file, 'utf8') : readStdin();
     let json;
     try {
         json = JSON.parse(raw);

package/dist/commands/ary.js

@@ -31,5 +31,8 @@ export function run(argv) {
         if (!values['no-open'])
             openInBrowser(url);
     });
+    // The default action of a signal would skip the cleanup that kills running page builds.
+    for (const [sig, code] of [['SIGINT', 130], ['SIGTERM', 143], ['SIGHUP', 129], ['SIGQUIT', 131]])
+        process.on(sig, () => { server.close(); process.exit(code); });
     return 0;
 }

package/dist/commands/carry.js

@@ -1,6 +1,6 @@
 import { parseArgs } from 'node:util';
 import { existsSync, readFileSync } from 'node:fs';
-import { commitDiff, git, GlossError, readNote, resolveCommit, resolveCommits, writeNote } from '../git.js';
+import { commitDiff, git, GlossError, readNote, rethrowTimeout, resolveCommit, resolveCommits, writeNote } from '../git.js';
 import { matchHunks } from '../loader.js';
 import { findOrigins } from '../origins.js';
 import { location, parseDiff } from '../diff.js';
@@ -20,6 +20,7 @@ export function targetState(sha) {
         return note ? (note.sources || note.carried_from ? 'carried' : 'glossed') : 'none';
     }
     catch (err) {
+        rethrowTimeout(err);
         if (err instanceof GlossError)
             return 'broken';
         throw err;
@@ -41,6 +42,7 @@ export function carry(sourceShas, target) {
             note = readNote(sha);
         }
         catch (err) {
+            rethrowTimeout(err);
             if (!(err instanceof GlossError))
                 throw err;
             unreadable.push(`${sha.slice(0, 7)} (${err.message.replace(/^the gloss on \S+ /, '')})`);

package/dist/commands/lint.js

@@ -0,0 +1,99 @@
+import { parseArgs } from 'node:util';
+import { GlossError, resolveCommits } from '../git.js';
+import { loadGloss } from '../loader.js';
+import { CONFIG_EDIT_NOTE } from '../signals.js';
+import { ratingIssues, tryAnalyze, whyText } from '../floor.js';
+import { attentionRank, impactRank } from '../attention.js';
+import { servesOf } from '../schema.js';
+import { unknownServes } from '../validate.js';
+import { plain } from '../plain.js';
+export const usage = 'lint [<commit> | wip] [--json]   advisory checks of a gloss that a reviewer would make by eye (always exits 0 for findings)';
+// What removal_impact says when it admits the group is not needed. Matched on the
+// lowercased text, after plain(): BARE phrases only when they are the whole text
+// ("Nothing." but not "Nothing else would work"); the others may start it.
+const NOTHING_BREAKS_WHOLE = ['nothing', 'none', 'n/a'];
+const NOTHING_BREAKS_START = ['nothing breaks', 'nothing would break', 'nothing is lost', 'nothing happens', 'no effect', 'no impact'];
+export function saysNothingBreaks(text) {
+    const t = plain(text).toLowerCase().trim().replace(/[\s.!;:,]+$/, '');
+    if (NOTHING_BREAKS_WHOLE.includes(t))
+        return true;
+    return NOTHING_BREAKS_START.some((p) => t === p || (t.startsWith(p) && /^[\s.,;:!-]/.test(t.slice(p.length))));
+}
+export function run(argv) {
+    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { json: { type: 'boolean' } } });
+    const arg = positionals[0] ?? 'HEAD';
+    const { shas, range } = resolveCommits(arg);
+    if (range)
+        throw new GlossError(`${arg}: lint takes one commit or wip, not a range`);
+    const sha = shas[0];
+    const gloss = loadGloss(sha);
+    if (!gloss)
+        throw new GlossError(`${sha.slice(0, 10)} has no gloss (annotate it with \`git gloss add\`)`);
+    for (const w of gloss.warnings)
+        console.error(`warning: ${plain(w)}`);
+    const a = gloss.note.annotation;
+    const findings = [];
+    // Text from a note is sanitized here, once, for both outputs.
+    const add = (code, message, at = {}) => findings.push({ code, ...(at.group !== undefined && { group: plain(at.group) }), ...(at.hunk !== undefined && { hunk: plain(at.hunk) }), message: plain(message) });
+    const ids = new Set(a.groups.map((g) => g.id));
+    const an = tryAnalyze(gloss);
+    if (an) {
+        const issues = ratingIssues(a, an);
+        if (issues.configEdit)
+            add('config-edit', CONFIG_EDIT_NOTE);
+        for (const u of issues.unrated)
+            add('no-impact', `no impact rated${u.signal ? ` (floor ${u.floor}: ${whyText(u.why)})` : ''}`, { group: u.id });
+        for (const b of issues.belowFloor)
+            add('impact-below-floor', `impact "${b.impact}" is below its floor "${b.floor}" (${whyText(b.why)})`, { group: b.id });
+        if (issues.attention)
+            add('attention-below-floor', `attention "${issues.attention.level}" is below the computed floor "${issues.attention.floor}" (${issues.attention.why}) and has no override_reason`);
+        const sigOf = new Map(an.signals.hunks.map((s) => [s.id, s]));
+        for (const g of gloss.groups) {
+            const f = an.groups.get(g.group.id);
+            // A mechanical group made only of lockfiles, docs, tests or generated files sits on a path-class floor honestly (the skill's lockfile example).
+            const real = g.hunks.some((h) => h.current && !sigOf.get(h.current.id)?.inert);
+            if (g.group.necessity === 'mechanical' && f && impactRank(f.floor) > impactRank('module') && real) {
+                add('mechanical-on-floor', `graded mechanical but its floor is "${f.floor}" (${whyText(f.why)})`, { group: g.group.id });
+            }
+            if (f?.testsOnly && !servesOf(g.group).some((t) => t !== 'task' && ids.has(t) && t !== g.group.id)) {
+                add('test-serves-nothing', 'a test group that serves no existing group (set serves to the groups it verifies)', { group: g.group.id });
+            }
+        }
+    }
+    for (const g of a.groups) {
+        const bad = unknownServes(g, ids);
+        if (bad.length)
+            add('unknown-serves', `serves names no such group: ${bad.map((t) => `"${t}"`).join(', ')}`, { group: g.id });
+        if (g.necessity === 'required' && saysNothingBreaks(g.removal_impact)) {
+            add('required-but-nothing-breaks', `graded required but removal_impact says: "${g.removal_impact}"`, { group: g.id });
+        }
+    }
+    const level = a.attention?.level ?? an?.derived.level;
+    if (level && attentionRank(level) >= attentionRank('careful') && !a.risks?.length) {
+        add('missing-risks', `attention is ${level} but no risks are listed`);
+    }
+    for (const u of gloss.unannotated) {
+        add('uncovered-hunks', `${u.hunk.file}: ${u.lines ? `changed lines ${[...u.lines].join(',')}` : 'the whole hunk'} not covered by any group`, { hunk: u.hunk.id });
+    }
+    if (values.json) {
+        console.log(JSON.stringify({ target: sha.slice(0, 10), findings, ...(an ? {} : { incomplete: true }) }, null, 2));
+        return 0;
+    }
+    const subjects = new Map();
+    for (const f of findings) {
+        const key = f.group !== undefined ? `group ${f.group}` : f.hunk !== undefined ? `hunk ${f.hunk}` : 'whole gloss';
+        subjects.set(key, [...(subjects.get(key) ?? []), f]);
+    }
+    for (const [key, fs] of subjects) {
+        console.log(key);
+        for (const f of fs)
+            console.log(`  ${f.code.padEnd(28)} ${f.message}`);
+    }
+    if (findings.length)
+        console.log(`${findings.length} finding${findings.length === 1 ? '' : 's'}`);
+    if (!an)
+        console.log('incomplete: the rating checks need the diff signals, which are unavailable (see the warning above)');
+    else if (!findings.length)
+        console.log('clean');
+    return 0;
+}

package/dist/commands/review.js

@@ -3,7 +3,7 @@ import { plain } from '../plain.js';
 import { commitDiff, commitSubject, isWipSnapshot, resolveCommits } from '../git.js';
 import { parseDiff } from '../diff.js';
 import { refLabel, sliceText } from '../selection.js';
-import { loadGloss } from '../loader.js';
+import { loadGloss, loadGlossInRange, refusedWarning } from '../loader.js';
 import { NECESSITY_HELP, servesOf } from '../schema.js';
 export const usage = 'review [<commit> | <range>] [--material]   print a review prompt for a commit or a branch (pipe it to an agent, e.g. `| claude -p`); --material prints only the gloss and code, for other review prompts';
 // A fence longer than any backtick run in the content, so a markdown file in
@@ -20,11 +20,12 @@ const hunkLine = (h) => `- ${h.id} ${plain(h.oldFile && h.oldFile !== h.file ? `
     `(-${h.oldStart},${h.oldLines} +${h.newStart},${h.newLines}, +${h.added} -${h.removed})`;
 // The material for one commit: its gloss and the code under each group, or,
 // for an unglossed commit in a range, its whole diff.
-function commitMaterial(sha, gloss) {
+function commitMaterial(sha, gloss, refused) {
     if (!gloss) {
         return [
             `## Commit ${sha.slice(0, 10)}: ${plain(commitSubject(sha))}`,
-            'This commit has no gloss. Review its changes as unexplained.',
+            refused ? "This commit's gloss was refused (reason below), so it is not shown. Review its changes as unexplained." : 'This commit has no gloss. Review its changes as unexplained.',
+            ...(refused ? [`Reason: ${q(plain(refused).slice(0, 300))}`] : []),
             fenced('diff', parseDiff(commitDiff(sha)).map((h) => `# ${plain(h.file)}\n${h.text}`).join('\n')),
         ];
     }
@@ -69,7 +70,11 @@ function commitMaterial(sha, gloss) {
 export function run(argv) {
     const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { material: { type: 'boolean' } } });
     const { shas, merges, range } = resolveCommits(positionals[0] ?? 'HEAD');
-    const glosses = shas.map((sha) => loadGloss(sha));
+    // In a range a refused gloss is skipped with a warning; a single commit fails with the error.
+    const loaded = shas.map((sha) => (range ? loadGlossInRange(sha) : { gloss: loadGloss(sha), refused: undefined }));
+    loaded.forEach((l, i) => { if (l.refused)
+        console.error(refusedWarning(shas[i], l.refused)); });
+    const glosses = loaded.map((l) => l.gloss);
     if (!range && !glosses[0]) {
         console.error(`${shas[0].slice(0, 10)} has no gloss to review`);
         return 1;
@@ -82,7 +87,7 @@ export function run(argv) {
                 ? `\n\nMerge commits in the range are not included below. A merge can still carry conflict resolutions or edits of its own; check them with \`git show <sha>\`:\n\n${list(merges)}`
                 : ''));
     }
-    shas.forEach((sha, i) => material.push(...commitMaterial(sha, glosses[i])));
+    shas.forEach((sha, i) => material.push(...commitMaterial(sha, glosses[i], loaded[i].refused)));
     // Just the material, for a reviewer that brings its own instructions. Its
     // author text is quoted but not framed as untrusted; the caller must say so.
     if (values.material) {

package/dist/commands/reviews.js

@@ -2,19 +2,34 @@ import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 import { commitSubject, gitTry, GlossError, resolveCommits } from '../git.js';
-import { addReviews, checkBy, checkDecision, MAX_DECISION_LINE, MAX_FINDINGS, MAX_REVIEW_LINE, decisionSummary, readDecisions, readReviews, reviewStatus, stamp, statusPhrase, verdictOf } from '../reviews.js';
+import { addReviews, checkDecision, resolveBy, isValidDecision, MAX_FINDINGS, MAX_REVIEW_LINE, decisionSummary, readDecisions, readReviews, reviewStatus, stamp, statusPhrase, verdictOf } from '../reviews.js';
+import { findingClashes, findingRefs, labelFindings, orderDecisions, refOf } from '../findings.js';
 import { plain } from '../plain.js';
 import { page, style } from '../render.js';
-export const usage = 'reviews [<commit> | <range> | wip] [--stamp | --record]   the reviews recorded for commits, with their findings and what was decided about them\n  reviews <target> --decide <review-id> --finding <text> --outcome <fixed|follow-up|rejected|accepted> [--note <text>] [--by <name>]\n  reviews <target> --decide <review-id> --complete   the arbiter is done; --stamp, --record and --decide are for tools';
+import { applyBatch, checkLength, prepareBatch, template } from '../batch.js';
+export const usage = 'reviews [<commit> | <range> | wip] [--stamp | --record]   the reviews recorded for commits, with their findings and what was decided about them\n  reviews <target> --decide <review-id> --finding <text> --outcome <fixed|follow-up|rejected|accepted> [--note <text>] [--by <name>]\n  reviews <target> --decide <review-id> --complete   the arbiter is done\n  reviews <target> --decide-template <review-id>   print a JSON skeleton of the findings of a review to fill in\n  reviews <target> --decide <review-id> --decide-file <file|->   record every decision of the filled-in skeleton at once, or none; --stamp, --record and --decide are for tools';
 export function run(argv) {
     const { values, positionals } = parseArgs({
         args: argv,
         allowPositionals: true,
         options: {
             stamp: { type: 'boolean' }, record: { type: 'boolean' }, decide: { type: 'string' }, finding: { type: 'string' },
-            outcome: { type: 'string' }, note: { type: 'string' }, complete: { type: 'boolean' }, by: { type: 'string' },
+            outcome: { type: 'string' }, 'decide-file': { type: 'string' }, 'decide-template': { type: 'string' }, note: { type: 'string' }, complete: { type: 'boolean' }, by: { type: 'string' },
         },
     });
+    const batchFlag = values['decide-file'] !== undefined ? '--decide-file' : values['decide-template'] !== undefined ? '--decide-template' : null;
+    if (batchFlag) {
+        for (const k of ['finding', 'outcome', 'note', 'complete', 'stamp', 'record']) {
+            if (values[k] !== undefined)
+                throw new GlossError(`${batchFlag} cannot be combined with --${k}`);
+        }
+        if (values['decide-file'] !== undefined && values['decide-template'] !== undefined)
+            throw new GlossError('--decide-file and --decide-template cannot be combined');
+        if (batchFlag === '--decide-template' && (values.decide !== undefined || values.by !== undefined))
+            throw new GlossError('--decide-template takes the review id itself and no --decide or --by');
+        if (batchFlag === '--decide-file' && values.decide === undefined)
+            throw new GlossError('--decide-file goes with --decide <review-id>');
+    }
     if (values.record) {
         const input = JSON.parse(readFileSync(0, 'utf8'));
         for (const k of ['stage', 'agent', 'target', 'findings']) {
@@ -53,23 +68,55 @@ export function run(argv) {
         return 0;
     }
     const { shas } = resolveCommits(positionals[0] ?? 'HEAD');
+    const target = positionals[0] ?? 'HEAD';
+    // Every commit of the target holding that review gets the decision.
+    const holdersOf = (id) => {
+        const holders = shas.filter((sha) => readReviews(sha).some((r) => r.id === id));
+        if (!holders.length) {
+            const known = [...new Set(shas.flatMap(readReviews).map((r) => r.id))];
+            throw new GlossError(`no review ${id} on ${target}` + (known.length ? ` (reviews there: ${plain(known.join(', '))})` : ' (it has no reviews)'));
+        }
+        return holders;
+    };
+    const reportOf = (id, holders) => holders.flatMap(readReviews).find((r) => r.id === id);
+    // A finding that starts with a ref names a finding of the report: say so when there is none (never refuse).
+    // The refs of a report are computed once, not once per entry.
+    const refsOfReport = new Map();
+    const warnUnknownRef = (id, report, finding, hint = '') => {
+        const ref = refOf(finding);
+        if (ref !== null && report && !(refsOfReport.get(report.findings) ?? refsOfReport.set(report.findings, findingRefs(report.findings)).get(report.findings)).has(ref))
+            console.error(`git-gloss: review ${plain(id)} has no finding ${ref} (${hint}see the refs in \`git gloss reviews ${target}\`); recording it anyway`);
+    };
+    if (values['decide-template'] !== undefined) {
+        const id = values['decide-template'];
+        const report = reportOf(id, holdersOf(id));
+        const clash = findingClashes(report.findings);
+        if (clash.length)
+            console.error(`git-gloss: review ${plain(id)}: these refs are ambiguous, so the template cannot list every finding under its own: ${clash.join(', ')}; the findings are in \`git gloss reviews ${target}\``);
+        console.log(JSON.stringify(template(id, report.findings), null, 2));
+        return 0;
+    }
+    if (values['decide-file'] !== undefined) {
+        const id = values.decide;
+        // Everything is checked before the first write: one bad entry records nothing.
+        const { batch, holders, records } = prepareBatch(values['decide-file'], id, values.by, holdersOf);
+        const report = reportOf(id, holders);
+        batch.entries.forEach((e, i) => warnUnknownRef(id, report, e.finding, `entry ${i + 1}; `));
+        const { decisions: n, marked, written, skipped } = applyBatch(holders, records);
+        console.log(`recorded ${n} decision${n === 1 ? '' : 's'} on ${written} commit${written === 1 ? '' : 's'}${marked ? ' and marked the review complete' : ''}${skipped ? ` (${skipped} already recorded)` : ''}`);
+        return 0;
+    }
     if (values.decide !== undefined) {
         const id = values.decide;
         if (values.complete) {
-            if (values.finding !== undefined || values.outcome !== undefined || values.note !== undefined) {
+            if (!isValidDecision({ complete: true, finding: values.finding, outcome: values.outcome, note: values.note })) {
                 throw new GlossError('--complete marks the review as arbitrated; it takes no --finding, --outcome or --note');
             }
         }
         else
             checkDecision(values);
-        // Every commit of the target holding that review gets the decision.
-        const holders = shas.filter((sha) => readReviews(sha).some((r) => r.id === id));
-        if (!holders.length) {
-            const known = [...new Set(shas.flatMap(readReviews).map((r) => r.id))];
-            throw new GlossError(`no review ${id} on ${positionals[0] ?? 'HEAD'}` + (known.length ? ` (reviews there: ${plain(known.join(', '))})` : ' (it has no reviews)'));
-        }
-        const by = values.by !== undefined ? values.by.trim() : gitTry(['config', 'user.name'])?.trim() || 'unknown';
-        checkBy(by);
+        const holders = holdersOf(id);
+        const by = resolveBy(values.by);
         const record = {
             decision: 1, review: id, at: new Date().toISOString(), by,
             ...(values.complete ? { complete: true } : {
@@ -78,8 +125,9 @@ export function run(argv) {
             }),
         };
         // Control characters are written as 6-byte escapes, so check the line itself against the reader's cap.
-        if (JSON.stringify(record).length > MAX_DECISION_LINE)
-            throw new GlossError('that decision is too long to record: the finding and note, as written, exceed what readers accept; shorten them');
+        checkLength(record, 'that decision');
+        if (record.finding !== undefined)
+            warnUnknownRef(id, reportOf(id, holders), record.finding);
         for (const sha of holders)
             addReviews(sha, [record]);
         console.log(`recorded ${values.complete ? 'the review as complete' : `"${record.finding}": ${record.outcome}`} on ${holders.length} commit${holders.length === 1 ? '' : 's'}`);
@@ -106,11 +154,11 @@ export function run(argv) {
             out.push(`  ${statusPhrase(s)}`);
             for (const r of s.reviews) {
                 out.push('', style('dim', `  ── ${r.stage} by ${r.agent}${r.model ? `:${r.model}` : ''}${r.mode ? ` (${r.mode})` : ''}, ${r.at.slice(0, 16).replace('T', ' ')}, of ${r.target}, id ${plain(r.id)}`));
-                out.push(...r.findings.trim().split('\n').map((l) => `  ${l}`));
+                out.push(...labelFindings(r.findings).trim().split('\n').map((l) => `  ${l}`));
                 const ds = decisions.filter((d) => d.review === r.id);
                 if (r.verdict !== 'clean' || ds.length) {
                     out.push('', `  decisions on this review: ${decisionSummary(ds)}`);
-                    for (const d of ds.filter((d) => d.outcome).sort((a, b) => a.at.localeCompare(b.at))) {
+                    for (const d of orderDecisions(ds.filter((d) => d.outcome))) {
                         out.push(`    ${d.outcome}: ${plain(d.finding)}${d.note ? ` — ${plain(d.note)}` : ''} ${style('dim', `(${plain(d.by)}, ${plain(d.at).slice(0, 10)})`)}`);
                     }
                 }

package/dist/commands/show.js

@@ -1,7 +1,7 @@
 import { parseArgs } from 'node:util';
-import { commitSubject, gitTry, readNote, resolveCommits } from '../git.js';
+import { commitSubject, gitTry, readNote, resolveCommits, rethrowTimeout } from '../git.js';
 import { refLabel, sliceStats, sliceText } from '../selection.js';
-import { loadGloss } from '../loader.js';
+import { loadGloss, loadGlossInRange, refusedWarning } from '../loader.js';
 import { impactRank } from '../attention.js';
 import { showsImpact, tryAnalyze } from '../floor.js';
 import { IMPACT, NECESSITY, isImpact, isNecessity } from '../schema.js';
@@ -61,7 +61,8 @@ export function run(argv) {
                     const groups = readNote(c)?.annotation.groups.map((g) => g.id) ?? [];
                     return missing.every((id) => groups.includes(id));
                 }
-                catch {
+                catch (err) {
+                    rethrowTimeout(err);
                     return false;
                 }
             });
@@ -84,7 +85,11 @@ export function run(argv) {
         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 loaded = shas.map((sha) => loadGlossInRange(sha));
+    const glosses = loaded.map((l) => l.gloss);
+    const refused = loaded.filter((l) => l.refused).length;
+    loaded.forEach((l, i) => { if (l.refused)
+        console.error(refusedWarning(shas[i], l.refused)); });
     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
@@ -97,13 +102,14 @@ export function run(argv) {
             (glossed ? style(vetted === glossed ? 'green' : 'yellow', `, ${vetted} honesty-reviewed`) : '') +
             (flagged ? style('yellow', ` (${flagged} with issues)`) : '') +
             (stale ? style('red', ` (${stale} stale)`) : '') +
+            (refused ? style('red', ` (${refused} refused)`) : '') +
             (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', plain(commitSubject(sha)))}`, style('dim', 'no gloss for this commit'));
+            out.push(`${style('yellow', sha.slice(0, 10))} ${style('bold', plain(commitSubject(sha)))}`, style('dim', loaded[i].refused ? 'gloss refused (see the warning)' : 'no gloss for this commit'));
             return;
         }
         // An --only filter can leave a commit with nothing to show; say so and move on.