@assuredloop/cli 0.1.0 → 0.2.1

package/src/snapshot.js

@@ -1,63 +0,0 @@
-// Snapshots of originals ([REC-3]): a header, a line starting with `---`, then
-// the text exactly as fetched. SHA-256 is of the bytes after that line.
-import { createHash } from 'node:crypto';
-
-export const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
-
-// A snapshot's bytes; `signed` makes it a sign-off ([REC-5]): the owner's
-// `words` after Source, and SIGNED as its separator.
-export function formatSnapshot({ source, words, fetched, updated, text, signed = false }) {
-  const header = [`Source: ${source}`];
-  if (words !== undefined) header.push(`Owner's words: ${words}`);
-  header.push(`Fetched: ${fetched}`);
-  if (updated) header.push(`Target updated: ${updated}`);
-  header.push(`SHA-256: ${sha256(text)}${signed ? '   (of the signed text below)' : ''}`, signed ? SIGNED : '---', '');
-  return Buffer.concat([Buffer.from(header.join('\n')), Buffer.from(text)]);
-}
-
-// What a file that is not a valid snapshot is said to lack.
-export const notSnapshot = (what) => `${what} is not a valid snapshot: it needs Source, Fetched and SHA-256, then a --- line`;
-
-// Every file in a request's origin/, whatever its name, each a snapshot
-// ([REC-3]): { file, s }, s null when it is not a valid one. Every reader
-// reads origin/ through this. A hidden file that is not a snapshot
-// (.DS_Store, an editor's) is left out; a hidden snapshot counts.
-export const snapshots = (tree, dir) => (tree.list(`${dir}/origin`) ?? [])
-  .map((file) => ({ file, s: parseSnapshot(tree.read(`${dir}/origin/${file}`) ?? Buffer.alloc(0)) }))
-  .filter(({ file, s }) => s || !file.startsWith('.'));
-
-// The header fields, the separator line, the text, and whether the text still
-// matches its hash. Null when the header lacks Source, Fetched or SHA-256, or
-// the separator.
-export function parseSnapshot(bytes) {
-  const fields = {};
-  let pos = 0;
-  while (pos < bytes.length) {
-    let end = bytes.indexOf(0x0a, pos);
-    if (end === -1) end = bytes.length;
-    const line = bytes.subarray(pos, end).toString('utf8').replace(/\r$/, '');
-    pos = end + 1;
-    if (line.startsWith('---')) {
-      const text = bytes.subarray(Math.min(pos, bytes.length));
-      const recorded = (fields['SHA-256'] || '').split(/\s/)[0].toLowerCase();
-      if (!recorded || !fields.Source || !fields.Fetched) return null;
-      return { fields, separator: line, text, recorded, intact: sha256(text) === recorded };
-    }
-    const m = line.match(/^([^:]+):\s?(.*)$/);
-    if (m) fields[m[1]] = m[2];
-  }
-  return null;
-}
-
-// A parsed snapshot is a sign-off ([REC-5]) only when its header ends with this
-// line, as record signoff writes it; the marker quoted in a text is not one.
-export const SIGNED = '--- signed text ---';
-export const isSignoff = (s) => s?.separator === SIGNED;
-
-// A file-name part from a source: `https://github.com/o/r/issues/31` gives
-// `github-com-o-r-issues-31`.
-export function slug(source) {
-  const s = source.toLowerCase().replace(/^[a-z]+:\/\//, '').replace(/[^a-z0-9]+/g, '-')
-    .slice(0, 50).replace(/^-+|-+$/g, '');
-  return s || 'source';
-}

package/src/spec.js

@@ -1,228 +0,0 @@
-// al spec: the design as it stands ([VW-5]), and numbering headings ([SPC-2], [SPC-3]).
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { isAbsolute, join, posix, relative, resolve } from 'node:path';
-import { Fail, HISTORY, gapFail, git, historyGap, isShallow } from './git.js';
-import { openTree, noSymlinkOn } from './tree.js';
-import { ID_TEXT, PREFIX_TEXT, parseSections, numberHeadings } from './sections.js';
-import { line } from './commands.js';
-import { hintLines } from './hints.js';
-import { allBlocks, parseChange, stateText, statesOf } from './states.js';
-import { sameSection } from './sections.js';
-
-// The baseline root when .assuredloop names none ([SPC-1]).
-export const ROOT = 'specs';
-
-const PREFIX = new RegExp(`^${PREFIX_TEXT}$`);
-const ID_OPEN = new RegExp(`\\[(${ID_TEXT})`, 'g');
-
-// A path `.assuredloop` names must lie inside this repo: never absolute,
-// through `..`, or through a symlink.
-function inside(top, tree, at, key, raw) {
-  const path = raw.replace(/\/+$/, '');
-  const parts = path.split('/');
-  let ok = !isAbsolute(raw) && !parts.includes('..') && !parts.includes('.');
-  // No part of it may be a symlink, in the commit or the working tree.
-  if (ok) ok = at ? !tree.linkOn(path) : noSymlinkOn(top, path);
-  if (!ok) throw new Fail(`${key} must be inside this repo: ${raw} (from .assuredloop)`, `set \`${key}:\` in .assuredloop to a ${key === 'root' ? 'folder' : 'path'} in this repo`);
-  return path;
-}
-
-// `text` without the spaces and tabs at its ends, and nothing else. A loop:
-// a regex that trims a long line's spaces takes quadratic time.
-export function trimBlanks(text) {
-  let [a, b] = [0, text.length];
-  while (a < b && (text[a] === ' ' || text[a] === '\t')) a++;
-  while (b > a && (text[b - 1] === ' ' || text[b - 1] === '\t')) b--;
-  return text.slice(a, b);
-}
-
-// The values of the `<key>: <path>` lines of `.assuredloop`, as written.
-const values = (tree, key) => [...(tree.read('.assuredloop')?.toString('utf8') ?? '').matchAll(new RegExp(`^${key}:(.*)$`, 'gm'))].map((m) => trimBlanks(m[1])).filter(Boolean);
-
-// The checked paths of the `tests:`, `results:` or `adrs:` lines ([LNK-3], [LNK-4]).
-export const configured = (top, tree, at, key) => values(tree, key).map((raw) => inside(top, tree, at, key, raw));
-
-// The baseline root: `specs`, or `root: <path>` in `.assuredloop` ([SPC-1]).
-// The baseline is on main, so the root must lie inside this repo. Every
-// other path the file names is checked here too, so a bad one stops any command.
-export function rootOf(top, tree, at) {
-  for (const key of ['tests', 'results', 'adrs']) configured(top, tree, at, key);
-  return inside(top, tree, at, 'root', values(tree, 'root')[0] ?? ROOT);
-}
-
-// A past tree's root, from its `root:` line only, or null when that line is
-// not a folder inside this repo; the other lines are not checked, so one old
-// bad line does not stop a read of history ([VW-7], [VW-8]).
-export function rootLine(top, tree, at) {
-  try { return inside(top, tree, at, 'root', values(tree, 'root')[0] ?? ROOT); } catch { return null; }
-}
-
-// A past tree's paths for `key`: only its lines that lie inside this repo, for
-// the same reason ([VW-8]).
-export const pastLines = (top, tree, at, key) => values(tree, key).flatMap((raw) => {
-  try { return [inside(top, tree, at, key, raw)]; } catch { return []; }
-});
-
-// Whether `path` names a baseline file: a .md file under the root, in plain form ([SPC-1]).
-export const inBaseline = (path, root) => posix.normalize(path) === path && path.startsWith(`${root}/`) && path.endsWith('.md');
-
-// The baseline's Markdown files, each with its sections.
-export function baseline(tree, root) {
-  return tree.walk(root).filter((p) => p.endsWith('.md'))
-    .map((path) => ({ path, text: tree.read(path).toString('utf8') }))
-    .map((f) => ({ ...f, sections: parseSections(f.text) }));
-}
-
-// Every ID found more than once in the root, with where: [[id, ['path:line', ...]]] ([SPC-3]).
-export function duplicateIds(files) {
-  const where = new Map();
-  for (const f of files) {
-    for (const s of f.sections) if (s.id) where.set(s.id, [...(where.get(s.id) ?? []), `${f.path}:${s.line}`]);
-  }
-  return [...where].filter(([, at]) => at.length > 1);
-}
-
-// The `not ok` for an ID found more than once in the root ([SPC-3]); no request owns it.
-export const duplicateHint = ([id, at]) => ({ kind: 'not ok', rank: 5, owners: [], counts: true, text: `duplicate ID [${id}] in ${at.join(' and ')}`, command: 'rename one copy by hand, then al spec --list' });
-
-// Those hints as check words them, three at most; check --all shows the rest ([HNT-1]).
-const duplicates = (files) => hintLines(duplicateIds(files).map(duplicateHint), 3, { more: 'al check --all' });
-
-export function spec(ctx) {
-  const { top, opts } = ctx;
-  if (opts['add-ids'] !== undefined) return addIds(ctx);
-  const tree = openTree(top, opts.at);
-  const root = rootOf(top, tree, opts.at);
-  const files = baseline(tree, root);
-  const notKnown = [isShallow(top) && HISTORY, 'whether the code does what the spec says (tests and review judge that)'].filter(Boolean);
-  // [VW-5]: each open change under the section it holds; an add not in the
-  // baseline yet under the baseline section its chain of anchors starts
-  // from; the rest (a new file) after the text. With no baseline yet, the
-  // open changes still show.
-  const blocks = allBlocks(tree);
-  const held = statesOf(files, blocks);
-  const empty = `no baseline yet; requests add sections as they go (root: ${root}/)`;
-  if (!files.length && !held.length) return { tree, body: [empty], next: 'al new <name> --from <file|->', notKnown };
-  const ids = new Set(files.flatMap((f) => f.sections.map((s) => s.id)));
-  const placed = (e, n = 0) => {
-    const anchor = blocks.get(e.block).anchor;
-    const up = held.find((x) => x.request === e.request && x.id === anchor && !ids.has(anchor));
-    return ids.has(anchor) ? anchor : up && n < 50 ? placed(up, n + 1) : null;
-  };
-  const under = (id) => held.filter((e) => e.id === id || (!ids.has(e.id) && placed(e) === id));
-  // A remove of a file's first section, gone from it, shows first under that file.
-  const paths = new Set(files.map((f) => f.path));
-  const first = (path) => held.filter((e) => !ids.has(e.id) && !placed(e) && e.op === 'remove' && e.file === path);
-  const loose = held.filter((e) => !ids.has(e.id) && !placed(e) && !(e.op === 'remove' && paths.has(e.file)));
-  const overlay = (s, text, list = under(s.id)) => list.flatMap((e) => {
-    const now = blocks.get(e.block).now;
-    const same = now && e.id === s.id && sameSection(now, s.text);
-    return [`>> ${e.block} ${stateText(e)}${!text ? '' : !now ? ', removes it' : same ? ', now as above' : ', now:'}`,
-      ...(text && now && !same ? now.replace(/\n+$/, '').split('\n').map((l) => `    ${l}`) : [])];
-  });
-  const body = files.length ? [] : [empty];
-  for (const f of files) {
-    body.push(line(body.length ? '' : 'Map', f.path), ...overlay({}, false, first(f.path)).map((l) => `${' '.repeat(14)}${l}`));
-    for (const s of f.sections) body.push(`${' '.repeat(12)}${s.id ? `[${s.id}] ` : ''}${s.title}`, ...overlay(s).map((l) => `${' '.repeat(14)}${l}`));
-  }
-  const into = [...new Set(loose.map((e) => e.file ?? 'no file named'))].map((p) => [p, loose.filter((e) => (e.file ?? 'no file named') === p)]);
-  for (const [p, list] of into) body.push(line('New', `${p} (not in the baseline yet)`), ...overlay({}, false, list).map((l) => `${' '.repeat(14)}${l}`));
-  if (files.length) body.push(line('Covers', files.map((f) => `${f.path} (${f.sections.length} sections)`).join(' · ')));
-  const hints = duplicates(files);
-  body.push(...hints);
-  if (!opts.list) {
-    for (const f of files) {
-      const preamble = f.text.slice(0, f.text.length - f.sections.reduce((n, s) => n + s.text.length, 0));
-      body.push('', `==> ${f.path}`, ...(preamble ? preamble.replace(/\n$/, '').split('\n') : []), ...overlay({}, true, first(f.path)));
-      for (const s of f.sections) body.push(...s.text.replace(/\n$/, '').split('\n'), ...overlay(s, true));
-    }
-    for (const [p, list] of into) body.push('', `==> ${p} (not in the baseline yet)`, ...overlay({}, true, list));
-    body.push('');
-  }
-  return {
-    tree,
-    body,
-    next: hints.length ? 'rename one copy of each duplicate ID by hand, to a new ID; an ID is never reused'
-      : opts.list ? 'al spec, for the text' : 'al spec --list, for the map only',
-    notKnown,
-  };
-}
-
-// Every `[ID` ever used ([SPC-3]): in the root and every request's change.md
-// now, and under the root and requests/ anywhere in the history of `rev`
-// (every ref by default), each ID with the paths where it headed a section:
-// a heading of a root .md file, out of code ([SPC-2]), or a block of a
-// change.md as the states read it ([SPC-5]).
-export function idsUsed(top, tree, root, rev = '--all') {
-  const used = new Map();
-  const note = (path, text) => {
-    for (const [, id] of text.matchAll(ID_OPEN)) if (!used.has(id)) used.set(id, new Set());
-    const headed = path.startsWith(`${root}/`) && path.endsWith('.md') ? parseSections(text).map((s) => s.id).filter(Boolean)
-      : /^requests\/(?:archive\/)?[^/]+\/change\.md$/.test(path) ? parseChange(text, '').map((b) => b.id) : [];
-    for (const id of headed) used.get(id).add(path);
-  };
-  for (const p of [...tree.walk(root).filter((x) => x.endsWith('.md')), ...tree.walk('requests').filter((x) => x.endsWith('/change.md'))]) note(p, tree.read(p).toString('utf8'));
-  // Each changed file whole, both sides, so headings are read with their
-  // fences; a merge against its first parent, so what only it brought counts.
-  const log = git(top, ['log', rev, '-p', '--diff-merges=first-parent', '--no-renames', '-U1000000', '--format=', '--', root, 'requests'], { allowFail: true }) ?? '';
-  let file = null;
-  const flush = () => { if (file?.path) { note(file.path, file.old.join('\n')); note(file.path, file.now.join('\n')); } };
-  for (const l of log.split('\n')) {
-    if (l.startsWith('diff --git ')) { flush(); file = { path: diffPath(l), old: [], now: [], hunk: false }; continue; }
-    if (!file) continue;
-    if (l.startsWith('@@')) file.hunk = true;
-    else if (file.hunk && (l[0] === ' ' || l[0] === '-')) file.old.push(l.slice(1));
-    if (file.hunk && (l[0] === ' ' || l[0] === '+')) file.now.push(l.slice(1));
-  }
-  flush();
-  return used;
-}
-
-// The path of a `diff --git` header under --no-renames, whose two sides name
-// one path: `a/P b/P`, or each side C-quoted by git when P has bytes it quotes.
-function diffPath(header) {
-  const rest = header.slice('diff --git '.length);
-  if (rest[0] !== '"') return rest.length % 2 ? rest.slice(2, 2 + (rest.length - 5) / 2) : null;
-  const bytes = [];
-  const ESC = { a: 7, b: 8, t: 9, n: 10, v: 11, f: 12, r: 13, '"': 34, '\\': 92 };
-  for (let i = 1; i < rest.length && rest[i] !== '"'; i++) {
-    // A character git leaves as it is, whole: one outside the BMP is two code units.
-    if (rest[i] !== '\\') { const c = String.fromCodePoint(rest.codePointAt(i)); bytes.push(...Buffer.from(c)); i += c.length - 1; }
-    else if (/[0-7]/.test(rest[i + 1])) { bytes.push(parseInt(rest.slice(i + 1, i + 4), 8)); i += 3; }
-    else bytes.push(ESC[rest[++i]] ?? rest.charCodeAt(i));
-  }
-  const path = Buffer.from(bytes).toString('utf8');
-  return path.startsWith('a/') ? path.slice(2) : null;
-}
-
-// The next ID for `prefix`: one more than the highest n of any `[PREFIX-n` in `used` ([SPC-3]).
-export const nextId = (used, prefix) => `${prefix}-${Math.max(0, ...[...used.keys()].filter((id) => id.split('-')[0] === prefix).map((id) => Number(id.split('-')[1].split('.')[0]))) + 1}`;
-
-function addIds({ top, cwd, opts }) {
-  if (opts.at !== undefined) throw new Fail('--add-ids writes the working tree; it does not take --at', 'al spec --add-ids <file> --prefix <PREFIX>');
-  if (opts.prefix === undefined || !PREFIX.test(opts.prefix)) {
-    throw new Fail(`--prefix ${JSON.stringify(opts.prefix ?? '')}: give capital letters and digits, starting with a letter, e.g. INV`,
-      'al spec --add-ids <file> --prefix <PREFIX>');
-  }
-  const tree = openTree(top);
-  const root = rootOf(top, tree, opts.at);
-  const path = relative(top, resolve(cwd, opts['add-ids']));
-  if (!path.endsWith('.md') || !path.startsWith(`${root}/`) || !existsSync(join(top, path)) || !noSymlinkOn(top, path)) {
-    throw new Fail(`${opts['add-ids']}: give a .md file under the baseline root ${root}/, not through a symlink`, `al spec --list shows the files under ${root}/`);
-  }
-  const gap = historyGap(top);
-  if (gap) throw gapFail(gap, ", and IDs can't be allocated safely without the full history");
-
-  const before = readFileSync(join(top, path), 'utf8');
-  const first = Number(nextId(idsUsed(top, tree, root), opts.prefix).split('-')[1]);
-  const { text, numbered } = numberHeadings(before, opts.prefix, first);
-  const body = duplicates(baseline(tree, root));
-  const notKnown = ['IDs used on branches that were never fetched here'];
-  if (!numbered.length) {
-    body.unshift(`${path}: every heading already has an ID; nothing to number`);
-    return { body, next: `al spec --list`, notKnown };
-  }
-  if (opts.yes) writeFileSync(join(top, path), text);
-  body.unshift(`${opts.yes ? 'Numbered' : 'Would number'} ${numbered.length} heading(s) in ${path}:`, ...numbered.map((h) => `  ${h}`));
-  return { body, next: opts.yes ? `review the diff of ${path} and commit it` : 'run the same command with --yes to write it', notKnown };
-}

package/src/states.js

@@ -1,227 +0,0 @@
-// The change spec ([SPC-5]) and the state of each held section: the link
-// first ([STA-1]), then the content ([STA-2]), and whether a block retains
-// nothing, shown positively ([STA-3]).
-import { openTree, requestDirs } from './tree.js';
-import { ID_TEXT, TITLES, closes, headingAt, parseSections, sameSection } from './sections.js';
-import { rootOf, baseline } from './spec.js';
-import { isDropped } from './signoff.js';
-
-const HEAD = new RegExp(`^### \\[(${ID_TEXT})\\]@(\\d+)\\s*(.*)$`);
-const FENCE = /^ {0,3}(`{3,}|~{3,})/;
-
-// The Was: or Now: text after a label: a fenced block, or the indented lines
-// (blank lines inside kept), with the indent removed.
-export function takeText(lines, i) {
-  while (i < lines.length && !lines[i].trim()) i++;
-  const f = lines[i]?.match(FENCE);
-  if (f) {
-    const out = [];
-    for (i++; i < lines.length && !closes(lines[i], f[1]); i++) out.push(lines[i]);
-    return { text: out.join('\n') + '\n', next: i + 1 };
-  }
-  const out = [];
-  for (; i < lines.length && (!lines[i].trim() || /^( {4}|\t)/.test(lines[i])); i++) out.push(lines[i].replace(/^( {4}|\t)/, ''));
-  while (out.length && !out.at(-1).trim()) out.pop();
-  return { text: out.length ? out.join('\n') + '\n' : null, next: i };
-}
-
-// The blocks of one change.md, each `<request>/<ID>@<n>`.
-export function parseChange(text, request) {
-  const lines = text.replace(/\r\n/g, '\n').split('\n');
-  const start = headingAt(lines, TITLES.specChanges);
-  const blocks = [];
-  let b = null;
-  for (let i = start + 1; start >= 0 && i < lines.length;) {
-    const line = lines[i];
-    const h = line.match(HEAD);
-    if (h) {
-      const [, id, n, rest] = h;
-      const on = rest.match(/builds on (\S+)/)?.[1];
-      const marker = (name) => rest.match(new RegExp(`${name} (\\S+) \\((D\\d+)\\)`))?.slice(1, 3) ?? null;
-      b = {
-        request, id, n: Number(n), key: `${request}/${id}@${n}`,
-        // [SPC-5]'s ops, the whole token matched; any other is a fault (blockFault), never a remove.
-        op: OPS.get(rest.split(/\s+/)[0]) ?? null,
-        opWord: rest.split(/\s+/)[0] ?? '',
-        path: rest.match(/^add in (\S+)/)?.[1] ?? null,
-        anchor: rest.match(/^(?:add after|remove, was after) \[([^\]]+)\]/)?.[1] ?? null,
-        // A remove of a file's first section records the file instead ([SPC-5]).
-        firstIn: rest.match(/^remove, was first in (\S+)/)?.[1] ?? null,
-        base: on ? (on.startsWith('@') ? `${request}/${id}${on}` : on) : Number(n) > 1 ? `${request}/${id}@${Number(n) - 1}` : null,
-        dropped: marker('Dropped'), kept: marker('Kept'), revised: marker('Revised'),
-        forR: rest.match(/for (R\d+(?:,\s*R\d+)*)/)?.[1].split(/,\s*/) ?? [],
-        was: null, now: null,
-      };
-      blocks.push(b);
-      i++;
-    } else if (b && /^(Was|Now):\s*$/.test(line.trim())) {
-      const { text: t, next } = takeText(lines, i + 1);
-      b[line.trim().startsWith('Was') ? 'was' : 'now'] = t;
-      i = next;
-    } else if (/^##?\s/.test(line)) {
-      break;
-    } else {
-      i++;
-    }
-  }
-  return blocks;
-}
-
-// The states in which a block's work is in the baseline: consolidate leaves it
-// alone, and conclude holds it ([STA-2], [STA-7]).
-export const CONSOLIDATED = ['consolidated', 'carried'];
-
-// A state as the views say it: `waiting on <block>`, `carried by <block>`.
-export const stateText = (e, by = e.by) => `${e.state}${by ? ` ${e.state === 'waiting' ? 'on' : 'by'} ${by}` : ''}`;
-
-const same = (a, b) => a != null && b != null && sameSection(a, b);
-// A section's body: the lines under its heading, trailing spaces and blank edge lines
-// dropped ([SPC-4]); indentation is kept.
-const body = (text) => text.replace(/\r\n/g, '\n').split('\n').slice(1).map((l) => l.replace(/[ \t]+$/, '')).join('\n').replace(/^\n+|\n+$/g, '');
-
-// Every block of every request (archived ones too, for chains), with the
-// request's status.
-export function allBlocks(tree) {
-  const blocks = new Map();
-  for (const { dir, name, open } of requestDirs(tree)) {
-    const text = tree.read(`${dir}/change.md`)?.toString('utf8');
-    if (!text) continue;
-    const md = tree.read(`${dir}/request.md`)?.toString('utf8') ?? '';
-    const dropped = isDropped(md);
-    // A repeated request/ID@n is a fault (blockFault); the first is kept, and says so.
-    for (const b of withRepeats(parseChange(text, name))) blocks.set(b.key, { ...b, open, requestDropped: dropped });
-  }
-  return blocks;
-}
-
-// [SPC-5]: why a block can't be read as written, or null: its request/ID@n
-// repeated, an op outside the grammar, a remove with no anchor, or Was:/Now:
-// against its op. check says so; consolidate and conclude refuse.
-export function blockFault(b) {
-  if (b.repeated) return `${b.key} appears ${b.repeated} times in change.md; each version of a section is one block ([SPC-5])`;
-  if (!b.op) return `${b.key}: "${b.opWord}" is not an op; use modify, add in <path>, add after [ID], remove, was after [ID], or remove, was first in <path> ([SPC-5])`;
-  if (b.op === 'add' && !b.path && !b.anchor) return `${b.key}: an add names neither "in <path>" nor "after [ID]" ([SPC-5])`;
-  if (b.op === 'remove' && !b.anchor && !b.firstIn) return `${b.key}: a remove names neither "was after [ID]" nor "was first in <path>" ([SPC-5])`;
-  if (b.op === 'add' && (b.was !== null || b.now === null)) return `${b.key}: an add has a Now: and no Was: ([SPC-5])`;
-  if (b.op === 'remove' && (b.now !== null || b.was === null)) return `${b.key}: a remove has a Was: and no Now: ([SPC-5])`;
-  if (b.op === 'modify' && (b.was === null || b.now === null)) return `${b.key}: a modify has both Was: and Now: ([SPC-5])`;
-  return null;
-}
-
-// [STA-4]: why a remove's `was after [X]` doesn't hold in `file` (the file
-// holding its section, { path, sections }), or null. [X] must be the nearest
-// section before it at its own level, or, for a first sub-section, its
-// parent: where a revert puts it back. The revert reads which of the two from
-// the Was's depth, so that depth must be on the same side of [X]'s as the
-// section's own ([SPC-4] lets the two differ).
-export function anchorFault(b, file) {
-  const i = file.sections.findIndex((s) => s.id === b.id);
-  if (i < 0) return null;
-  const name = (s) => (s.id ? `[${s.id}]` : `"${s.title}"`);
-  const level = file.sections[i].level;
-  const side = (s) => {
-    const was = b.was === null ? null : parseSections(b.was)[0];
-    if (!was || (was.level > s.level) === (level > s.level)) return null;
-    return `[${b.id}] is ${'#'.repeat(level)} in ${file.path} but its Was is headed ${'#'.repeat(was.level)}, so a revert would not put it back ${level > s.level ? 'first under' : 'after'} ${name(s)}; head the Was ${'#'.repeat(level)}`;
-  };
-  for (let j = i - 1; j >= 0; j--) {
-    const s = file.sections[j];
-    if (s.level < level) return s.id === b.anchor ? side(s) : `[${b.id}] is the first under ${name(s)}, not after [${b.anchor}], as its remove says`;
-    if (s.level === level) return s.id === b.anchor ? side(s) : `[${b.id}] stands after ${name(s)}, not [${b.anchor}], as its remove says`;
-  }
-  return `[${b.id}] is the first section of ${file.path}; write "remove, was first in ${file.path}"`;
-}
-
-// The op tokens of [SPC-5]: `modify`, `add in|after …`, `remove, was after …`.
-// A Map, so no name an object inherits (constructor, toString…) reads as one.
-const OPS = new Map([['modify', 'modify'], ['add', 'add'], ['remove,', 'remove'], ['remove', 'remove']]);
-
-// Blocks with a repeated request/ID@n marked `repeated`, the first kept ([SPC-5]).
-export function withRepeats(list) {
-  const seen = new Map();
-  for (const b of list) {
-    if (seen.has(b.key)) seen.get(b.key).repeated = (seen.get(b.key).repeated ?? 1) + 1;
-    else seen.set(b.key, b);
-  }
-  return [...seen.values()];
-}
-
-// [STA-1]: the link of a block that builds on another, checked first.
-function linkState(b, blocks) {
-  if (!b.base) return null;
-  const x = blocks.get(b.base);
-  if (!x) return 'broken link';
-  const seen = new Set([b.key]);
-  for (let cur = b; cur?.base; cur = blocks.get(cur.base)) {
-    if (seen.has(cur.base)) return 'broken link';
-    seen.add(cur.base);
-  }
-  if (!(b.was === null && x.now === null) && !same(b.was, x.now)) return 'broken link';
-  if ((x.dropped || x.requestDropped) && !x.kept) return 'base dropped';
-  if (x.revised && x.request !== b.request) return 'base revised';
-  return null;
-}
-
-// [STA-2]: the state of every open block, and [STA-3]: whether it retains nothing.
-export function changeStates(top, { at } = {}) {
-  const tree = openTree(top, at);
-  return statesOf(baseline(tree, rootOf(top, tree, at)), allBlocks(tree));
-}
-
-// The states of the blocks `include` picks (the open ones by default), read
-// against `files`: the baseline's files, each with its sections.
-export function statesOf(files, blocks, include = (b) => b.open) {
-  const sections = files.flatMap((f) => f.sections);
-  const byId = new Map();
-  const fileOf = new Map();
-  for (const f of files) {
-    for (const s of f.sections) if (s.id && !byId.has(s.id)) { byId.set(s.id, s.text); fileOf.set(s.id, f.path); }
-  }
-  const links = new Map([...blocks.values()].map((b) => [b.key, linkState(b, blocks)]));
-  const valid = (b) => b.base && links.get(b.key) === null;
-  // Blocks this one reaches upwards through valid links, nearest first.
-  const upward = (b) => {
-    const out = [];
-    for (let cur = b; valid(cur) && !out.includes(cur.base); cur = blocks.get(cur.base)) out.push(cur.base);
-    return out.map((k) => blocks.get(k));
-  };
-
-  // The file an add goes to: its own path, its anchor's file, or, for an
-  // anchor its request adds too, where that add goes; for a remove of a
-  // file's first section, that file.
-  const addedIn = (b, n = 0) => {
-    const anchor = [...blocks.values()].find((x) => x.request === b.request && x.id === b.anchor && x.op === 'add');
-    return b.path ?? b.firstIn ?? fileOf.get(b.anchor) ?? (anchor && n < 50 ? addedIn(anchor, n + 1) : null);
-  };
-  const result = [];
-  for (const b of blocks.values()) {
-    if (!include(b)) continue;
-    const base = byId.get(b.id);
-    const atWas = b.op === 'add' ? base === undefined : same(base, b.was);
-    const entry = (state, by = null, candidates = []) => ({
-      request: b.request, id: b.id, n: b.n, block: b.key, op: b.op, state, by, candidates, forR: b.forR,
-      mark: b.kept ? 'kept' : b.dropped ? 'dropped' : null, // the block's marker, for the views ([VW-2])
-      file: fileOf.get(b.id) ?? addedIn(b),
-      retainsNothing: same(b.was, b.now) || atWas || state === 'waiting',
-    });
-    const link = links.get(b.key);
-    if (link) { result.push(entry(link)); continue; }
-    if (same(b.was, b.now)) { result.push(entry('no change yet')); continue; }
-    if (b.op === 'remove' ? base === undefined : same(base, b.now)) { result.push(entry('consolidated')); continue; }
-    // [STA-2] row 3: a successor of the same section whose "now" is in the
-    // baseline; for a remove, as in row 2, the ID is absent.
-    const carriers = [...blocks.values()].filter((d) => d.key !== b.key && d.id === b.id && upward(d).includes(b)
-      && (d.op === 'remove' ? base === undefined : same(base, d.now)));
-    if (carriers.length) { result.push({ ...entry('carried', carriers[0].key), carriers: carriers.map((d) => d.key) }); continue; }
-    const waitOn = upward(b).find((u) => (u.op === 'add' ? base === undefined : same(base, u.was)));
-    if (waitOn) { result.push(entry('waiting', waitOn.key)); continue; }
-    if (atWas) { result.push(entry('pending')); continue; }
-    if (base === undefined) {
-      const bodies = [b.now, b.was].filter(Boolean).map(body);
-      result.push(entry('not found', null, sections.filter((s) => s.id && bodies.includes(body(s.text))).map((s) => s.id)));
-      continue;
-    }
-    result.push(entry('differs'));
-  }
-  return result;
-}