doctrina-cli 0.13.0 → 0.15.0

package/src/commands/contract.js

@@ -1,14 +1,21 @@
+// @ts-check
+import { getSection } from "../lib/doc-model.js";
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
 import { exists, isDir, isFile, read, relPath, write } from "../lib/fs-ops.js";
-import { locateTemplatesDir, substitute } from "../lib/templates.js";
+import { readTemplate, locateTemplatesDir, substitute } from "../lib/templates.js";
 import { specHeader } from "../lib/scan.js";
 import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
 import { flagBool } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
+import {
+  parseTable, parseRuntimeDeclaration, checkWiring, checkEmptySemantics,
+  checkEnums, checkSelectors,
+} from "../lib/runtime.js";
 
 // Contracts are the first-class home for the integration/runtime surface
 // no single capability owns: the port map, the env/dependency contract,
@@ -20,6 +27,11 @@ import { suggest } from "../lib/suggest.js";
 
 const SUBCOMMANDS = ["new", "list", "check"];
 
+// Flags this command accepts. Declared HERE, with the command, so
+// adding a command never requires editing the entrypoint — the gap that
+// let six flags ship undeclared and silently swallow a positional (C3).
+export const flags = { boolean: ["json", "force"], string: [] };
+
 export async function run(positional, flags) {
   const sub = positional[0];
   switch (sub) {
@@ -55,11 +67,12 @@ function contractNew(args, flags) {
     return 1;
   }
 
-  const templatesDir = locateTemplatesDir();
+  const tpl = readTemplate(projectRoot, "contract.md.template");
   const date = today();
-  const body = substitute(read(path.join(templatesDir, "contract.md.template")), { CONTRACT_NAME: name, DATE: date });
+  const body = substitute(tpl.body, { CONTRACT_NAME: name, DATE: date });
   write(targetPath, body, { force });
-  console.log(c.green("created") + ` ${relPath(projectRoot, targetPath)}`);
+  console.log(c.green("created") + ` ${relPath(projectRoot, targetPath)}` +
+    (tpl.source === "project" ? c.gray(" (project template)") : ""));
 
   const index = idx.load(projectRoot);
   idx.addContract(index, {
@@ -73,6 +86,7 @@ function contractNew(args, flags) {
   console.log(c.green("indexed") + ` contract "${name}"`);
   console.log("");
   console.log("Fill in the Ports / Environment / Interfaces tables, then run " + c.cyan("doctrina contract check") + ".");
+  console.log(c.gray("Declaring Wiring and Selectors rows is what makes the RUNTIME half checkable — without them, check can only verify the prose."));
   return 0;
 }
 
@@ -135,7 +149,7 @@ function contractCheck(args, _flags) {
     console.log(c.bold(name) + c.gray(` (${relPath(projectRoot, file)})`));
 
     // 1. Port collisions — two services must not claim the same port.
-    const ports = parseTable(sectionOf(text, "Ports"));
+    const ports = parseTable(getSection(text, "Ports"));
     if (ports) {
       const portCol = colIndex(ports.headers, "port");
       const svcCol = colIndex(ports.headers, "service");
@@ -155,7 +169,7 @@ function contractCheck(args, _flags) {
 
     // 2. Environment drift — every declared variable must exist in
     //    .env.example (when present), so code, example, and infra agree.
-    const env = parseTable(sectionOf(text, "Environment"));
+    const env = parseTable(getSection(text, "Environment"));
     if (env && envExample !== null) {
       const varCol = colIndex(env.headers, "variable");
       for (const row of env.rows) {
@@ -170,13 +184,42 @@ function contractCheck(args, _flags) {
     }
 
     // 3. Referenced capability specs must exist.
-    for (const refCap of referencedCapabilities(sectionOf(text, "References"))) {
+    for (const refCap of referencedCapabilities(getSection(text, "References"))) {
       const specPath = path.join(projectRoot, ".doctrina", "specs", refCap, "spec.md");
       if (!isFile(specPath)) {
         console.log(c.red("  ✗ ") + `references spec "${refCap}" but ${relPath(projectRoot, specPath)} does not exist`);
         errors += 1;
       }
     }
+
+    // 4. The RUNTIME half: a declaration is only worth what binds it to the
+    //    running system. These checks read the contract's Wiring, Selectors
+    //    and Values declarations and hold the implementation to them — the
+    //    "I set the secret in GitHub and nothing happened" class, the
+    //    default that an empty value never triggers, the enum nothing
+    //    validates, and the selector that matches zero cases and exits 0.
+    //    Every section is optional, so a contract written before they
+    //    existed checks exactly as it did before.
+    const decl = parseRuntimeDeclaration(text);
+    for (const f of [
+      ...checkWiring(projectRoot, decl),
+      ...checkEmptySemantics(projectRoot, decl),
+      ...checkEnums(projectRoot, decl),
+      ...checkSelectors(projectRoot, decl),
+    ]) {
+      const mark = f.level === "error" ? c.red("  ✗ ") : c.yellow("  ! ");
+      console.log(mark + f.message + c.gray(` [${f.code}]`));
+      console.log(`      ${c.gray(`fix: ${f.remedy}`)}`);
+      if (f.level === "error") errors += 1;
+      else warnings += 1;
+    }
+
+    if (decl.wiring.length + decl.selectors.length === 0) {
+      // Silence here is not proof of correctness — it is proof that nothing
+      // was declared. Saying so is what stops a green check from being read
+      // as "the wiring is verified".
+      console.log(c.gray("  · no Wiring or Selectors declared — the runtime surface is unchecked"));
+    }
   }
 
   console.log("");
@@ -189,37 +232,6 @@ function contractCheck(args, _flags) {
   return errors === 0 ? 0 : 1;
 }
 
-// Return the body of a "## <name>" section, up to the next "## " heading.
-function sectionOf(text, name) {
-  const lines = text.split(/\r?\n/);
-  const head = new RegExp(`^##\\s+${name}\\b`, "i");
-  let inSection = false;
-  const out = [];
-  for (const line of lines) {
-    if (/^##\s+/.test(line)) {
-      inSection = head.test(line);
-      continue;
-    }
-    if (inSection) out.push(line);
-  }
-  return out.join("\n");
-}
-
-// Parse a GitHub-flavoured Markdown table into { headers, rows }.
-function parseTable(text) {
-  const lines = text.split(/\r?\n/).filter((l) => /^\s*\|/.test(l));
-  if (lines.length < 2) return null;
-  const cells = (line) => line.trim().replace(/^\||\|$/g, "").split("|").map((cl) => cl.trim());
-  const headers = cells(lines[0]);
-  const rows = [];
-  for (let i = 1; i < lines.length; i++) {
-    const row = cells(lines[i]);
-    if (row.every((cl) => /^:?-+:?$/.test(cl) || cl === "")) continue; // separator row
-    rows.push(row);
-  }
-  return { headers, rows };
-}
-
 function colIndex(headers, name) {
   const i = headers.findIndex((h) => h.toLowerCase() === name.toLowerCase());
   return i < 0 ? 0 : i;
@@ -234,7 +246,7 @@ function referencedCapabilities(text) {
 
 function ensureDoctrinaProject(projectRoot) {
   if (!exists(path.join(projectRoot, ".doctrina"))) {
-    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+    throw notADoctrinaProject();
   }
 }
 
@@ -247,8 +259,29 @@ the port map, the environment contract, and API/WS/event interfaces.
 Subcommands:
   new <name>          Scaffold .doctrina/contracts/<name>.md and index it
   list                One line per contract: id, status, last updated
-  check [<name>]      Verify the mechanically checkable parts: no two
-                      services share a port, every declared env var exists
-                      in .env.example, and every referenced spec exists.
-                      Exits 1 on errors (port collisions, missing specs).
+  check [<name>]      Verify the mechanically checkable parts.
+
+                      Structure: no two services share a port, every
+                      declared env var exists in .env.example, and every
+                      referenced spec exists.
+
+                      Runtime — the declaration held to the implementation:
+                        RT01/02  a variable declared with origin vars or
+                                 secrets must be exported by an env: block
+                                 in the workflow the Wiring row names, from
+                                 the origin and name it declares.
+                        RT03     its consumer must not give it a default
+                                 that only applies when ABSENT: CI injects
+                                 the empty string, so the default never
+                                 fires (textual lint).
+                        RT04     a declared Values enum must hold in
+                                 .env.example, and the consumer should
+                                 validate it.
+                        RT05     every declared selector must match at
+                                 least one target, or a run dispatched on
+                                 it executes nothing and still exits 0.
+
+                      No CI system or test runner is parsed natively: each
+                      check reads the glob, pattern and origin the contract
+                      declares. Exits 1 on errors, 0 on warnings only.
 `;

package/src/commands/coverage.js

@@ -1,3 +1,4 @@
+// @ts-check
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
@@ -6,6 +7,8 @@ import { exists, isDir, isFile, read, relPath } from "../lib/fs-ops.js";
 import { specHeader } from "../lib/scan.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
+import { emitJson } from "../lib/json-out.js";
+import { notADoctrinaProject } from "../lib/exit-codes.js";
 
 // Traceability report: how many acceptance criteria cite an artifact or
 // test that actually exists on disk. Doctrina otherwise has no link
@@ -22,10 +25,19 @@ import { c } from "../lib/colors.js";
 // proves nothing — review G3: existence ≠ a passing test), "dangling" when
 // a cited path does not resolve, and "bare" when nothing is cited.
 
+// Flags this command accepts. Declared HERE, with the command, so
+// adding a command never requires editing the entrypoint — the gap that
+// let six flags ship undeclared and silently swallow a positional (C3).
+// This command builds its own JSON payload; the entrypoint must not
+// wrap it in the generic envelope.
+export const jsonNative = true;
+
+export const flags = { boolean: ["json", "run", "strict"], string: ["only"] };
+
 export async function run(_positional, flags) {
   const projectRoot = process.cwd();
   if (!exists(path.join(projectRoot, ".doctrina"))) {
-    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+    throw notADoctrinaProject();
   }
   const strict = flagBool(flags, "strict", false);
   const json = flagBool(flags, "json", false);
@@ -48,7 +60,7 @@ export async function run(_positional, flags) {
 
   if (reports.length === 0) {
     if (json) {
-      console.log(JSON.stringify({ specs: [], summary: { criteria: 0, covered: 0, dangling: 0, conditional: 0, pct: 100 } }, null, 2));
+      emitJson("coverage", { specs: [], summary: { criteria: 0, covered: 0, dangling: 0, conditional: 0, pct: 100 } });
       return 0;
     }
     console.log(c.gray("no acceptance criteria found under .doctrina/specs/"));
@@ -59,23 +71,26 @@ export async function run(_positional, flags) {
   let totalCovered = 0;
   let totalDangling = 0;
   let totalConditional = 0;
+  let totalUnguarded = 0;
   let totalDeferred = 0;
   for (const rep of reports) {
     totalCriteria += rep.rows.length;
     totalCovered += rep.rows.filter((r) => r.kind === "covered").length;
     totalDangling += rep.rows.filter((r) => r.kind === "dangling").length;
     totalConditional += rep.rows.filter((r) => r.kind === "conditional").length;
+    totalUnguarded += rep.rows.filter((r) => r.kind === "unguarded").length;
     totalDeferred += rep.rows.filter((r) => r.kind === "deferred").length;
   }
   const jsonPct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
   // Deferred criteria are visible but never gate: declared debt ≠ hidden debt.
-  const jsonClean = totalCovered + totalDeferred === totalCriteria && totalDangling === 0 && totalConditional === 0;
+  const jsonClean = totalCovered + totalDeferred === totalCriteria && totalDangling === 0
+    && totalConditional === 0 && totalUnguarded === 0;
 
   if (json) {
-    console.log(JSON.stringify({
+    emitJson("coverage", {
       specs: reports.map((rep) => ({ capability: rep.cap, deferred: rep.deferred, criteria: rep.rows })),
-      summary: { criteria: totalCriteria, covered: totalCovered, dangling: totalDangling, conditional: totalConditional, deferred: totalDeferred, pct: jsonPct },
-    }, null, 2));
+      summary: { criteria: totalCriteria, covered: totalCovered, dangling: totalDangling, conditional: totalConditional, unguarded: totalUnguarded, deferred: totalDeferred, pct: jsonPct },
+    });
     return jsonClean ? 0 : strict ? 1 : 0;
   }
 
@@ -86,10 +101,12 @@ export async function run(_positional, flags) {
     const covered = rep.rows.filter((r) => r.kind === "covered").length;
     const dangling = rep.rows.filter((r) => r.kind === "dangling").length;
     const conditional = rep.rows.filter((r) => r.kind === "conditional").length;
+    const unguarded = rep.rows.filter((r) => r.kind === "unguarded").length;
     const deferredN = rep.rows.filter((r) => r.kind === "deferred").length;
 
     const notes = [];
     if (conditional > 0) notes.push(c.yellow(`${conditional} conditional`));
+    if (unguarded > 0) notes.push(c.yellow(`${unguarded} unguarded`));
     if (dangling > 0) notes.push(c.yellow(`${dangling} dangling`));
     if (deferredN > 0) notes.push(c.gray(`${deferredN} deferred`));
     const note = notes.length > 0 ? `  (${notes.join(", ")})` : "";
@@ -102,6 +119,8 @@ export async function run(_positional, flags) {
         console.log(`    ${c.red("✗")} #${r.n}  no evidence linked — cite the file/test that proves it in backticks`);
       } else if (r.kind === "conditional") {
         console.log(`    ${c.yellow("!")} #${r.n}  evidence is a skipped test (proves nothing): ${r.skipped.map((m) => `\`${m}\``).join(", ")}`);
+      } else if (r.kind === "unguarded") {
+        console.log(`    ${c.red("✗")} #${r.n}  orchestration claim is not fail-closed: ${r.reason}`);
       } else {
         console.log(`    ${c.yellow("!")} #${r.n}  evidence not found on disk: ${r.missing.map((m) => `\`${m}\``).join(", ")}`);
       }
@@ -111,9 +130,11 @@ export async function run(_positional, flags) {
   const pct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
   console.log("");
   const summary = `${totalCovered} of ${totalCriteria} acceptance criteria across ${reports.length} spec${reports.length === 1 ? "" : "s"} have linked evidence (${pct}%)`;
-  const clean = totalCovered + totalDeferred === totalCriteria && totalDangling === 0 && totalConditional === 0;
+  const clean = totalCovered + totalDeferred === totalCriteria && totalDangling === 0
+    && totalConditional === 0 && totalUnguarded === 0;
   const extras = [];
   if (totalConditional > 0) extras.push(`${totalConditional} conditional`);
+  if (totalUnguarded > 0) extras.push(`${totalUnguarded} unguarded`);
   if (totalDangling > 0) extras.push(`${totalDangling} dangling`);
   if (totalDeferred > 0) extras.push(`${totalDeferred} deferred (not gated)`);
   const extraSummary = extras.length > 0 ? `, ${extras.join(", ")}` : "";
@@ -236,13 +257,14 @@ export function summarize(projectRoot) {
     const covered = rep.rows.filter((r) => r.kind === "covered").length;
     const dangling = rep.rows.filter((r) => r.kind === "dangling").length;
     const conditional = rep.rows.filter((r) => r.kind === "conditional").length;
+    const unguarded = rep.rows.filter((r) => r.kind === "unguarded").length;
     const deferred = rep.rows.filter((r) => r.kind === "deferred").length;
     totalCriteria += rep.rows.length;
     totalCovered += covered;
     totalDangling += dangling;
     totalConditional += conditional;
     totalDeferred += deferred;
-    perCap.push({ cap: rep.cap, total: rep.rows.length, covered, dangling, conditional, deferred });
+    perCap.push({ cap: rep.cap, total: rep.rows.length, covered, dangling, conditional, unguarded, deferred });
   }
   const pct = totalCriteria === 0 ? 100 : Math.round((totalCovered / totalCriteria) * 100);
   return { perCap, totalCriteria, totalCovered, totalDangling, totalConditional, totalDeferred, pct };
@@ -285,8 +307,84 @@ function extractAcceptanceCriteria(text) {
   return out.filter((s) => s.length > 0);
 }
 
+// ORCHESTRATION criteria (change 0029). Coverage measures CITATION: a
+// criterion is covered when it cites a file that exists (and, since G3, a
+// test whose suite is not skipped). That is the right test for "this
+// function behaves", and the wrong one for "the pipeline ran at all".
+//
+// A criterion like "absence of the report is explicit and the step does not
+// fail" is satisfied, on paper, by a job that executed zero cases and
+// printed a well-written empty state — the citation resolves, the suite is
+// not skipped, and the only visible signal is a tidy message saying nothing
+// happened. Coverage calls that proven.
+//
+// Marking a criterion `[orchestration]` says: the claim is that a RUN
+// happened, so the proof must be a fail-closed one. It cites a verify check
+// by name (`verify:<check>`), and that check must declare an `expect` guard
+// — the thing that turns "exit 0" into "exit 0 having actually done
+// something". A named check without a guard is UNGUARDED: the criterion is
+// not proven, and says so, instead of quietly counting as covered.
+const ORCHESTRATION_MARKER = /^orchestration\b/;
+
+function citedVerifyChecks(criterion) {
+  const out = new Set();
+  for (const m of criterion.matchAll(/`verify:([A-Za-z0-9_.-]+)`/g)) out.add(m[1]);
+  return [...out];
+}
+
+function guardedVerifyChecks(projectRoot) {
+  const configPath = path.join(projectRoot, ".doctrina", "verify.json");
+  if (!isFile(configPath)) return null;
+  let config;
+  try {
+    config = JSON.parse(read(configPath));
+  } catch {
+    return null;
+  }
+  const map = new Map();
+  for (const ch of Array.isArray(config?.checks) ? config.checks : []) {
+    if (!ch?.name) continue;
+    const exp = ch.expect;
+    const guarded = Boolean(exp && typeof exp === "object"
+      && (typeof exp.fail_if_output_matches === "string" || typeof exp.require_output_matches === "string"));
+    map.set(ch.name, guarded);
+  }
+  return map;
+}
+
+function classifyOrchestration(criterion, n, projectRoot) {
+  const named = citedVerifyChecks(criterion);
+  if (named.length === 0) {
+    return { kind: "unguarded", n, reason: "cites no verify check — an orchestration claim is proven by a fail-closed check, cited as `verify:<check>`" };
+  }
+  const checks = guardedVerifyChecks(projectRoot);
+  if (checks === null) {
+    return { kind: "dangling", n, missing: named.map((x) => `verify:${x}`) };
+  }
+  const unknown = named.filter((x) => !checks.has(x));
+  if (unknown.length > 0) {
+    return { kind: "dangling", n, missing: unknown.map((x) => `verify:${x}`) };
+  }
+  const unguarded = named.filter((x) => !checks.get(x));
+  if (unguarded.length > 0) {
+    return {
+      kind: "unguarded",
+      n,
+      reason: `verify check${unguarded.length === 1 ? "" : "s"} ${unguarded.join(", ")} declare${unguarded.length === 1 ? "s" : ""} no "expect" guard — a check that exits 0 having run nothing would still pass it`,
+    };
+  }
+  return { kind: "covered", n, evidence: [] };
+}
+
 // Decide whether a single criterion is covered, conditional, dangling, or bare.
 function classify(criterion, n, projectRoot, specDir) {
+  // An orchestration criterion is judged on its GUARD, not on whether a
+  // cited file exists — the whole point is that existence proves nothing here.
+  const marker = criterion.match(/^\[([^\]]+)\]/)?.[1]?.toLowerCase() ?? "";
+  if (ORCHESTRATION_MARKER.test(marker)) {
+    return classifyOrchestration(criterion, n, projectRoot);
+  }
+
   const cited = extractBacktickPaths(criterion);
   if (cited.length === 0) return { kind: "bare", n };
   const missing = [];
@@ -378,15 +476,31 @@ A criterion is covered when a cited path resolves to real proof,
 conditional when its only resolving proof is a test file whose suite is
 skipped (\`describe.skip\` / \`xit\` / \`@pytest.mark.skip\` — proves
 nothing), dangling when a cited path is missing on disk, and bare when
-nothing is cited. A spec that declares a deliberate deferral —
+nothing is cited.
+
+ORCHESTRATION criteria. Citation is the right proof for "this function
+behaves" and the wrong one for "the pipeline ran at all": a criterion
+like "absence of the report is explicit and the step does not fail" is
+satisfied on paper by a job that executed zero cases and printed a
+well-written empty state. Mark such a criterion [orchestration] and cite
+a verify check by name:
+
+  3. [orchestration] the e2e suite actually executes scenarios —
+     verified by \`verify:e2e\`
+
+That check must declare an "expect" guard (see \`doctrina verify --help\`).
+A cited check with no guard is reported UNGUARDED and fails --strict: a
+check that exits 0 having run nothing would otherwise satisfy the claim.
+
+A spec that declares a deliberate deferral —
 \`Implementation: planned — <why>\`, the same escape hatch validate
 honours — has its unproven criteria reported as DEFERRED: visible, but
 never a --strict failure (declared debt is not hidden debt).
 
 Flags:
-  --strict           Exit 1 when any criterion is bare, dangling, or
-                     conditional (CI gate). Deferred never fails. Without
-                     it the command always exits 0 (a report).
+  --strict           Exit 1 when any criterion is bare, dangling,
+                     conditional, or unguarded (CI gate). Deferred never
+                     fails. Without it the command always exits 0 (a report).
   --only <cap,cap>   Scope the report/gate to specific capabilities
                      (\`doctrina close\` uses this so an unrelated deferred
                      spec cannot block a change's close).