ddduck 0.1.0

package/scripts/lib/agent-readiness-report.mjs

@@ -0,0 +1,79 @@
+import { validateProduct } from "../check-model.mjs";
+import { loadQueryProduct, queryAnchors, querySpec } from "./product-query.mjs";
+
+const ownershipKinds = new Set(["Concept", "DomainInterface", "Guarantee"]);
+
+export function generateAgentReadinessReport(rootPath) {
+  const check = validateProduct(rootPath, { includeDocumentation: false });
+  if (check.errors.length > 0) {
+    return { unresolvedReferences: [...check.errors].sort(compareStrings) };
+  }
+
+  const product = loadQueryProduct(rootPath);
+  const ownedNodes = [...product.nodes.values()].filter(({ kind }) => ownershipKinds.has(kind)).sort(byId);
+  const ownersByNode = collectOwners(product);
+
+  const missingEvidence = [...product.nodes.values()]
+    .sort(byId)
+    .map((node) => {
+      const result = queryAnchors(product, node.id).result;
+      return {
+        id: result.node.id,
+        kind: result.node.kind,
+        sourcePath: result.node.sourcePath,
+        missingRoles: result.missingEvidence,
+      };
+    })
+    .filter(({ missingRoles }) => missingRoles.length > 0);
+  const staleGeneratedViews = querySpec(product)
+    .result.generatedViews.filter(({ freshness }) => freshness !== "fresh")
+    .sort(byPath);
+  const orphanedNodes = ownedNodes
+    .filter(({ id }) => (ownersByNode.get(id)?.size ?? 0) === 0)
+    .map((node) => summarizeNode(node, product));
+  const ambiguousOwnership = ownedNodes
+    .filter(({ id }) => (ownersByNode.get(id)?.size ?? 0) > 1)
+    .map((node) => ({
+      ...summarizeNode(node, product),
+      ownerDomains: [...ownersByNode.get(node.id)].sort(compareStrings),
+    }));
+
+  return {
+    missingEvidence,
+    unresolvedReferences: [],
+    staleGeneratedViews,
+    orphanedNodes,
+    ambiguousOwnership,
+  };
+}
+
+function collectOwners(product) {
+  const ownersByNode = new Map();
+  for (const edge of product.edges.filter(({ kind }) => kind === "owns")) {
+    if (product.nodes.get(edge.from)?.kind !== "Domain") continue;
+    if (!product.nodes.has(edge.to)) continue;
+    if (!ownersByNode.has(edge.to)) ownersByNode.set(edge.to, new Set());
+    ownersByNode.get(edge.to).add(edge.from);
+  }
+  return ownersByNode;
+}
+
+function summarizeNode(node, product) {
+  return {
+    id: node.id,
+    kind: node.kind,
+    sourcePath: product.sourcePaths.get(node.id),
+  };
+}
+
+function byId(left, right) {
+  return compareStrings(left.id, right.id);
+}
+
+function byPath(left, right) {
+  return compareStrings(left.path, right.path);
+}
+
+function compareStrings(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}

package/scripts/lib/cli-contract.mjs

