ddduck 0.1.0 → 0.1.2

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, 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,56 @@ 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 {
+      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 +498,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");

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);
 }