domain-knowledge-kit 0.1.0

package/dist/shared/graph.js

@@ -0,0 +1,250 @@
+/**
+ * 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 { forEachItem, itemAdrRefs } from "./item-visitor.js";
+// ── Helpers ───────────────────────────────────────────────────────────
+/** Build scoped id for a context-local item. */
+function scopedId(context, name) {
+    return `${context}.${name}`;
+}
+/** Build id for an actor. */
+function actorId(name) {
+    return `actor.${name}`;
+}
+/** Build id for a flow. */
+function flowId(name) {
+    return `flow.${name}`;
+}
+// ── DomainGraph ───────────────────────────────────────────────────────
+/**
+ * Adjacency-list graph over every item in a {@link DomainModel}.
+ *
+ * Construct via the static factory {@link DomainGraph.from}.
+ */
+export class DomainGraph {
+    /** All nodes keyed by id. */
+    nodes;
+    /** All edges. */
+    edges;
+    /** Adjacency list: node id → set of neighbour ids. */
+    adj;
+    constructor(nodes, edges, adj) {
+        this.nodes = nodes;
+        this.edges = edges;
+        this.adj = adj;
+    }
+    // ── Factory ───────────────────────────────────────────────────────
+    /**
+     * Build a domain graph from a loaded {@link DomainModel}.
+     */
+    static from(model) {
+        const nodes = new Map();
+        const edges = [];
+        const adj = new Map();
+        /** Ensure a node exists and return its id. */
+        function ensureNode(id, kind, name, context) {
+            const existing = nodes.get(id);
+            if (!existing) {
+                nodes.set(id, { id, kind, name, context });
+                adj.set(id, new Set());
+            }
+            else if (existing.kind === "glossary" && kind !== "glossary") {
+                // Structural kinds (aggregate, event, command, etc.) take precedence
+                // over glossary when both share the same scoped ID within a context.
+                existing.kind = kind;
+            }
+            return id;
+        }
+        /** Add an undirected edge (both directions in the adjacency list). */
+        function addEdge(from, to, label) {
+            edges.push({ from, to, label });
+            adj.get(from)?.add(to);
+            adj.get(to)?.add(from);
+        }
+        /** Wire adr_refs for any item. */
+        function wireAdrRefs(itemId, adrRefs) {
+            if (!adrRefs)
+                return;
+            for (const ref of adrRefs) {
+                // ADR node might not exist yet if the ADR file wasn't present;
+                // we still create a placeholder node so the edge is recorded.
+                ensureNode(ref, "adr", ref);
+                addEdge(itemId, ref, "adr_ref");
+            }
+        }
+        // ── Actors ────────────────────────────────────────────────────
+        for (const actor of model.actors) {
+            const id = ensureNode(actorId(actor.name), "actor", actor.name);
+            wireAdrRefs(id, actor.adr_refs);
+        }
+        // ── Bounded contexts & their items ────────────────────────────
+        for (const [ctxName, ctx] of model.contexts) {
+            const ctxId = ensureNode(`context.${ctxName}`, "context", ctxName);
+            wireAdrRefs(ctxId, undefined); // contexts don't have adr_refs currently
+            // Visit all item types: create node, add contains edge, wire ADR refs,
+            // then apply type-specific relationship wiring.
+            forEachItem(ctx, (type, name, item) => {
+                const nodeKind = type;
+                const id = ensureNode(scopedId(ctxName, name), nodeKind, name, ctxName);
+                addEdge(ctxId, id, "contains");
+                wireAdrRefs(id, itemAdrRefs(item));
+                // Type-specific relationship wiring
+                switch (type) {
+                    case "event": {
+                        const evt = item;
+                        if (evt.raised_by) {
+                            const aggId = ensureNode(scopedId(ctxName, evt.raised_by), "aggregate", evt.raised_by, ctxName);
+                            addEdge(aggId, id, "emits");
+                        }
+                        break;
+                    }
+                    case "command": {
+                        const cmd = item;
+                        if (cmd.handled_by) {
+                            const aggId = ensureNode(scopedId(ctxName, cmd.handled_by), "aggregate", cmd.handled_by, ctxName);
+                            addEdge(aggId, id, "handles");
+                        }
+                        if (cmd.actor) {
+                            const aId = ensureNode(actorId(cmd.actor), "actor", cmd.actor);
+                            addEdge(aId, id, "initiates");
+                        }
+                        break;
+                    }
+                    case "policy": {
+                        const pol = item;
+                        for (const trigger of pol.when?.events ?? []) {
+                            const evtId = ensureNode(scopedId(ctxName, trigger), "event", trigger, ctxName);
+                            addEdge(evtId, id, "triggers");
+                        }
+                        for (const emitted of pol.then?.commands ?? []) {
+                            const cmdId = ensureNode(scopedId(ctxName, emitted), "command", emitted, ctxName);
+                            addEdge(id, cmdId, "emits");
+                        }
+                        break;
+                    }
+                    case "aggregate": {
+                        const agg = item;
+                        for (const h of agg.handles?.commands ?? []) {
+                            const cmdId = ensureNode(scopedId(ctxName, h), "command", h, ctxName);
+                            addEdge(id, cmdId, "handles");
+                        }
+                        for (const e of agg.emits?.events ?? []) {
+                            const evtId = ensureNode(scopedId(ctxName, e), "event", e, ctxName);
+                            addEdge(id, evtId, "emits");
+                        }
+                        break;
+                    }
+                    case "read_model": {
+                        const rm = item;
+                        for (const sub of rm.subscribes_to ?? []) {
+                            const evtId = ensureNode(scopedId(ctxName, sub), "event", sub, ctxName);
+                            addEdge(id, evtId, "subscribes_to");
+                        }
+                        for (const user of rm.used_by ?? []) {
+                            const aId = ensureNode(actorId(user), "actor", user);
+                            addEdge(id, aId, "used_by");
+                        }
+                        break;
+                    }
+                    case "glossary":
+                        // Glossary items have no type-specific relationship wiring.
+                        break;
+                }
+            });
+        }
+        // ── ADRs ──────────────────────────────────────────────────────
+        for (const [adrId, adr] of model.adrs) {
+            ensureNode(adrId, "adr", adr.title);
+            // domain_refs → domain items
+            for (const ref of adr.domain_refs ?? []) {
+                // ref is in "context.Name" format — ensure node exists
+                const dotIdx = ref.indexOf(".");
+                if (dotIdx > 0) {
+                    const ctx = ref.slice(0, dotIdx);
+                    const name = ref.slice(dotIdx + 1);
+                    // We don't know the item kind from the ref alone; default to
+                    // a generic node that will be reconciled if it was already created.
+                    ensureNode(ref, "aggregate", name, ctx);
+                }
+                addEdge(adrId, ref, "domain_ref");
+            }
+            // superseded_by → another ADR
+            if (adr.superseded_by) {
+                ensureNode(adr.superseded_by, "adr", adr.superseded_by);
+                addEdge(adrId, adr.superseded_by, "superseded_by");
+            }
+        }
+        // ── Flows ─────────────────────────────────────────────────────
+        for (const flow of model.index.flows ?? []) {
+            const fId = ensureNode(flowId(flow.name), "flow", flow.name);
+            let prevStepId;
+            for (const step of flow.steps) {
+                const ref = step.ref;
+                const dotIdx = ref.indexOf(".");
+                const ctx = dotIdx > 0 ? ref.slice(0, dotIdx) : undefined;
+                const name = dotIdx > 0 ? ref.slice(dotIdx + 1) : ref;
+                const kind = step.type === "read_model" ? "read_model" : step.type;
+                ensureNode(ref, kind, name, ctx);
+                addEdge(fId, ref, "flow_step");
+                // Link consecutive flow steps
+                if (prevStepId) {
+                    addEdge(prevStepId, ref, "flow_next");
+                }
+                prevStepId = ref;
+            }
+        }
+        return new DomainGraph(nodes, edges, adj);
+    }
+    // ── Queries ───────────────────────────────────────────────────────
+    /**
+     * 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, depth = 1) {
+        const result = new Set();
+        if (!this.adj.has(startId))
+            return result;
+        const visited = new Set([startId]);
+        let frontier = [startId];
+        for (let d = 0; d < depth && frontier.length > 0; d++) {
+            const next = [];
+            for (const nodeId of frontier) {
+                for (const neighbour of this.adj.get(nodeId) ?? []) {
+                    if (!visited.has(neighbour)) {
+                        visited.add(neighbour);
+                        result.add(neighbour);
+                        next.push(neighbour);
+                    }
+                }
+            }
+            frontier = next;
+        }
+        return result;
+    }
+    /**
+     * Return direct neighbours of a node (shorthand for depth-1 traversal).
+     */
+    getNeighbours(nodeId) {
+        return new Set(this.adj.get(nodeId) ?? []);
+    }
+    /**
+     * Check whether a node id exists in the graph.
+     */
+    hasNode(id) {
+        return this.nodes.has(id);
+    }
+}
+//# sourceMappingURL=graph.js.map

