bmad-plus 0.20.0 → 0.22.0

package/tools/cli/commands/assurance.js

@@ -0,0 +1,162 @@
+/**
+ * Security assurance cases: start one from the Shield template, run the checks that produce
+ * evidence, verify a case against them.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const assurance = require('../lib/assurance');
+
+const ACTIONS = ['init', 'run', 'verify'];
+
+function print(json, payload, lines) {
+  if (json) console.log(JSON.stringify({ schemaVersion: 1, ...payload }, null, 2));
+  else for (const line of lines) console.log(line);
+}
+
+/** `--emit-check` writes a JSON file atomically, never over the case or its ledger. */
+function writeCheck(projectDir, value, kase, ledger, result) {
+  const file = path.resolve(projectDir, value);
+  if (!/\.json$/i.test(file)) throw new Error('--emit-check writes a .json file');
+  const protectedFiles = [path.resolve(projectDir, kase.file), ledger];
+  if (protectedFiles.some((taken) => path.relative(taken, file) === ''))
+    throw new Error('--emit-check must not overwrite the case or its ledger');
+  if (fs.existsSync(file) && !fs.statSync(file).isFile())
+    throw new Error(`--emit-check: ${file} is not a file`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(result, null, 2)}\n`, { flag: 'wx' });
+  try {
+    fs.renameSync(temporary, file);
+  } catch (error) {
+    fs.rmSync(temporary, { force: true });
+    throw error;
+  }
+  return file;
+}
+
+function initAction(projectDir, caseFile, json) {
+  const { file, id } = assurance.initCase(projectDir, caseFile);
+  print(json, { action: 'init', case: id, file }, [
+    `${file}: case ${id} started from the Shield template.`,
+    'Replace every example claim and check with those of the project, commit it, then run it.',
+  ]);
+}
+
+async function runAction(projectDir, kase, options, json) {
+  const { file, results, head, authenticated } = await assurance.runChecks(projectDir, kase, {
+    dir: options.dir,
+    only: options.check,
+  });
+  const failed = results.filter((result) => result.failures.length);
+  print(
+    json,
+    {
+      action: 'run',
+      case: kase.id,
+      ledger: file,
+      head,
+      authenticated,
+      results: results.map(({ check, failures, record }) => ({
+        check,
+        status: failures.length ? 'failed' : 'passed',
+        failures,
+        sequence: record.sequence,
+        exitCode: record.exitCode,
+        revision: record.revision,
+        dirty: record.dirty,
+        sha256: record.sha256,
+      })),
+    },
+    [
+      `${file}`,
+      ...results.map(
+        ({ check, failures, record }) =>
+          `  ${failures.length ? 'failed' : 'passed'} ${check.padEnd(24)} exit ${record.exitCode ?? '-'} in ${Math.round(record.durationMs / 100) / 10} s${failures.length ? ` — ${failures.join('; ')}` : ''}`
+      ),
+      ...(results.some(({ record }) => record.dirty !== false)
+        ? [
+            '  Ran on uncommitted changes, untracked files or outside git: a case bound to a commit will not accept these runs.',
+          ]
+        : []),
+      `Recorded ${results.length} run(s)${authenticated ? ', authenticated by key' : ''}; ledger head ${head}.`,
+      `Keep the head outside the ledger and verify with bmad-plus assurance verify ${kase.file} --ledger-head ${head}.`,
+    ]
+  );
+  process.exitCode = failed.length ? 1 : 0;
+}
+
+function verifyAction(projectDir, kase, options, json) {
+  const verdict = assurance.verifyCase(projectDir, kase, {
+    dir: options.dir,
+    head: options.ledgerHead ?? null,
+  });
+  let check = null;
+  if (options.emitCheck)
+    check = writeCheck(
+      projectDir,
+      options.emitCheck,
+      kase,
+      assurance.ledgerFile(projectDir, options.dir, kase.id),
+      assurance.checkResult(verdict)
+    );
+  print(
+    json,
+    { action: 'verify', ...verdict, check },
+    [
+      `${kase.id}: ${verdict.status} — ${verdict.claims.filter((c) => c.status === 'supported').length}/${verdict.claims.length} claim(s) supported, ${verdict.ledger.runs} recorded run(s)`,
+      ...verdict.reasons.map((reason) => `  - ${reason}`),
+      ...Object.entries(verdict.checks)
+        .filter(([, judged]) => judged.status !== 'passed')
+        .map(([id, judged]) => `  ${judged.status.padEnd(7)} ${id}: ${judged.reasons.join('; ')}`),
+      ...verdict.claims
+        .filter((claim) => claim.status !== 'supported')
+        .map((claim) => `  unsupported claim ${claim.id}: ${claim.reasons.join('; ')}`),
+      ...(verdict.controls.supported.length
+        ? [`  controls with executed evidence: ${verdict.controls.supported.join(', ')}`]
+        : []),
+      check ? `  check: ${check}` : '',
+    ].filter(Boolean)
+  );
+  process.exitCode = verdict.exitCode;
+}
+
+module.exports = {
+  command: 'assurance <action> <case>',
+  description: 'Security assurance case bound to executed checks: init, run, verify',
+  options: [
+    ['-d, --directory <path>', 'Project directory'],
+    ['--dir <path>', 'Evidence folder inside the project', assurance.DEFAULT_DIR],
+    ['--check <id>', 'run: only this check (repeatable)', (v, all) => [...all, v], []],
+    ['--ledger-head <sha256>', 'verify: fail unless the ledger still holds this record'],
+    ['--emit-check <file>', 'verify: also write the verdict as a JSON check result for CI'],
+    ['--json', 'Machine-readable output'],
+  ],
+  action: async (action, caseFile, options = {}) => {
+    const projectDir = path.resolve(options.directory || process.cwd());
+    const json = Boolean(options.json);
+    const settings = { dir: options.dir || assurance.DEFAULT_DIR, check: options.check || [] };
+    try {
+      if (!ACTIONS.includes(action))
+        throw new Error(`unknown action "${action}" (${ACTIONS.join(', ')})`);
+      if (action === 'init') return initAction(projectDir, caseFile, json);
+      const kase = assurance.loadCase(projectDir, caseFile);
+      if (action === 'run') await runAction(projectDir, kase, settings, json);
+      else
+        verifyAction(
+          projectDir,
+          kase,
+          { ...settings, emitCheck: options.emitCheck, ledgerHead: options.ledgerHead },
+          json
+        );
+    } catch (error) {
+      if (json)
+        console.log(
+          JSON.stringify({ schemaVersion: 1, status: 'error', message: error.message }, null, 2)
+        );
+      else console.error(`assurance: ${error.message}`);
+      process.exitCode = 3;
+    }
+  },
+};

package/tools/cli/commands/review.js

@@ -7,7 +7,7 @@ const review = require('../lib/review');
 const reviewRules = require('../lib/review-rules');
 
 const ID = /^[a-z0-9][a-z0-9.-]{0,80}$/;
-const ACTIONS = ['scope', 'anchor', 'gate', 'compare', 'rules'];
+const ACTIONS = ['scope', 'anchor', 'gate', 'continue', 'compare', 'rules'];
 
 function fail(message) {
   throw new Error(message);
@@ -28,6 +28,48 @@ function writeJson(file, value) {
   fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
 }
 
+/** A reader of the file sees the previous version or the new one, never half of it. */
+function writeAtomically(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, text, { flag: 'wx' });
+  try {
+    fs.renameSync(temporary, file);
+  } catch (error) {
+    fs.rmSync(temporary, { force: true });
+    throw error;
+  }
+}
+
+const inside = (dir, file) => {
+  const relative = path.relative(dir, file);
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+};
+
+/**
+ * Where `--emit-check` writes: a JSON file, resolved against the project, never the evidence
+ * itself. A working-tree scope selects untracked files, so its check stays in the review
+ * folder or out of the project: anywhere else it would enter the change it reports on.
+ */
+function checkTarget(projectDir, value, paths, scope) {
+  const file = path.resolve(projectDir, value);
+  if (!/\.json$/i.test(file)) fail('--emit-check writes a .json file');
+  const evidence = Object.entries(paths).filter(([key]) => key !== 'root');
+  if (evidence.some(([, taken]) => path.relative(taken, file) === ''))
+    fail('--emit-check must not overwrite the review evidence');
+  if (
+    scope.identity.workspace &&
+    inside(projectDir, file) &&
+    !inside(path.dirname(paths.root), file)
+  )
+    fail(
+      `--emit-check: a working-tree review writes its check in ${path.relative(projectDir, path.dirname(paths.root)) || '.'} or outside the project, where it cannot enter the reviewed change`
+    );
+  if (fs.existsSync(file) && !fs.statSync(file).isFile())
+    fail(`--emit-check: ${file} is not a file`);
+  return file;
+}
+
 function print(json, payload, lines) {
   if (json) console.log(JSON.stringify({ schemaVersion: 1, ...payload }, null, 2));
   else for (const line of lines) console.log(line);
@@ -46,6 +88,75 @@ function loadReview(projectDir, dir, id) {
   return { paths, scope };
 }
 
+/** One line of observed usage: what the host reported, nothing estimated. */
+function describeUsage(stop, usage) {
+  const parts = [
+    `stopped: ${stop || 'unstated'}`,
+    `${usage.passes ?? '?'}/${usage.plannedPasses ?? '?'} pass(es)`,
+    `${usage.unitsAttempted}/${usage.units} unit(s) attempted in ${usage.attempts} attempt(s), ${usage.failedAttempts} failed`,
+  ];
+  if (usage.tokens !== undefined) parts.push(`${usage.tokens} tokens`);
+  if (usage.durationMs !== undefined) parts.push(`${Math.round(usage.durationMs / 1000)} s`);
+  return parts.join(', ');
+}
+
+/**
+ * `review continue <id>`: what an interrupted review still owes, against the same sealed
+ * scope. Refused when the code or the rules moved — a new scope and a compare answer that.
+ */
+function continueAction(projectDir, dir, id, paths, scope, json) {
+  const drift = review.scopeDrift(projectDir, scope, {
+    ruleset: reviewRules.loadRuleset(projectDir),
+    outputDir: dir,
+  });
+  if (drift.length) {
+    const next = [
+      `bmad-plus review scope <new-id> (same options as ${id})`,
+      `bmad-plus review compare <new-id> --since ${id}`,
+    ];
+    print(json, { action: 'continue', id, status: 'moved', drift, next }, [
+      `${id} cannot continue: the sealed scope no longer describes the code.`,
+      ...drift.map((reason) => `  - ${reason}`),
+      `  Seal a new scope and compare: ${next.join(', then ')}.`,
+    ]);
+    process.exitCode = 3;
+    return undefined;
+  }
+  const coverage = readJson(paths.coverage, 'coverage.json');
+  const coverageErrors = coverage ? review.validateCoverage(coverage, scope) : [];
+  if (coverageErrors.length) {
+    print(json, { action: 'continue', id, status: 'error', errors: coverageErrors }, [
+      `${id}: coverage.json must be valid before the review continues`,
+      ...coverageErrors.map((e) => `  error   ${e}`),
+    ]);
+    process.exitCode = 3;
+    return undefined;
+  }
+  const findings = readJson(paths.findings, 'findings.json');
+  const findingErrors = findings ? review.validateFindings(findings, scope) : [];
+  const anchored =
+    findings && !findingErrors.length ? review.anchorFindings(projectDir, scope, findings) : null;
+  const packet = review.remainingWork({ scope, coverage, anchored, findingErrors });
+  writeJson(paths.continue, packet);
+  const c = packet.counts;
+  const nothing = !c.files && !c.requote && !c.findingErrors && !c.passes;
+  print(json, { action: 'continue', id, status: 'ready', file: paths.continue, counts: c }, [
+    `${paths.continue} — same scope ${scope.sha256.slice(0, 12)}`,
+    `${c.files} file(s) in ${c.units} unit(s) to review, ${c.requote} finding(s) to requote, ${c.passes} pass(es) left`,
+    ...packet.units.map((unit) => `  ${unit.id.padEnd(5)} ${unit.paths.join(', ')}`),
+    ...packet.abandoned.map(
+      (file) => `  abandoned ${file.path} (${file.unit}): three failed attempts; it stays failed`
+    ),
+    ...packet.requote.map((f) => `  requote ${f.id} ${f.path} (${f.status})`),
+    ...packet.findingErrors.map((e) => `  fix     ${e}`),
+    nothing
+      ? `Nothing remains: once coverage.json records the run as completed, run bmad-plus review gate ${id}.`
+      : 'Add to the same coverage.json and findings.json; set run.stop when this session ends.',
+  ]);
+  process.exitCode = 0;
+  return undefined;
+}
+
 /** `review rules [path]`: the effective rule set, or the rules one path would get. */
 function rulesAction(projectDir, target, json) {
   const ruleset = reviewRules.loadRuleset(projectDir);
@@ -58,21 +169,30 @@ function rulesAction(projectDir, target, json) {
       action: 'rules',
       path: file,
       sha256: ruleset.sha256,
+      packFiles: ruleset.packFiles,
       projectFile: ruleset.projectFile,
       disabled: ruleset.disabled,
-      rules: listed.map(({ id, title, layer, globs, source }) => ({
+      rules: listed.map(({ id, title, group, layer, pack, globs, controls, source }) => ({
         id,
         title,
+        group,
         layer,
+        ...(pack ? { pack } : {}),
         globs,
+        controls,
         source,
       })),
+      controls: reviewRules.controlsOf(
+        ruleset,
+        listed.map((rule) => rule.id)
+      ),
     },
     [
-      `rule set ${ruleset.sha256.slice(0, 12)}${ruleset.projectFile ? ` (built-in + ${ruleset.projectFile})` : ' (built-in)'}`,
+      `rule set ${ruleset.sha256.slice(0, 12)} (${['built-in', ...ruleset.packFiles, ...(ruleset.projectFile ? [ruleset.projectFile] : [])].join(' + ')})`,
       ...(file ? [`${file} gets ${listed.length} rule(s):`] : []),
       ...listed.map(
-        (rule) => `  ${rule.id.padEnd(24)} ${rule.layer.padEnd(8)} ${rule.globs.join(' ')}`
+        (rule) =>
+          `  ${rule.id.padEnd(24)} ${rule.group.padEnd(12)} ${rule.layer.padEnd(8)} ${rule.globs.join(' ')}${rule.controls.length ? `\n  ${''.padEnd(24)} controls: ${rule.controls.join(' ')}` : ''}`
       ),
       ...ruleset.disabled.map((id) => `  ${id.padEnd(24)} disabled by the project`),
     ]
@@ -81,7 +201,7 @@ function rulesAction(projectDir, target, json) {
 
 module.exports = {
   command: 'review <action> [id]',
-  description: 'Code review evidence: scope, anchor, gate, compare, rules',
+  description: 'Code review evidence: scope, anchor, gate, continue, compare, rules',
   options: [
     ['-d, --directory <path>', 'Project directory'],
     ['--dir <path>', 'Review folder inside the project', review.DEFAULT_DIR],
@@ -95,6 +215,7 @@ module.exports = {
       `Review depth: ${Object.keys(review.EFFORTS).join(', ')} (default medium)`,
     ],
     ['--since <id>', 'compare: the earlier review to compare against'],
+    ['--emit-check <file>', 'gate: also write the verdict as a JSON check result for CI'],
     ['--json', 'Machine-readable output'],
   ],
   action: (action, id, options = {}) => {
@@ -116,6 +237,7 @@ module.exports = {
           include: options.include,
           exclude: options.exclude,
           effort: options.effort,
+          outputDir: dir,
           ruleset,
         });
         const paths = review.layout(projectDir, dir, id);
@@ -201,21 +323,33 @@ module.exports = {
         if (findings && !review.validateFindings(findings, scope).length)
           anchored = review.anchorFindings(projectDir, scope, findings);
         const verdict = review.reviewGate({ scope, findings, coverage, anchored });
+        let check = null;
+        if (options.emitCheck) {
+          check = checkTarget(projectDir, options.emitCheck, paths, scope);
+          writeAtomically(
+            check,
+            `${JSON.stringify(review.checkResult({ id, scope, verdict, anchored }), null, 2)}\n`
+          );
+        }
         print(
           json,
-          { action, id, ...verdict },
+          { action, id, ...verdict, check },
           [
             `${id}: ${verdict.status} — coverage ${verdict.coverage.completed}/${verdict.coverage.selected} completed (${verdict.coverage.waived} waived), ${verdict.findings.open} open finding(s), ${verdict.findings.refuted} refuted`,
             ...verdict.reasons.map((reason) => `  - ${reason}`),
+            verdict.usage ? `  run: ${describeUsage(verdict.stop, verdict.usage)}` : '',
+            check ? `  check: ${check}` : '',
             verdict.status === 'clean'
               ? '  clean: no open finding within a fully covered scope. It does not prove the code correct.'
               : '',
           ].filter(Boolean)
         );
-        process.exitCode = { clean: 0, findings: 1, incomplete: 2 }[verdict.status];
+        process.exitCode = review.GATE_EXIT[verdict.status];
         return undefined;
       }
 
+      if (action === 'continue') return continueAction(projectDir, dir, id, paths, scope, json);
+
       // compare: this review against an earlier one.
       const sinceId = requireId(options.since, '--since <earlier review id>');
       if (sinceId === id) fail('--since must name a different review');