@@ -0,0 +1,162 @@
+export class CliUsageError extends Error {
+  constructor(message, { nextAction } = {}) {
+    super(message);
+    this.name = "CliUsageError";
+    if (nextAction !== undefined) this.nextAction = nextAction;
+  }
+}
+
+export function parseCommandArgs(args, { positionals = {}, options = {} } = {}) {
+  const minimum = positionals.min ?? 0;
+  const maximum = positionals.max ?? minimum;
+  const parsed = {};
+  for (const [name, definition] of Object.entries(options)) {
+    if (!definition.value) parsed[name] = false;
+    if (definition.repeatable) parsed[name] = [];
+  }
+  const values = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (!argument.startsWith("--")) {
+      values.push(argument);
+      continue;
+    }
+    const separatorIndex = argument.indexOf("=");
+    const name = separatorIndex === -1 ? argument.slice(2) : argument.slice(2, separatorIndex);
+    const inlineValue = separatorIndex === -1 ? undefined : argument.slice(separatorIndex + 1);
+    const definition = options[name];
+    if (!definition) throw new CliUsageError(`Unknown option --${name}`);
+    if (!definition.repeatable && (definition.value ? parsed[name] !== undefined : parsed[name])) {
+      throw new CliUsageError(`Duplicate option --${name}`);
+    }
+    if (!definition.value) {
+      if (inlineValue !== undefined) throw new CliUsageError(`Option --${name} does not take a value`);
+      parsed[name] = true;
+      continue;
+    }
+    const value = inlineValue ?? args[index + 1];
+    if (value === undefined || value === "") throw new CliUsageError(`Missing value for --${name}`);
+    if (inlineValue === undefined && value.startsWith("--")) {
+      throw new CliUsageError(`Missing value for --${name}; pass values starting with -- as --${name}=<value>`);
+    }
+    if (definition.repeatable) parsed[name].push(value);
+    else parsed[name] = value;
+    if (inlineValue === undefined) index += 1;
+  }
+
+  if (values.length < minimum || values.length > maximum) {
+    const expected = minimum === maximum ? minimum : `${minimum}-${maximum}`;
+    const usage = positionals.syntax ? `; usage: ${positionals.syntax}` : "";
+    throw new CliUsageError(
+      `Expected ${expected} positional argument${minimum === 1 && maximum === 1 ? "" : "s"}${usage}`,
+    );
+  }
+  return { positionals: values, options: parsed };
+}
+
+export function renderHelp(command) {
+  const usage = {
+    undefined: [
+      "Usage: ddduck <command> [options]",
+      "Commands: init, check, generate, query, install, create, move, split, retire.",
+      "Run `ddduck <command> --help` for command usage.",
+    ],
+    init: [
+      "Syntax: ddduck init [destination] --id model:<product-id> [--json]",
+      "Defaults: destination is the productRoot configured in .ddduck/config.json, else ddd.",
+      "Writes: product.yaml, canonical directories, and all generated views in the new product root.",
+      "Success output: one text result with root, Model ID, canonical paths, and generated paths.",
+      "Exit status: 0 on success or help; nonzero if input is invalid or the destination is not empty.",
+      "JSON: --json emits the same result as one JSON object.",
+    ],
+    check: [
+      "Syntax: ddduck check [--root <product-root>] [--base <previous-product-root>] [--docs-root <docs-root> ...] [--source-only]",
+      "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery); --base is unset; documentation references are checked inside the product root unless --docs-root replaces that scope; generated freshness is checked.",
+      "Writes: nothing.",
+      "Success output: none.",
+      "Exit status: 0 on a valid fresh product or help; nonzero on invalid source, stale views, leftover interrupted-operation state, or invalid input.",
+      "JSON: unavailable; --json is not accepted.",
+    ],
+    generate: [
+      "Syntax: ddduck generate [--root <product-root>] [--json]",
+      "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery); text output is used.",
+      "Writes: all required generated docs and graph views after staged validation.",
+      "Success output: one text result with the root and refreshed generated paths.",
+      "Exit status: 0 on publication or help; nonzero with no intended product changes on failure.",
+      "JSON: --json emits the same result as one JSON object.",
+    ],
+    query: [
+      "Syntax: ddduck query <node|neighbors|impact|anchors|spec|context> [options] [--json]",
+      "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery) except context requires it; --history is false.",
+      "Writes: nothing.",
+      "Success output: exactly one JSON query document.",
+      "Exit status: 0 on a resolved query or help; nonzero on invalid input, product, or selection.",
+      "JSON: output is always JSON; --json is accepted and has no effect.",
+      "Options: --id <model-node-id> (repeatable for context), --root <product-root>, --history.",
+    ],
+    install: [
+      "Syntax: ddduck install skill update-ddduck-specs [--repo <repository-root>]",
+      "Defaults: --repo is the current directory.",
+      "Writes: the selected host skill adapter and .ddduck/agent-skills.lock.json in --repo.",
+      "Success output: one text result with the action (created, upgraded, or no-op), repository, canonical path, and lock path.",
+      "Exit status: 0 on installation, no-op, or help; nonzero on invalid input or conflicting host state.",
+      "JSON: unavailable; --json is not accepted.",
+    ],
+    create: [
+      "Syntax: ddduck create guarantee --origin <origin> --classification <invariant|acceptance-criterion> --owner <domain-id> --statement <text> [--root <product-root>] [--json]",
+      "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery); the next origin/classification serial is allocated.",
+      "Writes: the new Guarantee, its owning Domain, and all generated views through staged publication.",
+      "Success output: one text result with the allocated ID, root, canonical paths, and generated paths.",
+      "Exit status: 0 on publication or help; nonzero with no intended product changes on failure.",
+      "JSON: --json emits the same result as one JSON object.",
+    ],
+    move: [
+      "Syntax: ddduck move guarantee <guarantee-id> --to <domain-id> [--root <product-root>] [--json]",
+      "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery).",
+      "Writes: the Guarantee, affected Domains, and all generated views through staged publication.",
+      "Success output: one text result with affected IDs, root, canonical paths, and generated paths.",
+      "Exit status: 0 on publication or help; nonzero with no intended product changes on failure.",
+      "JSON: --json emits the same result as one JSON object.",
+    ],
+    split: [
+      "Syntax: ddduck split guarantee <guarantee-id> --into <successor-id,successor-id> --decision ADR-NNN [--root <product-root>] [--json]",
+      "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery).",
+      "Writes: the source Guarantee lifecycle state and all generated views through staged publication.",
+      "Success output: one text result with affected IDs, root, canonical paths, and generated paths.",
+      "Exit status: 0 on publication or help; nonzero with no intended product changes on failure.",
+      "JSON: --json emits the same result as one JSON object.",
+    ],
+    retire: [
+      "Syntax: ddduck retire guarantee <guarantee-id> --decision ADR-NNN [--root <product-root>] [--json]",
+      "Defaults: --root is the resolved product root (enclosing directory, config, or unique discovery).",
+      "Writes: the Guarantee lifecycle state and all generated views through staged publication.",
+      "Success output: one text result with affected IDs, root, canonical paths, and generated paths.",
+      "Exit status: 0 on publication or help; nonzero with no intended product changes on failure.",
+      "JSON: --json emits the same result as one JSON object.",
+    ],
+    "audit-fr-to-code": [
+      "Usage: audit-fr-to-code --input <audit.yaml> --source-root <source-id>=<checkout> [--source-root <source-id>=<checkout> ...] --json",
+    ],
+  };
+  return `${(usage[command] ?? usage.undefined).join("\n")}\n`;
+}
+
+export function formatCliError(error, { nextAction } = {}) {
+  const message = error instanceof Error ? error.message : String(error);
+  const action = error?.nextAction ?? nextAction ?? "Review the diagnostic, correct the input, and retry.";
+  const lines = message
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => line.length > 0);
+  if (lines.length <= 1) {
+    const safeMessage = (lines[0] ?? "").replace(/[.\s]+$/, "");
+    return `Error: ${safeMessage}. Next: ${action}`;
+  }
+  return [`Error: ${lines[0]}`, ...lines.slice(1), `Next: ${action}`].join("\n");
+}
+
+export function writeCliError(error, { stderr = process.stderr, nextAction } = {}) {
+  stderr.write(`${formatCliError(error, { nextAction })}\n`);
+  process.exitCode = 1;
+}