package/dist/shared/graph.js.map

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

package/dist/shared/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Barrel export for all shared / cross-cutting modules.
+ *
+ * Consumers can import from `../shared/index.js` (or just `../shared/`)
+ * instead of reaching into individual files.
+ */
+export * from "./types/domain.js";
+export * from "./types/index.js";
+export { type ItemType, type AnyDomainItem, ITEM_TYPES, itemName, itemDescription, itemAdrRefs, forEachItem, mapItems, } from "./item-visitor.js";
+export { loadDomainModel, type LoaderOptions } from "./loader.js";
+export { DomainGraph, type NodeKind, type GraphNode, type GraphEdge } from "./graph.js";
+export { repoRoot, domainDir, contextsDir, actorsFile, indexFile, adrDir, docsDir, templatesDir, schemaDir, repoRelative, } from "./paths.js";
+export { parseYaml, stringifyYaml } from "./yaml.js";
+export { parseAdrFrontmatter, parseAdrFile } from "./adr-parser.js";
+export { formatCliError, isYAMLException, isNodeSystemError } from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shared/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,UAAU,EACV,QAAQ,EACR,eAAe,EACf,WAAW,EACX,WAAW,EACX,QAAQ,GACT,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAGlE,OAAO,EAAE,WAAW,EAAE,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAGxF,OAAO,EACL,QAAQ,EACR,SAAS,EACT,WAAW,EACX,UAAU,EACV,SAAS,EACT,MAAM,EACN,OAAO,EACP,YAAY,EACZ,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAGrD,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/shared/index.js

