ddduck 0.1.0 → 0.2.0

package/scripts/lib/product-query.mjs

@@ -1,36 +1,58 @@
+/**
+ * The read-only query engine behind `ddduck query`: loadQueryProduct builds a
+ * validated in-memory product (nodes, derived graph edges, source digest,
+ * lifecycle redirects for inactive guarantees) after refusing busy roots and
+ * interrupted-operation leftovers, and the query* functions implement the
+ * node, neighbors, impact, anchors, and spec operations. Anchors and spec
+ * also report generated-view freshness (the SVG checked via subprocess) and
+ * the check/generate verification commands agents should run.
+ */
+
+import { spawnSync } from "node:child_process";
 import { readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { validateProduct } from "../check-model.mjs";
 import { buildModelOverview } from "../generate-docs.mjs";
 import { buildModelGraph, buildModelGraphOutputs } from "../generate-graph.mjs";
-import { sourceDigestFromSources } from "./context-pack.mjs";
+import { shellQuote, sourceDigestFromSources, unknownModelNodeError } from "./context-pack.mjs";
 import { detectProductLayout, loadProductNodes } from "./product-layout.mjs";
-import { assertProductNotBusy } from "./product-operation.mjs";
+import { assertProductNotBusy, findLeftoverOperationState, generatedPaths } from "./product-operation.mjs";
 
 const impactEdgeKinds = new Set(["owns", "requires", "preserves", "establishes", "uses", "guarantees"]);
 // Only these kinds accept an `evidence` field in their schemas, so source and
 // verification anchors may only be demanded of them.
 const evidenceAnchorKinds = new Set(["DomainInterface", "UseCase", "Guarantee"]);
-const generatedViewPaths = [
-  "generated/docs/model-overview.md",
-  "generated/graph/model-graph.json",
-  "generated/graph/model-graph.ndjson",
-];
+const svgViewPath = "generated/graph/model-graph.svg";
+const svgCheckerScript = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "check-generated-graph-svg.mjs",
+);
 function verificationCommandsFor(product) {
   const root = shellQuote(product.root);
   return [`ddduck check --root ${root}`, `ddduck generate --root ${root}`];
 }
 
-// Emitted commands are copied into shells by humans and agents; roots with
-// spaces or metacharacters must survive that round trip.
-function shellQuote(value) {
-  if (/^[A-Za-z0-9_\-./]+$/.test(value)) return value;
-  return `'${value.replaceAll("'", "'\\''")}'`;
-}
-
+/**
+ * Load the queryable product for a root: refuse busy or interrupted state,
+ * validate the source (documentation excluded), and assemble nodes, edges,
+ * source paths, the sha256 source digest, decisions, and policies.
+ * @param {string} rootPath - Product root path.
+ * @param {{history?: boolean}} [options] - With history, inactive guarantees stay in `nodes`; otherwise they become lifecycleRedirects.
+ * @returns {{root: string, rootModelId: string, nodes: Map<string, object>, sourcePaths: Map<string, string>, sourceDigest: string, edges: object[], lifecycleRedirects: Map<string, object>, decisions: Map<string, string>, policies: string[]}} The loaded query product.
+ */
 export function loadQueryProduct(rootPath, { history = false } = {}) {
   const layout = detectProductLayout(rootPath);
   assertProductNotBusy(layout.root);
+  // Leftover state from an interrupted mutation means the snapshot may be
+  // partially published; refuse to serve a digest over it, exactly like check.
+  const leftover = findLeftoverOperationState(layout.root);
+  if (leftover) {
+    const error = new Error(`An interrupted ddduck operation left ${leftover.entries.join(", ")} in ${layout.root}`);
+    error.nextAction = `Run ddduck generate --root ${shellQuote(layout.root)} to reclaim the interrupted operation state, then retry the query.`;
+    throw error;
+  }
   const check = validateProduct(layout.root, { includeDocumentation: false });
   if (check.errors.length > 0) throw new Error(check.errors.join("\n"));
   const loaded = loadProductNodes(layout);
@@ -69,6 +91,14 @@ export function loadQueryProduct(rootPath, { history = false } = {}) {
   };
 }
 
