@assuredloop/cli 0.1.0 → 0.2.0

package/src/v4/conclude.js

@@ -0,0 +1,119 @@
+// al conclude <name> [--yes] (T11; design.md 5 The close rule, 6, 8): the
+// only command that refuses. It reads the working tree, the closing PR's
+// 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. With
+// --yes it writes the Outcome, sets the status and archives the request.
+import { mkdirSync, renameSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { Fail, day, exists, guard, isName, now, write } from './base.js';
+import { judgeRequest } from './dispositions.js';
+import { git } from './git.js';
+import { openRecord, recordText } from './records.js';
+import { isPromise, loadState, qualify, servesSigned } from './state.js';
+import { signState } from './views.js';
+
+const NOT_KNOWN = ['whether the code, tests and documents do what the paragraphs say',
+  'whether the work has ended: the tool does not take a merged task or a reconciled spec as evidence of that'];
+
+// The reasons the close rule refuses, each naming its IDs; [] when it holds.
+function reasons(state, r) {
+  const out = [];
+  if (r.spike) {
+    if (!r.reqs.length) out.push(`the spike has no organized question to sign in ${r.dir}/request.md`);
+    const unsigned = r.reqs.filter((q) => !signState(state, r, q).startsWith('signed'));
+    if (unsigned.length) out.push(`the spike's current question is not signed: ${unsigned.map((q) => `${r.name}/${q.id} (${signState(state, r, q)})`).join(', ')}`);
+    return { out, judged: [] };
+  }
+  const judged = judgeRequest(state, r);
+  // A paragraph abandoned with no kept effect needs no sign-off (design.md 6);
+  // one whose effect an owner decision keeps is judged with its sign-off in judge().
+  const dropped = new Set(judged.filter((j) => j.status === 'abandoned' && j.valid && j.kept === false).map((j) => j.p.id));
+  const unsigned = [
+    ...[...r.paras.values()].filter((p) => isPromise(state, p.kind) && !dropped.has(p.id) && !servesSigned(state, p, r.name)).map((p) => `${r.name}/${p.id}`),
+    ...[...state.spec.values()].filter((p) => isPromise(state, p.kind) && p.links.serves.some((s) => qualify(s, null).req === r.name)
+      && !servesSigned(state, p, null)).map((p) => p.id),
+  ];
+  if (unsigned.length) out.push(`a promise change with no signed requirement that covers it: ${unsigned.join(', ')}`);
+  const open = judged.filter((j) => j.status === 'pending' || !j.valid);
+  if (open.length) {
+    out.push(`no valid disposition for the current version of ${open.map((j) => `${j.id} (${j.status === 'pending' ? 'none' : `${j.status}, not valid: ${j.reason}`})`).join(', ')}`);
+  }
+  return { out, judged };
+}
+
+// The Outcome block: what became of each requirement, with the evidence and
+// what is unknown.
+function outcome(state, r, judged, top) {
+  const head = git(top, ['rev-parse', '--short=7', 'HEAD'], { allowFail: true });
+  const lines = ['## Outcome', '', `Concluded ${day(now())} with al conclude, on the working tree${head ? ` at ${head}` : ''}.`, ''];
+  const shown = (j) => `  - ${j.p.id} ${j.p.kind}: ${j.status}${j.d?.spec ? `${j.status === 'incorporated' ? ' as' : ''} ${j.d.spec}` : ''}${j.d?.by ? ` by ${j.d.by}` : ''}${j.reason ? ` (${j.reason})` : ''}`;
+  const placed = new Set();
+  for (const q of r.reqs) {
+    const version = (Array.isArray(r.data?.requirements) ? r.data.requirements : []).filter((v) => v?.id === q.id && v.sha256 === q.sha256).at(-1)?.version;
+    const v = version ? `version ${version}` : 'version not indexed';
+    if (r.spike) {
+      lines.push(`- ${q.id} ${q.title}, ${v}, ${signState(state, r, q)}: the answer answers ${q.id} ${v}.`);
+      continue;
+    }
+    lines.push(`- ${q.id} ${q.title}, ${v}, ${signState(state, r, q)}:`);
+    const mine = judged.filter((j) => j.p.links.serves.some((s) => qualify(s, r.name).key === `${r.name}/${q.id}`));
+    for (const j of mine) { lines.push(shown(j)); placed.add(j.id); }
+    // A path-1 promise is served by the spec paragraph itself (design.md 5).
+    const inSpec = [...state.spec.values()].filter((p) => p.links.serves.some((s) => qualify(s, null).key === `${r.name}/${q.id}`));
+    for (const p of inSpec) lines.push(`  - ${p.id} ${p.kind ?? '-'}: in ${p.file}, serves it`);
+    if (!mine.length && !inSpec.length) lines.push('  - no change paragraph and no spec paragraph serves it');
+  }
+  const rest = judged.filter((j) => !placed.has(j.id));
+  if (rest.length) lines.push('- Other paragraphs with a baseline effect:', ...rest.map(shown));
+  lines.push(`- Not known: ${NOT_KNOWN.join('; ')}.`, '');
+  return lines;
+}
+
+const withStatus = (md) => (/\bStatus:\s*\S+/.test(md) ? md.replace(/\bStatus:\s*\S+/, 'Status: concluded')
+  : md.replace(/^(.*\n)/, '$1Status: concluded\n'));
+
+function withOutcome(md, block) {
+  const lines = md.replace(/\r\n?/g, '\n').replace(/\n*$/, '\n').split('\n');
+  const at = lines.findIndex((l) => /^##\s+Outcome\s*$/.test(l));
+  if (at < 0) return `${lines.join('\n').replace(/\n*$/, '\n')}\n${block.join('\n')}`;
+  let end = lines.findIndex((l, i) => i > at && /^#{1,2}\s/.test(l));
+  if (end < 0) end = lines.length;
+  return [...lines.slice(0, at), ...block, ...lines.slice(end)].join('\n').replace(/\n*$/, '\n');
+}
+
+export function conclude({ top, args, opts }) {
+  const [name] = args;
+  if (!isName(name)) throw new Fail(`${JSON.stringify(name ?? '')} is not a request name`, 'al conclude <name> [--yes]');
+  const state = loadState(top);
+  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 { out, judged } = reasons(state, r);
+  if (out.length) {
+    return {
+      body: out.map((x) => `refused: ${x}`),
+      read: 'working tree',
+      next: `al context ${name}; sign, record the dispositions, or align what is named, then al index`,
+      notKnown: NOT_KNOWN,
+      exit: 1,
+    };
+  }
+  const block = outcome(state, r, judged, top);
+  const target = `requests/archive/${name}`;
+  if (exists(top, target)) throw new Fail(`${target} already exists; a request name is never reused`, `al context ${name}`);
+  const what = `Status: concluded, the Outcome in ${target}/request.md, status: concluded in the record, and ${r.dir}/ moved to ${target}/`;
+  if (!opts.yes) {
+    return { body: [`Would conclude ${name}: ${what}`, ...block.slice(2).map((l) => `  ${l}`)], read: 'working tree', next: 'run the same command with --yes to do it', notKnown: NOT_KNOWN };
+  }
+  const rec = openRecord(top, name);
+  if (!rec) throw new Fail(`${name} has no record .assuredloop/records/requests/${name}.yaml`, 'a v4 request is made with al new');
+  guard(top, [`${r.dir}/request.md`, `${target}/request.md`, rec.path]);
+  const md = withOutcome(withStatus(r.md), block);
+  rec.doc.set('status', 'concluded');
+  mkdirSync(dirname(join(top, target)), { recursive: true });
+  renameSync(join(top, r.dir), join(top, target));
+  write(top, `${target}/request.md`, md);
+  write(top, rec.path, recordText(rec));
+  return { body: [`Concluded ${name}: ${what}`], read: 'working tree', next: 'commit the archive move with the closing PR', notKnown: NOT_KNOWN };
+}

package/src/v4/config.js

@@ -0,0 +1,75 @@
+// v4 settings (design.md 2, schema.md 7): `.assuredloop/config.yaml` (the spec
+// root, the docs and their ID prefixes) and `.assuredloop/schema.yaml` (the
+// kinds, with a version). Both are optional: an absent file gives the defaults.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isSeq, parse, parseDocument } from 'yaml';
+import { KINDS, LINK_WORDS } from './markers.js';
+import { symlinkOn } from './scope.js';
+
+export const SCHEMA_VERSION = 'assuredloop/1';
+const DIR = '.assuredloop';
+
+function read(top, name) {
+  const link = symlinkOn(top, `${DIR}/${name}`);
+  if (link) throw new Error(`${DIR}/${name} is reached through the symlink ${link}; nothing was read`);
+  const path = join(top, DIR, name);
+  if (!existsSync(path)) return null;
+  try {
+    return parse(readFileSync(path, 'utf8')) ?? {};
+  } catch (e) {
+    throw new Error(`${DIR}/${name}: not valid YAML: ${e.message.split('\n')[0]}`);
+  }
+}
+
+export function loadConfig(top) {
+  const c = read(top, 'config.yaml') ?? {};
+  if (typeof c !== 'object' || Array.isArray(c)) throw new Error(`${DIR}/config.yaml: give a mapping of settings`);
+  return { ...c, root: c.root ?? 'specs', docs: Array.isArray(c.docs) ? c.docs : [] };
+}
+
+export function loadSchema(top) {
+  const s = read(top, 'schema.yaml') ?? {};
+  if (typeof s !== 'object' || Array.isArray(s)) throw new Error(`${DIR}/schema.yaml: give a mapping`);
+  return { ...s, schema: s.schema ?? SCHEMA_VERSION, kinds: s.kinds ?? KINDS };
+}
+
+const SCHEMA_TEXT = `# The AssuredLoop model (design.md 3, schema.md 4 and 6), with a version.
+schema: ${SCHEMA_VERSION}
+kinds:
+${Object.entries(KINDS).map(([g, ks]) => `  ${g}: [${ks.join(', ')}]`).join('\n')}
+# The link words a marker may hold.
+links: [${Object.keys(LINK_WORDS).join(', ')}]
+`;
+
+// Writes schema.yaml and config.yaml when absent, and lists `file` with its
+// prefix in config's docs when `prefix` is given and the file is not listed.
+// Comments in an existing config.yaml stay. Returns the paths written.
+export function writeSetup(top, file, prefix) {
+  const written = [];
+  mkdirSync(join(top, DIR), { recursive: true });
+  if (!existsSync(join(top, DIR, 'schema.yaml'))) {
+    writeFileSync(join(top, DIR, 'schema.yaml'), SCHEMA_TEXT);
+    written.push(`${DIR}/schema.yaml`);
+  }
+  const path = join(top, DIR, 'config.yaml');
+  const had = existsSync(path);
+  const doc = parseDocument(had ? readFileSync(path, 'utf8') : `# AssuredLoop settings (design.md 2, schema.md 7).\nschema: ${SCHEMA_VERSION}\nroot: specs\ndocs: []\n`);
+  const docs = doc.get('docs');
+  const listed = docs?.items?.some((d) => d.get?.('file') === file);
+  if (prefix && !listed) {
+    const entry = doc.createNode({ file, prefix });
+    entry.flow = true;
+    if (isSeq(docs)) {
+      docs.flow = false;
+      docs.add(entry);
+    } else {
+      doc.set('docs', doc.createNode([entry]));
+    }
+  }
+  if (!had || (prefix && !listed)) {
+    writeFileSync(path, doc.toString());
+    written.push(`${DIR}/config.yaml`);
+  }
+  return written;
+}

package/src/v4/dispositions.js

@@ -0,0 +1,191 @@
+// Dispositions and the close rule (design.md 5; the architect's answers for
+// #179, decision D15): for each change paragraph with a baseline effect, the
+// disposition of its current version, and whether that disposition is valid
+// in the given state. Read by al check, al context and al conclude.
+import { git } from './git.js';
+import { parseMarkdown } from './markers.js';
+import { SPEC, docsInScope } from './scope.js';
+import { closeness, NEAR } from './words.js';
+import { hasBaselineEffect, isPromise, qualify, servesSigned, settingsAt } from './state.js';
+
+const list = (x) => (Array.isArray(x) ? x : []);
+
+// The disposition of `source` (<request>/SP-n) for the version with hash
+// `sha`: the last entry for that version; an entry whose hash is not filled
+// yet (not indexed) stands for the current version.
+function dispositionOf(data, source, sha) {
+  const mine = list(data?.dispositions).filter((d) => d?.source === source);
+  return mine.filter((d) => d.source_sha256 === sha).at(-1) ?? mine.filter((d) => !d.source_sha256).at(-1) ?? null;
+}
+
+// The binding of `holder` `link` `target` in a record's data, or null.
+const bindingOf = (data, holder, link, target) => list(data?.bindings)
+  .find((b) => b?.holder === holder && b.link === link && b.target === target) ?? null;
+
+// Whether disposition `d` of source paragraph `p` (request `r`) is valid.
+// Returns { valid, reason, notes }. `seen` guards a supersession chain.
+export function judge(state, r, p, d, opts = {}, seen = new Set()) {
+  const source = `${r.name}/${p.id}`;
+  const notes = [];
+  const no = (reason) => ({ valid: false, reason, notes });
+  const yes = (reason = null) => ({ valid: true, reason, notes });
+  const decision = (id) => list(r.data?.decisions).find((x) => x?.id === id) ?? null;
+  const spec = (id) => state.spec.get(id) ?? null;
+
+  switch (d.disposition) {
+    case 'incorporated': {
+      const s = spec(d.spec);
+      if (!d.spec) return no('it names no spec paragraph');
+      if (!s) return no(`${d.spec} is not in specs/`);
+      if (d.spec_sha256 && s.sha256 !== d.spec_sha256) return no(`${d.spec} changed after it was incorporated`);
+      if (s.sha256 === p.sha256) return yes();
+      if (d.decision) {
+        const w = decision(d.decision)?.wording;
+        if (!w) return no(`${d.decision} is not a wording decision in the record`);
+        if (w.source_sha256 !== p.sha256 || w.target_sha256 !== s.sha256) return no(`${d.decision} names other versions of ${p.id} and ${d.spec}`);
+        return yes(`worded by ${d.decision}`);
+      }
+      if (opts.typo?.has(d.spec) && opts.baseSpec?.get(d.spec)?.sha256 === d.spec_sha256) {
+        notes.push(`a typo claim on this branch changes ${d.spec}; a claim, not proven`);
+        return yes('a typo claim');
+      }
+      return no(`${d.spec} does not equal ${p.id} (no wording decision, no typo claim)`);
+    }
+    case 'removed': {
+      const id = d.spec ?? p.links.removes[0];
+      if (!id) return no('it names no spec paragraph');
+      if (!p.links.removes.includes(id)) return no(`${p.id} does not declare removes:${id}`);
+      if (spec(id)) return no(`${id} is still in specs/`);
+      const wasKind = opts.baseSpec?.get(id)?.kind ?? pastKind(state, id);
+      if ((isPromise(state, p.kind) || isPromise(state, wasKind)) && !servesSigned(state, p, r.name)) {
+        return no(`${id} is a promise, and no signed requirement covers its removal`);
+      }
+      return yes();
+    }
+    case 'superseded': {
+      if (!d.by) return no('it names no later change (by:)');
+      const by = qualify(String(d.by), r.name);
+      const rb = state.requests.get(by.req);
+      if (!rb) return no(`${d.by}: no such request`);
+      // The incorporated version: on this entry, or on the earlier incorporated entry it replaced.
+      const was = d.spec_sha256 ?? list(r.data?.dispositions).filter((x) => x?.source === source && x.disposition === 'incorporated'
+        && x.spec === d.spec && x.source_sha256 === p.sha256).at(-1)?.spec_sha256;
+      const b = bindingOf(rb.data, d.by, 'changes', d.spec) ?? bindingOf(rb.data, d.by, 'removes', d.spec);
+      if (!b || !was || b.target_sha256 !== was) return no(`${d.by} has no changes or removes binding to the incorporated version of ${d.spec}`);
+      if (seen.has(source)) return no('the supersession chain goes round in a circle');
+      seen.add(source);
+      const pb = rb.paras.get(by.id);
+      if (!rb.open) {
+        // An archived change is never checked again: its record stands.
+        const ok = list(rb.data?.dispositions).some((x) => x?.source === d.by && ['incorporated', 'removed', 'superseded'].includes(x.disposition));
+        return ok ? yes(`by ${d.by}, archived`) : no(`${d.by} has no disposition in its archived record`);
+      }
+      if (!pb) return no(`${d.by} is not in its change spec`);
+      const db = dispositionOf(rb.data, d.by, pb.sha256);
+      if (!db || !['incorporated', 'removed', 'superseded'].includes(db.disposition)) return no(`${d.by} has no incorporated, removed or superseded disposition`);
+      const v = judge(state, rb, pb, db, opts, seen);
+      return v.valid ? yes(`by ${d.by}`) : no(`${d.by}: ${v.reason}`);
+    }
+    case 'abandoned': {
+      // First the facts of no kept effect (D15 rules a-c): then no sign-off is
+      // needed, whatever decision names the drop (design.md 6).
+      const effect = keptEffect(state, r, p, source);
+      if (!effect) {
+        if (d.decision && !decision(d.decision)) return no(`${d.decision} is not in the record`);
+        notes.push(...nearNotes(state, p));
+        return { valid: true, reason: d.decision ? `never applied, or reverted; dropped by ${d.decision}` : null, notes, kept: false };
+      }
+      // Its effect is still in specs/: only an owner decision can keep it, and
+      // a kept promise needs a signed requirement (D15 rule d, design.md 5).
+      if (!d.decision) return no(effect);
+      const x = decision(d.decision);
+      if (!x) return no(`${d.decision} is not in the record`);
+      if (!/^owner\b/i.test(String(x.source ?? ''))) return no(`${d.decision}'s source is not the owner, and ${effect}`);
+      if (isPromise(state, p.kind) && !servesSigned(state, p, r.name)) return no(`${d.decision} keeps a promise, and no signed requirement covers it`);
+      return { valid: true, reason: `its effect is kept by ${d.decision}`, notes, kept: true };
+    }
+    default:
+      return no(`"${d.disposition}" is not a disposition`);
+  }
+}
+
+// The kind that spec paragraph `id` had in the newest commit that held it,
+// from git history, or null. First the selected commit itself; then, newest
+// first, each commit whose diff adds or removes the marker (in any spacing
+// the parser allows, in any path) or changes .assuredloop/config.yaml (which
+// can bring a marked file into scope or take it out). Each commit, then its
+// parent, is read with that commit's own config and schema.
+export function pastKind(state, id) {
+  const top = state.top;
+  const rev = state.rev ?? 'HEAD';
+  const marker = `<!--[[:space:]][[:space:]]*${id}[[:space:]]`;
+  const list = (args) => (git(top, ['log', '--format=%H', ...args], { allowFail: true }) ?? '').split('\n').filter(Boolean);
+  const candidates = new Set([...list(['-G', marker, rev]), ...list([rev, '--', '.assuredloop/config.yaml'])]);
+  const ordered = (git(top, ['rev-list', rev], { allowFail: true }) ?? '').split('\n').filter((sha) => candidates.has(sha));
+  const kindAt = (at) => {
+    const { config, kinds } = settingsAt(top, at);
+    for (const d of docsInScope(top, config, at).filter((x) => x.scope === SPEC)) {
+      const p = parseMarkdown(d.text, d.path, { kinds }).paragraphs.find((x) => x.id === id);
+      if (p) return p.kind;
+    }
+    return undefined;
+  };
+  for (const at of [rev, ...ordered.flatMap((sha) => [sha, `${sha}^`])]) {
+    const kind = kindAt(at);
+    if (kind !== undefined) return kind;
+  }
+  return null;
+}
+
+// Why paragraph `p` (<request>/SP-n `source`) still has an effect in specs/,
+// or null when it has none: its changes or removes targets keep the text they
+// were bound to, and a paragraph with neither link has no copy in specs/.
+function keptEffect(state, r, p, source) {
+  const spec = (id) => state.spec.get(id) ?? null;
+  for (const id of p.links.changes) {
+    const b = bindingOf(r.data, source, 'changes', id);
+    if (!b) return `no changes binding to ${id}, so whether it was applied is unknown`;
+    if (spec(id)?.sha256 !== b.target_sha256) return `${id} is not the version that ${p.id} bound: applied, or changed since`;
+  }
+  for (const id of p.links.removes) {
+    const b = bindingOf(r.data, source, 'removes', id);
+    if (!b) return `no removes binding to ${id}, so whether it was applied is unknown`;
+    if (spec(id)?.sha256 !== b.target_sha256) return `${id} is gone or changed: the removal was applied`;
+  }
+  if (!p.links.changes.length && !p.links.removes.length) {
+    const same = [...state.spec.values()].find((s) => s.sha256 === p.sha256);
+    if (same) return `its text is in specs/ as ${same.id}`;
+  }
+  return null;
+}
+
+// A near match in specs/ for a paragraph with no changes or removes link.
+const nearNotes = (state, p) => {
+  if (p.links.changes.length || p.links.removes.length) return [];
+  const near = [...state.spec.values()].find((s) => s.kind !== 'note' && closeness(s.text, p.text) >= NEAR);
+  return near ? [`near-match ${near.id}: applied in another form?`] : [];
+};
+
+// Every change paragraph of request `r` with a baseline effect, with the
+// disposition of its current version and its validity. A spike has none.
+export function judgeRequest(state, r, opts = {}) {
+  if (r.spike) return [];
+  const out = [];
+  for (const p of r.paras.values()) {
+    if (!hasBaselineEffect(state, p.kind) && !p.links.removes.length) continue;
+    const id = `${r.name}/${p.id}`;
+    const d = dispositionOf(r.data, id, p.sha256);
+    if (!d) {
+      out.push({ id, p, d: null, status: 'pending', valid: false, reason: 'no disposition for its current version', notes: [] });
+      continue;
+    }
+    // An archived request is never checked again against today's spec (design.md 5).
+    if (!r.open) {
+      out.push({ id, p, d, status: String(d.disposition), valid: true, reason: 'as recorded at the close; not checked again', notes: [] });
+      continue;
+    }
+    const v = judge(state, r, p, d, opts);
+    out.push({ id, p, d, status: String(d.disposition), ...v });
+  }
+  return out;
+}