ddduck 0.1.0

package/scripts/lib/product-query.mjs

@@ -0,0 +1,284 @@
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+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 { detectProductLayout, loadProductNodes } from "./product-layout.mjs";
+import { assertProductNotBusy } 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",
+];
+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("'", "'\\''")}'`;
+}
+
+export function loadQueryProduct(rootPath, { history = false } = {}) {
+  const layout = detectProductLayout(rootPath);
+  assertProductNotBusy(layout.root);
+  const check = validateProduct(layout.root, { includeDocumentation: false });
+  if (check.errors.length > 0) throw new Error(check.errors.join("\n"));
+  const loaded = loadProductNodes(layout);
+  const graph = buildModelGraph(layout.root, { history });
+  const sourcePaths = new Map(
+    [...loaded.nodeFiles].map(([id, filePath]) => [id, productRelativePath(layout.root, filePath)]),
+  );
+  const sourceFiles = new Map([...loaded.nodeSources].map(([id, source]) => [sourcePaths.get(id), source]));
+  const nodes = new Map(
+    [...loaded.nodes].filter(([, node]) => history || node.kind !== "Guarantee" || node.status === "active"),
+  );
+  const lifecycleRedirects = new Map(
+    [...loaded.nodes]
+      .filter(([, node]) => node.kind === "Guarantee" && node.status !== "active")
+      .map(([id, node]) => [
+        id,
+        {
+          id,
+          status: node.status,
+          lifecycleDecision: node.lifecycleDecision,
+          successors: [...(node.successors ?? [])].sort(),
+        },
+      ]),
+  );
+
+  return {
+    root: layout.root,
+    rootModelId: graph.modelId,
+    nodes,
+    sourcePaths,
+    sourceDigest: sourceDigestFromSources(sourceFiles),
+    edges: graph.edges,
+    lifecycleRedirects,
+    decisions: loadDecisionPaths(layout),
+    policies: [...(check.policyChecks ?? [])].sort(),
+  };
+}
+
+export function queryNode(product, id, { history = false } = {}) {
+  const node = product.nodes.get(id);
+  if (node) {
+    return envelope(product, "node", id, history, { node: renderNode(node, product.sourcePaths) });
+  }
+  const lifecycleRedirect = product.lifecycleRedirects.get(id);
+  if (lifecycleRedirect) {
+    return envelope(product, "node", id, history, { lifecycleRedirect });
+  }
+  throw new Error(`Unknown model node ${id}`);
+}
+
+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}`);
+  }
+  const incoming = product.edges
+    .filter((edge) => edge.to === id)
+    .sort(byId)
+    .map((edge) => ({ edge, node: summarizeNode(product.nodes.get(edge.from), product.sourcePaths) }));
+  const outgoing = product.edges
+    .filter((edge) => edge.from === id)
+    .sort(byId)
+    .map((edge) => ({ edge, node: summarizeNode(product.nodes.get(edge.to), product.sourcePaths) }));
+  return envelope(product, "neighbors", id, history, {
+    node: summarizeNode(node, product.sourcePaths),
+    incoming,
+    outgoing,
+  });
+}
+
+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}`);
+  }
+
+  const visited = new Set([id]);
+  const impacts = [];
+  let frontier = [id];
+  let depth = 0;
+  while (frontier.length > 0) {
+    depth += 1;
+    const candidates = frontier
+      .flatMap((targetId) => product.edges.filter((edge) => edge.to === targetId && impactEdgeKinds.has(edge.kind)))
+      .sort(byId);
+    const next = [];
+    for (const edge of candidates) {
+      if (visited.has(edge.from)) continue;
+      visited.add(edge.from);
+      impacts.push({ depth, edge, node: summarizeNode(product.nodes.get(edge.from), product.sourcePaths) });
+      next.push(edge.from);
+    }
+    frontier = next.sort();
+  }
+
+  return envelope(product, "impact", id, history, {
+    source: summarizeNode(node, product.sourcePaths),
+    impacts,
+  });
+}
+
+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}`);
+  }
+
+  const declaredAnchors = [...(node.evidence ?? [])].sort(byAnchor);
+  const decisions = reachableDecisionIds(product, id)
+    .sort()
+    .map((decisionId) => ({ id: decisionId, path: product.decisions.get(decisionId) }));
+  const declaredRoles = new Set(declaredAnchors.map((anchor) => anchor.role));
+  const expectsAnchors = evidenceAnchorKinds.has(node.kind);
+  const missingEvidence = [
+    ...(!expectsAnchors || declaredRoles.has("source") ? [] : ["source"]),
+    ...(declaredRoles.has("decision") || decisions.length > 0 ? [] : ["decision"]),
+    ...(!expectsAnchors || declaredRoles.has("verification") ? [] : ["verification"]),
+  ];
+
+  return envelope(product, "anchors", id, history, {
+    node: summarizeNode(node, product.sourcePaths),
+    declaredAnchors,
+    decisions,
+    policies: product.policies,
+    generatedViews: generatedViews(product),
+    verificationCommands: verificationCommandsFor(product),
+    missingEvidence,
+  });
+}
+
+export function querySpec(product, { history = false } = {}) {
+  const root = product.nodes.get(product.rootModelId);
+  if (!root) throw new Error(`Unknown model node ${product.rootModelId}`);
+  const ownedDomains = product.edges
+    .filter((edge) => edge.kind === "owns" && edge.from === root.id && product.nodes.get(edge.to)?.kind === "Domain")
+    .sort(byId)
+    .map((edge) => summarizeNode(product.nodes.get(edge.to), product.sourcePaths));
+
+  return envelope(product, "spec", root.id, history, {
+    root: renderNode(root, product.sourcePaths),
+    ownedDomains,
+    generatedViews: generatedViews(product),
+    verificationCommands: verificationCommandsFor(product),
+  });
+}
+
+function envelope(product, operation, id, history, result) {
+  return {
+    schemaVersion: "1",
+    query: { operation, id, history },
+    rootModelId: product.rootModelId,
+    result,
+    diagnostics: [],
+  };
+}
+
+function renderNode(node, sourcePaths) {
+  return { ...node, sourcePath: sourcePaths.get(node.id) };
+}
+
+function summarizeNode(node, sourcePaths) {
+  if (!node) throw new Error("derived graph edge endpoint is missing from the query product");
+  return {
+    id: node.id,
+    kind: node.kind,
+    name: node.name ?? null,
+    sourcePath: sourcePaths.get(node.id),
+  };
+}
+
+function loadDecisionPaths(layout) {
+  const decisions = new Map();
+  try {
+    for (const file of readdirSync(layout.decisionsDirectory).sort()) {
+      const match = file.match(/^(ADR-[0-9]{3})-.*\.md$/);
+      if (match) decisions.set(match[1], productRelativePath(layout.root, path.join(layout.decisionsDirectory, file)));
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  return decisions;
+}
+
+function reachableDecisionIds(product, id) {
+  const decisions = new Set();
+  const visited = new Set([id]);
+  let frontier = [id];
+  while (frontier.length > 0) {
+    const next = [];
+    for (const currentId of frontier) {
+      const current = product.nodes.get(currentId);
+      for (const decisionId of [
+        ...(current.decisions ?? []),
+        ...(current.lifecycleDecision ? [current.lifecycleDecision] : []),
+      ]) {
+        decisions.add(decisionId);
+      }
+      for (const edge of product.edges.filter((edge) => edge.kind === "owns" && edge.to === currentId).sort(byId)) {
+        if (visited.has(edge.from)) continue;
+        visited.add(edge.from);
+        next.push(edge.from);
+      }
+    }
+    frontier = next.sort();
+  }
+  return [...decisions];
+}
+
+function generatedViews(product) {
+  const outputs = buildModelGraphOutputs(product.root);
+  const expectedByPath = new Map([
+    ["generated/docs/model-overview.md", buildModelOverview(product.root)],
+    ["generated/graph/model-graph.json", outputs.json],
+    ["generated/graph/model-graph.ndjson", outputs.ndjson],
+  ]);
+  return generatedViewPaths.map((relativePath) => ({
+    path: relativePath,
+    freshness: readGeneratedView(product.root, relativePath) === expectedByPath.get(relativePath) ? "fresh" : "stale",
+  }));
+}
+
+function readGeneratedView(root, relativePath) {
+  try {
+    return readFileSync(path.join(root, relativePath), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+function productRelativePath(root, filePath) {
+  return path.relative(root, filePath).split(path.sep).join("/");
+}
+
+function byId(left, right) {
+  return left.id.localeCompare(right.id);
+}
+
+function byAnchor(left, right) {
+  return (
+    left.role.localeCompare(right.role) ||
+    left.path.localeCompare(right.path) ||
+    left.anchor.localeCompare(right.anchor)
+  );
+}

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

@@ -0,0 +1,167 @@
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { parseDocument } from "yaml";
+import { validateProduct } from "../check-model.mjs";
+import { findRepositoryRoot, loadDdduckConfig } from "./ddduck-config.mjs";
+import { shouldIgnoreScanEntry } from "./scan-ignore.mjs";
+
+export { findRepositoryRoot, loadDdduckConfig } from "./ddduck-config.mjs";
+
+export const initStagingPrefix = ".ddduck-init-stage-";
+export const nonProductSourceEntries = Object.freeze([
+  ".git",
+  ".ddduck",
+  "node_modules",
+  "generated",
+  ".superpowers",
+  ".worktrees",
+]);
+
+export function resolveProductRoot({ cwd = process.cwd(), explicitRoot } = {}) {
+  if (explicitRoot) return validateSelectedRoot(path.resolve(cwd, explicitRoot), "Explicit product root");
+
+  const repositoryRoot = findRepositoryRoot(cwd);
+  const enclosingRoot = findEnclosingProductRoot(cwd, repositoryRoot);
+  if (enclosingRoot) return enclosingRoot;
+
+  const config = loadDdduckConfig(repositoryRoot);
+  if (config) {
+    const configuredRoot = path.resolve(repositoryRoot, config.productRoot);
+    return validateSelectedRoot(configuredRoot, "Configured product root", config.productRoot, repositoryRoot);
+  }
+
+  const candidates = discoverProductRoots(repositoryRoot);
+  const primary = candidates.filter((candidate) => candidate.classification === "primary");
+  if (primary.length === 1) return primary[0].root;
+  if (primary.length > 1) throw ambiguousRoots(primary);
+
+  const relevantExamples = candidates.filter(
+    (candidate) => candidate.classification === "example" && isSameOrDescendant(cwd, candidate.root),
+  );
+  if (relevantExamples.length === 1) return relevantExamples[0].root;
+
+  if (candidates.length > 1) throw ambiguousRoots(candidates);
+  throw new Error("No ddduck product root found; pass --root <product-root>");
+}
+
+export function resolveInitDestination({ cwd = process.cwd(), explicitDestination } = {}) {
+  if (explicitDestination) return path.resolve(cwd, explicitDestination);
+  const repositoryRoot = findRepositoryRoot(cwd);
+  const config = loadDdduckConfig(repositoryRoot);
+  if (config) return path.resolve(repositoryRoot, config.productRoot);
+  return path.resolve(cwd, "ddd");
+}
+
+function findEnclosingProductRoot(cwd, repositoryRoot) {
+  let current = path.resolve(cwd);
+  while (isSameOrDescendant(current, repositoryRoot)) {
+    if (!path.basename(current).startsWith(initStagingPrefix) && hasProductRootShape(current)) {
+      return realpathSync(current);
+    }
+    if (current === repositoryRoot) break;
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+function discoverProductRoots(repositoryRoot) {
+  const roots = [];
+  visitDirectory(
+    repositoryRoot,
+    (directory) => {
+      if (hasProductRootShape(directory)) {
+        const classification = classifyCandidate(repositoryRoot, directory);
+        if (classification !== "ignored") {
+          roots.push({ root: realpathSync(directory), classification, valid: passesProductValidation(directory) });
+        }
+        return false;
+      }
+      return true;
+    },
+    true,
+  );
+  return roots.sort((left, right) => left.root.localeCompare(right.root));
+}
+
+// The scan-ignore predicate skips dot-entries, node_modules, generated output,
+// and staging debris. It applies only to child entries as the scan descends, not
+// to the explicitly chosen traversal root: a repository checked out under a
+// dot-prefixed directory (for example `/tmp/.scratch`) must still be scanned.
+function visitDirectory(directory, visitor, isRoot = false) {
+  const metadata = lstatSync(directory);
+  if (!metadata.isDirectory() || metadata.isSymbolicLink()) return;
+  const baseName = path.basename(directory);
+  if (
+    !isRoot &&
+    (shouldIgnoreScanEntry(baseName) || baseName === "generated" || baseName.startsWith(initStagingPrefix))
+  )
+    return;
+  if (visitor(directory) === false) return;
+  for (const entry of readdirSync(directory, { withFileTypes: true }).sort((left, right) =>
+    left.name.localeCompare(right.name),
+  )) {
+    if (entry.isDirectory() && !entry.isSymbolicLink()) visitDirectory(path.join(directory, entry.name), visitor);
+  }
+}
+
+function classifyCandidate(repositoryRoot, root) {
+  const relativePath = path.relative(repositoryRoot, root).split(path.sep).join("/");
+  if (relativePath === "") return "primary";
+  if (relativePath.startsWith("test/") || relativePath.includes("/fixtures/")) return "ignored";
+  if (relativePath.startsWith("examples/")) return "example";
+  return "primary";
+}
+
+function validateSelectedRoot(root, label, displayPath = root, containingRoot) {
+  if (hasProductRootShape(root)) {
+    const realRoot = realpathSync(root);
+    if (containingRoot) {
+      const realContainingRoot = realpathSync(containingRoot);
+      if (!isSameOrDescendant(realRoot, realContainingRoot)) {
+        throw new Error(`${label} is invalid: ${displayPath}; productRoot must stay inside the repository`);
+      }
+    }
+    return realRoot;
+  }
+  throw new Error(`${label} is invalid: ${displayPath}; pass --root <product-root>`);
+}
+
+function passesProductValidation(root) {
+  try {
+    return validateProduct(root, { includeDocumentation: false }).errors.length === 0;
+  } catch {
+    return false;
+  }
+}
+
+function hasProductRootShape(root) {
+  try {
+    const productPath = path.join(root, "product.yaml");
+    if (!existsSync(productPath) || !lstatSync(productPath).isFile()) return false;
+    if (!existsSync(path.join(root, "model")) || !lstatSync(path.join(root, "model")).isDirectory()) return false;
+    const document = parseDocument(readFileSync(productPath, "utf8"), {
+      strict: true,
+      uniqueKeys: true,
+    });
+    if (document.errors.length > 0) return false;
+    const product = document.toJSON();
+    if (!product || typeof product !== "object" || Array.isArray(product)) return false;
+    return product.schemaVersion === "1" && product.kind === "Model" && /^model:[a-z0-9][a-z0-9-]*$/.test(product.id);
+  } catch {
+    return false;
+  }
+}
+
+function ambiguousRoots(candidates) {
+  const roots = candidates
+    .map((candidate) => `${candidate.classification}: ${candidate.root}${candidate.valid ? "" : " (fails validation)"}`)
+    .join("; ");
+  return new Error(`Multiple ddduck product roots found; pass --root <product-root>. Candidates: ${roots}`);
+}
+
+function isSameOrDescendant(candidatePath, rootPath) {
+  const candidate = path.resolve(candidatePath);
+  const root = path.resolve(rootPath);
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}

package/scripts/lib/scan-ignore.mjs

@@ -0,0 +1,8 @@
+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.
+export function shouldIgnoreScanEntry(name, extraNames = []) {
+  return name.startsWith(".") || defaultIgnoredEntryNames.includes(name) || extraNames.includes(name);
+}