package/scripts/lib/context-pack.mjs

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+export function resolveContextPack(product, selectedIds) {
+  const ids = validateSelectedIds(product, selectedIds);
+  const selectedSet = new Set(ids);
+  const selected = ids.map((id) => renderNode(product.nodes.get(id), product.sourcePaths));
+  const edges = directEdges(product.edges, selectedSet);
+  const neighbors = summarizeUnselectedEndpoints(product, selectedSet, edges);
+
+  return {
+    schemaVersion: "1",
+    query: { operation: "context", ids, history: false },
+    rootModelId: product.rootModelId,
+    snapshot: { algorithm: "sha256", sourceDigest: product.sourceDigest },
+    result: { selected, edges, neighbors },
+    diagnostics: [],
+  };
+}
+
+export function sourceDigest(root, sourcePaths) {
+  const sources = new Map(
+    [...new Set(sourcePaths.values())].map((relativePath) => [
+      relativePath,
+      readFileSync(path.resolve(root, relativePath)),
+    ]),
+  );
+  return sourceDigestFromSources(sources);
+}
+
+export function sourceDigestFromSources(sources) {
+  const hash = createHash("sha256");
+  for (const relativePath of [...sources.keys()].sort(byString)) {
+    hash.update(relativePath, "utf8");
+    hash.update("\0", "utf8");
+    hash.update(sources.get(relativePath));
+    hash.update("\0", "utf8");
+  }
+  return hash.digest("hex");
+}
+
+function validateSelectedIds(product, selectedIds) {
+  if (!Array.isArray(selectedIds)) throw new Error("Context pack selection must be an array of IDs");
+  if (selectedIds.length === 0) throw new Error("Context pack requires at least one selected ID");
+  if (selectedIds.some((id) => typeof id !== "string" || id.length === 0)) {
+    throw new Error("Context pack selection must contain non-empty string IDs");
+  }
+
+  const ids = [...selectedIds].sort(byString);
+  for (let index = 1; index < ids.length; index += 1) {
+    if (ids[index] === ids[index - 1]) throw new Error(`Context pack selection contains duplicate ID ${ids[index]}`);
+  }
+
+  for (const id of ids) {
+    const node = product.nodes.get(id);
+    if (node) {
+      if (node.kind === "Guarantee" && node.status !== "active") {
+        throw new Error(`Cannot select inactive model node ${id} (${node.status})`);
+      }
+      continue;
+    }
+    const lifecycleRedirect = product.lifecycleRedirects.get(id);
+    if (lifecycleRedirect) {
+      throw new Error(`Cannot select inactive model node ${id} (${lifecycleRedirect.status})`);
+    }
+    throw new Error(`Unknown model node ${id}`);
+  }
+  return ids;
+}
+
+function directEdges(edges, selectedIds) {
+  const edgeById = new Map();
+  for (const edge of edges) {
+    if ((selectedIds.has(edge.from) || selectedIds.has(edge.to)) && !edgeById.has(edge.id)) {
+      edgeById.set(edge.id, edge);
+    }
+  }
+  return [...edgeById.values()].sort((left, right) => byString(left.id, right.id));
+}
+
+function summarizeUnselectedEndpoints(product, selectedIds, edges) {
+  const neighborIds = new Set();
+  for (const edge of edges) {
+    if (!selectedIds.has(edge.from)) neighborIds.add(edge.from);
+    if (!selectedIds.has(edge.to)) neighborIds.add(edge.to);
+  }
+  return [...neighborIds].sort(byString).map((id) => summarizeNode(product.nodes.get(id), product.sourcePaths));
+}
+
+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 byString(left, right) {
+  return left.localeCompare(right);
+}

