ddduck 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ddduck",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "An opinionated DDD framework for authoring, validating, and visualizing machine-readable product-spec models.",
   "keywords": [
     "ddd",
@@ -23,7 +23,7 @@
     "url": "https://github.com/diegomarino/ddduck/issues"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "type": "module",
   "files": [
@@ -32,6 +32,8 @@
     "policies/",
     "skills/",
     "docs/architecture.md",
+    "docs/definition-workflow.md",
+    "docs/templates/change-brief.md",
     "docs/getting-started.md",
     "docs/model.md",
     "docs/model-reference.md",
@@ -41,7 +43,8 @@
     "ddduck": "scripts/ddduck.mjs"
   },
   "scripts": {
-    "check": "npm run check:model && npm run check:docs && npm run check:graph && npm run check:graph:svg && npm run lint && npm run lint:md && npm run format:check && npm test",
+    "check": "npm run check:static && npm test",
+    "check:static": "npm run check:model && npm run check:docs && npm run check:graph && npm run check:graph:svg && npm run lint && npm run lint:md && npm run format:check",
     "check:docs": "node scripts/check-generated-docs.mjs",
     "check:graph": "node scripts/check-generated-graph.mjs",
     "check:graph:svg": "node scripts/check-generated-graph-svg.mjs",
@@ -51,7 +54,7 @@
     "generate:graph": "node scripts/generate-graph.mjs",
     "generate:graph:svg": "node scripts/generate-graph-svg.mjs",
     "lint": "eslint .",
-    "lint:md": "markdownlint-cli2 \"*.md\" \"docs/**/*.md\" \"examples/**/*.md\"",
+    "lint:md": "markdownlint-cli2 \"*.md\" \"docs/**/*.md\" \"examples/**/*.md\" \"#CHANGELOG.md\" \"#docs/audits\" \"#docs/superpowers\"",
     "test": "node --test test/*.test.mjs",
     "test:coverage": "node --test --experimental-test-coverage test/*.test.mjs",
     "pack:dry-run": "npm pack --dry-run --cache .npm-cache",
@@ -71,6 +74,6 @@
     "prettier": "^3.9.6"
   },
   "overrides": {
-    "fast-uri": "^3.1.5"
+    "fast-uri": "^3.1.7"
   }
 }

package/schemas/model-diff.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ddduck.local/schemas/model-diff.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "kind",
+    "before",
+    "after",
+    "scope",
+    "excludedScopes",
+    "added",
+    "removed",
+    "changed",
+    "relocated"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "1" },
+    "kind": { "const": "ModelDiff" },
+    "before": { "$ref": "#/$defs/identity" },
+    "after": { "$ref": "#/$defs/identity" },
+    "scope": { "const": "canonical-yaml-only" },
+    "excludedScopes": { "const": ["decision-content", "evidence-content", "delivery-artifacts", "runtime"] },
+    "added": { "type": "array", "items": { "$ref": "#/$defs/record" } },
+    "removed": { "type": "array", "items": { "$ref": "#/$defs/record" } },
+    "changed": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "kind", "changes"],
+        "properties": {
+          "id": { "type": "string" },
+          "kind": { "type": "string" },
+          "changes": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/change" } }
+        }
+      }
+    },
+    "relocated": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "kind", "beforePath", "afterPath"],
+        "properties": {
+          "id": { "type": "string" },
+          "kind": { "type": "string" },
+          "beforePath": { "type": "string" },
+          "afterPath": { "type": "string" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["modelId", "sourceDigest"],
+      "properties": {
+        "modelId": { "type": "string", "pattern": "^model:" },
+        "sourceDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    },
+    "record": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "sourcePath", "node"],
+      "properties": {
+        "id": { "type": "string" },
+        "kind": { "type": "string" },
+        "sourcePath": { "type": "string" },
+        "node": { "type": "object" }
+      }
+    },
+    "change": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "beforePresent", "afterPresent"],
+      "properties": {
+        "path": { "type": "string", "pattern": "^(?:/(?:[^~/]|~[01])*)+$" },
+        "beforePresent": { "type": "boolean" },
+        "afterPresent": { "type": "boolean" },
+        "before": {},
+        "after": {}
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "beforePresent": { "const": true } } },
+          "then": { "required": ["before"] },
+          "else": { "not": { "required": ["before"] } }
+        },
+        {
+          "if": { "properties": { "afterPresent": { "const": true } } },
+          "then": { "required": ["after"] },
+          "else": { "not": { "required": ["after"] } }
+        },
+        {
+          "anyOf": [
+            { "properties": { "beforePresent": { "const": true } } },
+            { "properties": { "afterPresent": { "const": true } } }
+          ]
+        }
+      ]
+    }
+  }
+}

