@assuredloop/cli 2.0.0 → 3.0.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.0.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

@@ -178,18 +178,44 @@ const ADR_REF = /^ADR-(\d+)(?:-\d+)?$/;
 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';

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) {