package/scripts/lib/ddduck-config.mjs

@@ -0,0 +1,57 @@
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+const configRelativePath = path.join(".ddduck", "config.json");
+
+export const defaultConfigIgnore = Object.freeze(["vendor", "target", "build", "dist", "__pycache__"]);
+
+export function findRepositoryRoot(startPath = process.cwd()) {
+  let current = path.resolve(startPath);
+  if (existsSync(current) && !lstatSync(current).isDirectory()) current = path.dirname(current);
+  while (true) {
+    if (existsSync(path.join(current, ".git"))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(startPath);
+    current = parent;
+  }
+}
+
+export function loadDdduckConfig(repositoryRoot) {
+  const configPath = path.join(repositoryRoot, configRelativePath);
+  if (!existsSync(configPath)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(configPath, "utf8"));
+  } catch (error) {
+    throw new Error(`${configRelativePath}: invalid JSON: ${error.message}`);
+  }
+  if (parsed?.schemaVersion !== "1") throw new Error(`${configRelativePath}: schemaVersion must be "1"`);
+  if (typeof parsed.productRoot !== "string" || parsed.productRoot.length === 0) {
+    throw new Error(`${configRelativePath}: productRoot must be a non-empty string`);
+  }
+  if (path.isAbsolute(parsed.productRoot) || parsed.productRoot.split(/[\\/]+/).includes("..")) {
+    throw new Error(`${configRelativePath}: productRoot must stay inside the repository`);
+  }
+  const config = { schemaVersion: "1", productRoot: parsed.productRoot };
+  if (parsed.ignore !== undefined) {
+    if (!Array.isArray(parsed.ignore)) {
+      throw new Error(`${configRelativePath}: ignore must be an array of directory names`);
+    }
+    for (const entry of parsed.ignore) {
+      if (typeof entry !== "string" || entry.length === 0) {
+        throw new Error(`${configRelativePath}: ignore entries must be non-empty strings`);
+      }
+      if (entry.includes("/") || entry.includes("\\") || entry === "." || entry === "..") {
+        throw new Error(`${configRelativePath}: ignore entries must be plain directory names`);
+      }
+    }
+    config.ignore = parsed.ignore;
+  }
+  return config;
+}
+
+export function resolveConfiguredIgnores(repositoryRoot) {
+  const config = loadDdduckConfig(repositoryRoot);
+  if (!config || config.ignore === undefined) return [...defaultConfigIgnore];
+  return config.ignore;
+}

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

