@ok-ggwp/git-gloss 0.3.0 → 0.5.0

package/dist/loader.js

@@ -1,6 +1,6 @@
-import { commitDiff, commitSubject, readNote } from './git.js';
+import { commitDiff, commitSubject, GlossError, readNote } from './git.js';
 import { parseDiff } from './diff.js';
-import { changedCount, selections, uncovered } from './selection.js';
+import { changedCount, claimsProblem, selections, uncovered } from './selection.js';
 const locationKey = (h) => [h.file, h.oldFile ?? '', h.oldStart, h.oldLines, h.newStart, h.newLines].join('\0');
 // Pair each stored hunk with a current one: first by the hash of its changes
 // (it may have moved in a rebase), then by location (same place, different
@@ -49,6 +49,10 @@ export function loadGloss(sha) {
         })),
     }));
     const claims = groups.flatMap((g) => g.hunks.flatMap((h) => (h.current ? [{ hunk: h.current, lines: h.lines }] : [])));
+    // Readers refuse what `add` refuses (see claimsProblem).
+    const tooMany = claimsProblem(claims, current);
+    if (tooMany)
+        throw new GlossError(`the gloss on ${sha.slice(0, 10)} is refused: ${tooMany}`);
     const unannotated = uncovered(current, claims);
     const bad = [...resolved.values()].filter((h) => h.status !== 'ok').length;
     const matched = new Set([...resolved.values()].map((h) => h.current));
@@ -58,5 +62,5 @@ export function loadGloss(sha) {
         warnings.push(`this gloss no longer matches the commit (${bad} glossed hunk(s) changed or gone, ${unknown} new); ` +
             'the commit was probably amended or rebased after glossing. Re-gloss it with `git gloss add --force`.');
     }
-    return { sha, subject: commitSubject(sha), note, groups, unannotated, stale: warnings.length > 0, warnings };
+    return { sha, subject: commitSubject(sha), note, hunks: current, groups, unannotated, stale: warnings.length > 0, warnings };
 }

package/dist/merge.js

@@ -1,4 +1,5 @@
 import { matchHunks } from './loader.js';
+import { combineAttention } from './attention.js';
 import { servesOf } from './schema.js';
 import { bodyLines, changedCount, formatRanges, selections, uncovered } from './selection.js';
 import { alsoServed } from './validate.js';