@@ -0,0 +1,24 @@
+/**
+ * Barrel export for all shared / cross-cutting modules.
+ *
+ * Consumers can import from `../shared/index.js` (or just `../shared/`)
+ * instead of reaching into individual files.
+ */
+// ── Types ─────────────────────────────────────────────────────────────
+export * from "./types/domain.js";
+export * from "./types/index.js";
+// ── Item visitor ──────────────────────────────────────────────────────
+export { ITEM_TYPES, itemName, itemDescription, itemAdrRefs, forEachItem, mapItems, } from "./item-visitor.js";
+// ── Loader ────────────────────────────────────────────────────────────
+export { loadDomainModel } from "./loader.js";
+// ── Graph ─────────────────────────────────────────────────────────────
+export { DomainGraph } from "./graph.js";
+// ── Path helpers ──────────────────────────────────────────────────────
+export { repoRoot, domainDir, contextsDir, actorsFile, indexFile, adrDir, docsDir, templatesDir, schemaDir, repoRelative, } from "./paths.js";
+// ── YAML helpers ──────────────────────────────────────────────────────
+export { parseYaml, stringifyYaml } from "./yaml.js";
+// ── ADR parser ────────────────────────────────────────────────────────
+export { parseAdrFrontmatter, parseAdrFile } from "./adr-parser.js";
+// ── Error formatting ──────────────────────────────────────────────────
+export { formatCliError, isYAMLException, isNodeSystemError } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/shared/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/shared/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,yEAAyE;AACzE,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AAEjC,yEAAyE;AACzE,OAAO,EAGL,UAAU,EACV,QAAQ,EACR,eAAe,EACf,WAAW,EACX,WAAW,EACX,QAAQ,GACT,MAAM,mBAAmB,CAAC;AAE3B,yEAAyE;AACzE,OAAO,EAAE,eAAe,EAAsB,MAAM,aAAa,CAAC;AAElE,yEAAyE;AACzE,OAAO,EAAE,WAAW,EAAiD,MAAM,YAAY,CAAC;AAExF,yEAAyE;AACzE,OAAO,EACL,QAAQ,EACR,SAAS,EACT,WAAW,EACX,UAAU,EACV,SAAS,EACT,MAAM,EACN,OAAO,EACP,YAAY,EACZ,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,yEAAyE;AACzE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAErD,yEAAyE;AACzE,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpE,yEAAyE;AACzE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/shared/item-visitor.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Item visitor utility — encapsulates the 'iterate over all item types
+ * in a bounded context' pattern.
+ *
+ * Before this utility, the sequence
+ *   `ctx.events ?? [] → ctx.commands ?? [] → ctx.policies ?? [] →
+ *    ctx.aggregates ?? [] → ctx.read_models ?? [] → ctx.glossary ?? []`
+ * was copy-pasted in 5+ locations. Adding a new domain item type
+ * required modifying every one of those sites.
+ *
+ * Two entry points are provided:
+ *
+ * - {@link forEachItem} — iterate with a callback (side-effects).
+ * - {@link mapItems}    — collect mapped results into an array.
+ */
+import type { DomainContext, DomainEvent, Command, Policy, Aggregate, ReadModel, GlossaryEntry, AdrRef } from "./types/domain.js";
+/** The six domain item categories that live inside a bounded context. */
+export type ItemType = "event" | "command" | "policy" | "aggregate" | "read_model" | "glossary";
+/** Union of every domain item interface. */
+export type AnyDomainItem = DomainEvent | Command | Policy | Aggregate | ReadModel | GlossaryEntry;
+/**
+ * Canonical item types in their standard iteration order.
+ * Matches the order used historically across the codebase.
+ */
+export declare const ITEM_TYPES: readonly ItemType[];
+/**
+ * Get the canonical display name of any domain item.
+ *
+ * Most items use `.name`; glossary entries use `.term`.
+ */
+export declare function itemName(item: AnyDomainItem): string;
+/**
+ * Get the description text of any domain item.
+ *
+ * Most items use `.description`; glossary entries use `.definition`.
+ */
+export declare function itemDescription(item: AnyDomainItem): string;
+/**
+ * Get `adr_refs` from any domain item (all types carry this optional field).
+ */
+export declare function itemAdrRefs(item: AnyDomainItem): AdrRef[] | undefined;
+/**
+ * Iterate every domain item in a bounded context, calling `fn` once
+ * per item. Items are visited in canonical type order (events, commands,
+ * policies, aggregates, read models, glossary).
+ *
+ * @param ctx - The bounded context to visit.
+ * @param fn  - Callback receiving the item type, its canonical name,
+ *              and the item object itself.
+ */
+export declare function forEachItem(ctx: DomainContext, fn: (type: ItemType, name: string, item: AnyDomainItem) => void): void;
+/**
+ * Map every domain item in a bounded context to a value, collecting
+ * all results into an array. Items are visited in canonical type order.
+ *
+ * @param ctx - The bounded context to visit.
+ * @param fn  - Mapping function receiving the item type, its canonical
+ *              name, and the item object itself.
+ * @returns An array of mapped values, one per item.
+ */
+export declare function mapItems<R>(ctx: DomainContext, fn: (type: ItemType, name: string, item: AnyDomainItem) => R): R[];
+//# sourceMappingURL=item-visitor.d.ts.map

