@assuredloop/cli 0.1.0 → 0.2.1

package/src/adrs.js

@@ -1,110 +0,0 @@
-// Decision records ([LNK-4]): `NNNN-<decision>.md` in docs/adr and each
-// `adrs:` folder of .assuredloop, in the kit's format. The tool shows the
-// ADRs governing a section, lists those a request added or superseded, and
-// flags what breaks the format's rules; it never writes one.
-import { git } from './git.js';
-import { openTree } from './tree.js';
-import { configured, pastLines } from './spec.js';
-import { cites, idsOn, paths, requestOf } from './links.js';
-
-// A file name is bounded (255 bytes), so the name is too: unbounded, a long token takes quadratic time.
-const numbers = (s) => [...new Set([...s.matchAll(/\bADR[ \t]+(\d{4})\b|(?<![\w-])(\d{4})-[\w.-]{0,250}\.md\b/g)].map((m) => m[1] ?? m[2]))];
-const numberOf = (p) => p.match(/(?:^|\/)(\d{4})-[^/]*\.md$/)?.[1];
-// `Status:` anywhere in the header, the lines before the first `##` heading,
-// so `Date: … Status: superseded by …` on one line is read. The status ends
-// with its sentence, so a field after it on the line is not part of it.
-const STATUS = /(?<![\w-])Status:[ \t]*(.*?)(?:\.(?=[ \t]|$)|$)/m;
-const statusIn = (text) => { const end = text.search(/^##[ \t]/m); return (end < 0 ? text : text.slice(0, end)).match(STATUS); };
-
-// A `past` tree's `adrs:` lines are read leniently ([VW-8]).
-export const adrFolders = (top, tree, at, past = false) => [...new Set(['docs/adr', ...(past ? pastLines : configured)(top, tree, at, 'adrs')])];
-
-// Every ADR in `tree`: its path, number, text, status word, and its links.
-export function adrsIn(top, tree, at, past = false) {
-  return adrFolders(top, tree, at, past).flatMap((d) => (tree.list(d) ?? []).filter((f) => numberOf(f)).map((f) => {
-    const text = tree.read(`${d}/${f}`)?.toString('utf8') ?? '';
-    const field = (k) => text.match(new RegExp(`^${k}:[ \\t]*(.*)$`, 'm'))?.[1] ?? '';
-    const m = statusIn(text);
-    const status = m?.[1] ?? '';
-    return { path: `${d}/${f}`, n: numberOf(f), text, status: status.match(/^[a-z]+/i)?.[0].toLowerCase() ?? '', hasStatus: Boolean(m),
-      by: /^superseded/i.test(status) ? numbers(status) : [], supersedes: numbers(field('Supersedes')), hasSupersedes: /^Supersedes:/m.test(text),
-      request: field('Request').trim(), governs: idsOn(field('Governs')) };
-  }));
-}
-
-const shown = (a) => `${a.n} ${a.status === 'superseded' ? `superseded by ${a.by.join(', ')}` : a.status || 'no status'}`;
-
-// The ADRs that govern section `id` (a Governs: line) or name it, current first.
-export function governing(top, tree, id, at) {
-  return adrsIn(top, tree, at).filter((a) => a.governs.includes(id) || cites(a.text, id))
-    .sort((x, y) => (y.status === 'accepted') - (x.status === 'accepted') || x.n.localeCompare(y.n))
-    .map((a) => `${shown(a)} (${a.governs.includes(id) ? 'governs' : 'names'} [${id}])`);
-}
-
-// The ADRs request `name` added (its Request: line, or the commit that added
-// the file maps to it, [LNK-2]), and the ADRs those supersede.
-export function adrsOf(top, tree, at, name, requests) {
-  const all = adrsIn(top, tree, at);
-  const addedIn = new Map();
-  let sha = null;
-  // -z keeps each path literal: `>sha`, then its paths, each ended by NUL.
-  for (const l of paths(git(top, ['log', '--diff-filter=A', '--name-only', '-z', '--format=>%H', at ?? 'HEAD', '--', ...adrFolders(top, tree, at)], { allowFail: true }))) {
-    const p = l.replace(/^\n/, '');
-    if (p.startsWith('>')) sha = p.slice(1);
-    else if (!addedIn.has(p)) addedIn.set(p, sha);
-  }
-  // A commit that touched several request folders maps to none of them here.
-  const seen = new Map();
-  const mapped = (sha) => requestOf(top, sha, requests, seen);
-  const added = all.filter((a) => a.request === name || (addedIn.has(a.path) && mapped(addedIn.get(a.path)).how !== 'folder, ambiguous' && mapped(addedIn.get(a.path)).names.includes(name)));
-  return { added, superseded: all.filter((o) => added.some((a) => a.supersedes.includes(o.n) || o.by.includes(a.n))) };
-}
-
-// The ADR hints of branch `b`: not ok for an accepted ADR edited beyond its
-// status (base against the final state), a broken or one-way supersede link,
-// a reused number; a note for a superseded ADR cited as current.
-export function adrHints(top, b) {
-  const out = [];
-  const add = (kind, owners, text, command) => out.push({ kind, rank: kind === 'note' ? 14 : 5, owners, text, command });
-  const all = adrsIn(top, b.tree, b.at);
-  const byN = new Map();
-  for (const a of all) byN.set(a.n, [...(byN.get(a.n) ?? []), a]);
-  // A number's file names over history. A rename that keeps the number
-  // replaces its name; a renumbering leaves the old number used.
-  const names = new Map();
-  const log = paths(git(top, ['log', '--reverse', '-M', '--diff-filter=AR', '--name-status', '-z', '--format=', b.at ?? 'HEAD', '--', ...adrFolders(top, b.tree, b.at)], { allowFail: true }));
-  for (let i = 0; i < log.length; i += log[i][0] === 'R' ? 3 : 2) {
-    const [was, p] = log[i][0] === 'R' ? [log[i + 1], log[i + 2]] : [null, log[i + 1]];
-    if (was && numberOf(was) === numberOf(p)) names.get(numberOf(was))?.delete(was);
-    if (numberOf(p)) names.set(numberOf(p), (names.get(numberOf(p)) ?? new Set()).add(p));
-  }
-  for (const a of all) names.set(a.n, (names.get(a.n) ?? new Set()).add(a.path));
-  for (const [n, ps] of names) if (ps.size > 1) add('not ok', [], `ADR number ${n} is reused: ${[...ps].join(' and ')}; a number is never reused`, 'git mv the newer one to the next free number, then al check');
-  for (const a of all) {
-    // A field the record already has is changed, never added again.
-    const links = [...a.supersedes.map((n) => [n, 'supersedes', (t) => t.by.includes(a.n),
-      (t) => (t.hasStatus ? `set its Status: to "superseded by ADR ${a.n}" in` : `add "Status: superseded by ADR ${a.n}" to`)]),
-    ...a.by.map((n) => [n, 'is superseded by', (t) => t.supersedes.includes(a.n),
-      (t) => (t.hasSupersedes ? `add ADR ${a.n} to the Supersedes: line of` : `add "Supersedes: ADR ${a.n}" to`)])];
-    for (const [n, says, back, fix] of links) {
-      const t = byN.get(n);
-      if (!t) add('not ok', [], `a broken supersede link: ${a.path} ${says} ADR ${n}, which does not exist`, `correct the link in ${a.path}, then al check`);
-      else if (!t.some(back)) add('not ok', [], `a one-way supersede link: ${a.path} ${says} ADR ${n}, but ${t[0].path} does not say so back`, `${fix(t[0])} ${t[0].path}, then al check`);
-    }
-  }
-  if (b.base) {
-    const strip = (t) => { const m = statusIn(t); return m ? t.slice(0, m.index) + t.slice(m.index + m[0].length) : t; };
-    for (const a of adrsIn(top, openTree(top, b.base), b.base, true).filter((x) => x.status === 'accepted')) {
-      const now = b.tree.read(a.path)?.toString('utf8');
-      if (now === undefined || strip(now) !== strip(a.text)) {
-        add('not ok', [], `${a.path} was accepted at ${b.base.slice(0, 7)} and is ${now === undefined ? 'deleted' : 'edited beyond its Status line'} on this branch; a change is a new ADR that supersedes it`, `git diff ${b.base.slice(0, 7)} -- ${a.path}`);
-      }
-    }
-  }
-  const old = (text) => numbers(text).filter((n) => byN.get(n)?.some((a) => a.status === 'superseded'));
-  for (const f of b.files) {
-    for (const s of f.sections) for (const n of old(s.text)) add('note', [], `${s.id ? `[${s.id}]` : `${f.path}:${s.line}`} cites ADR ${n}, which is superseded`, `al context ${s.id ?? f.path}`);
-  }
-  for (const x of b.blocks.values()) if (x.open && x.now) for (const n of old(x.now)) add('note', [x.request], `${x.key} of ${x.request} cites ADR ${n}, which is superseded`, `al context ${x.request}`);
-  return out;
-}

package/src/audit.js

@@ -1,176 +0,0 @@
-// --audit ([VW-7]): the whole trace of a request, a section or a code line,
-// nothing capped, every hash re-checked. History is main's first-parent line
-// (the --at commit's under --at): what reached main.
-import { isAbsolute } from 'node:path';
-import { Fail, HISTORY, day, git, isShallow, mainCommit, resolveCommit } from './git.js';
-import { openTree, findRequest, noSymlinkOn } from './tree.js';
-import { ROOT, rootOf, rootLine, baseline, configured } from './spec.js';
-import { allBlocks, stateText, statesOf } from './states.js';
-import { ID_TEXT, TITLES, headingAt, sameSection, sectionsById } from './sections.js';
-import { isSignoff, snapshots } from './snapshot.js';
-import { line, entriesOf, concludedOnMain, concluding } from './commands.js';
-import { blame, filesOf, requestCommits, requestOf, requestsIn } from './links.js';
-import { testMatcher } from './tests.js';
-import { adrsOf } from './adrs.js';
-import { organized, parentOf, parts, samePart, signoffState } from './signoff.js';
-import { sinceConclusion } from './views.js';
-
-const ID = new RegExp(`^${ID_TEXT}$`);
-const indented = (text) => text.replace(/\n+$/, '').split('\n').map((l) => `            ${l}`);
-
-export function audit(top, target, at) {
-  const tree = openTree(top, at);
-  const tip = at ? resolveCommit(top, at) : mainCommit(top);
-  const a = { top, tree, at, tip, root: rootOf(top, tree, at), shallow: isShallow(top), requests: requestsIn(tree), seen: new Map() };
-  a.gap = a.shallow ? HISTORY : !tip ? 'no main to read it along' : null;
-  const pos = target.match(/^(.+):(\d+)$/);
-  if (!pos && !ID.test(target) && !findRequest(tree, target)) throw new Fail(`no request named ${target} in the ${tree.label}`, 'al context <name | ID | path:line> --audit');
-  return {
-    tree,
-    body: pos ? fromLine(a, pos[1], Number(pos[2])) : ID.test(target) ? fromSection(a, target) : trace(a, target),
-    next: 'git show <sha> for any commit named here',
-    notKnown: ['who spoke (the records name their source)', 'drafts inside a PR: only what reached main is kept'],
-  };
-}
-
-const commitLine = (a, c) => `${c.sha.slice(0, 7)} ${day(c.when)} ${git(a.top, ['show', '-s', '--format=%s', c.sha])} (${c.names.length ? `${c.names.join(', ')} by ${c.how}` : 'no request'})`;
-
-// Main's first-parent commits that changed the baseline, oldest first, each
-// with its sections by ID.
-// Each tree is read with its own root: today's, or any `root:` line
-// .assuredloop held, so a moved root keeps its earlier history.
-function history(a) {
-  if (a.walk || a.gap) return a.walk ?? [];
-  const shas = (args) => git(a.top, args).split('\n').filter(Boolean);
-  const roots = new Set([a.root, ROOT, ...shas(['log', '--format=%H', a.tip, '--', '.assuredloop']).map((sha) => rootLine(a.top, openTree(a.top, sha), sha))]);
-  roots.delete(null);
-  // .assuredloop too: a commit that only switches root: can change a section's text.
-  a.walk = shas(['log', '--first-parent', '--reverse', '--format=%H', a.tip, '--', '.assuredloop', ...[...roots].map((r) => `${r}/`)]).map((sha) => {
-    const tree = openTree(a.top, sha);
-    const root = rootLine(a.top, tree, sha);
-    return { sha, sections: root ? sectionsById(baseline(tree, root)) : new Map() };
-  });
-  return a.walk;
-}
-
-// The whole trace of request `name`.
-function trace(a, name) {
-  const { top, tree } = a;
-  const dir = findRequest(tree, name);
-  const md = tree.read(`${dir}/request.md`).toString('utf8');
-  const body = [line('Audit', `${name}  ${(md.match(/^# (.*)$/m)?.[1] ?? name).trim()}  (${dir})`),
-    ...entriesOf(md, TITLES.words).map((e) => line('Words', e))];
-  // Each snapshot of `from`'s origin/, re-checked; with `signoffsOnly`, its sign-offs and any file that is
-  // not a valid snapshot, which may have been one. `whose` names another request's.
-  const recheck = (from, signoffsOnly, whose = '') => {
-    for (const { file: f, s } of snapshots(tree, from)) {
-      const ok = !s ? 'not ok: not a valid snapshot' : s.intact ? 'SHA-256 matches' : 'not ok: no longer matches its SHA-256';
-      if (isSignoff(s)) body.push(line('Sign-off', `${whose}origin/${f} (${s.fields.Fetched}) ${ok}; signed text:`), ...indented(s.text.toString('utf8')));
-      else if (!signoffsOnly || !s) body.push(line('Snapshot', `${whose}origin/${f} ${s ? `(${s.fields.Source}, fetched ${s.fields.Fetched}) ` : ''}${ok}`));
-    }
-  };
-  recheck(dir, false);
-  // [REC-5]: a child inherits its parent's latest sign-off for the parts it copies word for word: named only
-  // when it does. The parent's sign-offs are re-checked here too, as the parent's.
-  const parent = parentOf(tree, name);
-  if (parent) {
-    const s = signoffState(tree, dir, name);
-    const org = organized(md);
-    const copied = s.parentSignoff && org ? parts(org.text, org.oneLine)
-      .filter((p) => parts(s.parentSignoff.text, s.parentSignoff.oneLine).some((q) => samePart(p, q))).map((p) => p.key) : [];
-    if (copied.length) body.push(line('Sign-off', `through ${parent.name} for ${copied.join(', ')}, copied word for word from its origin/${s.parentSignoff.file}${s.blocked ? `; ${s.reason}` : ''}`));
-    recheck(parent.dir, true, `parent ${parent.name}: `);
-  }
-  body.push(...entriesOf(md, TITLES.decisions).map((e) => line('Decision', e)));
-  const place = (f) => [`requests/${name}/${f}`, `requests/archive/${name}/${f}`];
-  const records = [...place('request.md'), ...place('change.md')];
-  const versions = a.gap ? [] : git(top, ['log', '--first-parent', '--format=%H', a.tip, '--', ...records]).split('\n').filter(Boolean);
-  body.push(...(a.gap ? [line('Versions', a.gap)] : versions.map((sha) =>
-    line('Version', `${commitLine(a, requestOf(top, sha, a.requests, a.seen))}: ${filesOf(top, sha).filter((p) => records.includes(p)).join(', ')}`))));
-  // Each block, with its state and when it reached the baseline on main, read
-  // only over the request's own life there: its first record to its conclusion.
-  const blocks = allBlocks(tree);
-  const order = new Map(a.gap ? [] : git(top, ['rev-list', '--first-parent', '--reverse', a.tip]).split('\n').map((sha, i) => [sha, i]));
-  const end = concluding(top, name, a.at).sha;
-  const [from, to] = [order.get(versions.at(-1)) ?? 0, end ? order.get(end) : Infinity];
-  const walk = history(a).map((c, i, all) => ({ ...c, before: all[i - 1] })).filter((c) => order.get(c.sha) >= from && order.get(c.sha) <= to);
-  const where = (landed) => a.gap ?? (landed ? `consolidated on main at ${landed.sha.slice(0, 7)}` : 'not consolidated on main');
-  // An archived request is never re-judged against today's baseline: its sections as at conclusion, or what changed them since ([STA-8]).
-  const since = dir.startsWith('requests/archive/') ? sinceConclusion(top, name, a.at) : null;
-  const held = statesOf(baseline(tree, a.root), blocks, (b) => b.request === name);
-  for (const e of held) {
-    const b = blocks.get(e.block);
-    // A removal lands where the section goes from present to absent.
-    const landed = b.op === 'remove' ? walk.find((c) => !c.sections.has(b.id) && c.before?.sections.has(b.id))
-      : walk.find((c) => c.sections.has(b.id) && sameSection(c.sections.get(b.id), b.now ?? ''));
-    body.push(line('Section', `${e.block} ${since ? since.say(e.id) : stateText(e)}; ${where(landed)}`));
-  }
-  // A concluded request with no blocks (tier 1): the sections its Outcome lists, each landing where it
-  // first took the text it had at conclusion, or, removed, where it went from present to absent.
-  const last = walk.at(-1)?.sections ?? new Map();
-  for (const id of held.length ? [] : since?.ids ?? []) {
-    const landed = last.has(id) ? walk.find((c) => c.sections.has(id) && sameSection(c.sections.get(id), last.get(id)))
-      : walk.find((c) => !c.sections.has(id) && c.before?.sections.has(id));
-    body.push(line('Section', `[${id}] ${since.say(id)}; ${where(landed)}`));
-  }
-  // The linked commits ([LNK-2]) and the test files they changed.
-  if (a.shallow) body.push(line('Commits', HISTORY));
-  else {
-    const rev = a.at ?? 'HEAD';
-    // Every route [LNK-2] maps by: a Request: line, the folder, an issue number in the owner's words.
-    const issues = [...new Set(entriesOf(md, TITLES.words).join('\n').match(/#\d+/g) ?? [])];
-    const mine = requestCommits(top, name, issues, rev, a.requests, a.seen);
-    body.push(...mine.map((c) => line('Commit', commitLine(a, c))));
-    const isTest = testMatcher(a.root, configured(top, tree, a.at, 'tests'));
-    body.push(line('Tests', [...new Set(mine.flatMap((c) => filesOf(top, c.sha)).filter(isTest))].sort().join(' · ') || 'none changed by its commits'));
-  }
-  const adrs = adrsOf(top, tree, a.at, name, a.requests);
-  body.push(line('ADRs', [...adrs.added.map((x) => `${x.path} (added)`), ...adrs.superseded.map((x) => `${x.path} (superseded)`)].join(' · ') || 'none'));
-  if (dir.startsWith('requests/archive/')) body.push(line('Concluded', concludedOnMain(top, name, a.at)));
-  const mdLines = md.split('\n');
-  const head = headingAt(mdLines, TITLES.outcome);
-  const stop = mdLines.findIndex((l, i) => i > head && /^#{1,2} /.test(l));
-  const outcome = head < 0 ? '' : mdLines.slice(head + 1, stop < 0 ? mdLines.length : stop).join('\n').trim();
-  body.push(...(outcome ? [line('Outcome', ''), ...indented(outcome)] : [line('Outcome', 'none yet')]));
-  return body;
-}
-
-// A section: its text, each main commit that changed it with its request,
-// then the trace of every request that shaped it or holds it.
-function fromSection(a, id) {
-  const s = baseline(a.tree, a.root).flatMap((f) => f.sections.map((x) => ({ ...x, path: f.path }))).find((x) => x.id === id);
-  const names = new Set([...allBlocks(a.tree).values()].filter((b) => b.id === id).map((b) => b.request));
-  if (!s && !names.size) return [`[${id}] not found: not in the baseline, and no request holds it`];
-  const body = [line('Audit', s ? `[${id}] ${s.title}  in ${s.path}` : `[${id}] not in the baseline`), ...(s ? indented(s.text) : [])];
-  if (a.gap) body.push(line('Changed', a.gap));
-  let was;
-  for (const c of history(a)) {
-    const now = c.sections.get(id);
-    if (now === was || (now !== undefined && was !== undefined && sameSection(now, was))) continue;
-    was = now;
-    const r = requestOf(a.top, c.sha, a.requests, a.seen);
-    r.names.forEach((n) => names.add(n));
-    body.push(line('Changed', `${now === undefined ? 'removed' : 'written'} at ${commitLine(a, r)}`));
-  }
-  for (const n of names) if (findRequest(a.tree, n)) body.push('', ...trace(a, n));
-  return body;
-}
-
-// A code or baseline line: blame, the commit's request, then its trace.
-function fromLine(a, path, n) {
-  // Only a path inside the repo, never through a symlink, as the tool writes ([SPC-1]).
-  if (isAbsolute(path) || path.split('/').includes('..') || (a.at ? a.tree.linkOn(path) : !noSymlinkOn(a.top, path))) {
-    throw new Fail(`${path} is not a path inside this repo, or goes through a symlink`, 'al context <path>:<line> --audit, for a repo-relative path');
-  }
-  const lines = a.tree.read(path)?.toString('utf8').replace(/\n$/, '').split('\n');
-  if (!lines || n < 1 || n > lines.length) throw new Fail(`${path}:${n}: no such line in the ${a.tree.label}`, 'al context <path>:<line> --audit, for a line that exists');
-  const body = [line('Audit', `${path}:${n}  ${lines[n - 1].trim()}`)];
-  if (a.shallow) return [...body, line('Blame', HISTORY)];
-  const [b] = blame(a.top, a.at ? a.tip : null, path, [[n, n]], { code: !path.startsWith(`${a.root}/`) });
-  if (!b || /^0+$/.test(b.sha)) return [...body, line('Blame', 'not committed yet: the trail stops here')];
-  const c = requestOf(a.top, b.sha, a.requests, a.seen);
-  body.push(line('Blame', commitLine(a, c)));
-  if (!c.names.length) return [...body, line('Request', `${b.sha.slice(0, 7)} maps to no request: the trail stops here`)];
-  for (const name of c.names) body.push('', ...(findRequest(a.tree, name) ? trace(a, name) : [line('Request', `${name}: no such request in the ${a.tree.label}`)]));
-  return body;
-}

package/src/check.js

@@ -1,127 +0,0 @@
-// al check [--strict] [--all]: every hint for the branch ([HNT-2]), ranked and
-// capped ([HNT-1]); the final state is the working tree, the commits are
-// main..HEAD. Among them, the append-only records ([REC-12]), per commit, each
-// commit against its first parent: the owner's words and the decisions only
-// grow at the end; a file in origin/ never changes or goes; nothing changes
-// under a request archived on main; the move to archive/ is not an edit.
-// check exits 0, and --strict exits 1 on a not ok that counts ([HNT-3]).
-import { HISTORY, cutOffNotes, git, hasCommits, isShallow, mainCommit, mainName, ownCommits, resolveCommit } from './git.js';
-import { folderName, openTree } from './tree.js';
-import { movesOf, ownFiles } from './links.js';
-import { line } from './commands.js';
-import { TITLES, headingAt } from './sections.js';
-import { hintText, hintsOf, ranked, readBranch } from './hints.js';
-import { assertionsChanged, headNote, nearIds, resultLines, testLines } from './tests.js';
-
-const NOTE = 'append-only is checked per commit over main..HEAD; this protects a PR only when check runs on it';
-const APPEND_ONLY = [TITLES.words, TITLES.decisions];
-
-// Git's path lists, NUL-separated, so every name comes as it is (never quoted).
-const paths = (out) => out.split('\0').filter(Boolean);
-
-// The files of request `name` at `rev`, by their path inside the request folder
-// (open or archived), each with its blob and full path.
-function requestFiles(top, rev, name) {
-  const out = git(top, ['ls-tree', '-r', '-z', rev, '--', `requests/${name}/`, `requests/archive/${name}/`]);
-  const files = new Map();
-  for (const l of paths(out)) {
-    const [, sha, path] = l.match(/^\S+ \S+ (\S+)\t([\s\S]*)$/);
-    files.set(path.replace(/^requests\/(archive\/)?[^/]+\//, ''), { sha, path });
-  }
-  return files;
-}
-
-// The entries of a `## <title>` section: the text before the first item, then
-// each top-level item with its continuation lines, trailing spaces dropped.
-function entries(md, title) {
-  const lines = md.replace(/\r\n/g, '\n').split('\n');
-  const at = headingAt(lines, title);
-  const out = [];
-  for (const l of at < 0 ? [] : lines.slice(at + 1)) {
-    if (/^#{1,2}\s/.test(l)) break;
-    if (!out.length || /^(-|\d+\.)\s/.test(l)) out.push(l.trimEnd());
-    else out[out.length - 1] += `\n${l.trimEnd()}`;
-  }
-  return out.map((e) => e.replace(/\n+$/, '')).filter((e) => e.trim());
-}
-
-function problems(top, parent, commit, name, frozen) {
-  const before = requestFiles(top, parent, name);
-  const after = requestFiles(top, commit, name);
-  const out = [];
-  const bad = (path, what) => out.push({ kind: 'not ok', rank: 3, owners: [name], text: `${commit.slice(0, 7)} ${path}: ${what} ([REC-12])`, command: `git show ${commit.slice(0, 7)} -- ${path}` });
-  if (frozen.has(name)) {
-    const paths = new Set([...before.values(), ...after.values()].map((f) => f.path).filter((p) => p.startsWith('requests/archive/')));
-    const sha = (files, p) => [...files.values()].find((f) => f.path === p)?.sha;
-    for (const p of paths) if (sha(before, p) !== sha(after, p)) bad(p, 'changes a request archived on main');
-    return out;
-  }
-  for (const [rel, f] of before) {
-    if (rel.startsWith('origin/') && after.get(rel)?.sha !== f.sha) {
-      bad(after.get(rel)?.path ?? f.path, after.has(rel) ? 'edits a file in origin/' : 'deletes a file in origin/');
-    }
-  }
-  const [was, now] = [before.get('request.md'), after.get('request.md')];
-  if (was && was.sha !== now?.sha) {
-    const [a, b] = [git(top, ['cat-file', 'blob', was.sha]), now ? git(top, ['cat-file', 'blob', now.sha]) : ''];
-    for (const title of APPEND_ONLY) {
-      const [old, grown] = [entries(a, title), entries(b, title)];
-      if (!old.every((e, i) => e === grown[i])) bad(now?.path ?? was.path, `edits or removes an entry of "## ${title}"`);
-    }
-  }
-  return out;
-}
-
-// The append-only hints of `commits` (main..HEAD), each owned by its request.
-export function appendOnly(top, main, commits) {
-  const frozen = new Set(paths(git(top, ['ls-tree', '-z', '--name-only', `${main}:requests/archive`], { allowFail: true }) ?? ''));
-  const out = [];
-  for (const commit of commits) {
-    const parent = git(top, ['rev-parse', '--verify', '--quiet', `${commit}^1`], { allowFail: true });
-    if (!parent) continue;
-    const changed = ownFiles(top, commit).filter((p) => p.startsWith('requests/'));
-    for (const name of new Set(changed.map(folderName).filter(Boolean))) out.push(...problems(top, parent, commit, name, frozen));
-  }
-  return out;
-}
-
-// Under --at X, the final state is X's tree and the commits main..X ([VW-8]).
-export function check({ top, opts }) {
-  const main = mainCommit(top);
-  const head = opts.at ? resolveCommit(top, opts.at) : 'HEAD';
-  const to = opts.at ? head.slice(0, 7) : 'HEAD';
-  const base = main ? git(top, ['merge-base', main, head], { allowFail: true }) : null;
-  const commits = main ? ownCommits(top, main, head) : [];
-  const range = `${mainName(top)}..${to}`;
-  const b = readBranch(top, { base, commits, tree: openTree(top, opts.at), at: opts.at, range });
-  b.all = opts.all; // the linked-tests note names every test only under --all
-  // Under --at, main is read only up to X's fork point, so no later commit leaks in.
-  const list = ranked(hintsOf(top, b, { main: opts.at ? base : main }), b);
-  const notKnown = [...headNote(top, b), ...(opts.at ? ["main after X's fork point (read only up to it under --at)"] : [])];
-  if (!hasCommits(top)) notKnown.push('no commits yet, so no history');
-  if (isShallow(top)) notKnown.push(`${HISTORY}: commits before the shallow boundary`, ...cutOffNotes(top, commits));
-  const body = [line('Serves', [...[...b.served].filter((n) => !b.archived.has(n)), ...[...b.archived].map((n) => `archives ${n}`)].join(' · ') || 'no request')];
-  if (b.tier) {
-    // [REC-11]: the claim with its evidence: the spec edits, the sections near the changed code, the tests whose assertions changed.
-    // A section moved to another file, its text unchanged, is a move, not an edit ([REC-10]).
-    const moves = movesOf(b.before, b.files).map((m) => `[${m.id}] ${m.from} → ${m.to}`);
-    body.push(line('Tier', b.tier), line('Evidence', [...(b.changedIds.length || !moves.length ? [`edits ${b.changedIds.map((i) => `[${i}]`).join(', ') || 'no baseline section'}`] : []),
-      ...(moves.length ? [`moves ${moves.join(', ')}, text unchanged`] : []),
-      `near the changed code: ${nearIds(top, b).map((i) => `[${i}]`).join(', ') || 'none'}`,
-      `tests whose assertions changed: ${assertionsChanged(top, b).join(', ') || 'none'}`].join(' · ')));
-  }
-  body.push(...testLines(top, b, false), ...resultLines(top, b));
-  const cap = opts.all ? list.length : 5;
-  body.push(...list.slice(0, cap).map(hintText));
-  if (list.length > cap) body.push(`${list.length - cap} more hidden, --all`);
-  if (!main) body.push('no main to compare with, so no commits were checked');
-  body.push(NOTE);
-  const counting = list.filter((h) => h.counts).length;
-  return {
-    tree: { label: `${opts.at ? `commit ${to}` : 'working tree'} and ${commits.length} commit(s) over ${range}` },
-    body,
-    exit: opts.strict && counting ? 1 : 0,
-    next: counting ? 'fix or explain each not ok that counts, then al check --strict' : 'run al check again after each push; it certifies only what it read',
-    notKnown,
-  };
-}