@sabaiway/agent-workflow-kit 10.0.0 → 10.2.0

package/tools/spec-coverage-cli.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// The CLI half of the coverage requirement: argv, fs and the debt record. No rule lives here (the
+// rule is spec-coverage.mjs), and the ratchet is enforced HERE because it is the only write.
+//
+// Exit codes: 0 accept; 1 refuse (an uncovered tool, or a settled debt entry still recorded); 2
+// usage — an unknown flag, a flag with no value, an unreadable scope or store, a reasonless write.
+
+import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { isDirectRun } from './direct-run.mjs';
+import { claimsOf, formatFindings, judgeCoverage, settleAfter } from './spec-coverage.mjs';
+
+export const SCOPE_PATH = join('docs', 'ai', 'spec-coverage.json');
+export const STORE_ROOT = join('docs', 'ai', 'specs');
+const REASON_MAX_BYTES = 300;
+
+const HELP = `spec-coverage — every shipped tool is governed by a contract, or the debt names it.
+
+Usage:
+  node spec-coverage-cli.mjs --report      [--root <dir>]
+  node spec-coverage-cli.mjs --check       [--root <dir>]
+  node spec-coverage-cli.mjs --write-debt --reason "<what was paid, and by which contract>" [--root <dir>]
+
+--report      one line per in-scope tool: the contract that covers it, or that none does.
+--check       refuses an in-scope tool no contract claims and is not recorded as debt, and a
+              recorded entry that is already settled — the record must not overstate the debt.
+--write-debt  records what was PAID: every adopted path whose contract now exists moves into the
+              settled set, and nothing else changes. It never touches the adoption baseline, so a
+              path outside it cannot be invented — it is refused by name. Write the contract first.
+
+Scope and debt: ${SCOPE_PATH}. Contracts: ${STORE_ROOT}. Exit codes: 0 accept; 1 refuse; 2 usage.`;
+
+const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
+const posix = (p) => p.split(sep).join('/');
+
+// A scope this tool cannot trust is worse than no scope: `{}`, an empty `roots`, or an `exclude`
+// carrying an empty string all yield a census of ZERO tools and a cheerful PASS — a gate answering
+// about a domain it never looked at, which is the exact failure this whole rung exists to end.
+const validateScope = (scope, path) => {
+  const bad = (why) => { throw fail(2, `the coverage scope ${path} is unusable: ${why}`); };
+  if (scope === null || typeof scope !== 'object' || Array.isArray(scope)) bad('it is not an object');
+  if (scope.schema !== 1) bad(`schema must be 1, got ${JSON.stringify(scope.schema)}`);
+  const list = (key, required) => {
+    const value = scope[key];
+    if (value === undefined && !required) return [];
+    if (!Array.isArray(value) || value.some((v) => typeof v !== 'string' || v === '')) bad(`${key} must be an array of non-empty strings`);
+    if (required && value.length === 0) bad(`${key} is empty, so nothing would ever be judged`);
+    return value;
+  };
+  list('roots', true);
+  const extensions = list('extensions', true);
+  if (extensions.some((ext) => !ext.startsWith('.'))) bad('every extension starts with a dot');
+  list('exclude', false);
+  // Both recorded sets are PATHS. `Array.isArray` alone let `[42]` through, and a scope the tool
+  // cannot trust is the thing this validator exists to catch.
+  if (!Array.isArray(scope.adopted)) bad('adopted is the frozen set measured at adoption, and it must be an array');
+  list('adopted', false);
+  list('settled', false);
+  return scope;
+};
+
+const readJson = (path, what) => {
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (err) {
+    throw fail(2, `cannot read ${what} ${path}: ${err.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw fail(2, `${what} ${path} is not valid JSON: ${err.message}`);
+  }
+};
+
+// Deterministic order in both walks: a report a human compares between runs must not depend on the
+// order a directory happens to be read in.
+const sorted = (entries) => [...entries].sort((a, b) => (a.name < b.name ? -1 : 1));
+
+export const specDocuments = (root, io = { readdirSync, readFileSync }) => {
+  const out = [];
+  const walk = (dir) => {
+    for (const entry of sorted(io.readdirSync(dir, { withFileTypes: true }))) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.name.endsWith('.md')) out.push({ rel: posix(relative(root, full)), text: io.readFileSync(full, 'utf8') });
+    }
+  };
+  walk(join(root, STORE_ROOT));
+  return out;
+};
+
+// A test file is never in scope: a contract governs the module, and its tests are the evidence FOR
+// that contract, not a second thing to write one for. A `<name>.test/` directory is the same answer.
+export const toolsIn = (root, scope, io = { readdirSync }) => {
+  const extensions = scope.extensions ?? ['.mjs'];
+  // A textual prefix is not a path. `.../fixtures` would also hide `.../fixtures-escape.mjs`, so a
+  // new tool could leave the scope by being named next to an excluded directory. The boundary is a
+  // path COMPONENT: the entry itself, or something under it.
+  const excluded = (rel) => (scope.exclude ?? []).some((prefix) => rel === prefix || rel.startsWith(`${prefix}/`));
+  const isTest = (name) => extensions.some((ext) => name.endsWith(`.test${ext}`));
+  const out = [];
+  const walk = (dir) => {
+    for (const entry of sorted(io.readdirSync(dir, { withFileTypes: true }))) {
+      const full = join(dir, entry.name);
+      const rel = posix(relative(root, full));
+      if (excluded(rel)) continue;
+      if (entry.isDirectory()) {
+        if (!entry.name.endsWith('.test')) walk(full);
+      } else if (extensions.some((ext) => entry.name.endsWith(ext)) && !isTest(entry.name)) out.push(rel);
+    }
+  };
+  for (const scopeRoot of scope.roots ?? []) walk(join(root, scopeRoot));
+  return out;
+};
+
+const parseArgv = (argv) => {
+  if (argv.length === 1 && (argv[0] === '--help' || argv[0] === '-h')) return { mode: 'help' };
+  const options = { mode: null, root: process.cwd(), reason: null };
+  const seen = new Set();
+  const valueOf = (index, flag) => {
+    const value = argv[index + 1];
+    if (value === undefined || value === '' || value.startsWith('--')) throw fail(2, `${flag} takes a value`);
+    return value;
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--report' || arg === '--check' || arg === '--write-debt') {
+      if (options.mode) throw fail(2, `--${options.mode} was already given — name exactly one mode`);
+      options.mode = arg.slice(2);
+    } else if (arg === '--root' || arg === '--reason') {
+      if (seen.has(arg)) throw fail(2, `${arg} was given twice — each option is named exactly once`);
+      seen.add(arg);
+      options[arg === '--root' ? 'root' : 'reason'] = valueOf(index, arg);
+      index += 1;
+    } else throw fail(2, `unknown argument "${arg}" — run with --help`);
+  }
+  if (!options.mode) throw fail(2, 'one of --report, --check or --write-debt is required — run with --help');
+  // A repayment with no stated reason is how a ratchet becomes a rubber stamp: the reason is recorded
+  // in the file it changes and is what the commit message and the changelog restate.
+  if (options.mode === 'write-debt' && !options.reason) throw fail(2, '--write-debt requires --reason "<what was paid, and by which contract>"');
+  if (options.reason && Buffer.byteLength(options.reason, 'utf8') > REASON_MAX_BYTES) {
+    throw fail(2, `a reason must be at most ${REASON_MAX_BYTES} UTF-8 bytes, got ${Buffer.byteLength(options.reason, 'utf8')}`);
+  }
+  return options;
+};
+
+export const main = (argv, { log = console.log, error = console.error, io } = {}) => {
+  let options;
+  try {
+    options = parseArgv(argv);
+  } catch (err) {
+    error(err.message);
+    return err.exitCode ?? 2;
+  }
+  if (options.mode === 'help') {
+    log(HELP);
+    return 0;
+  }
+
+  let scope;
+  let judged;
+  let unreadable;
+  try {
+    scope = validateScope(readJson(join(options.root, SCOPE_PATH), 'the coverage scope'), join(options.root, SCOPE_PATH));
+    const documents = specDocuments(options.root, io);
+    const found = claimsOf(documents);
+    unreadable = found.unreadable;
+    const tools = toolsIn(options.root, scope, io);
+    // A census of nothing is not a pass. Either the roots are wrong or the tree is not what the
+    // scope describes; both are refusals, never a green.
+    if (tools.length === 0) throw fail(2, `the declared roots (${(scope.roots ?? []).join(', ')}) hold no file this scope would judge — a census of zero is not a pass`);
+    judged = judgeCoverage({ tools, claims: found.claims, adopted: scope.adopted, settled: scope.settled ?? [] });
+  } catch (err) {
+    error(err.message);
+    return err.exitCode ?? 2;
+  }
+
+  if (options.mode === 'report') {
+    for (const { path, by } of judged.covered) log(`${path}\tcovered\t${by}`);
+    for (const path of judged.uncovered) log(`${path}\tuncovered\t-`);
+    for (const path of judged.debt) log(`${path}\tdebt\t-`);
+    return 0;
+  }
+
+  if (options.mode === 'write-debt') {
+    // What is PAYABLE is a subset of what was ADOPTED by construction — it is the owed set filtered,
+    // and the owed set is the baseline minus what is already settled. So this write cannot invent a
+    // path even in principle; `settleAfter` states that as a rule and refuses one directly, which is
+    // where it is asserted. A branch here would be unreachable, and an unreachable guard is not a
+    // guard: it is a claim nobody can check.
+    const next = settleAfter(scope.adopted, scope.settled ?? [], judged.payable);
+    // `adopted` is never rewritten here: it is the state this write is judged against.
+    writeFileSync(join(options.root, SCOPE_PATH), `${JSON.stringify({ ...scope, reason: options.reason, settled: next.settled }, null, 2)}\n`);
+    log(`spec-coverage: debt ${judged.debt.length} → ${judged.debt.length - next.added.length} (${next.added.length} paid and recorded)`);
+    log(`reason: ${options.reason}`);
+    return 0;
+  }
+
+  const findings = formatFindings({ ...judged, unreadable });
+  if (findings.length === 0) {
+    log(`spec-coverage: PASS — ${judged.covered.length} tool(s) governed by a contract, ${judged.debt.length} still owed`);
+    return 0;
+  }
+  error(`spec-coverage: FAIL — ${findings.length} finding(s) against ${join(options.root, SCOPE_PATH)}:`);
+  for (const line of findings) error(line);
+  error('spec-coverage: WHY — no work is done without a specification; a tool no contract governs promises nothing anyone can check.');
+  return 1;
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/tools/spec-coverage.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// NO WORK IS DONE WITHOUT A SPECIFICATION — the half prose cannot do.
+//
+// The spec store answers "what does this module promise?" only for the modules somebody chose to
+// write a contract for, so a contract has been a suggestion: measured when this module was written,
+// 122 tool modules under `agent-workflow-kit/tools/` and 14 of them covered. This module makes the
+// contract a REQUIREMENT with a ratchet — a shipped tool no contract governs is a REFUSAL, and the
+// debt of today's uncovered tools may only shrink.
+//
+// The contract this module is built to is `docs/ai/specs/kit/spec-coverage.md`, and it was written
+// BEFORE this file. That order is the point: a contract amended after the code describes whatever
+// the last review happened to find, which makes review an open question with no bounded answer.
+//
+// Pure functions. No filesystem, no argv, no side effects on import — the CLI half owns all of that.
+// Dependency-free, Node >= 22.
+
+import { readSpecDocument } from '../references/scripts/spec-schema.mjs';
+
+// One `## Module` bullet, carried with the document that made the claim so a refusal can name the
+// owner. The two forms are the ones the spec schema already validates and there is no third here:
+// a `dir/` root covers by PREFIX, a file claim by EQUALITY. The trailing slash is what makes the
+// prefix test safe — `tools/manifest/` can never swallow `tools/manifest-validate.mjs`.
+// Only a LIVE contract claims shipped code. A `draft` is a proposal — it may name a module nobody
+// has built and bind a scenario to nothing — and a `retired` one has stopped promising anything. If
+// either counted, a tool could ship covered by a contract that was never in force.
+const CLAIMING_KINDS = new Set(['spec']);
+const CLAIMING_STATUS = 'live';
+
+export const claimsOf = (documents) => {
+  const claims = [];
+  const unreadable = [];
+  for (const { rel, text } of documents) {
+    const verdict = readSpecDocument(String(text ?? ''), rel);
+    // Only a CONTRACT claims code. A navigator (`kind: index`) lists children and a part belongs to
+    // the module its parent already claims, so neither is asked for a `## Module` — skipping them by
+    // KIND, never by the absence of the section, is what keeps the next line honest.
+    if (!CLAIMING_KINDS.has(verdict.kind) || verdict.status !== CLAIMING_STATUS) continue;
+    const module = verdict.structure?.module;
+    // A CONTRACT whose module cannot be read is its OWN finding, never a silent skip: the tools it
+    // would have covered would look uncovered and the refusal would name the wrong defect.
+    if (!module) unreadable.push({ rel, why: verdict.errors?.[0]?.message ?? 'no readable ## Module declaration' });
+    else for (const path of module.paths) claims.push({ path, form: module.form, by: rel });
+  }
+  return { claims, unreadable };
+};
+
+export const coveredBy = (claims, path) =>
+  claims.find((claim) => (claim.path.endsWith('/') ? path.startsWith(claim.path) : claim.path === path)) ?? null;
+
+// The verdict over one census. The debt is DERIVED — `adopted` minus `settled` — so there is no
+// stored list a hand can edit into a lie. Three findings:
+//   uncovered       a tool no contract covers and the derived debt does not owe — the refusal
+//   falselySettled  a path recorded as PAID whose contract is not there — the record claims what the
+//                   contracts do not say, and it is checked against them every run
+//   payable         a path still owed whose contract now EXISTS — the debt shrank and the record did
+//                   not, so run --write-debt; until then the record overstates what is owed
+export const judgeCoverage = ({ tools, claims, adopted = [], settled = [] }) => {
+  const paid = new Set(settled);
+  const owed = adopted.filter((path) => !paid.has(path));
+  const stillOwed = new Set(owed);
+  const present = new Set(tools);
+  const covered = [];
+  const uncovered = [];
+  for (const path of tools) {
+    const claim = coveredBy(claims, path);
+    if (claim) covered.push({ path, by: claim.by });
+    else if (!stillOwed.has(path)) uncovered.push(path);
+  }
+  const falselySettled = settled.filter((path) => present.has(path) && coveredBy(claims, path) === null);
+  const payable = owed.filter((path) => !present.has(path) || coveredBy(claims, path) !== null);
+  return { covered, uncovered, falselySettled, payable, debt: owed };
+};
+
+// What a `--write-debt` run may record: every path whose contract now exists moves into `settled`,
+// and nothing else changes. `adopted` is never touched, so a path that is not in it cannot be
+// invented — the run names it and says to write the contract.
+export const settleAfter = (adopted, settled, payable) => {
+  const unknown = payable.filter((path) => !adopted.includes(path));
+  if (unknown.length) return { ok: false, unknown };
+  return { ok: true, settled: [...new Set([...settled, ...payable])].sort(), added: payable };
+};
+
+export const formatFindings = ({ uncovered, falselySettled = [], payable = [], unreadable = [] }) => [
+  ...unreadable.map((u) => `  ${u.rel}: its ## Module cannot be read (${u.why}) — the tools it claims are unknown`),
+  ...uncovered.map((p) => `  ${p}: no contract under docs/ai/specs/ claims this module — write one, or it cannot ship`),
+  ...falselySettled.map((p) => `  ${p}: recorded as SETTLED, but no live contract claims it — the record asserts a contract that is not there`),
+  ...payable.map((p) => `  ${p}: still recorded as owed although it is covered now (or gone) — run --write-debt to record what was paid`),
+];