ddduck 0.1.0 → 0.2.0

package/scripts/lib/product-diff.mjs

@@ -0,0 +1,155 @@
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { validateProduct } from "../check-model.mjs";
+import { shellQuote, sourceDigestFromSources } from "./context-pack.mjs";
+import { detectProductLayout, loadProductNodes } from "./product-layout.mjs";
+import { assertProductNotBusy, findLeftoverOperationState } from "./product-operation.mjs";
+
+export function compareProductSnapshots(before, after) {
+  const beforeModel = modelId(before);
+  const afterModel = modelId(after);
+  if (beforeModel !== afterModel) {
+    const error = new Error(`Cannot compare different Model IDs: ${beforeModel} and ${afterModel}`);
+    error.nextAction = "Choose two product roots representing the same Model ID, then retry the diff.";
+    throw error;
+  }
+  const beforeNodes = new Map(before.nodes.map((node) => [node.id, node]));
+  const afterNodes = new Map(after.nodes.map((node) => [node.id, node]));
+  const result = { added: [], removed: [], changed: [], relocated: [] };
+  for (const id of [...new Set([...beforeNodes.keys(), ...afterNodes.keys()])].sort()) {
+    const previous = beforeNodes.get(id);
+    const current = afterNodes.get(id);
+    if (!previous) {
+      result.added.push(record(current, after.canonicalPaths[id]));
+    } else if (!current) {
+      result.removed.push(record(previous, before.canonicalPaths[id]));
+    } else {
+      const changes = fieldChanges(previous, current);
+      if (changes.length > 0) result.changed.push({ id, kind: current.kind, changes });
+      if (before.canonicalPaths[id] !== after.canonicalPaths[id]) {
+        result.relocated.push({
+          id,
+          kind: current.kind,
+          beforePath: before.canonicalPaths[id],
+          afterPath: after.canonicalPaths[id],
+        });
+      }
+    }
+  }
+  return result;
+}
+
+export function compareProductRoots(beforeRoot, afterRoot) {
+  const before = loadDiffRoot(beforeRoot);
+  const after = loadDiffRoot(afterRoot);
+  return {
+    schemaVersion: "1",
+    kind: "ModelDiff",
+    before: { modelId: modelId(before.snapshot), sourceDigest: before.sourceDigest },
+    after: { modelId: modelId(after.snapshot), sourceDigest: after.sourceDigest },
+    scope: "canonical-yaml-only",
+    excludedScopes: ["decision-content", "evidence-content", "delivery-artifacts", "runtime"],
+    ...compareProductSnapshots(before.snapshot, after.snapshot),
+  };
+}
+
+export function renderProductDiff(report) {
+  const lines = [
+    `Model diff: ${report.before.modelId}`,
+    `Before: ${report.before.sourceDigest}`,
+    `After: ${report.after.sourceDigest}`,
+    `Scope: ${report.scope}`,
+    `Excluded: ${report.excludedScopes.join(", ")}`,
+  ];
+  for (const entry of report.added) lines.push(`Added ${entry.id} (${entry.kind}) at ${entry.sourcePath}`);
+  for (const entry of report.removed) lines.push(`Removed ${entry.id} (${entry.kind}) from ${entry.sourcePath}`);
+  for (const entry of report.changed) {
+    lines.push(`Changed ${entry.id} (${entry.kind})`);
+    for (const change of entry.changes) {
+      const before = change.beforePresent ? JSON.stringify(change.before) : "<absent>";
+      const after = change.afterPresent ? JSON.stringify(change.after) : "<absent>";
+      lines.push(`  ${change.path}: ${before} -> ${after}`);
+    }
+  }
+  for (const entry of report.relocated) {
+    lines.push(`Relocated ${entry.id} (${entry.kind}): ${entry.beforePath} -> ${entry.afterPath}`);
+  }
+  if ([report.added, report.removed, report.changed, report.relocated].every((entries) => entries.length === 0)) {
+    lines.push("No canonical record changes.");
+  }
+  lines.push("Structural comparison requires human interpretation; source reads are not atomic snapshots.");
+  return lines.join("\n");
+}
+
+function loadDiffRoot(rootPath) {
+  const layout = detectProductLayout(rootPath);
+  try {
+    assertReadable(layout.root);
+    const check = validateProduct(layout.root, { includeDocumentation: false, sourceOnly: true });
+    if (check.errors.length > 0) throw new Error(`Validation failed for ${layout.root}:\n${check.errors.join("\n")}`);
+    const loaded = loadProductNodes(layout);
+    const canonicalPaths = Object.fromEntries(
+      [...loaded.nodeFiles].map(([id, filePath]) => [
+        id,
+        path.relative(layout.root, filePath).split(path.sep).join("/"),
+      ]),
+    );
+    const sources = new Map([...loaded.nodeSources].map(([id, bytes]) => [canonicalPaths[id], bytes]));
+    assertReadable(layout.root);
+    return {
+      snapshot: { nodes: [...loaded.nodes.values()], canonicalPaths },
+      sourceDigest: sourceDigestFromSources(sources),
+    };
+  } catch (error) {
+    error.nextAction ??= `Fix the product root and its source files, run ddduck check --root ${shellQuote(layout.root)}, then retry the diff.`;
+    throw error;
+  }
+}
+
+function assertReadable(root) {
+  assertProductNotBusy(root);
+  const leftover = findLeftoverOperationState(root);
+  if (leftover) {
+    const error = new Error(`An interrupted ddduck operation left ${leftover.entries.join(", ")} in ${root}`);
+    error.nextAction = `Run ddduck generate --root ${shellQuote(root)} to reclaim the interrupted operation state, then retry the diff.`;
+    throw error;
+  }
+}
+
+function modelId(snapshot) {
+  const models = snapshot.nodes.filter((node) => node.kind === "Model");
+  if (models.length !== 1) throw new Error("A product snapshot must contain exactly one Model record");
+  return models[0].id;
+}
+
+function record(node, sourcePath) {
+  return { id: node.id, kind: node.kind, sourcePath, node: globalThis.structuredClone(node) };
+}
+
+function fieldChanges(before, after, pointer = "") {
+  const changes = [];
+  for (const key of [...new Set([...Object.keys(before), ...Object.keys(after)])].sort()) {
+    const fieldPath = `${pointer}/${key.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+    const beforePresent = Object.hasOwn(before, key);
+    const afterPresent = Object.hasOwn(after, key);
+    const previous = before[key];
+    const current = after[key];
+    if (beforePresent && afterPresent && isDeepStrictEqual(previous, current)) continue;
+    if (beforePresent && afterPresent && isMapping(previous) && isMapping(current)) {
+      changes.push(...fieldChanges(previous, current, fieldPath));
+    } else {
+      changes.push({
+        path: fieldPath,
+        beforePresent,
+        afterPresent,
+        ...(beforePresent ? { before: globalThis.structuredClone(previous) } : {}),
+        ...(afterPresent ? { after: globalThis.structuredClone(current) } : {}),
+      });
+    }
+  }
+  return changes.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
+}
+
+function isMapping(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/scripts/lib/product-layout.mjs

@@ -1,9 +1,33 @@
+/**
+ * Defines the on-disk layout of a product root and loads its canonical YAML:
+ * product.yaml plus the model/{domains,concepts,relationships,use-cases,
+ * interfaces,guarantees} directories (nodeDirectoryKinds maps directory to
+ * node kind). loadProductNodes yields mutable nodes with file paths and raw
+ * sources (for the query digest); loadProductSnapshot yields the deep-frozen
+ * snapshot with root-relative canonical paths that mutation transforms plan
+ * against. Strict YAML parsing: duplicate keys and non-mapping files fail.
+ */
+
 import { readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 import { parseDocument } from "yaml";
 
-const nodeDirectories = ["domains", "concepts", "relationships", "use-cases", "interfaces", "guarantees"];
+export const nodeDirectoryKinds = new Map([
+  ["domains", "Domain"],
+  ["concepts", "Concept"],
+  ["relationships", "Relationship"],
+  ["use-cases", "UseCase"],
+  ["interfaces", "DomainInterface"],
+  ["guarantees", "Guarantee"],
+]);
+
+const nodeDirectories = [...nodeDirectoryKinds.keys()];
 
+/**
+ * Describe the canonical layout below a product root.
+ * @param {string} rootPath - Product root path.
+ * @returns {{root: string, productPath: string, nodeDirectories: string[], decisionsDirectory: string, generatedDirectory: string}} Resolved layout paths.
+ */
 export function detectProductLayout(rootPath) {
   const root = path.resolve(rootPath);
   return {
@@ -15,6 +39,11 @@ export function detectProductLayout(rootPath) {
   };
 }
 
+/**
+ * Load every canonical YAML node under a layout, rejecting duplicate node IDs.
+ * @param {{root: string, productPath: string, nodeDirectories: string[]}} layout - Layout from detectProductLayout.
+ * @returns {{nodes: Map<string, object>, nodeFiles: Map<string, string>, nodeSources: Map<string, Buffer>}} Nodes, their file paths, and raw source bytes keyed by ID.
+ */
 export function loadProductNodes(layout) {
   const nodes = new Map();
   const nodeFiles = new Map();
@@ -35,6 +64,12 @@ export function loadProductNodes(layout) {
   return { nodes, nodeFiles, nodeSources };
 }
 
+/**
+ * Load the deep-frozen snapshot that mutation transforms receive: immutable
+ * nodes plus each node's root-relative canonical path.
+ * @param {{root: string, productPath: string, nodeDirectories: string[]}} layout - Layout from detectProductLayout.
+ * @returns {{nodes: readonly object[], canonicalPaths: Record<string, string>}} Frozen snapshot.
+ */
 export function loadProductSnapshot(layout) {
   const loaded = loadProductNodes(layout);
   const nodes = Object.freeze([...loaded.nodes.values()].map((node) => deepFreeze(node)));
@@ -49,6 +84,12 @@ export function loadProductSnapshot(layout) {
   return Object.freeze({ nodes, canonicalPaths });
 }
 
+/**
+ * Parse one canonical YAML file strictly (unique keys) into a plain mapping.
+ * @param {string} filePath - File path, used in diagnostics.
+ * @param {string} [source] - YAML source; read from filePath when omitted.
+ * @returns {object} The parsed YAML mapping.
+ */
 export function parseYamlMapping(filePath, source = readFileSync(filePath, "utf8")) {
   const document = parseDocument(source, { keepSourceTokens: true, strict: true, uniqueKeys: true });
   if (document.errors.length > 0) {

package/scripts/lib/product-operation.mjs

@@ -1,3 +1,13 @@
+/**
+ * The locked, staged mutation runner behind every product-changing ddduck
+ * command (generate, create/move/split/retire). Holds the invariants: one
+ * operation at a time per product root (.ddduck-operation.lock, reclaimable
+ * only when its owner PID is dead), all edits validated in a staging copy
+ * before any canonical or generated file is published, and canonical YAML
+ * rewritten comment-preservingly. Also exports the canonical generatedPaths
+ * list and the busy/leftover-state probes used by check and query.
+ */
+
 import { spawnSync } from "node:child_process";
 import {
   closeSync,
@@ -16,10 +26,11 @@ import {
 } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { stringify } from "yaml";
+import { isScalar, isSeq, parseDocument, stringify } from "yaml";
 import { checkGeneratedDocs } from "../check-generated-docs.mjs";
 import { checkGeneratedGraph } from "../check-generated-graph.mjs";
 import { validateProduct } from "../check-model.mjs";
+import { shellQuote } from "./context-pack.mjs";
 import { writeModelOverview } from "../generate-docs.mjs";
 import { writeModelGraph } from "../generate-graph.mjs";
 import { detectProductLayout, loadProductSnapshot } from "./product-layout.mjs";
@@ -29,19 +40,23 @@ import { nonProductSourceEntries } from "./product-root-resolver.mjs";
 const lockRelativePath = ".ddduck-operation.lock";
 const reclaimRelativePath = ".ddduck-operation.reclaim";
 const stagingPrefix = ".ddduck-operation-stage-";
-const generatedPaths = Object.freeze([
+// The canonical generated views: one list consumed by mutation results, query
+// freshness, the check gate, and the docs. The SVG is rendered by the Graphviz
+// WASM engine, which is async, so we produce it in a child process to keep this
+// runner synchronous (mirrors the check subprocess).
+export const generatedPaths = Object.freeze([
   "generated/docs/model-overview.md",
   "generated/graph/model-graph.json",
   "generated/graph/model-graph.ndjson",
+  "generated/graph/model-graph.svg",
 ]);
-// The canonical SVG is published atomically alongside the reported outputs, but
-// kept off `generatedPaths` so it stays out of the CLI/query freshness contract.
-// It is rendered by the Graphviz WASM engine, which is async, so we produce it in
-// a child process to keep this runner synchronous (mirrors the check subprocess).
-const auxiliaryGeneratedPaths = Object.freeze(["generated/graph/model-graph.svg"]);
 const svgGeneratorScript = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "generate-graph-svg.mjs");
 const excludedSourceEntries = new Set([...nonProductSourceEntries, lockRelativePath, reclaimRelativePath]);
 
+/**
+ * Raised when a product root's operation lock is held; carries exitCode 2 when
+ * the holder is a live process (the one retryable failure).
+ */
 export class ProductBusyError extends Error {
   constructor(root, lockPath, ownerPid) {
     const holder = ownerPid ? ` (held by running process ${ownerPid})` : "";
@@ -50,9 +65,22 @@ export class ProductBusyError extends Error {
     this.nextAction = ownerPid
       ? `Wait for process ${ownerPid} to finish and retry, or delete ${lockPath} and retry if that process is not a ddduck operation.`
       : `If no other ddduck operation is running on this product, delete ${lockPath} and retry.`;
+    // Contention with a running ddduck operation is the one retryable failure;
+    // exit code 2 lets callers retry it without string-matching stderr. Every
+    // other failure, including a lock without a live owner, stays exit 1.
+    if (ownerPid) this.exitCode = 2;
   }
 }
 
+/**
+ * Run one mutation against a product root: acquire the lock, sweep dead
+ * reclaim claims and orphaned staging, copy the source into staging, apply the
+ * transform's replacement plan, validate the staged product, regenerate every
+ * generated view (SVG via subprocess), then publish canonical and generated
+ * files back file-by-file. The lock and staging are always cleaned up.
+ * @param {{root: string, transform: (snapshot: {nodes: object[], canonicalPaths: Record<string, string>}) => {operation: string, affectedIds: string[], replacements: {path: string, value: object}[]}}} params - Product root and plan-building transform.
+ * @returns {{operation: string, root: string, affectedIds: string[], canonicalPaths: string[], generatedPaths: string[]}} The published operation result.
+ */
 export function runProductOperation({ root, transform }) {
   if (typeof transform !== "function") throw new TypeError("product operation requires a transform function");
   const normalizedRoot = realpathSync(path.resolve(root));
@@ -60,9 +88,6 @@ export function runProductOperation({ root, transform }) {
   const publishGeneratedTargets = generatedPaths.map((relativePath) =>
     resolveContainedOutput(normalizedRoot, relativePath),
   );
-  const publishAuxiliaryTargets = auxiliaryGeneratedPaths.map((relativePath) =>
-    resolveContainedOutput(normalizedRoot, relativePath),
-  );
   let lockAcquired = false;
   let stagingRoot;
 
@@ -77,7 +102,7 @@ export function runProductOperation({ root, transform }) {
     const snapshot = loadProductSnapshot(detectProductLayout(stagingRoot));
     const plan = validatePlan(transform(snapshot));
     const canonicalPaths = applyReplacements(stagingRoot, plan.replacements);
-    validateStagedProduct(stagingRoot);
+    validateStagedProduct(stagingRoot, normalizedRoot);
     writeModelOverview(stagingRoot);
     writeModelGraph(stagingRoot);
     renderModelGraphSvg(stagingRoot);
@@ -96,10 +121,6 @@ export function runProductOperation({ root, transform }) {
         relativePath,
         targetPath: publishGeneratedTargets[index],
       })),
-      ...auxiliaryGeneratedPaths.map((relativePath, index) => ({
-        relativePath,
-        targetPath: publishAuxiliaryTargets[index],
-      })),
     ]);
     for (let index = 0; index < canonicalPaths.length; index += 1) {
       copyPublishedFile(stagingRoot, canonicalPaths[index], publishCanonicalTargets[index]);
@@ -107,9 +128,6 @@ export function runProductOperation({ root, transform }) {
     for (let index = 0; index < generatedPaths.length; index += 1) {
       copyPublishedFile(stagingRoot, generatedPaths[index], publishGeneratedTargets[index]);
     }
-    for (let index = 0; index < auxiliaryGeneratedPaths.length; index += 1) {
-      copyPublishedFile(stagingRoot, auxiliaryGeneratedPaths[index], publishAuxiliaryTargets[index]);
-    }
 
     return {
       operation: plan.operation,
@@ -278,7 +296,12 @@ function readLockOwner(lockPath) {
   return { state: "unknown" };
 }
 
-function isProcessAlive(pid) {
+/**
+ * Probe whether a PID belongs to a live process (signal 0; EPERM counts as alive).
+ * @param {number} pid - Process ID recorded in a lock, claim, or init stage name.
+ * @returns {boolean} True unless the process is definitely gone (ESRCH).
+ */
+export function isProcessAlive(pid) {
   try {
     process.kill(pid, 0);
     return true;
@@ -310,6 +333,12 @@ function sweepOrphanedStaging(root) {
   }
 }
 
+/**
+ * Throw ProductBusyError if the product's operation lock is held by a live
+ * process; used by read paths (check, query) that must not run mid-mutation.
+ * @param {string} root - Product root path.
+ * @returns {void}
+ */
 export function assertProductNotBusy(root) {
   const normalizedRoot = realpathSync(path.resolve(root));
   const lockPath = path.join(normalizedRoot, lockRelativePath);
@@ -319,6 +348,13 @@ export function assertProductNotBusy(root) {
   }
 }
 
+/**
+ * List interrupted-operation debris (ownerless lock, dead reclaim claims,
+ * staging directories) that a future operation would reclaim; live locks are
+ * not leftovers.
+ * @param {string} root - Product root path.
+ * @returns {{root: string, entries: string[]}|null} The leftover entries, or null when the root is clean.
+ */
 export function findLeftoverOperationState(root) {
   const normalizedRoot = realpathSync(path.resolve(root));
   const lockPath = path.join(normalizedRoot, lockRelativePath);
@@ -400,13 +436,64 @@ function applyReplacements(stagingRoot, replacements) {
     }
     const target = resolveContainedOutput(stagingRoot, relativePath);
     mkdirSync(path.dirname(target), { recursive: true });
-    writeFileSync(target, stringify(replacement.value));
+    writeFileSync(target, serializeReplacement(target, relativePath, replacement.value));
     seenPaths.add(relativePath);
     canonicalPaths.push(relativePath);
   }
   return canonicalPaths.sort();
 }
 
+/**
+ * Rewrite an existing canonical file by editing its parsed YAML document key by
+ * key instead of re-serializing the plan value wholesale, so authored comments
+ * and formatting outside the keys a mutation actually changes survive. New
+ * files have no authored content to preserve and take the plain serialization.
+ * Staged validation still covers the exact published bytes: this runs before
+ * validateStagedProduct, and publication copies these staged bytes verbatim.
+ * @param {string} target - Absolute staged path of the canonical file.
+ * @param {string} relativePath - Root-relative canonical path (for diagnostics).
+ * @param {object} value - The replacement YAML mapping from the operation plan.
+ * @returns {string} The staged file's new YAML source.
+ */
+function serializeReplacement(target, relativePath, value) {
+  let source;
+  try {
+    source = readFileSync(target, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return stringify(value);
+  }
+  const document = parseDocument(source, { keepSourceTokens: true, strict: true, uniqueKeys: true });
+  if (document.errors.length > 0) {
+    throw new Error(
+      `invalid YAML in canonical replacement ${relativePath}: ${document.errors.map((error) => error.message).join("; ")}`,
+    );
+  }
+  const current = document.toJSON();
+  if (current === null || typeof current !== "object" || Array.isArray(current)) return stringify(value);
+  for (const [key, next] of Object.entries(value)) {
+    if (key in current && JSON.stringify(current[key]) === JSON.stringify(next)) continue;
+    const existing = document.get(key, true);
+    if (isScalar(existing) && (next === null || typeof next !== "object")) {
+      existing.value = next;
+    } else if (
+      isSeq(existing) &&
+      Array.isArray(next) &&
+      next.length > existing.items.length &&
+      next.every((item) => item === null || typeof item !== "object") &&
+      existing.items.every((item, index) => isScalar(item) && item.value === next[index])
+    ) {
+      for (const item of next.slice(existing.items.length)) existing.add(document.createNode(item));
+    } else {
+      document.set(key, document.createNode(next));
+    }
+  }
+  for (const key of Object.keys(current)) {
+    if (!(key in value)) document.delete(key);
+  }
+  return document.toString();
+}
+
 function normalizeCanonicalPath(relativePath) {
   if (typeof relativePath !== "string") throw new TypeError("canonical replacement requires path");
   const normalized = relativePath.split(path.sep).join("/");
@@ -419,9 +506,40 @@ function normalizeCanonicalPath(relativePath) {
   return normalized;
 }
 
-function validateStagedProduct(stagingRoot) {
+function validateStagedProduct(stagingRoot, root) {
   const check = validateProduct(stagingRoot);
-  if (check.errors.length > 0) throw new Error(check.errors.join("\n"));
+  if (check.errors.length > 0) throw validationFailureError(root, check.errors);
+}
+
+/**
+ * Build the error for a failed product validation. Validation failures are
+ * model failures, not CLI-input failures, so the Next: line must point at the
+ * real unblock instead of the per-command usage hint: referential lifecycle
+ * blockers name the referencing file and the edit-regenerate-retry path,
+ * base-retention failures name the sanctioned remedies, and everything else is
+ * a source-file fix.
+ * @param {string} root - Product root the validation ran against.
+ * @param {string[]} errors - Checker diagnostics, one per line.
+ * @returns {Error} Error with a tailored nextAction property.
+ */
+export function validationFailureError(root, errors) {
+  const error = new Error(`Validation failed for ${root}:\n${errors.join("\n")}`);
+  const referencingFiles = [
+    ...new Set(
+      errors
+        .filter((line) => /: (?:non-effective guarantee|split successor must be) /.test(line))
+        .map((line) => line.slice(0, line.indexOf(":"))),
+    ),
+  ];
+  if (referencingFiles.length > 0) {
+    error.nextAction = `Edit ${referencingFiles.join(", ")} to remove or replace the blocking guarantee reference, run ddduck generate --root ${shellQuote(root)}, and retry.`;
+  } else if (errors.some((line) => line.startsWith("guarantee disappeared from the product"))) {
+    error.nextAction =
+      "Restore the guarantee record from the base product, or record the transition with ddduck retire or ddduck split, then re-run ddduck check.";
+  } else {
+    error.nextAction = "Fix the listed source files, then re-run ddduck check.";
+  }
+  return error;
 }
 
 function copyPublishedFile(stagingRoot, relativePath, targetPath) {

package/scripts/lib/product-paths.mjs

@@ -1,6 +1,22 @@
+/**
+ * Path-containment guard for every write below a product root. Any file
+ * ddduck creates or publishes (generated views, staged canonical files, lock
+ * and staging paths, eval outputs) resolves its destination through
+ * resolveContainedOutput, which rejects absolute paths, `..` traversal,
+ * escapes above the root, and symbolic links anywhere on the target path — so
+ * no operation can be steered into writing outside the root.
+ */
+
 import { lstatSync, realpathSync } from "node:fs";
 import path from "node:path";
 
+/**
+ * Resolve a root-relative output path to an absolute one, proving it stays
+ * below the real root and traverses or targets no symbolic link.
+ * @param {string} rootPath - The containing root (product root or repo root).
+ * @param {string} relativePath - Root-relative destination path.
+ * @returns {string} The absolute, contained target path.
+ */
 export function resolveContainedOutput(rootPath, relativePath) {
   if (path.isAbsolute(relativePath)) {
     throw new Error("output path must be relative to root");