+/**
+ * Answer `query node`: the full node, or a lifecycleRedirect for an inactive
+ * guarantee ID.
+ * @param {object} product - Product from loadQueryProduct.
+ * @param {string} id - Model node ID.
+ * @param {{history?: boolean}} [options] - Echoed into the query envelope.
+ * @returns {object} The query document.
+ */
 export function queryNode(product, id, { history = false } = {}) {
   const node = product.nodes.get(id);
   if (node) {
@@ -78,15 +108,23 @@ export function queryNode(product, id, { history = false } = {}) {
   if (lifecycleRedirect) {
     return envelope(product, "node", id, history, { lifecycleRedirect });
   }
-  throw new Error(`Unknown model node ${id}`);
+  throw unknownModelNodeError(product, id);
 }
 
+/**
+ * Answer `query neighbors`: every incoming and outgoing edge of a node with a
+ * summary of the peer node on each edge.
+ * @param {object} product - Product from loadQueryProduct.
+ * @param {string} id - Model node ID.
+ * @param {{history?: boolean}} [options] - Echoed into the query envelope.
+ * @returns {object} The query document.
+ */
 export function queryNeighbors(product, id, { history = false } = {}) {
   const node = product.nodes.get(id);
   if (!node) {
     const lifecycleRedirect = product.lifecycleRedirects.get(id);
     if (lifecycleRedirect) return envelope(product, "neighbors", id, history, { lifecycleRedirect });
-    throw new Error(`Unknown model node ${id}`);
+    throw unknownModelNodeError(product, id);
   }
   const incoming = product.edges
     .filter((edge) => edge.to === id)
@@ -103,12 +141,21 @@ export function queryNeighbors(product, id, { history = false } = {}) {
   });
 }
 
+/**
+ * Answer `query impact`: breadth-first walk of everything that depends on the
+ * node, following owns/requires/preserves/establishes/uses/guarantees edges
+ * backwards, with each hit tagged by depth.
+ * @param {object} product - Product from loadQueryProduct.
+ * @param {string} id - Model node ID.
+ * @param {{history?: boolean}} [options] - Echoed into the query envelope.
+ * @returns {object} The query document.
+ */
 export function queryImpact(product, id, { history = false } = {}) {
   const node = product.nodes.get(id);
   if (!node) {
     const lifecycleRedirect = product.lifecycleRedirects.get(id);
     if (lifecycleRedirect) return envelope(product, "impact", id, history, { lifecycleRedirect });
-    throw new Error(`Unknown model node ${id}`);
+    throw unknownModelNodeError(product, id);
   }
 
   const visited = new Set([id]);
@@ -136,12 +183,22 @@ export function queryImpact(product, id, { history = false } = {}) {
   });
 }
 
+/**
+ * Answer `query anchors`: the node's declared evidence anchors, reachable
+ * decisions, executed policies, generated-view freshness, verification
+ * commands, and which evidence roles (source/decision/verification) are still
+ * missing for kinds that expect them.
+ * @param {object} product - Product from loadQueryProduct.
+ * @param {string} id - Model node ID.
+ * @param {{history?: boolean}} [options] - Echoed into the query envelope.
+ * @returns {object} The query document.
+ */
 export function queryAnchors(product, id, { history = false } = {}) {
   const node = product.nodes.get(id);
   if (!node) {
     const lifecycleRedirect = product.lifecycleRedirects.get(id);
     if (lifecycleRedirect) return envelope(product, "anchors", id, history, { lifecycleRedirect });
-    throw new Error(`Unknown model node ${id}`);
+    throw unknownModelNodeError(product, id);
   }
 
   const declaredAnchors = [...(node.evidence ?? [])].sort(byAnchor);
@@ -167,6 +224,13 @@ export function queryAnchors(product, id, { history = false } = {}) {
   });
 }
 
+/**
+ * Answer `query spec`: the root Model node, its owned Domains, generated-view
+ * freshness, and the verification commands.
+ * @param {object} product - Product from loadQueryProduct.
+ * @param {{history?: boolean}} [options] - Echoed into the query envelope.
+ * @returns {object} The query document.
+ */
 export function querySpec(product, { history = false } = {}) {
   const root = product.nodes.get(product.rootModelId);
   if (!root) throw new Error(`Unknown model node ${product.rootModelId}`);
@@ -252,12 +316,30 @@ function generatedViews(product) {
     ["generated/graph/model-graph.json", outputs.json],
     ["generated/graph/model-graph.ndjson", outputs.ndjson],
   ]);