package/dist/shared/item-visitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-visitor.d.ts","sourceRoot":"","sources":["../../src/shared/item-visitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EACX,OAAO,EACP,MAAM,EACN,SAAS,EACT,SAAS,EACT,aAAa,EACb,MAAM,EACP,MAAM,mBAAmB,CAAC;AAI3B,yEAAyE;AACzE,MAAM,MAAM,QAAQ,GAChB,OAAO,GACP,SAAS,GACT,QAAQ,GACR,WAAW,GACX,YAAY,GACZ,UAAU,CAAC;AAEf,4CAA4C;AAC5C,MAAM,MAAM,aAAa,GACrB,WAAW,GACX,OAAO,GACP,MAAM,GACN,SAAS,GACT,SAAS,GACT,aAAa,CAAC;AAElB;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAOhC,CAAC;AAIX;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAIpD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAI3D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,EAAE,GAAG,SAAS,CAErE;AAID;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,aAAa,EAClB,EAAE,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,KAAK,IAAI,GAC9D,IAAI,CAON;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,GAAG,EAAE,aAAa,EAClB,EAAE,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,KAAK,CAAC,GAC3D,CAAC,EAAE,CAML"}

package/dist/shared/item-visitor.js

@@ -0,0 +1,95 @@
+/**
+ * Item visitor utility — encapsulates the 'iterate over all item types
+ * in a bounded context' pattern.
+ *
+ * Before this utility, the sequence
+ *   `ctx.events ?? [] → ctx.commands ?? [] → ctx.policies ?? [] →
+ *    ctx.aggregates ?? [] → ctx.read_models ?? [] → ctx.glossary ?? []`
+ * was copy-pasted in 5+ locations. Adding a new domain item type
+ * required modifying every one of those sites.
+ *
+ * Two entry points are provided:
+ *
+ * - {@link forEachItem} — iterate with a callback (side-effects).
+ * - {@link mapItems}    — collect mapped results into an array.
+ */
+/**
+ * Canonical item types in their standard iteration order.
+ * Matches the order used historically across the codebase.
+ */
+export const ITEM_TYPES = [
+    "event",
+    "command",
+    "policy",
+    "aggregate",
+    "read_model",
+    "glossary",
+];
+// ── Helpers ───────────────────────────────────────────────────────────
+/**
+ * Get the canonical display name of any domain item.
+ *
+ * Most items use `.name`; glossary entries use `.term`.
+ */
+export function itemName(item) {
+    return "term" in item && typeof item.term === "string"
+        ? item.term
+        : item.name;
+}
+/**
+ * Get the description text of any domain item.
+ *
+ * Most items use `.description`; glossary entries use `.definition`.
+ */
+export function itemDescription(item) {
+    return "definition" in item && typeof item.definition === "string"
+        ? item.definition
+        : item.description;
+}
+/**
+ * Get `adr_refs` from any domain item (all types carry this optional field).
+ */
+export function itemAdrRefs(item) {
+    return item.adr_refs;
+}
+// ── Entry points ──────────────────────────────────────────────────────
+/**
+ * Iterate every domain item in a bounded context, calling `fn` once
+ * per item. Items are visited in canonical type order (events, commands,
+ * policies, aggregates, read models, glossary).
+ *
+ * @param ctx - The bounded context to visit.
+ * @param fn  - Callback receiving the item type, its canonical name,
+ *              and the item object itself.
+ */
+export function forEachItem(ctx, fn) {
+    for (const e of ctx.events ?? [])
+        fn("event", e.name, e);
+    for (const c of ctx.commands ?? [])
+        fn("command", c.name, c);
+    for (const p of ctx.policies ?? [])
+        fn("policy", p.name, p);
+    for (const a of ctx.aggregates ?? [])
+        fn("aggregate", a.name, a);
+    for (const r of ctx.read_models ?? [])
+        fn("read_model", r.name, r);
+    for (const g of ctx.glossary ?? [])
+        fn("glossary", g.term, g);
+}
+/**
+ * Map every domain item in a bounded context to a value, collecting
+ * all results into an array. Items are visited in canonical type order.
+ *
+ * @param ctx - The bounded context to visit.
+ * @param fn  - Mapping function receiving the item type, its canonical
+ *              name, and the item object itself.
+ * @returns An array of mapped values, one per item.
+ */
+export function mapItems(ctx, fn) {
+    const results = [];
+    forEachItem(ctx, (type, name, item) => {
+        results.push(fn(type, name, item));
+    });
+    return results;
+}
+//# sourceMappingURL=item-visitor.js.map

