domain-knowledge-kit 0.1.0

package/dist/features/query/tests/searcher.test.js

@@ -0,0 +1,320 @@
+/**
+ * Tests for the SQLite FTS5 searcher.
+ *
+ * Builds a DomainModel in a temp directory, indexes it, then runs
+ * search queries and verifies results.
+ */
+import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { loadDomainModel } from "../../../shared/loader.js";
+import { DomainGraph } from "../../../shared/graph.js";
+import { buildIndex } from "../../pipeline/indexer.js";
+import { search } from "../searcher.js";
+// ── Fixture setup ─────────────────────────────────────────────────────
+const TMP = join(tmpdir(), `dkk-search-test-${Date.now()}`);
+const DOMAIN = join(TMP, "domain");
+const CONTEXTS = join(DOMAIN, "contexts");
+const ADR_DIR = join(TMP, "docs", "adr");
+const DB_PATH = join(TMP, ".domain-pack", "index.db");
+function setup() {
+    mkdirSync(join(CONTEXTS, "ordering", "events"), { recursive: true });
+    mkdirSync(join(CONTEXTS, "ordering", "commands"), { recursive: true });
+    mkdirSync(join(CONTEXTS, "ordering", "policies"), { recursive: true });
+    mkdirSync(join(CONTEXTS, "ordering", "aggregates"), { recursive: true });
+    mkdirSync(join(CONTEXTS, "ordering", "read-models"), { recursive: true });
+    mkdirSync(join(CONTEXTS, "shipping", "events"), { recursive: true });
+    mkdirSync(join(CONTEXTS, "shipping", "commands"), { recursive: true });
+    mkdirSync(join(CONTEXTS, "shipping", "aggregates"), { recursive: true });
+    mkdirSync(join(CONTEXTS, "shipping", "read-models"), { recursive: true });
+    mkdirSync(ADR_DIR, { recursive: true });
+    // domain/index.yml
+    writeFileSync(join(DOMAIN, "index.yml"), [
+        "contexts:",
+        "  - name: ordering",
+        '    description: "Order management"',
+        "  - name: shipping",
+        '    description: "Shipping logistics"',
+        "flows:",
+        "  - name: PlaceAndShip",
+        '    description: "Order to shipment"',
+        "    steps:",
+        "      - ref: ordering.PlaceOrder",
+        "        type: command",
+        "      - ref: ordering.OrderPlaced",
+        "        type: event",
+        "      - ref: shipping.ShipOrder",
+        "        type: command",
+    ].join("\n"));
+    // domain/actors.yml
+    writeFileSync(join(DOMAIN, "actors.yml"), [
+        "actors:",
+        "  - name: Customer",
+        "    type: human",
+        '    description: "A paying customer who places orders"',
+        "  - name: WarehouseBot",
+        "    type: system",
+        '    description: "Automated warehouse robot"',
+    ].join("\n"));
+    // domain/contexts/ordering/ — per-item directory
+    writeFileSync(join(CONTEXTS, "ordering", "context.yml"), [
+        "name: ordering",
+        'description: "Handles the order lifecycle"',
+        "glossary:",
+        "  - term: Order",
+        '    definition: "A customer purchase request"',
+        "    aliases:",
+        "      - Purchase",
+        "      - Booking",
+        "    adr_refs:",
+        "      - adr-0001",
+    ].join("\n"));
+    writeFileSync(join(CONTEXTS, "ordering", "events", "OrderPlaced.yml"), [
+        "name: OrderPlaced",
+        'description: "Raised when an order is placed"',
+        "fields:",
+        "  - name: orderId",
+        "    type: UUID",
+        "raised_by: Order",
+    ].join("\n"));
+    writeFileSync(join(CONTEXTS, "ordering", "events", "OrderCancelled.yml"), [
+        "name: OrderCancelled",
+        'description: "Raised when an order is cancelled"',
+        "raised_by: Order",
+    ].join("\n"));
+    writeFileSync(join(CONTEXTS, "ordering", "commands", "PlaceOrder.yml"), [
+        "name: PlaceOrder",
+        'description: "Submit a new order"',
+        "actor: Customer",
+        "handled_by: Order",
+    ].join("\n"));
+    writeFileSync(join(CONTEXTS, "ordering", "commands", "CancelOrder.yml"), [
+        "name: CancelOrder",
+        'description: "Cancel an existing order"',
+        "handled_by: Order",
+    ].join("\n"));
+    writeFileSync(join(CONTEXTS, "ordering", "policies", "NotifyOnCancel.yml"), [
+        "name: NotifyOnCancel",
+        'description: "Notify customer when order is cancelled"',
+        "when:",
+        "  events:",
+        "    - OrderCancelled",
+        "then:",
+        "  commands:",
+        "    - SendNotification",
+    ].join("\n"));
+    writeFileSync(join(CONTEXTS, "ordering", "aggregates", "Order.yml"), [
+        "name: Order",
+        'description: "Order aggregate root"',
+        "handles:",
+        "  commands:",
+        "    - PlaceOrder",
+        "    - CancelOrder",
+        "emits:",
+        "  events:",
+        "    - OrderPlaced",
+        "    - OrderCancelled",
+    ].join("\n"));
+    writeFileSync(join(CONTEXTS, "ordering", "read-models", "OrderSummary.yml"), [
+        "name: OrderSummary",
+        'description: "Summary view of all orders"',
+        "subscribes_to:",
+        "  - OrderPlaced",
+        "  - OrderCancelled",
+        "used_by:",
+        "  - Customer",
+    ].join("\n"));
+    // domain/contexts/shipping/ — per-item directory
+    writeFileSync(join(CONTEXTS, "shipping", "context.yml"), [
+        "name: shipping",
+        'description: "Handles shipment tracking"',
+    ].join("\n"));
+    writeFileSync(join(CONTEXTS, "shipping", "commands", "ShipOrder.yml"), [
+        "name: ShipOrder",
+        'description: "Initiate shipment for an order"',
+        "handled_by: Shipment",
+    ].join("\n"));
+    writeFileSync(join(CONTEXTS, "shipping", "events", "ShipmentDispatched.yml"), [
+        "name: ShipmentDispatched",
+        'description: "Raised when a shipment is dispatched"',
+        "raised_by: Shipment",
+    ].join("\n"));
+    writeFileSync(join(CONTEXTS, "shipping", "read-models", "ShipmentStatus.yml"), [
+        "name: ShipmentStatus",
+        'description: "Current status of a shipment"',
+        "subscribes_to:",
+        "  - ShipmentDispatched",
+        "used_by:",
+        "  - Customer",
+    ].join("\n"));
+    writeFileSync(join(CONTEXTS, "shipping", "aggregates", "Shipment.yml"), [
+        "name: Shipment",
+        'description: "Shipment aggregate"',
+        "handles:",
+        "  commands:",
+        "    - ShipOrder",
+        "emits:",
+        "  events:",
+        "    - ShipmentDispatched",
+    ].join("\n"));
+    // docs/adr/0001-use-yaml.md
+    writeFileSync(join(ADR_DIR, "0001-use-yaml.md"), [
+        "---",
+        "id: adr-0001",
+        "title: Use YAML for domain models",
+        "status: accepted",
+        "date: 2026-01-15",
+        "deciders:",
+        "  - Alice",
+        "domain_refs:",
+        "  - ordering.Order",
+        "---",
+        "",
+        "# ADR-0001 — Use YAML for domain models",
+        "",
+        "## Context",
+        "",
+        "We evaluated serialization formats including JSON, TOML, and YAML.",
+        "YAML provides the best human-readability for domain modeling artifacts.",
+        "",
+        "## Decision",
+        "",
+        "Adopt YAML as the canonical serialization format for all domain definitions.",
+        "",
+        "## Consequences",
+        "",
+        "Domain experts can directly read and edit model files without specialized tooling.",
+    ].join("\n"));
+    writeFileSync(join(ADR_DIR, "README.md"), "# ADRs\n");
+}
+function teardown() {
+    rmSync(TMP, { recursive: true, force: true });
+}
+// ── Assertions ────────────────────────────────────────────────────────
+let passed = 0;
+let failed = 0;
+function assert(label, condition, detail) {
+    if (condition) {
+        console.log(`  OK: ${label}`);
+        passed++;
+    }
+    else {
+        console.error(`FAIL: ${label}${detail ? ` — ${detail}` : ""}`);
+        failed++;
+    }
+}
+// ── Run tests ─────────────────────────────────────────────────────────
+setup();
+try {
+    const model = loadDomainModel({ root: TMP });
+    const graph = DomainGraph.from(model);
+    // Build index (setup for search tests)
+    buildIndex(model, { root: TMP, dbPath: DB_PATH });
+    // ── Basic FTS search ──────────────────────────────────────────────
+    console.log("\n=== Basic search ===");
+    const orderResults = search("order", {}, { dbPath: DB_PATH });
+    assert("search 'order' returns results", orderResults.length > 0);
+    assert("search 'order' includes OrderPlaced", orderResults.some((r) => r.id === "ordering.OrderPlaced"));
+    assert("search 'order' includes PlaceOrder", orderResults.some((r) => r.id === "ordering.PlaceOrder"));
+    // Verify result shape
+    const first = orderResults[0];
+    assert("result has id", typeof first.id === "string" && first.id.length > 0);
+    assert("result has type", typeof first.type === "string");
+    assert("result has name", typeof first.name === "string");
+    assert("result has excerpt", typeof first.excerpt === "string");
+    assert("result has score", typeof first.score === "number" && first.score > 0);
+    assert("result has relatedIds array", Array.isArray(first.relatedIds));
+    assert("result has adrIds array", Array.isArray(first.adrIds));
+    // ── Search actors ─────────────────────────────────────────────────
+    console.log("\n=== Search actors ===");
+    const customerResults = search("customer", {}, { dbPath: DB_PATH });
+    assert("search 'customer' returns results", customerResults.length > 0);
+    assert("search 'customer' includes actor.Customer", customerResults.some((r) => r.id === "actor.Customer"));
+    // ── Search ADRs ───────────────────────────────────────────────────
+    console.log("\n=== Search ADRs ===");
+    const yamlResults = search("YAML", {}, { dbPath: DB_PATH });
+    assert("search 'YAML' returns results", yamlResults.length > 0);
+    assert("search 'YAML' includes adr-0001", yamlResults.some((r) => r.id === "adr-0001"));
+    // ── Search ADR body content ─────────────────────────────────────
+    console.log("\n=== Search ADR body content ===");
+    const serializationResults = search("serialization", {}, { dbPath: DB_PATH });
+    assert("search 'serialization' returns results", serializationResults.length > 0);
+    assert("search 'serialization' finds adr-0001 via body content", serializationResults.some((r) => r.id === "adr-0001"));
+    const readabilityResults = search("human-readability", {}, { dbPath: DB_PATH });
+    assert("search 'human-readability' returns results", readabilityResults.length > 0);
+    assert("search 'human-readability' finds adr-0001 via body content", readabilityResults.some((r) => r.id === "adr-0001"));
+    const toolingResults = search("tooling", {}, { dbPath: DB_PATH });
+    assert("search 'tooling' returns results", toolingResults.length > 0);
+    assert("search 'tooling' finds adr-0001 via Consequences section", toolingResults.some((r) => r.id === "adr-0001"));
+    // ── Search glossary (aliases) ─────────────────────────────────────
+    console.log("\n=== Search glossary aliases ===");
+    const purchaseResults = search("purchase", {}, { dbPath: DB_PATH });
+    assert("search 'purchase' returns results", purchaseResults.length > 0);
+    assert("search 'purchase' finds glossary Order via alias", purchaseResults.some((r) => r.id === "ordering.Order" && r.type === "glossary"));
+    // ── Filter by context ─────────────────────────────────────────────
+    console.log("\n=== Filter by context ===");
+    const shippingOnly = search("shipment", { context: "shipping" }, { dbPath: DB_PATH });
+    assert("filter context=shipping returns results", shippingOnly.length > 0);
+    assert("all results are in shipping context", shippingOnly.every((r) => r.context === "shipping"));
+    // ── Filter by type ────────────────────────────────────────────────
+    console.log("\n=== Filter by type ===");
+    const eventsOnly = search("order", { type: "event" }, { dbPath: DB_PATH });
+    assert("filter type=event returns results", eventsOnly.length > 0);
+    assert("all results are events", eventsOnly.every((r) => r.type === "event"));
+    // ── Filter by tag ─────────────────────────────────────────────────
+    console.log("\n=== Filter by tag ===");
+    const humanActors = search("customer", { tag: "human" }, { dbPath: DB_PATH });
+    assert("filter tag=human returns results", humanActors.length > 0);
+    assert("tagged results include actor.Customer", humanActors.some((r) => r.id === "actor.Customer"));
+    // ── Scoring: exact ID match gets highest score ────────────────────
+    console.log("\n=== Scoring ===");
+    const exactResults = search("ordering.OrderPlaced", {}, { dbPath: DB_PATH });
+    if (exactResults.length > 0) {
+        assert("exact ID match has highest score", exactResults[0].id === "ordering.OrderPlaced" ||
+            exactResults[0].score >= exactResults[exactResults.length - 1].score);
+    }
+    // ── Graph expansion ───────────────────────────────────────────────
+    console.log("\n=== Graph expansion ===");
+    const expandedResults = search("PlaceOrder", {}, { dbPath: DB_PATH, graph, expandTopN: 3 });
+    assert("expanded search returns results", expandedResults.length > 0);
+    const placeOrderResult = expandedResults.find((r) => r.id === "ordering.PlaceOrder");
+    if (placeOrderResult) {
+        assert("expanded result has relatedIds from graph", placeOrderResult.relatedIds.length > 0);
+        assert("expanded result includes Order aggregate in relatedIds", placeOrderResult.relatedIds.includes("ordering.Order"));
+    }
+    else {
+        assert("PlaceOrder found in expanded results", false);
+    }
+    // ── Empty query ───────────────────────────────────────────────────
+    console.log("\n=== Edge cases ===");
+    const emptyResults = search("", {}, { dbPath: DB_PATH });
+    assert("empty query returns empty array", emptyResults.length === 0);
+    const whitespaceResults = search("   ", {}, { dbPath: DB_PATH });
+    assert("whitespace query returns empty array", whitespaceResults.length === 0);
+    // ── Missing index ─────────────────────────────────────────────────
+    let missingThrew = false;
+    try {
+        search("order", {}, { dbPath: join(TMP, "nonexistent.db") });
+    }
+    catch {
+        missingThrew = true;
+    }
+    assert("search with missing DB throws", missingThrew);
+    // ── Search flows ──────────────────────────────────────────────────
+    console.log("\n=== Search flows ===");
+    const flowResults = search("PlaceAndShip", {}, { dbPath: DB_PATH });
+    assert("search for flow name returns results", flowResults.length > 0);
+    assert("flow result found", flowResults.some((r) => r.id === "flow.PlaceAndShip"));
+    // ── Limit ─────────────────────────────────────────────────────────
+    console.log("\n=== Limit ===");
+    const limitResults = search("order", {}, { dbPath: DB_PATH, limit: 2 });
+    assert("limit caps results", limitResults.length <= 2);
+}
+finally {
+    teardown();
+}
+// ── Summary ───────────────────────────────────────────────────────────
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed > 0)
+    process.exit(1);
+//# sourceMappingURL=searcher.test.js.map