@@ -0,0 +1,144 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import Ajv2020 from "ajv/dist/2020.js";
+
+const auditSchema = JSON.parse(
+  readFileSync(
+    path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../schemas/fr-to-code-audit.schema.json"),
+    "utf8",
+  ),
+);
+const validateAudit = new Ajv2020({ allErrors: true, strict: true }).compile(auditSchema);
+
+export function verifyFrToCodeAudit(record, sourceReader) {
+  const normalized = validateRecord(record);
+  requireReader(sourceReader);
+  const sourcesById = new Map(normalized.sources.map((source) => [source.id, source]));
+  const requirementSource = requireSource(sourcesById, normalized.requirement.sourceId);
+  const requirementPath = requireRelativePath(normalized.requirement.sourcePath, "requirement source path");
+  const requirementText = sourceReader.readFile(requirementSource, requirementPath);
+  requireText(requirementText, normalized.requirement.id, "requirement ID");
+  if (normalized.requirement.tracedGuarantee) {
+    requireText(requirementText, normalized.requirement.tracedGuarantee, "traced guarantee");
+  }
+
+  const productionAnchors = renderAnchors(normalized.productionAnchors, sourcesById, sourceReader);
+  const testAnchors = renderAnchors(normalized.testAnchors, sourcesById, sourceReader);
+  validateVerdict(normalized.verdict, productionAnchors, testAnchors);
+  return renderReport(normalized, productionAnchors, testAnchors);
+}
+
+function validateRecord(record) {
+  if (!validateAudit(record)) {
+    throw new Error(`FrToCodeAudit must match the audit schema: ${validateAudit.errors[0].message}`);
+  }
+  if (record.sources.some((source, index) => record.sources.findIndex(({ id }) => id === source.id) !== index)) {
+    throw new Error("FrToCodeAudit sources must have unique IDs");
+  }
+  for (const anchor of [...record.productionAnchors, ...record.testAnchors]) {
+    if (anchor.endLine < anchor.startLine) {
+      throw new Error("FrToCodeAudit anchor endLine must be greater than or equal to startLine");
+    }
+  }
+  return JSON.parse(JSON.stringify(record));
+}
+
+function requireReader(sourceReader) {
+  if (!sourceReader || typeof sourceReader.readFile !== "function") {
+    throw new Error("FrToCodeAudit sourceReader must provide readFile(source, relativePath)");
+  }
+}
+
+function requireSource(sourcesById, sourceId) {
+  const source = sourcesById.get(sourceId);
+  if (!source) throw new Error(`FrToCodeAudit references undeclared source ID ${sourceId}`);
+  return source;
+}
+
+function requireRelativePath(relativePath, label) {
+  if (path.posix.isAbsolute(relativePath) || relativePath.split("/").includes("..")) {
+    throw new Error(`FrToCodeAudit ${label} must be source-relative without lexical escapes`);
+  }
+  return relativePath;
+}
+
+function requireText(text, value, label) {
+  if (typeof text !== "string") throw new Error(`FrToCodeAudit source reader must return text for ${label}`);
+  if (!text.includes(value)) throw new Error(`FrToCodeAudit ${label} ${value} is missing from its source file`);
+}
+
+function renderAnchors(anchors, sourcesById, sourceReader) {
+  return anchors
+    .map((anchor) => {
+      const source = requireSource(sourcesById, anchor.sourceId);
+      const relativePath = requireRelativePath(anchor.path, "anchor path");
+      const text = sourceReader.readFile(source, relativePath);
+      if (typeof text !== "string")
+        throw new Error(`FrToCodeAudit source reader must return text for ${anchor.sourceId}:${relativePath}`);
+      const lines = text.split("\n");
+      const lineCount = lines.at(-1) === "" ? lines.length - 1 : lines.length;
+      if (anchor.endLine > lineCount) {
+        throw new Error(
+          `FrToCodeAudit anchor ${anchor.startLine}-${anchor.endLine} is outside ${anchor.sourceId}:${relativePath}`,
+        );
+      }
+      const excerpt = lines.slice(anchor.startLine - 1, anchor.endLine).join("\n");
+      return {
+        sourceId: anchor.sourceId,
+        path: relativePath,
+        startLine: anchor.startLine,
+        endLine: anchor.endLine,
+        excerptDigest: { algorithm: "sha256", value: digest(excerpt) },
+      };
+    })
+    .sort(byAnchor);
+}
+
+function validateVerdict(verdict, productionAnchors, testAnchors) {
+  if (verdict === "realized-and-tested" && (productionAnchors.length === 0 || testAnchors.length === 0)) {
+    throw new Error("FrToCodeAudit realized-and-tested requires production and test anchors");
+  }
+  if (verdict === "realized-untested" && (productionAnchors.length === 0 || testAnchors.length !== 0)) {
+    throw new Error("FrToCodeAudit realized-untested requires production anchors and no test anchors");
+  }
+  if (verdict === "unrealized" && (productionAnchors.length !== 0 || testAnchors.length !== 0)) {
+    throw new Error("FrToCodeAudit unrealized permits no production or test anchors");
+  }
+}
+
+function renderReport(record, productionAnchors, testAnchors) {
+  return {
+    schemaVersion: "1",
+    kind: "FrToCodeAuditReport",
+    audit: { id: record.id },
+    sources: [...record.sources].sort((left, right) => compareLexical(left.id, right.id)),
+    requirement: record.requirement,
+    coverage: record.coverage,
+    verdict: record.verdict,
+    productionAnchors,
+    testAnchors,
+    reviewerDisposition: record.reviewerDisposition,
+    diagnostics: [],
+  };
+}
+
+function digest(text) {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+function byAnchor(left, right) {
+  return (
+    compareLexical(left.sourceId, right.sourceId) ||
+    compareLexical(left.path, right.path) ||
+    left.startLine - right.startLine ||
+    left.endLine - right.endLine
+  );
+}
+
+function compareLexical(left, right) {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}

package/scripts/lib/product-layout.mjs

@@ -0,0 +1,93 @@
+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 function detectProductLayout(rootPath) {
+  const root = path.resolve(rootPath);
+  return {
+    root,
+    productPath: path.join(root, "product.yaml"),
+    nodeDirectories,
+    decisionsDirectory: path.join(root, "decisions"),
+    generatedDirectory: path.join(root, "generated"),
+  };
+}
+
+export function loadProductNodes(layout) {
+  const nodes = new Map();
+  const nodeFiles = new Map();
+  const nodeSources = new Map();
+  const files = productFiles(layout);
+
+  for (const filePath of files) {
+    const source = readFileSync(filePath);
+    const node = parseYamlMapping(filePath, source.toString("utf8"));
+    if (nodes.has(node.id)) {
+      throw new Error(`duplicate model node ${node.id}`);
+    }
+    nodes.set(node.id, node);
+    nodeFiles.set(node.id, filePath);
+    nodeSources.set(node.id, source);
+  }
+
+  return { nodes, nodeFiles, nodeSources };
+}
+
+export function loadProductSnapshot(layout) {
+  const loaded = loadProductNodes(layout);
+  const nodes = Object.freeze([...loaded.nodes.values()].map((node) => deepFreeze(node)));
+  const canonicalPaths = Object.freeze(
+    Object.fromEntries(
+      [...loaded.nodeFiles].map(([id, filePath]) => [
+        id,
+        path.relative(layout.root, filePath).split(path.sep).join("/"),
+      ]),
+    ),
+  );
+  return Object.freeze({ nodes, canonicalPaths });
+}
+
+export function parseYamlMapping(filePath, source = readFileSync(filePath, "utf8")) {
+  const document = parseDocument(source, { keepSourceTokens: true, strict: true, uniqueKeys: true });
+  if (document.errors.length > 0) {
+    throw new Error(`invalid YAML in ${filePath}: ${document.errors.map((error) => error.message).join("; ")}`);
+  }
+  const value = document.toJSON();
+  if (!isPlainObject(value)) {
+    throw new Error(`model node file must contain a YAML mapping: ${filePath}`);
+  }
+  return value;
+}
+
+function productFiles(layout) {
+  return [
+    layout.productPath,
+    ...layout.nodeDirectories.flatMap((directory) => listYamlFiles(path.join(layout.root, "model", directory))),
+  ];
+}
+
+function listYamlFiles(directory) {
+  try {
+    return readdirSync(directory)
+      .filter((file) => file.endsWith(".yaml"))
+      .sort()
+      .map((file) => path.join(directory, file));
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function deepFreeze(value) {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}