package/scripts/audit-fr-to-code.mjs

@@ -1,5 +1,15 @@
 #!/usr/bin/env node
 
+/**
+ * CLI for verifying FR-to-code audit records (`audit-fr-to-code --input
+ * <audit.yaml> --source-root <source-id>=<checkout> --json`). Reads the YAML
+ * audit record, binds each declared source to a local git checkout whose
+ * origin URL and pinned 40-hex revision must match, reads anchored files via
+ * `git show` at that exact revision (regular-file tree entries only), and
+ * delegates verdict verification to lib/fr-to-code-audit.mjs, emitting one
+ * JSON report on stdout.
+ */
+
 import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -7,6 +17,13 @@ import { parseDocument } from "yaml";
 import { verifyFrToCodeAudit } from "./lib/fr-to-code-audit.mjs";
 import { CliUsageError, parseCommandArgs, renderHelp, writeCliError } from "./lib/cli-contract.mjs";
 
+/**
+ * Parse arguments, verify the audit record against its pinned sources, and
+ * write the JSON report.
+ * @param {string[]} args - CLI arguments (--input, repeatable --source-root, --json).
+ * @param {{stdout?: {write: (chunk: string) => unknown}}} [io] - Output stream override for tests.
+ * @returns {void}
+ */
 export function runFrToCodeAudit(args, { stdout = process.stdout } = {}) {
   if (args.length === 1 && args[0] === "--help") {
     stdout.write(renderHelp("audit-fr-to-code"));
@@ -61,6 +78,14 @@ function validateDeclaredSources(record, filePath) {
   }
 }
 
+/**
+ * Build the source reader that serves file contents from pinned git revisions.
+ * Requires exactly one --source-root mapping per declared source and verifies
+ * each checkout's origin URL and revision presence up front.
+ * @param {{sources: {id: string, repository: string, revision: string}[]}} record - The validated audit record.
+ * @param {{id: string, root: string}[]} sourceRoots - Parsed --source-root mappings.
+ * @returns {{readFile: (source: object, relativePath: string) => string}} Reader handed to verifyFrToCodeAudit.
+ */
 function createGitSourceReader(record, sourceRoots) {
   if (!Array.isArray(record.sources)) throw new Error("audit input must declare sources");
   const declaredIds = new Set(record.sources.map((source) => source?.id));

package/scripts/check-generated-docs.mjs

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 
+/**
+ * Freshness gate for the generated docs view: rebuilds
+ * generated/docs/model-overview.md from the canonical YAML and compares it
+ * byte-for-byte against the committed file. Consumed by `ddduck check` and the
+ * staged operation runner (both import checkGeneratedDocs); also runnable
+ * standalone, where a stale view exits 1 with a regenerate remedy.
+ */
+
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -8,10 +16,21 @@ import { resolveProductRoot } from "./lib/product-root-resolver.mjs";
 
 const outputPath = path.join("generated", "docs", "model-overview.md");
 
-function staleMessage(root) {
-  return `${outputPath} is missing or stale; run ddduck generate --root ${root}`;
+// The message states the fact only, so callers that add their own next-action
+// line never state the remedy twice; `remedy` carries the regenerate hint for
+// callers with no next-action surface (the standalone gate below).
+function staleError(root) {
+  const error = new Error(`${outputPath} is missing or stale`);
+  error.remedy = `run ddduck generate --root ${root}`;
+  return error;
 }
 
+/**
+ * Throw if generated/docs/model-overview.md is missing or differs from the
+ * output rebuilt from the current canonical YAML.
+ * @param {string} rootPath - Product root path.
+ * @returns {void}
+ */
 export function checkGeneratedDocs(rootPath) {
   const root = path.resolve(rootPath);
   const expected = buildModelOverview(root);
@@ -19,10 +38,10 @@ export function checkGeneratedDocs(rootPath) {
   try {
     actual = readFileSync(path.join(root, outputPath), "utf8");
   } catch (error) {
-    if (error.code === "ENOENT") throw new Error(staleMessage(root));
+    if (error.code === "ENOENT") throw staleError(root);
     throw error;
   }
-  if (actual !== expected) throw new Error(staleMessage(root));
+  if (actual !== expected) throw staleError(root);
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
@@ -31,7 +50,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
     checkGeneratedDocs(resolveProductRoot({ explicitRoot: options.root }));
     if (options.verbose) console.log("generated docs ok");
   } catch (error) {
-    console.error(error.message);
+    console.error(error.remedy ? `${error.message}; ${error.remedy}` : error.message);
     process.exit(1);
   }
 }

package/scripts/check-generated-graph-svg.mjs

@@ -1,5 +1,14 @@
 #!/usr/bin/env node
 
+/**
+ * Freshness gate for the canonical SVG view generated/graph/model-graph.svg.
+ * Rendering uses the async Graphviz WASM engine, so unlike the docs and
+ * JSON/NDJSON gates this one is always executed as a child process by
+ * `ddduck check`, the staged operation runner, and query freshness — never
+ * imported into their synchronous flows. Standalone runs exit 1 on a missing
+ * or stale SVG with a regenerate remedy.
+ */
+
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -7,13 +16,22 @@ import { buildModelGraph } from "./generate-graph.mjs";
 import { buildModelGraphSvg, svgOutputPath } from "./generate-graph-svg.mjs";
 import { resolveProductRoot } from "./lib/product-root-resolver.mjs";
 
-function staleMessage(root) {
-  return `${svgOutputPath} is missing or stale; run ddduck generate --root ${root}`;
+// The message states the fact only, so callers that add their own next-action
+// line never state the remedy twice; `remedy` carries the regenerate hint for
+// callers with no next-action surface (the standalone gate below).
+function staleError(root) {
+  const error = new Error(`${svgOutputPath} is missing or stale`);
+  error.remedy = `run ddduck generate --root ${root}`;
+  return error;
 }
 
-// Pin the canonical SVG byte-for-byte: rebuild it from the source model and
-// compare against the committed file. Deterministic because @hpcc-js/wasm is
-// version-pinned in the lockfile (the SVG embeds its Graphviz version).
+/**
+ * Pin the canonical SVG byte-for-byte: rebuild it from the source model and
+ * compare against the committed file. Deterministic because @hpcc-js/wasm is
+ * version-pinned in the lockfile (the SVG embeds its Graphviz version).
+ * @param {string} rootPath - Product root path.
+ * @returns {Promise<void>} Rejects when the SVG is missing or stale.
+ */
 export async function checkGeneratedGraphSvg(rootPath) {
   const root = path.resolve(rootPath);
   const expected = await buildModelGraphSvg(buildModelGraph(root));
@@ -21,10 +39,10 @@ export async function checkGeneratedGraphSvg(rootPath) {
   try {
     actual = readFileSync(path.join(root, svgOutputPath), "utf8");
   } catch (error) {
-    if (error.code === "ENOENT") throw new Error(staleMessage(root));
+    if (error.code === "ENOENT") throw staleError(root);
     throw error;
   }
-  if (actual !== expected) throw new Error(staleMessage(root));
+  if (actual !== expected) throw staleError(root);
 }
 
 function parseArgs(args) {
@@ -54,7 +72,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
     await checkGeneratedGraphSvg(resolveProductRoot({ explicitRoot: options.root }));
     if (options.verbose) console.log("generated graph svg ok");
   } catch (error) {
-    console.error(error.message);
+    console.error(error.remedy ? `${error.message}; ${error.remedy}` : error.message);
     process.exit(1);
   }
 }

package/scripts/check-generated-graph.mjs

@@ -1,15 +1,35 @@
 #!/usr/bin/env node
 
+/**
+ * Freshness gate for the generated graph views: rebuilds
+ * generated/graph/model-graph.json and .ndjson from the canonical YAML and
+ * compares each byte-for-byte against the committed files. Consumed by
+ * `ddduck check` and the staged operation runner (both import
+ * checkGeneratedGraph); also runnable standalone, where a stale view exits 1
+ * with a regenerate remedy.
+ */
+
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { buildModelGraphOutputs, jsonOutputPath, ndjsonOutputPath } from "./generate-graph.mjs";
 import { resolveProductRoot } from "./lib/product-root-resolver.mjs";
 
-function staleMessage(relativePath, root) {
-  return `${relativePath} is missing or stale; run ddduck generate --root ${root}`;
+// The message states the fact only, so callers that add their own next-action
+// line never state the remedy twice; `remedy` carries the regenerate hint for
+// callers with no next-action surface (the standalone gate below).
+function staleError(relativePath, root) {
+  const error = new Error(`${relativePath} is missing or stale`);
+  error.remedy = `run ddduck generate --root ${root}`;
+  return error;
 }
 
+/**
+ * Throw if model-graph.json or model-graph.ndjson is missing or differs from
+ * the outputs rebuilt from the current canonical YAML.
+ * @param {string} rootPath - Product root path.
+ * @returns {void}
+ */
 export function checkGeneratedGraph(rootPath) {
   const root = path.resolve(rootPath);
   const expected = buildModelGraphOutputs(root);
@@ -23,13 +43,13 @@ function checkOutput(root, relativePath, expected) {
     actual = readFileSync(path.join(root, relativePath), "utf8");
   } catch (error) {
     if (error.code === "ENOENT") {
-      throw new Error(staleMessage(relativePath, root));
+      throw staleError(relativePath, root);
     }
     throw error;
   }
 
   if (actual !== expected) {
-    throw new Error(staleMessage(relativePath, root));
+    throw staleError(relativePath, root);
   }
 }
 
@@ -60,7 +80,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
     checkGeneratedGraph(resolveProductRoot({ explicitRoot: options.root }));
     if (options.verbose) console.log("generated graph ok");
   } catch (error) {
-    console.error(error.message);
+    console.error(error.remedy ? `${error.message}; ${error.remedy}` : error.message);
     process.exit(1);
   }
 }

package/scripts/check-model.mjs

@@ -1,5 +1,15 @@
 #!/usr/bin/env node
 
+/**
+ * The model checker behind `ddduck check`: validates a product root's canonical
+ * YAML against the framework schemas, referential integrity (single Model,
+ * ownership, decisions), evidence anchors, guarantee lifecycle rules, and the
+ * executable policy checks (ownership, documentation model-reference
+ * resolution). With --base it also enforces guarantee history retention against
+ * a previous product root. Exports validateProduct for the operation runner,
+ * query loader, and root resolver; runs standalone as a CLI (exit 1 on errors).
+ */
+
 import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -7,7 +17,7 @@ import Ajv2020 from "ajv/dist/2020.js";
 import { unified } from "unified";
 import remarkParse from "remark-parse";
 import { parseDocument } from "yaml";
-import { detectProductLayout, loadProductNodes } from "./lib/product-layout.mjs";
+import { detectProductLayout, loadProductNodes, nodeDirectoryKinds } from "./lib/product-layout.mjs";
 import { shouldIgnoreScanEntry } from "./lib/scan-ignore.mjs";
 import { findRepositoryRoot, resolveConfiguredIgnores } from "./lib/ddduck-config.mjs";
 
@@ -18,7 +28,7 @@ const executableRuleChecks = new Set([
 ]);
 
 const markdownReferencePattern =
-  /\b(?:(?:model|domain|concept|rel|rule|use-case|interface):[a-z0-9][a-z0-9-]*|[A-Z][A-Z0-9-]+-(?:INV|AC)-[0-9]+|ADR-[0-9]{3})\b/g;
+  /\b(?:(?:model|domain|concept|rel|use-case|interface):[a-z0-9][a-z0-9-]*|[A-Z][A-Z0-9-]+-(?:INV|AC)-[0-9]+|ADR-[0-9]{3})\b/g;
 
 const defaultFrameworkRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -58,6 +68,11 @@ function parseArgs(args) {
   return parsed;
 }
 
+/**
+ * One validation run over a product root: loads nodes and decisions, then
+ * accumulates every diagnostic in `errors` (file-relative, one per line) while
+ * counting nodes, references, and executed policies for the verbose summary.
+ */
 class ProductCheck {
   constructor(rootPath, frameworkPath, basePath, documentationRoots, { sourceOnly = false } = {}) {
     this.root = rootPath;
@@ -78,6 +93,7 @@ class ProductCheck {
     this.loadDecisions();
     this.loadNodes();
     this.validateSchemas();
+    this.validateNodeDirectories();
     this.validateEvidenceAnchors();
     this.validateReferences();
     this.validateGuaranteeLifecycle();
@@ -147,6 +163,22 @@ class ProductCheck {
     }
   }
 
+  validateNodeDirectories() {
+    for (const [id, filePath] of this.nodeFiles) {
+      const segments = path.relative(this.root, filePath).split(path.sep);
+      if (segments[0] !== "model") continue;
+      const expectedKind = nodeDirectoryKinds.get(segments[1]);
+      if (!expectedKind) continue;
+      const node = this.nodes.get(id);
+      if (node.kind !== expectedKind) {
+        this.addError(
+          id,
+          `node kind ${node.kind} does not match directory model/${segments[1]} (expected ${expectedKind})`,
+        );
+      }
+    }
+  }
+
   validateReferences() {
     const models = [...this.nodes.values()].filter((node) => node.kind === "Model");
     if (models.length !== 1) {
@@ -195,6 +227,15 @@ class ProductCheck {
             node.id,
             `evidence anchor path must resolve to an existing regular file below product root: ${evidence.path}`,
           );
+          continue;
+        }
+        // Markdown targets must contain the anchor text; non-Markdown anchors
+        // stay free-form labels.
+        if (evidence.path.endsWith(".md") && typeof evidence.anchor === "string") {
+          const content = readFileSync(path.resolve(this.root, evidence.path), "utf8");
+          if (!content.includes(evidence.anchor)) {
+            this.addError(node.id, `evidence anchor not found in ${evidence.path}: ${evidence.anchor}`);
+          }
         }
       }
     }
@@ -207,8 +248,17 @@ class ProductCheck {
         if (successors.length === 0) this.addError(node.id, "split guarantee requires active successors");
         for (const id of successors) {
           const successor = this.nodes.get(id);
-          if (!successor || successor.kind !== "Guarantee" || successor.status !== "active")
-            this.addError(node.id, `split successor must be an active guarantee ${id}`);
+          if (!successor || successor.kind !== "Guarantee") {
+            this.addError(node.id, `split successor must be a guarantee ${id}`);
+            continue;
+          }
+          // A successor may leave `active` through its own authorized lifecycle
+          // transition; its record must then carry a registered lifecycleDecision.
+          if (successor.status !== "active" && !this.decisions.has(successor.lifecycleDecision))
+            this.addError(
+              node.id,
+              `split successor must be an active guarantee or carry a registered lifecycleDecision ${id}`,
+            );
         }
       }
       if (node.kind === "DomainInterface" || node.kind === "UseCase") {
@@ -269,9 +319,35 @@ class ProductCheck {
       this.errors.push(`base: ${error.message}`);
       return;
     }
+    const legalStatusTransitions = new Map([
+      ["active", ["active", "split", "retired"]],
+      ["split", ["split"]],
+      ["retired", ["retired"]],
+    ]);
     for (const baseNode of baseNodes.values()) {
-      if (baseNode.kind === "Guarantee" && !this.nodes.has(baseNode.id)) {
+      if (baseNode.kind !== "Guarantee") continue;
+      const current = this.nodes.get(baseNode.id);
+      if (!current) {
         this.errors.push(`guarantee disappeared from the product: ${baseNode.id}`);
+        continue;
+      }
+      if (!(legalStatusTransitions.get(baseNode.status) ?? []).includes(current.status)) {
+        this.addError(baseNode.id, `illegal guarantee status transition ${baseNode.status} -> ${current.status}`);
+        continue;
+      }
+      if (baseNode.status === "split" || baseNode.status === "retired") {
+        if (current.lifecycleDecision !== baseNode.lifecycleDecision)
+          this.addError(
+            baseNode.id,
+            `closed guarantee must keep lifecycleDecision ${baseNode.lifecycleDecision} from base`,
+          );
+        const baseSuccessors = asArray(baseNode.successors);
+        const currentSuccessors = asArray(current.successors);
+        if (
+          baseSuccessors.length !== currentSuccessors.length ||
+          baseSuccessors.some((id, index) => currentSuccessors[index] !== id)
+        )
+          this.addError(baseNode.id, `closed guarantee must keep successors ${baseSuccessors.join(", ")} from base`);
       }
     }
   }
@@ -373,6 +449,14 @@ function listFiles(directory, pattern) {
   }
 }
 
+/**
+ * Recursively list Markdown files under a documentation root, skipping ignored
+ * scan entries, nested git checkouts, nested product roots, and the audit and
+ * superpowers doc areas.
+ * @param {string} rootPath - Documentation root to walk.
+ * @param {string[]} [ignoredEntryNames] - Extra directory names to skip (from .ddduck config).
+ * @returns {string[]} Sorted absolute Markdown file paths.
+ */
 function listMarkdownFiles(rootPath, ignoredEntryNames = []) {
   const files = [];
 
@@ -454,6 +538,12 @@ function executePolicyChecks(check, checksToRun, { includeDocumentation = true }
   }
 }
 
+/**
+ * Validate a product root and return the completed check (inspect `.errors`).
+ * @param {string} rootPath - Product root to validate.
+ * @param {{baseRoot?: string, includeDocumentation?: boolean, documentationRoots?: string[], sourceOnly?: boolean}} [options] - Base product for history retention, documentation scope, and whether generated docs are scanned.
+ * @returns {ProductCheck} The finished check with errors and counters.
+ */
 export function validateProduct(
   rootPath,
   { baseRoot, includeDocumentation = true, documentationRoots, sourceOnly = false } = {},