package/dist/features/query/tests/searcher.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"searcher.test.js","sourceRoot":"","sources":["../../../../src/features/query/tests/searcher.test.ts"],"names":[],"mappings":"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"}

package/dist/shared/adr-parser.d.ts

@@ -0,0 +1,14 @@
+import type { AdrRecord } from "./types/domain.js";
+/**
+ * Parse YAML frontmatter from a Markdown string.
+ *
+ * @returns The parsed `AdrRecord`, or `null` if no frontmatter is found.
+ */
+export declare function parseAdrFrontmatter(markdown: string): AdrRecord | null;
+/**
+ * Read an ADR Markdown file from disk and return its frontmatter.
+ *
+ * @returns The parsed `AdrRecord`, or `null` if the file has no valid frontmatter.
+ */
+export declare function parseAdrFile(filePath: string): AdrRecord | null;
+//# sourceMappingURL=adr-parser.d.ts.map

package/dist/shared/adr-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adr-parser.d.ts","sourceRoot":"","sources":["../../src/shared/adr-parser.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAgCnD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAwBtE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAG/D"}

package/dist/shared/adr-parser.js

@@ -0,0 +1,72 @@
+/**
+ * ADR frontmatter parser.
+ *
+ * Reads Markdown files from `docs/adr/` and extracts the YAML
+ * frontmatter block (delimited by `---`) into typed `AdrRecord` objects.
+ */
+import { readFileSync } from "node:fs";
+import { parseYaml } from "./yaml.js";
+/** Regex that captures the YAML block between the opening and closing `---`. */
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+/**
+ * Strip Markdown formatting from body text for cleaner search indexing.
+ *
+ * Removes heading markers, link syntax, emphasis, inline code, and
+ * fenced code-block delimiters while preserving the readable content.
+ */
+function stripMarkdown(md) {
+    return md
+        // Remove fenced code-block delimiters (``` or ~~~)
+        .replace(/^(`{3,}|~{3,}).*$/gm, "")
+        // Remove heading markers
+        .replace(/^#{1,6}\s+/gm, "")
+        // Remove images ![alt](url)
+        .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+        // Remove links [text](url)
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+        // Remove bold/italic markers
+        .replace(/\*{1,3}([^*]+)\*{1,3}/g, "$1")
+        .replace(/_{1,3}([^_]+)_{1,3}/g, "$1")
+        // Remove inline code backticks
+        .replace(/`([^`]*)`/g, "$1")
+        // Collapse multiple whitespace into single space
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/**
+ * Parse YAML frontmatter from a Markdown string.
+ *
+ * @returns The parsed `AdrRecord`, or `null` if no frontmatter is found.
+ */
+export function parseAdrFrontmatter(markdown) {
+    const match = FRONTMATTER_RE.exec(markdown);
+    if (!match)
+        return null;
+    const raw = parseYaml(match[1]);
+    // The frontmatter must at minimum contain `id`, `title`, `status`, `date`.
+    if (!raw.id || !raw.title || !raw.status || !raw.date)
+        return null;
+    // js-yaml auto-converts ISO date strings to Date objects; normalise back.
+    if (raw.date instanceof Date) {
+        raw.date = raw.date.toISOString().slice(0, 10);
+    }
+    // Extract body text after the closing ---
+    const closingIndex = markdown.indexOf("---", match.index + 3);
+    if (closingIndex !== -1) {
+        const bodyRaw = markdown.slice(closingIndex + 3).trim();
+        if (bodyRaw.length > 0) {
+            raw.body = stripMarkdown(bodyRaw);
+        }
+    }
+    return raw;
+}
+/**
+ * Read an ADR Markdown file from disk and return its frontmatter.
+ *
+ * @returns The parsed `AdrRecord`, or `null` if the file has no valid frontmatter.
+ */
+export function parseAdrFile(filePath) {
+    const content = readFileSync(filePath, "utf-8");
+    return parseAdrFrontmatter(content);
+}
+//# sourceMappingURL=adr-parser.js.map

package/dist/shared/adr-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adr-parser.js","sourceRoot":"","sources":["../../src/shared/adr-parser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,gFAAgF;AAChF,MAAM,cAAc,GAAG,6BAA6B,CAAC;AAErD;;;;;GAKG;AACH,SAAS,aAAa,CAAC,EAAU;IAC/B,OAAO,EAAE;QACP,mDAAmD;SAClD,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC;QACnC,yBAAyB;SACxB,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC;QAC5B,4BAA4B;SAC3B,OAAO,CAAC,yBAAyB,EAAE,IAAI,CAAC;QACzC,2BAA2B;SAC1B,OAAO,CAAC,wBAAwB,EAAE,IAAI,CAAC;QACxC,6BAA6B;SAC5B,OAAO,CAAC,wBAAwB,EAAE,IAAI,CAAC;SACvC,OAAO,CAAC,sBAAsB,EAAE,IAAI,CAAC;QACtC,+BAA+B;SAC9B,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC;QAC5B,iDAAiD;SAChD,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IAClD,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IAExB,MAAM,GAAG,GAAG,SAAS,CAA0B,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAEzD,2EAA2E;IAC3E,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAEnE,0EAA0E;IAC1E,IAAI,GAAG,CAAC,IAAI,YAAY,IAAI,EAAE,CAAC;QAC7B,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,0CAA0C;IAC1C,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IAC9D,IAAI,YAAY,KAAK,CAAC,CAAC,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACxD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,GAAG,CAAC,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,OAAO,GAA2B,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAChD,OAAO,mBAAmB,CAAC,OAAO,CAAC,CAAC;AACtC,CAAC"}

package/dist/shared/errors.d.ts

@@ -0,0 +1,43 @@
+/**
+ * CLI error-formatting helpers.
+ *
+ * These are presentation-infrastructure utilities used by the CLI entry
+ * point to turn raw errors into user-friendly messages.
+ */
+/**
+ * Node.js system error shape (ENOENT, EACCES, EPERM, etc.).
+ * Not all Error objects carry these, so we use a type guard.
+ */
+interface NodeSystemError extends Error {
+    code: string;
+    path?: string;
+    syscall?: string;
+}
+export declare function isNodeSystemError(err: unknown): err is NodeSystemError;
+/**
+ * js-yaml YAMLException shape.
+ * We detect by `name` rather than importing the class to keep coupling low.
+ */
+interface YAMLExceptionLike extends Error {
+    name: "YAMLException";
+    reason?: string;
+    mark?: {
+        name?: string | null;
+        line?: number;
+        column?: number;
+        snippet?: string;
+    };
+}
+export declare function isYAMLException(err: unknown): err is YAMLExceptionLike;
+/**
+ * Format an error into a user-friendly CLI message.
+ *
+ * Categories handled:
+ * - YAML parse errors  → clean "Failed to parse YAML" with location
+ * - ENOENT             → "File not found" with path
+ * - EACCES / EPERM     → "Permission denied" with path
+ * - Everything else    → the error message without a stack trace
+ */
+export declare function formatCliError(err: unknown): string;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/shared/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,UAAU,eAAgB,SAAQ,KAAK;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,eAAe,CAEtE;AAED;;;GAGG;AACH,UAAU,iBAAkB,SAAQ,KAAK;IACvC,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACnF;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,iBAAiB,CAEtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAwCnD"}

package/dist/shared/errors.js

@@ -0,0 +1,60 @@
+/**
+ * CLI error-formatting helpers.
+ *
+ * These are presentation-infrastructure utilities used by the CLI entry
+ * point to turn raw errors into user-friendly messages.
+ */
+export function isNodeSystemError(err) {
+    return err instanceof Error && typeof err.code === "string";
+}
+export function isYAMLException(err) {
+    return err instanceof Error && err.name === "YAMLException";
+}
+/**
+ * Format an error into a user-friendly CLI message.
+ *
+ * Categories handled:
+ * - YAML parse errors  → clean "Failed to parse YAML" with location
+ * - ENOENT             → "File not found" with path
+ * - EACCES / EPERM     → "Permission denied" with path
+ * - Everything else    → the error message without a stack trace
+ */
+export function formatCliError(err) {
+    // 1. YAML parse errors
+    if (isYAMLException(err)) {
+        const reason = err.reason ?? "invalid YAML syntax";
+        const mark = err.mark;
+        if (mark && mark.line != null) {
+            const file = mark.name ? `${mark.name} ` : "";
+            // js-yaml lines are 0-based; display as 1-based
+            const location = `line ${mark.line + 1}, column ${(mark.column ?? 0) + 1}`;
+            let msg = `Failed to parse YAML — ${reason} (${file}${location})`;
+            if (mark.snippet) {
+                msg += `\n${mark.snippet}`;
+            }
+            return msg;
+        }
+        return `Failed to parse YAML — ${reason}`;
+    }
+    // 2. Node.js filesystem / system errors
+    if (isNodeSystemError(err)) {
+        const filePath = err.path ? ` "${err.path}"` : "";
+        switch (err.code) {
+            case "ENOENT":
+                return `File not found:${filePath}. Check that the path exists and the domain/ directory is present.`;
+            case "EACCES":
+            case "EPERM":
+                return `Permission denied:${filePath}. Check file permissions.`;
+            case "EISDIR":
+                return `Expected a file but found a directory:${filePath}.`;
+            default:
+                return `System error (${err.code}):${filePath} — ${err.message}`;
+        }
+    }
+    // 3. Generic errors — just the message, no stack trace
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}
+//# sourceMappingURL=errors.js.map

package/dist/shared/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/shared/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,OAAO,GAAG,YAAY,KAAK,IAAI,OAAQ,GAAuB,CAAC,IAAI,KAAK,QAAQ,CAAC;AACnF,CAAC;AAYD,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,OAAO,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,eAAe,CAAC;AAC9D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,uBAAuB;IACvB,IAAI,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,qBAAqB,CAAC;QACnD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;QACtB,IAAI,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC;YAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,gDAAgD;YAChD,MAAM,QAAQ,GAAG,QAAQ,IAAI,CAAC,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3E,IAAI,GAAG,GAAG,0BAA0B,MAAM,KAAK,IAAI,GAAG,QAAQ,GAAG,CAAC;YAClE,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,GAAG,IAAI,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;YAC7B,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;QACD,OAAO,0BAA0B,MAAM,EAAE,CAAC;IAC5C,CAAC;IAED,wCAAwC;IACxC,IAAI,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;YACjB,KAAK,QAAQ;gBACX,OAAO,kBAAkB,QAAQ,oEAAoE,CAAC;YACxG,KAAK,QAAQ,CAAC;YACd,KAAK,OAAO;gBACV,OAAO,qBAAqB,QAAQ,2BAA2B,CAAC;YAClE,KAAK,QAAQ;gBACX,OAAO,yCAAyC,QAAQ,GAAG,CAAC;YAC9D;gBACE,OAAO,iBAAiB,GAAG,CAAC,IAAI,KAAK,QAAQ,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC;QACrE,CAAC;IACH,CAAC;IAED,uDAAuD;IACvD,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,OAAO,GAAG,CAAC,OAAO,CAAC;IACrB,CAAC;IAED,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC"}

package/dist/shared/graph.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Domain graph — adjacency-list representation of domain model relationships.
+ *
+ * Nodes represent every domain item (event, command, policy, aggregate,
+ * read-model, actor, ADR, flow). Edges capture the structural
+ * relationships declared in the YAML model (handles, emits, triggers,
+ * subscribes_to, actor, used_by, adr_refs, domain_refs, flow steps).
+ *
+ * The primary query surface is {@link DomainGraph.getRelated} which
+ * performs a breadth-first traversal up to a specified depth.
+ */
+import type { DomainModel } from "./types/domain.js";
+/** The kind of domain item a node represents. */
+export type NodeKind = "context" | "event" | "command" | "policy" | "aggregate" | "read_model" | "actor" | "adr" | "glossary" | "flow";
+/** A single node in the domain graph. */
+export interface GraphNode {
+    /** Unique identifier (e.g. "ordering.OrderPlaced", "actor.Customer"). */
+    id: string;
+    /** Kind of domain item. */
+    kind: NodeKind;
+    /** Human-readable display name. */
+    name: string;
+    /** Bounded-context name, when applicable. */
+    context?: string;
+}
+/** An undirected edge between two nodes. */
+export interface GraphEdge {
+    /** Source node id. */
+    from: string;
+    /** Target node id. */
+    to: string;
+    /** Describes the relationship (e.g. "handles", "emits", "adr_ref"). */
+    label: string;
+}
+/**
+ * Adjacency-list graph over every item in a {@link DomainModel}.
+ *
+ * Construct via the static factory {@link DomainGraph.from}.
+ */
+export declare class DomainGraph {
+    /** All nodes keyed by id. */
+    readonly nodes: ReadonlyMap<string, GraphNode>;
+    /** All edges. */
+    readonly edges: readonly GraphEdge[];
+    /** Adjacency list: node id → set of neighbour ids. */
+    private readonly adj;
+    private constructor();
+    /**
+     * Build a domain graph from a loaded {@link DomainModel}.
+     */
+    static from(model: DomainModel): DomainGraph;
+    /**
+     * Return the set of node ids reachable from `startId` within `depth`
+     * hops (BFS). The start node itself is **not** included unless it is
+     * reachable via a cycle within the depth limit.
+     *
+     * @param startId  The id of the node to start from.
+     * @param depth    Maximum traversal depth (default: 1).
+     * @returns A set of related node ids.
+     */
+    getRelated(startId: string, depth?: number): Set<string>;
+    /**
+     * Return direct neighbours of a node (shorthand for depth-1 traversal).
+     */
+    getNeighbours(nodeId: string): Set<string>;
+    /**
+     * Check whether a node id exists in the graph.
+     */
+    hasNode(id: string): boolean;
+}
+//# sourceMappingURL=graph.d.ts.map

package/dist/shared/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/shared/graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAsD,MAAM,mBAAmB,CAAC;AAMzG,iDAAiD;AACjD,MAAM,MAAM,QAAQ,GAChB,SAAS,GACT,OAAO,GACP,SAAS,GACT,QAAQ,GACR,WAAW,GACX,YAAY,GACZ,OAAO,GACP,KAAK,GACL,UAAU,GACV,MAAM,CAAC;AAEX,yCAAyC;AACzC,MAAM,WAAW,SAAS;IACxB,yEAAyE;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B;IAC3B,IAAI,EAAE,QAAQ,CAAC;IACf,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,4CAA4C;AAC5C,MAAM,WAAW,SAAS;IACxB,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;CACf;AAqBD;;;;GAIG;AACH,qBAAa,WAAW;IACtB,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC/C,iBAAiB;IACjB,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IAErC,sDAAsD;IACtD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA2B;IAE/C,OAAO;IAYP;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW;IAkL5C;;;;;;;;OAQG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,MAAU,GAAG,GAAG,CAAC,MAAM,CAAC;IAwB3D;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAI1C;;OAEG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;CAG7B"}