@@ -177,6 +178,9 @@ export function mergeGlosses(sources, target) {
     const summaries = unique(notes.flatMap((a) => (a.summary ? [a.summary] : [])));
     const alternatives = unique(notes.flatMap((a) => a.alternatives ?? []));
     const risks = unique(notes.flatMap((a) => a.risks ?? []));
+    const rated = used.filter((i) => sources[i].note.annotation.attention);
+    // One unrated source makes the whole gloss unrated: its changes have no level to take.
+    const attention = rated.length < used.length ? undefined : combineAttention(rated.map((i) => sources[i].note.annotation.attention), (part, id) => newId.get(`${rated[part]}\0${id}`), groups);
     const annotation = {
         version: 1,
         task: tasks.join('; '),
@@ -184,6 +188,7 @@ export function mergeGlosses(sources, target) {
         groups,
         ...(alternatives.length ? { alternatives } : {}),
         ...(risks.length ? { risks } : {}),
+        ...(attention ? { attention } : {}),
         ...(notes[0].author ? { author: notes[0].author } : {}),
     };
     const claims = kept.flatMap(({ byHunk }) => [...byHunk].map(([hunk, lines]) => ({ hunk, lines })));

package/dist/plain.js

@@ -0,0 +1,9 @@
+// Text from a note is shown in a terminal: no escape sequences or other
+// control characters get through. Newlines and tabs stay when `multiline`.
+export function plain(text, multiline = false) {
+    return text
+        // OSC (ended by BEL or ESC \) and CSI sequences, then any lone ESC and control characters (newline and tab kept when multiline).
+        .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?/g, '')
+        .replace(/\x1b\[[0-?]*[ -/]*[@-~]?/g, '')
+        .replace(/[\x00-\x1f\x7f-\x9f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g, (c) => (multiline && (c === '\n' || c === '\t') ? c : ' '));
+}

package/dist/render.js

@@ -1,8 +1,10 @@
+import { plain } from './plain.js';
 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';
+import { attentionRank } from './attention.js';
+import { IMPACT, servesOf } from './schema.js';
 export const style = (s, text) => styleText(s, text);
 const NECESSITY_STYLE = {
     required: 'green',
@@ -18,12 +20,57 @@ export function necessityTag(n) {
 export function necessityWord(n, pad = 0) {
     return style(NECESSITY_STYLE[n], n.padEnd(pad));
 }
+const IMPACT_STYLE = {
+    local: 'gray',
+    module: 'white',
+    shared: 'yellow',
+    contract: 'magenta',
+    sensitive: 'red',
+};
+// "[contract]", padded to `pad` columns.
+export function impactTag(i, pad = 0) {
+    return style(['bold', IMPACT_STYLE[i]], `[${i}]`) + ' '.repeat(Math.max(0, pad - i.length - 2));
+}
+// "(contract)": an impact derived from the diff rather than declared.
+export function derivedImpactTag(i, pad = 0) {
+    return style('dim', `(${i})`) + ' '.repeat(Math.max(0, pad - i.length - 2));
+}
+// Width of the widest impact tag, "[sensitive]".
+export const IMPACT_W = Math.max(...IMPACT.map((i) => i.length)) + 2;
+export const ATTENTION_STYLE = {
+    skim: 'gray',
+    look: 'cyan',
+    careful: 'yellow',
+    'must-read': 'red',
+};
+// Declared below the computed floor.
+export const belowFloor = (a, view) => !!a && !!view && attentionRank(a.level) < attentionRank(view.floor);
+// "attention: CAREFUL (declared) · floor: careful · focus: a, b" with the
+// reasons beneath. Without a declared level but with signals: "LOOK (derived)"
+// and why. "unrated" where nothing is declared and no signals could be computed.
+export function attentionBlock(a, view) {
+    const level = (l) => style(['bold', ATTENTION_STYLE[l]], l.toUpperCase());
+    if (!a) {
+        if (!view)
+            return [style('dim', 'attention: unrated')];
+        const d = view.derived;
+        return [`attention: ${level(d.level)} ${style('dim', '(derived)')}` + (d.level === view.floor ? '' : ` · floor: ${view.floor}`),
+            ...d.reasons.flatMap((r) => field('•', r)), ...timedOutLines(view)];
+    }
+    const head = `attention: ${level(a.level)}${view ? ' ' + style('dim', '(declared)') + ` · floor: ${view.floor}` : ''}` +
+        (a.focus?.length ? ` · focus: ${a.focus.join(', ')}` : '');
+    const below = belowFloor(a, view);
+    return [head, ...(a.reasons ?? []).flatMap((r) => field('•', r)),
+        ...(below ? field('⚠', `declared ${a.level}, below the computed floor ${view.floor}` + (a.override_reason ? '' : ' (no override_reason)'), 2).map((l) => style('yellow', l)) : []),
+        ...(a.override_reason ? field('override:', a.override_reason) : []), ...timedOutLines(view)];
+}
+const timedOutLines = (view) => (view?.timedOut ?? []).flatMap((r) => field('⚠', r, 2).map((l) => style('yellow', l)));
 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)) {
+    for (const word of plain(text).split(/\s+/).filter(Boolean)) {
         if (line && line.length + 1 + word.length > width) {
             lines.push(line);
             line = word;
@@ -45,7 +92,7 @@ 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 file = plain(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}`)}`;
 }
@@ -63,13 +110,16 @@ export function colorDiff(text, indent = '') {
         .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));
+    const impact = g.impact ? ` [${g.impact}]` : '';
+    const prefix = `■ [${g.necessity}]${impact} `;
+    const out = wrap(g.intent, termWidth() - prefix.length).map((l, i) => (i === 0 ? `${style('bold', '■')} ${necessityTag(g.necessity)}${g.impact ? ' ' + impactTag(g.impact) : ''} ` : ' '.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.impact_reason)
+        out.push(...field('impact:', g.impact_reason));
     if (g.evidence)
         out.push(...field('evidence:', g.evidence));
     if (g.notes)

package/dist/reviews.js

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { commitDiff, git, gitTry, GlossError, readNote } from './git.js';
 import { parseDiff } from './diff.js';
 import { bodyLines } from './selection.js';
+import { plain } from './plain.js';
 // Reviews of commits (by git-gud, or anything else that records them), kept
 // beside the glosses so a reader can see whether a gloss was checked. One JSON
 // record per line: notes from different people and machines combine by taking
@@ -56,12 +57,29 @@ export function stamp(sha) {
     catch { /* an unreadable gloss: nothing to stamp */ }
     return { lines: lineKeys(parseDiff(commitDiff(sha))), groups };
 }
+// What a review record may hold, for readers and for `--record`. The line
+// carries a stamp of one 16-character key per changed line, so it can be large
+// for a large change (16,000 changed lines make about 300 KB) without being
+// junk: measured, JSON.parse reads 32 MB in under 0.1 s. So the line is only
+// bounded generously (8 MiB, about 440,000 changed lines), and the report text,
+// which is what gets rendered and printed, is bounded on its own.
+export const MAX_REVIEW_LINE = 8 * 1024 * 1024;
+export const MAX_FINDINGS = 256 * 1024;
+const warnedLong = new Set();
 export function readReviews(sha) {
     const raw = gitTry(['notes', '--ref', REVIEWS_REF, 'show', sha]);
     if (!raw)
         return [];
     // A rebase can join a note onto one with the same lines; each counts once.
-    return [...new Set(raw.split('\n'))].flatMap((line) => {
+    const kept = [];
+    let skipped = 0;
+    for (const l of new Set(raw.split('\n'))) {
+        if (l.length <= MAX_REVIEW_LINE)
+            kept.push(l);
+        else if (!isDecisionLine(l))
+            skipped++;
+    }
+    const records = kept.flatMap((line) => {
         try {
             const r = JSON.parse(line);
             // Records arrive from other machines; skip any that aren't whole.
@@ -69,6 +87,57 @@ export function readReviews(sha) {
                 ['id', 'at', 'stage', 'agent', 'target', 'findings'].every((k) => typeof r[k] === 'string') &&
                 ['model', 'mode'].every((k) => r[k] === undefined || typeof r[k] === 'string') &&
                 (r.verdict === undefined || r.verdict === 'clean' || r.verdict === 'issues');
+            // Everything shown later may reach a terminal: clean it once, here. The
+            // id stays as written, since decisions refer to it.
+            if (!ok)
+                return [];
+            if (r.findings.length > MAX_FINDINGS) {
+                skipped++;
+                return [];
+            }
+            const one = (v) => plain(v);
+            return [{
+                    ...r, at: one(r.at), stage: one(r.stage), agent: one(r.agent), target: one(r.target), findings: plain(r.findings, true),
+                    ...(r.model !== undefined ? { model: one(r.model) } : {}), ...(r.mode !== undefined ? { mode: one(r.mode) } : {}),
+                }];
+        }
+        catch {
+            return [];
+        }
+    });
+    // Said once per commit, though several readers ask for the same note.
+    if (skipped && !warnedLong.has(sha)) {
+        warnedLong.add(sha);
+        console.error(`warning: skipped ${skipped} review record${skipped === 1 ? '' : 's'} on ${sha.slice(0, 10)} with a report over ${MAX_FINDINGS / 1024} KiB or a line over ${MAX_REVIEW_LINE / 1024 / 1024} MiB`);
+    }
+    return records;
+}
+export const OUTCOMES = ['fixed', 'follow-up', 'rejected', 'accepted'];
+const MAX_TEXT = 2000;
+const MAX_BY = 200;
+// A decision line is a few hundred bytes; anything this long is junk, skipped
+// before it is parsed.
+export const MAX_DECISION_LINE = 16 * 1024;
+export const isDecisionLine = (line) => /^\s*\{\s*"decision"\s*:/.test(line.slice(0, 64));
+// Reads the decisions on a commit that answer a review recorded on it.
+export function readDecisions(sha) {
+    const raw = gitTry(['notes', '--ref', REVIEWS_REF, 'show', sha]);
+    if (!raw)
+        return [];
+    const lines = [...new Set(raw.split('\n'))].filter((l) => l.length <= MAX_DECISION_LINE && isDecisionLine(l));
+    if (!lines.length)
+        return [];
+    const ids = new Set(readReviews(sha).map((r) => r.id));
+    return lines.flatMap((line) => {
+        try {
+            const r = JSON.parse(line);
+            const str = (k) => typeof r[k] === 'string';
+            const ok = r?.decision === 1 && ids.has(r.review) && str('at') && str('by') &&
+                (r.complete === true
+                    ? r.finding === undefined && r.outcome === undefined
+                    : str('finding') && r.finding.length > 0 && r.finding.length <= MAX_TEXT &&
+                        OUTCOMES.includes(r.outcome) && (r.note === undefined || (str('note') && r.note.length <= MAX_TEXT))) &&
+                r.at.length <= 64 && r.by.length <= MAX_BY;
             return ok ? [r] : [];
         }
         catch {
@@ -76,7 +145,31 @@ export function readReviews(sha) {
         }
     });
 }
-// Adds records to a commit's reviews, keeping each line once. Several
+export const checkBy = (by) => {
+    if (!by)
+        throw new GlossError('--by needs a name (or set git config user.name)');
+    if (by.length > MAX_BY)
+        throw new GlossError(`--by is too long (${by.length} characters; at most ${MAX_BY})`);
+};
+export const checkDecision = (d) => {
+    if (!d.finding?.trim())
+        throw new GlossError('--decide needs --finding <text naming the finding>');
+    if (!OUTCOMES.includes(d.outcome))
+        throw new GlossError(`--outcome must be one of ${OUTCOMES.join(', ')}`);
+    for (const [k, v] of [['finding', d.finding], ['note', d.note]]) {
+        if (v && v.length > MAX_TEXT)
+            throw new GlossError(`--${k} is too long (${v.length} characters; at most ${MAX_TEXT})`);
+    }
+};
+// "3 fixed, 1 rejected · complete", or "2 decided · not marked complete".
+export function decisionSummary(ds, complete = ds.some((d) => d.complete)) {
+    const counts = OUTCOMES.map((o) => [o, ds.filter((d) => d.outcome === o).length]).filter(([, n]) => n);
+    const n = counts.reduce((a, [, c]) => a + c, 0);
+    if (!n)
+        return complete ? 'none · complete' : 'none yet';
+    return `${complete ? counts.map(([o, c]) => `${c} ${o}`).join(', ') : `${n} decided`} · ${complete ? 'complete' : 'not marked complete'}`;
+}
+// Adds records (reviews or decisions) to a commit's note, keeping each line once. Several
 // reviews can finish at once, so the write is a compare-and-swap: the new
 // notes commit is built under a private ref, and the reviews ref moves to it
 // only if nobody else moved it meanwhile; otherwise it starts again.
@@ -109,7 +202,8 @@ export function addReviews(sha, records) {
 // Reviews follow a gloss onto commits made from the reviewed ones (adopt,
 // carry); their keys decide what they still cover there.
 export function copyReviews(from, to) {
-    const records = from.flatMap(readReviews);
+    // Decisions come with the reviews they answer.
+    const records = [...from.flatMap(readReviews), ...from.flatMap(readDecisions)];
     if (records.length)
         addReviews(to, records);
 }
@@ -199,7 +293,7 @@ export function statusPhrase(s) {
         return `${s.stage}: ${never ? 'reviewed before it was glossed' : 'gloss changed since review'} (${who})`;
     }
     const v = verdict(s);
-    const words = WORDS[s.stage] ?? WORDS.default;
+    const words = Object.hasOwn(WORDS, s.stage) ? WORDS[s.stage] : WORDS.default;
     return `${s.stage}: ${v === 'clean' ? words.clean : v === 'issues' ? words.issues : 'reviewed'} (${who}` +
         `${earlierIssues(s) ? '; an earlier review found issues' : ''})`;
 }

package/dist/safe-match.js

@@ -0,0 +1,30 @@
+import vm from 'node:vm';
+// Patterns come from a repo's config, so one may backtrack without end. Each
+// batch of lines runs in a vm with a time budget; a pattern that exceeds it is
+// reported once on stderr, and from then on it counts as matching every line:
+// failing open would let a change pad a line to switch a trusted pattern off. Lines are never cut: a
+// change controls its own lines, and padding one must not hide a hit.
+const BUDGET_MS = 250;
+const script = new vm.Script('texts.map((t) => re.test(t))');
+// One context for all calls: creating one per call dominates the cost.
+const ctx = vm.createContext({ re: null, texts: [] });
+const skipped = new Set();
+// `timedOut` is true when the answer is the fail-closed one (this call or an
+// earlier one in the process hit the budget), so hits can say so.
+export function matchLines(re, texts) {
+    const key = `${re.source}/${re.flags}`;
+    if (skipped.has(key))
+        return { hit: texts.map(() => true), timedOut: true };
+    ctx.re = re;
+    ctx.texts = texts;
+    try {
+        return { hit: script.runInContext(ctx, { timeout: BUDGET_MS }), timedOut: false };
+    }
+    catch (err) {
+        if (err.code !== 'ERR_SCRIPT_EXECUTION_TIMEOUT')
+            throw err;
+        skipped.add(key);
+        console.error(`warning: pattern ${JSON.stringify(re.source)} took over ${BUDGET_MS}ms and is treated as matching every line from now on (catastrophic backtracking, or a padded line?)`);
+        return { hit: texts.map(() => true), timedOut: true };
+    }
+}

package/dist/schema.js

@@ -10,6 +10,7 @@ export const NECESSITY = [
     'speculative',
     'mechanical',
 ];
+export const isNecessity = (s) => NECESSITY.includes(s);
 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`)',
@@ -18,6 +19,30 @@ export const NECESSITY_HELP = {
     defensive: 'Guards edge cases or failures nobody asked about',
     speculative: 'Added because it might be useful later',
 };
+// How far a group's effect reaches if it is wrong, lowest first.
+export const IMPACT = ['local', 'module', 'shared', 'contract', 'sensitive'];
+export const isImpact = (s) => IMPACT.includes(s);
+export const IMPACT_HELP = {
+    local: 'Contained in one file or component; no outside callers (a private helper, template text, a test)',
+    module: 'One feature or project; its callers are inside it',
+    shared: 'Code used by several projects or modules, or root build, test or lint config',
+    contract: 'An interface others depend on: public APIs, routes, state shape, message formats, schemas, config keys, dependency versions, CI definitions',
+    sensitive: 'Correctness or safety critical whatever the size: auth, crypto, permissions, data writes or deletes, payments, hardware I/O, secrets',
+};
+// What a reviewer should do with the change, lowest first.
+export const ATTENTION = ['skim', 'look', 'careful', 'must-read'];
+export const ATTENTION_HELP = {
+    skim: 'Glance at the summary',
+    look: 'Read the focus groups',
+    careful: 'Read every non-mechanical group',
+    'must-read': 'Read line by line before approving',
+};
+// Notes come from anyone who can push to the remote, and the readers cost more
+// than linear in the groups (the page lists, for each group, the groups it
+// shares lines with) and spread lists into function calls. Real glosses have
+// a few dozen groups; these are far above that.
+export const MAX_GROUPS = 500;
+export const MAX_ITEMS = 500;
 export const Group = z.object({
     id: z
         .string()
@@ -36,22 +61,44 @@ export const Group = z.object({
         .string()
         .optional()
         .describe('A test, requirement or task line that demonstrates the need'),
+    impact: z
+        .enum(IMPACT)
+        .optional()
+        .describe('How far the effect reaches if this group is wrong: ' + IMPACT.join(' < ') + '; the highest that applies'),
+    impact_reason: z
+        .string()
+        .max(120)
+        .optional()
+        .describe('One short sentence on why the impact applies (expected for contract and sensitive)'),
     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 Attention = z.object({
+    level: z.enum(ATTENTION).describe('What the reviewer should do: ' + ATTENTION.map((l) => `${l} (${ATTENTION_HELP[l].toLowerCase()})`).join(', ')),
+    focus: z
+        .array(z.string())
+        .min(1)
+        .max(3)
+        .optional()
+        .describe('One to three group ids to look at first'),
+    reasons: z.array(z.string()).max(MAX_ITEMS).optional().describe('Short reasons for the level'),
+    override_reason: z.string().optional().describe('Why the level is lower than the change would suggest, if it is'),
+});
 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),
+    groups: z.array(Group).min(1).max(MAX_GROUPS),
     alternatives: z
         .array(z.object({ option: z.string(), rejected_because: z.string() }))
+        .max(MAX_ITEMS)
         .optional()
         .describe('Approaches considered and why they were not taken'),
-    risks: z.array(z.string()).optional().describe('Known risks or open questions'),
+    risks: z.array(z.string()).max(MAX_ITEMS).optional().describe('Known risks or open questions'),
+    attention: Attention.optional().describe('How much attention a human reviewer should give this change'),
     author: z
         .object({
         agent: z.string().optional(),
@@ -63,10 +110,14 @@ export const Annotation = z.object({
 // 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,
+// 3 serves lists; 4 impact, impact_reason or attention. 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 const NOTE_FORMAT = 4;
 export function noteFormat(a) {
+    // Readers of lower formats drop fields they don't know (they would lose
+    // these on a carry), so they must refuse the note instead.
+    if (a.attention || a.groups.some((g) => g.impact || g.impact_reason))
+        return 4;
     if (a.groups.some((g) => servesOf(g).length > 1))
         return 3;
     if (a.groups.some((g) => g.hunks.some((ref) => ref.includes(':'))))

package/dist/selection.js

@@ -145,3 +145,24 @@ export function uncovered(hunks, claims) {
     }
     return out;
 }
+// Every group's page carries the lines it claims, and building it costs more
+// than linear in them: measured, 200,000 claimed lines build in about half a
+// second, 1,000,000 in 3 to 10 s, 5,000,000 in over a minute. Sharing a hunk
+// between a few dozen groups is normal (one per dependency in a lockfile); the
+// budget is far above that, and a gloss may always claim 5 times the diff.
+export const MAX_CLAIMED_LINES = 500_000;
+const MAX_CLAIM_FACTOR = 5;
+// A message for a gloss whose groups claim too many lines, or null. Used when a
+// gloss is written and when it is read, so `add` never writes one readers refuse.
+export function claimsProblem(claims, hunks) {
+    let total = 0;
+    for (const h of hunks)
+        total += changedCount(h);
+    let claimed = 0;
+    for (const c of claims)
+        claimed += c.lines ? c.lines.size : changedCount(c.hunk);
+    const limit = Math.max(MAX_CLAIMED_LINES, MAX_CLAIM_FACTOR * total);
+    if (claimed <= limit)
+        return null;
+    return `the groups claim ${claimed} changed lines in all (the commit has ${total}; at most ${limit} are allowed): give each group only the lines it explains (h1:1-40) instead of the whole hunk, or use fewer groups on the same hunk`;
+}