package/dist/shared/item-visitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-visitor.js","sourceRoot":"","sources":["../../src/shared/item-visitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAiCH;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAwB;IAC7C,OAAO;IACP,SAAS;IACT,QAAQ;IACR,WAAW;IACX,YAAY;IACZ,UAAU;CACF,CAAC;AAEX,yEAAyE;AAEzE;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAmB;IAC1C,OAAO,MAAM,IAAI,IAAI,IAAI,OAAQ,IAAsB,CAAC,IAAI,KAAK,QAAQ;QACvE,CAAC,CAAE,IAAsB,CAAC,IAAI;QAC9B,CAAC,CAAE,IAA8C,CAAC,IAAI,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAAmB;IACjD,OAAO,YAAY,IAAI,IAAI,IAAI,OAAQ,IAAsB,CAAC,UAAU,KAAK,QAAQ;QACnF,CAAC,CAAE,IAAsB,CAAC,UAAU;QACpC,CAAC,CAAE,IAA8C,CAAC,WAAW,CAAC;AAClE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,IAAmB;IAC7C,OAAQ,IAAgC,CAAC,QAAQ,CAAC;AACpD,CAAC;AAED,yEAAyE;AAEzE;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CACzB,GAAkB,EAClB,EAA+D;IAE/D,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE;QAAE,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACzD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,QAAQ,IAAI,EAAE;QAAE,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC7D,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,QAAQ,IAAI,EAAE;QAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC5D,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,UAAU,IAAI,EAAE;QAAE,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACjE,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,WAAW,IAAI,EAAE;QAAE,EAAE,CAAC,YAAY,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACnE,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,QAAQ,IAAI,EAAE;QAAE,EAAE,CAAC,UAAU,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CACtB,GAAkB,EAClB,EAA4D;IAE5D,MAAM,OAAO,GAAQ,EAAE,CAAC;IACxB,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;QACpC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/shared/loader.d.ts

@@ -0,0 +1,19 @@
+import type { DomainModel } from "./types/domain.js";
+/** Options for the loader. */
+export interface LoaderOptions {
+    /** Override repository root (default: auto-detected). */
+    root?: string;
+}
+/**
+ * Load the complete domain model from disk.
+ *
+ * 1. Parses `domain/index.yml`
+ * 2. Parses `domain/actors.yml`
+ * 3. Discovers and parses every bounded-context YAML file
+ *    under `domain/contexts/`
+ * 4. Discovers and parses ADR frontmatter from `docs/adr/*.md`
+ *
+ * @returns A fully-populated {@link DomainModel}.
+ */
+export declare function loadDomainModel(options?: LoaderOptions): DomainModel;
+//# sourceMappingURL=loader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/shared/loader.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAKV,WAAW,EAOZ,MAAM,mBAAmB,CAAC;AAiH3B,8BAA8B;AAC9B,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,aAAkB,GAAG,WAAW,CAkCxE"}