@assuredloop/cli 2.0.0 → 3.1.0

package/README.md

@@ -228,6 +228,8 @@ ADRs that supersede it: `superseded by ADR-11, ADR-12` or
 - A current place that names a superseded ADR also names the ADR that
   supersedes it, in the same marker or the same paragraph. Current places
   are the spec docs, the open requests and the proposed and accepted ADRs.
+  The text names an ADR by `ADR-40`, by `ADR 0040`, or in a list or a range
+  such as `ADRs 0003, 0005 and 0040` or `ADRs 0003 to 0005`.
   The chain itself and dated records are exempt: an ADR that supersedes it,
   a superseded ADR, an ADR's `## History`, a request's `## Decisions`, the
   `origin/` files and the archived requests. Else `al check` gives

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/cli",
-  "version": "2.0.0",
+  "version": "3.1.0",
   "description": "AssuredLoop keeps an AI focused on one change: the al command gathers and checks a change's requirement, spec, decisions, code and tests.",
   "license": "MIT",
   "repository": {

package/src/v4/blocks.js

@@ -175,21 +175,47 @@ export const citedMessage = (c) => (c.next.length
 
 // The ADR that a link value or word names: `ADR-n` and `ADR-n-k` name ADR-n.
 const ADR_REF = /^ADR-(\d+)(?:-\d+)?$/;
-const adrOf = (ref) => (ADR_REF.test(ref) ? `ADR-${Number(ADR_REF.exec(ref)[1])}` : null);
+export const adrOf = (ref) => (ADR_REF.test(ref) ? `ADR-${Number(ADR_REF.exec(ref)[1])}` : null);
 const MARKER = /^\s*<!--(.*)-->\s*$/;
 
+// The words that name ADRs in a text (adr-lists R1): `ADR-n`, or the number
+// after `ADR` or `ADRs` and a space, and each item of a list or a range that
+// follows. An item is a number or `ADR-n`; a comma, `and` or both join a
+// list, and `to` a range. A range names its two ends and each ADR in `known`
+// (the numbers of the ADRs that exist) between them, so a long one costs
+// nothing; a reversed range names only its ends.
+const ITEM = String.raw`(?:ADR-\d+(?:-\d+)?|\d+)\b`;
+const NAMING = new RegExp(String.raw`\b(?:ADRs?\s+(?=\d)|(?=ADR-\d))${ITEM}(?:(?:\s*,\s*(?:and\s+)?|\s+(?:and|to)\s+)${ITEM})*`, 'g');
+function adrsNamed(text, known) {
+  const out = new Set();
+  for (const m of text.matchAll(NAMING)) {
+    let last = null;
+    let range = false;
+    for (const t of m[0].matchAll(/ADR-(\d+)(?:-\d+)?|\d+|\bto\b/g)) {
+      if (t[0] === 'to') { range = true; continue; }
+      const n = Number(t[1] ?? t[0]);
+      if (range && last < n) for (const k of known) if (k > last && k < n) out.add(`ADR-${k}`);
+      out.add(`ADR-${n}`);
+      last = n;
+      range = false;
+    }
+  }
+  return out;
+}
+
 // The places of a Markdown text: each marker line and each run of text lines,
 // with the ADRs it names and the ID of the marker it falls under. A heading
 // that `skip` matches starts a section that is not read, up to the next
 // heading of level 1 or 2.
-function places(textOf, skip) {
+function places(textOf, skip, known) {
   const lines = textOf.replace(/\r\n?/g, '\n').split('\n');
   const out = [];
   let id = null;
   let skipping = false;
   let run = null;
   const close = () => {
-    if (run && run.names.size) out.push(run);
+    const names = run ? adrsNamed(run.lines.join('\n'), known) : new Set();
+    if (names.size) out.push({ line: run.line, id: run.id, link: false, names });
     run = null;
   };
   lines.forEach((l, i) => {
@@ -204,8 +230,8 @@ function places(textOf, skip) {
       if (names.size) out.push({ line: i + 1, id, link: true, names });
       return;
     }
-    if (!run) run = { line: i + 1, id, link: false, names: new Set() };
-    for (const w of l.matchAll(/\bADR-(\d+)(?:-\d+)?\b/g)) run.names.add(`ADR-${Number(w[1])}`);
+    if (!run) run = { line: i + 1, id, lines: [] };
+    run.lines.push(l);
   });
   close();
   return out;
@@ -229,7 +255,8 @@ export function supersededIn(state) {
     return seen;
   };
   const superseded = (id) => state.adrs.get(id)?.status === 'superseded';
-  return (textOf, { skip = null, exempt = new Set() } = {}) => places(textOf, skip).flatMap((p) => [...p.names]
+  const known = [...state.adrs.keys()].map((id) => Number(id.slice('ADR-'.length)));
+  return (textOf, { skip = null, exempt = new Set() } = {}) => places(textOf, skip, known).flatMap((p) => [...p.names]
     .filter((x) => superseded(x) && !exempt.has(x) && ![...above(x)].some((y) => p.names.has(y)))
     .map((x) => ({ line: p.line, id: p.id, link: p.link, adr: x, next: up(x) })));
 }

package/src/v4/check.js

@@ -1,17 +1,17 @@
 // al check (design.md 3, What the script checks): the lints of every marker in
 // scope, and per scope the ID lints of the branch against its base (lost, used
 // again, one ID in two files), then each paragraph's change (T8); then the
-// checks that read records (T10, checks.js). The base is the merge-base of
-// HEAD with main; the head is the working tree. It exits 0; with --strict, 1
-// when it prints a `not ok`. A finding has the same severity in both modes:
-// the marker and ID lints are hints for the review, and only the exact rules
-// of checks.js are `not ok` (#238). With --issues <folder> it also checks the
+// checks that read records (T10, checks.js). The base is baseOf (git.js), the
+// merge-base of HEAD with main or origin/main; the head is the working tree.
+// It exits 0; with --strict, 1 when it prints a `not ok`. A finding has the
+// same severity in both modes: the marker and ID lints are hints for the
+// review, and only the exact rules of checks.js are `not ok` (#238). With --issues <folder> it also checks the
 // work items that the caller saved there (issue-hints R1).
 import { relative } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { read, recordPath } from './base.js';
 import { loadConfig, loadSchema } from './config.js';
-import { mergeBase } from './git.js';
+import { baseOf } from './git.js';
 import { diffParagraphs, idLints } from './ids.js';
 import { docsInScope, idsEverUsed, isShallow, notRead, parseScopes, rootNotOk, rootProblem, SPEC } from './scope.js';
 import { Fail } from './spec.js';
@@ -41,7 +41,8 @@ function checkAll({ top, cwd, opts }) {
   const phrases = loadPhrases(config);
   // The work items that the caller saved; a folder that is not there is a refusal.
   const issues = opts.issues === undefined ? null : loadItems(cwd ?? top, opts.issues);
-  const base = mergeBase(top);
+  const found = baseOf(top);
+  const base = found?.commit ?? null;
   const now = parseScopes(docsInScope(top, config), kinds);
   const was = base ? parseScopes(docsInScope(top, config, base), kinds) : null;
   const used = base ? idsEverUsed(top, config, base) : null;
@@ -85,7 +86,7 @@ function checkAll({ top, cwd, opts }) {
   else if (isShallow(top)) notKnown.unshift('IDs used before the shallow history begins');
   return {
     body,
-    read: base ? `working tree · base ${base.slice(0, 7)} (merge-base with main)` : 'working tree · no base',
+    read: base ? `working tree · base ${base.slice(0, 7)} (merge-base with ${found.ref})` : 'working tree · no base',
     next: nextStep([...(rootLine ? ['not ok'] : []), ...lints.map((l) => l.severity), ...t10.findings.map((f) => f.severity),
       ...central.body.map((l) => (/^not ok /.test(l) ? 'not ok' : /^hint /.test(l) ? 'hint' : 'info'))], lints.some((l) => l.code === 'no-id'),
       t10.findings.some((f) => f.code === 'unsigned-requirement')),

package/src/v4/checks.js

@@ -1,8 +1,9 @@
 // The checks that read records (T10; design.md 3-7 and 9, schema.md 5; the
 // architect's answers for #179, decision D15). Each finding is
 // { severity, code, file, line, id, message }: `not ok`, `hint` or `info`.
-// They compare the working tree with the base (the merge-base with main) and
-// read the records of the open requests. No AI, no network.
+// They compare the working tree with the base (baseOf in git.js: the
+// merge-base with main or origin/main) and read the records of the open
+// requests. No AI, no network.
 import { createHash } from 'node:crypto';
 import { parse as parseYaml } from 'yaml';
 import { read } from './base.js';
@@ -17,7 +18,7 @@ import {
 import { NEAR, closeness, diffWords, marks, requirementWords, sentencesOf, showHunk } from './words.js';
 import { groupOf, markerLines, onlyLinksAdded, sameBlocks } from './markers.js';
 import { canAlignTo, declaredNow, isCentral } from './indexer.js';
-import { recordBlocks, supersededBlocks } from './blocks.js';
+import { adrOf, recordBlocks, supersededBlocks } from './blocks.js';
 import { phraseFindings } from './phrases.js';
 import { issueHints } from './issues.js';
 
@@ -387,11 +388,22 @@ export function checks(top, { base, phrases = [], issues = null }) {
   // changed (#4) and the rest unchanged; that gives no finding.
   const linksAdded = (a, h) => a.status === 'accepted' && a.head && h.head && a.rest === h.rest
     && onlyLinksAdded(a.marker, h.marker, now.kinds);
+  // A status goes only forward: accepted to superseded, and a superseded-by
+  // list only gains ADRs (#31). Any other change of a known status line is a
+  // change of the ADR; an unknown one has its own hint, adr-status.
+  const statusBack = (a, h) => h.known
+    && !(h.status === 'superseded' ? a.by.every((b) => h.by.includes(b)) : h.status === a.status);
   for (const [id, a] of was?.adrs ?? []) {
     if (!['accepted', 'superseded'].includes(a.status)) continue;
     const h = now.adrs.get(id);
-    if (!h) add('hint', 'adr-changed', a.file, id, `${id} was ${a.status} and its file is gone: check that its decision is not lost; an ADR that no longer holds is superseded by a new ADR, not deleted`);
-    else if (h.body !== a.body && !linksAdded(a, h)) add('hint', 'adr-changed', h.head ?? h.file, id, `${id}'s text changed: check that its decision is unchanged; if the decision changed, write a new ADR that supersedes it`);
+    if (!h) {
+      add('hint', 'adr-changed', a.file, id, `${id} was ${a.status} and its file is gone: check that its decision is not lost; an ADR that no longer holds is superseded by a new ADR, not deleted`);
+      continue;
+    }
+    const back = statusBack(a, h);
+    const changed = h.body !== a.body && !linksAdded(a, h);
+    if (back) add('hint', 'adr-changed', h.head ?? h.file, id, `${id}'s status changed from "${a.line}" to "${h.line}"${changed ? ', and its text changed' : ''}, but a status goes only forward: proposed, accepted, superseded by ADR-n; check that its decision is unchanged; if the decision changed, write a new ADR that supersedes it`);
+    else if (changed) add('hint', 'adr-changed', h.head ?? h.file, id, `${id}'s text changed: check that its decision is unchanged; if the decision changed, write a new ADR that supersedes it`);
   }
   // Every ADR, whatever its status (#4): a first line that is not a known
   // status, and a marker line that holds more than its ID, a kind and links.
@@ -409,9 +421,13 @@ export function checks(top, { base, phrases = [], issues = null }) {
     if (missing.length) add('hint', 'adr-links', a.head ?? a.file, a.id, `${a.id} has ${missing.map((w) => `no ${w}:`).join(' and ')}; add the links to its marker`);
   }
   for (const a of now.adrs.values()) {
-    for (const old of a.head?.links.supersedes ?? []) {
+    // ADR-n-k, a paragraph of ADR-n, names ADR-n (schema.md 5), once each.
+    for (const old of new Set((a.head?.links.supersedes ?? []).map(adrOf).filter(Boolean))) {
       const o = now.adrs.get(old);
       if (o && o.status !== 'superseded') add('hint', 'adr-supersede', a.head, a.id, `${a.id} supersedes ${old}, whose status is ${o.status ?? 'missing'}; set it to superseded`);
+      // The other direction of superseded-status (#31): the status line of
+      // the superseded ADR names each ADR that supersedes it.
+      else if (o && !o.by.includes(a.id)) add('hint', 'adr-supersede', a.head, a.id, `${a.id} supersedes ${old}, but the status line of ${old} leaves out ${a.id}: write "Status: superseded by ${[...o.by, a.id].join(', ')}"`);
     }
   }
   for (const c of changes.filter((x) => !x.request)) {

package/src/v4/conclude.js

@@ -3,7 +3,7 @@
 // state, and refuses while a promise change has no signed requirement, a
 // spike's current question is not signed, or a change paragraph with a
 // baseline effect has no valid disposition for its current version. A promise
-// change of the branch, against the merge-base with main, counts as al check
+// change of the branch, against its base (baseOf), counts as al check
 // counts it (branchOf, #217). With
 // --yes it writes the Outcome, sets the status and archives the request.
 import { mkdirSync, renameSync, statSync } from 'node:fs';
@@ -11,7 +11,7 @@ import { dirname, join } from 'node:path';
 import { Fail, day, exists, guard, isName, now, write } from './base.js';
 import { branchOf } from './checks.js';
 import { judgeRequest } from './dispositions.js';
-import { git, mergeBase } from './git.js';
+import { baseOf, git } from './git.js';
 import { openRecord, recordText } from './records.js';
 import { isPromise, loadState, qualify, servesSigned } from './state.js';
 import { signState } from './views.js';
@@ -95,9 +95,10 @@ export function conclude({ top, args, opts }) {
   const r = state.requests.get(name);
   if (!r) throw new Fail(`no request named ${name}`, 'al context lists the open requests');
   if (!r.open) throw new Fail(`${name} is already archived (requests/archive/${name}); an archived request is not concluded again`, `al context ${name}`);
-  const base = mergeBase(top);
+  const found = baseOf(top);
+  const base = found?.commit ?? null;
   const branch = base ? branchOf(top, state, loadState(top, base), base).uncovered : [];
-  const read = base ? `working tree · base ${base.slice(0, 7)} (merge-base with main)` : 'working tree · no base';
+  const read = base ? `working tree · base ${base.slice(0, 7)} (merge-base with ${found.ref})` : 'working tree · no base';
   const notKnown = base ? NOT_KNOWN : ['the promise changes of the branch: no base (no main branch, or no commit)', ...NOT_KNOWN];
   const { out, judged } = reasons(state, r, branch);
   if (out.length) {

package/src/v4/git.js

@@ -12,15 +12,29 @@ export function git(top, args, { allowFail = false } = {}) {
   }
 }
 
-// The merge-base of HEAD with main (or origin/main), or null.
-export function mergeBase(top) {
-  for (const main of ['main', 'origin/main']) {
-    if (git(top, ['rev-parse', '--verify', '--quiet', `${main}^{commit}`], { allowFail: true }) === null) continue;
-    return git(top, ['merge-base', 'HEAD', main], { allowFail: true }) || null;
-  }
-  return null;
+// The base of the branch, { commit, ref }, or null: the merge-base of HEAD
+// with main or with origin/main, and the ref that gave it. With only one of
+// the two, that one. With both, the later merge-base (the other is its
+// ancestor), so a local main that is behind origin/main does not give an old
+// base; when neither is the later, the local main (#22). It reads only the
+// refs in the clone, and never fetches.
+export function baseOf(top) {
+  const refs = ['main', 'origin/main'].filter((ref) => git(top, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], { allowFail: true }) !== null);
+  const of = (ref) => {
+    const commit = git(top, ['merge-base', 'HEAD', ref], { allowFail: true });
+    return commit ? { commit, ref } : null;
+  };
+  if (!refs.length) return null;
+  const local = of(refs[0]);
+  if (refs.length === 1) return local;
+  const remote = of(refs[1]);
+  if (!local || !remote || local.commit === remote.commit) return local;
+  return git(top, ['merge-base', '--is-ancestor', local.commit, remote.commit], { allowFail: true }) === null ? local : remote;
 }
 
+// The base commit of the branch (baseOf), or null.
+export const mergeBase = (top) => baseOf(top)?.commit ?? null;
+
 // Git objects by name (a blob hash, or `<commit>:<path>`), read with one
 // `git cat-file --batch` process: Map name -> bytes for each name that is a
 // blob. A missing, ambiguous or other object is not in the Map. Every reader

package/src/v4/indexer.js

@@ -281,8 +281,9 @@ export function index({ top, opts }) {
   if (symlinkOn(top, `${root}/adr`)) notes.push(`not indexed: ${root}/adr: through a symlink`);
   const names = requestNames(top);
 
-  // The base: the merge-base with main; with no main, HEAD (so a committed
-  // link with no binding stays unknown); with no commit, nothing.
+  // The base: mergeBase (the merge-base with main or origin/main); with no
+  // main, HEAD (so a committed link with no binding stays unknown); with no
+  // commit, nothing.
   const main = mergeBase(top);
   const head = git(top, ['rev-parse', '--verify', '--quiet', 'HEAD'], { allowFail: true });
   const base = main ?? head ?? null;

package/src/v4/repos.js

@@ -289,7 +289,7 @@ export function crossRepo(top) {
   return { repos: repos.map(({ dir, ...r }) => r), links, results };
 }
 
-// In an output repo: the files that the branch changed (merge-base with main
+// In an output repo: the files that the branch changed (the base, mergeBase,
 // to the working tree, and untracked files not ignored), or with no base every
 // file; never under .assuredloop/.
 function changedFiles(top, base) {

package/src/v4/state.js

@@ -175,7 +175,9 @@ export function loadState(top, rev = null) {
     const by = [...new Set([...(s?.[2] ?? '').matchAll(/ADR-(\d+)/gi)].map((m) => `ADR-${Number(m[1])}`))];
     const known = Boolean(s) && !/[\r\n]/.test(s[1]);
     const marker = head && lf(text).split('\n')[head.line - 1];
-    adrs.set(id, { id, file, text, status, by, known, body: adrBody(text), rest: head && adrRest(text, head), paragraphs, head, marker });
+    // The words after `Status:`, for a hint that names a changed status (#31).
+    const line = /^\s*Status:[ \t]*([^\r\n]*)/i.exec(text)?.[1].trim() ?? null;
+    adrs.set(id, { id, file, text, status, by, known, line, body: adrBody(text), rest: head && adrRest(text, head), paragraphs, head, marker });
   }
   return { top, rev, config, kinds, root, get, docs, scopes, lints, spec, requests, adrs, unreadableAdrs };
 }