-  return generatedViewPaths.map((relativePath) => ({
+  return generatedPaths.map((relativePath) => ({
     path: relativePath,
-    freshness: readGeneratedView(product.root, relativePath) === expectedByPath.get(relativePath) ? "fresh" : "stale",
+    freshness:
+      relativePath === svgViewPath
+        ? svgViewFreshness(product.root)
+        : readGeneratedView(product.root, relativePath) === expectedByPath.get(relativePath)
+          ? "fresh"
+          : "stale",
   }));
 }
 
+// The canonical SVG is rendered by the async Graphviz WASM engine, so its
+// freshness is checked in a child process to keep queries synchronous
+// (mirrors the check and generate subprocesses).
+function svgViewFreshness(root) {
+  const result = spawnSync(process.execPath, [svgCheckerScript, "--root", root], { encoding: "utf8" });
+  if (result.error) {
+    throw new Error(`Failed to run the model graph SVG check for ${root}: ${result.error.message}`);
+  }
+  if (result.status === 0) return "fresh";
+  if (/missing or stale/.test(result.stderr ?? "")) return "stale";
+  throw new Error(`Failed to run the model graph SVG check for ${root}: ${(result.stderr ?? "").trim()}`);
+}
+
 function readGeneratedView(root, relativePath) {
   try {
     return readFileSync(path.join(root, relativePath), "utf8");

package/scripts/lib/product-root-resolver.mjs

@@ -1,3 +1,13 @@
+/**
+ * Resolves which product root a rootless command addresses, in priority
+ * order: explicit --root, the enclosing product root of the cwd, the
+ * productRoot pinned in .ddduck/config.json, then repository-wide discovery
+ * (a unique primary candidate, or a unique example candidate when run inside
+ * it; test/ and fixtures/ candidates are ignored, ambiguity is an error).
+ * Also owns resolveInitDestination, the init staging-name prefix, and the
+ * nonProductSourceEntries list that mutation staging excludes.
+ */
+
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { parseDocument } from "yaml";
@@ -17,6 +27,12 @@ export const nonProductSourceEntries = Object.freeze([
   ".worktrees",
 ]);
 
+/**
+ * Resolve the product root for a command: explicit root, enclosing root,
+ * configured root, or unique discovery — otherwise throw with candidates.
+ * @param {{cwd?: string, explicitRoot?: string}} [options] - Working directory and the --root override.
+ * @returns {string} The real (symlink-resolved) product root path.
+ */
 export function resolveProductRoot({ cwd = process.cwd(), explicitRoot } = {}) {
   if (explicitRoot) return validateSelectedRoot(path.resolve(cwd, explicitRoot), "Explicit product root");
 
@@ -41,9 +57,16 @@ export function resolveProductRoot({ cwd = process.cwd(), explicitRoot } = {}) {
   if (relevantExamples.length === 1) return relevantExamples[0].root;
 
   if (candidates.length > 1) throw ambiguousRoots(candidates);
+  if (candidates.length === 1) throw irrelevantCandidate(candidates[0]);
   throw new Error("No ddduck product root found; pass --root <product-root>");
 }
 
+/**
+ * Resolve where `ddduck init` publishes: the explicit destination, the
+ * configured productRoot, or `ddd` under the current directory.
+ * @param {{cwd?: string, explicitDestination?: string}} [options] - Working directory and the optional positional destination.
+ * @returns {string} Absolute destination path.
+ */
 export function resolveInitDestination({ cwd = process.cwd(), explicitDestination } = {}) {
   if (explicitDestination) return path.resolve(cwd, explicitDestination);
   const repositoryRoot = findRepositoryRoot(cwd);
@@ -134,6 +157,13 @@ function passesProductValidation(root) {
   }
 }
 
+/**
+ * Test whether a directory has the shape of a product root: a product.yaml
+ * that is a valid schemaVersion-1 Model with a model:<slug> ID, plus a model/
+ * directory. Shape only; full validation happens elsewhere.
+ * @param {string} root - Candidate directory.
+ * @returns {boolean} True when the directory looks like a product root.
+ */
 function hasProductRootShape(root) {
   try {
     const productPath = path.join(root, "product.yaml");
@@ -152,6 +182,16 @@ function hasProductRootShape(root) {
   }
 }
 
+// A repository whose only candidate is an example resolves implicitly only
+// from inside it. From anywhere else, name the candidate that was found and
+// rejected as irrelevant (mirroring the ambiguity message) instead of claiming
+// no product exists.
+function irrelevantCandidate(candidate) {
+  return new Error(
+    `No ddduck product root selected; found ${candidate.classification} candidate: ${candidate.root}${candidate.valid ? "" : " (fails validation)"}. Pass --root ${candidate.root} or run inside it.`,
+  );
+}
+
 function ambiguousRoots(candidates) {
   const roots = candidates
     .map((candidate) => `${candidate.classification}: ${candidate.root}${candidate.valid ? "" : " (fails validation)"}`)

package/scripts/lib/scan-ignore.mjs

@@ -1,8 +1,19 @@
+/**
+ * The single skip predicate shared by every ddduck repository scanner (product
+ * root discovery and the documentation reference walk), so both agree on which
+ * directory entries are invisible. Name-based and deterministic; it never
+ * reads .gitignore.
+ */
+
 export const defaultIgnoredEntryNames = Object.freeze(["node_modules"]);
 
-// A directory/file entry is skipped by every ddduck repo scanner when its
-// basename is a dot-entry, a known dependency directory, or a product-declared
-// extra ignore. Name-based and deterministic; it never reads .gitignore.
+/**
+ * Decide whether a scanner should skip a directory/file entry: dot-entries,
+ * known dependency directories, and product-declared extra ignores.
+ * @param {string} name - The entry's basename.
+ * @param {string[]} [extraNames] - Extra names from .ddduck/config.json ignore.
+ * @returns {boolean} True when the entry must be skipped.
+ */
 export function shouldIgnoreScanEntry(name, extraNames = []) {
   return name.startsWith(".") || defaultIgnoredEntryNames.includes(name) || extraNames.includes(name);
 }