@assuredloop/cli 0.0.0-stage → 0.1.0

package/src/audit.js

@@ -0,0 +1,176 @@
+// --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

@@ -0,0 +1,127 @@
+// 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,
+  };
+}