domain-knowledge-kit 0.1.0

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

@@ -0,0 +1,34 @@
+/**
+ * Search index record type for the deterministic search index.
+ *
+ * Each record represents a single searchable domain item that can be
+ * looked up by keyword, type, or context.
+ */
+import type { AdrRef, DomainRef } from "./domain.js";
+/** The kind of domain item stored in a search index record. */
+export type SearchItemType = "context" | "glossary" | "actor" | "event" | "command" | "policy" | "aggregate" | "read_model" | "adr" | "flow";
+/**
+ * A single record in the search index, representing one domain item
+ * with enough metadata for keyword look-up and filtering.
+ */
+export interface SearchIndexRecord {
+    /** Unique composite key: "<context>.<Name>" for context-scoped items,
+     *  or the item's own id/name for top-level items (actors, ADRs, flows). */
+    id: string;
+    /** Kind of domain item. */
+    type: SearchItemType;
+    /** Human-readable display name. */
+    name: string;
+    /** Bounded-context name this item belongs to (if applicable). */
+    context?: string;
+    /** Short description (first sentence or full). */
+    description: string;
+    /** Searchable keywords extracted from name, aliases, fields, etc. */
+    keywords: string[];
+    /** Related ADR references. */
+    adr_refs?: AdrRef[];
+    /** Related domain item references. */
+    domain_refs?: DomainRef[];
+}
+export * from "./domain.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/types/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,SAAS,EACV,MAAM,aAAa,CAAC;AAErB,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,UAAU,GACV,OAAO,GACP,OAAO,GACP,SAAS,GACT,QAAQ,GACR,WAAW,GACX,YAAY,GACZ,KAAK,GACL,MAAM,CAAC;AAEX;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;+EAC2E;IAC3E,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B;IAC3B,IAAI,EAAE,cAAc,CAAC;IACrB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,sCAAsC;IACtC,WAAW,CAAC,EAAE,SAAS,EAAE,CAAC;CAC3B;AAGD,cAAc,aAAa,CAAC"}

package/dist/shared/types/index.js

@@ -0,0 +1,9 @@
+/**
+ * Search index record type for the deterministic search index.
+ *
+ * Each record represents a single searchable domain item that can be
+ * looked up by keyword, type, or context.
+ */
+// Re-export all domain types for convenience.
+export * from "./domain.js";
+//# sourceMappingURL=index.js.map

package/dist/shared/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/shared/types/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4CH,8CAA8C;AAC9C,cAAc,aAAa,CAAC"}

package/dist/shared/yaml.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Parse a YAML string into a typed object.
+ *
+ * @throws {yaml.YAMLException} on malformed YAML.
+ */
+export declare function parseYaml<T = Record<string, unknown>>(text: string): T;
+/**
+ * Stringify a value to a YAML string.
+ *
+ * Uses block-style scalars and 2-space indent for readability.
+ */
+export declare function stringifyYaml(value: unknown): string;
+//# sourceMappingURL=yaml.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.d.ts","sourceRoot":"","sources":["../../src/shared/yaml.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAOpD"}

package/dist/shared/yaml.js

@@ -0,0 +1,29 @@
+/**
+ * YAML parse / stringify helpers.
+ *
+ * Thin wrappers around js-yaml that pin options and give
+ * narrower return types than the generic `unknown`.
+ */
+import yaml from "js-yaml";
+/**
+ * Parse a YAML string into a typed object.
+ *
+ * @throws {yaml.YAMLException} on malformed YAML.
+ */
+export function parseYaml(text) {
+    return yaml.load(text);
+}
+/**
+ * Stringify a value to a YAML string.
+ *
+ * Uses block-style scalars and 2-space indent for readability.
+ */
+export function stringifyYaml(value) {
+    return yaml.dump(value, {
+        indent: 2,
+        lineWidth: 120,
+        noRefs: true,
+        sortKeys: false,
+    });
+}
+//# sourceMappingURL=yaml.js.map

package/dist/shared/yaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.js","sourceRoot":"","sources":["../../src/shared/yaml.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,IAAI,MAAM,SAAS,CAAC;AAE3B;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAA8B,IAAY;IACjE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAM,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE;QACtB,MAAM,EAAE,CAAC;QACT,SAAS,EAAE,GAAG;QACd,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,KAAK;KAChB,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "domain-knowledge-kit",
+  "version": "0.1.0",
+  "description": "Domain Knowledge Pack — YAML + ADR links + deterministic search + generated docs",
+  "type": "module",
+  "bin": {
+    "dkk": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "tools/domain-pack/schema/",
+    "tools/domain-pack/templates/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "check": "npm run typecheck && npm run lint",
+    "prepublishOnly": "npm run build",
+    "test": "tsx src/features/pipeline/tests/validate-schemas.test.ts && tsx src/shared/tests/loader.test.ts && tsx src/features/pipeline/tests/validator.test.ts && tsx src/shared/tests/graph.test.ts && tsx src/features/pipeline/tests/indexer.test.ts && tsx src/features/query/tests/searcher.test.ts && tsx src/features/pipeline/tests/renderer.test.ts && tsx src/shared/tests/verify-collision-fix.test.ts && tsx test/cli-integration.ts"
+  },
+  "engines": {
+    "node": ">=21.2.0"
+  },
+  "keywords": [],
+  "license": "Elastic-2.0",
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/js-yaml": "^4.0.9",
+    "eslint": "^10.0.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "typescript-eslint": "^8.56.0"
+  },
+  "dependencies": {
+    "ajv": "^8.12.0",
+    "ajv-formats": "^3.0.1",
+    "better-sqlite3": "^11.0.0",
+    "commander": "^12.0.0",
+    "fast-glob": "^3.3.2",
+    "handlebars": "^4.7.8",
+    "js-yaml": "^4.1.0"
+  }
+}

package/tools/domain-pack/schema/actors.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "actors.schema.json",
+  "title": "Actors File",
+  "description": "Top-level actors definition file (domain/actors.yml)",
+  "type": "object",
+  "properties": {
+    "actors": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[A-Za-z][A-Za-z0-9 ]*$",
+            "description": "Actor display name (e.g. Customer, Payment Gateway)"
+          },
+          "type": {
+            "type": "string",
+            "enum": ["human", "system", "external"],
+            "description": "Whether the actor is a person, internal system, or external system"
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "description": "What role this actor plays in the domain"
+          },
+          "adr_refs": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+            "uniqueItems": true,
+            "description": "Related ADR identifiers"
+          }
+        },
+        "required": ["name", "type", "description"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["actors"],
+  "additionalProperties": false
+}

package/tools/domain-pack/schema/adr-frontmatter.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "adr-frontmatter.schema.json",
+  "title": "ADR Frontmatter",
+  "description": "Frontmatter metadata for an Architecture Decision Record",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^adr-\\d{4}$",
+      "description": "Stable ADR identifier (e.g. adr-0001)"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable title of the decision"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["proposed", "accepted", "deprecated", "superseded"],
+      "description": "Current lifecycle status of the ADR"
+    },
+    "date": {
+      "type": "string",
+      "format": "date",
+      "description": "ISO-8601 date when the decision was recorded (YYYY-MM-DD)"
+    },
+    "deciders": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "People involved in making this decision"
+    },
+    "domain_refs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*\\.[A-Za-z][A-Za-z0-9]*$",
+        "description": "Domain item reference in context.Name format (e.g. ordering.OrderPlaced)"
+      },
+      "uniqueItems": true,
+      "description": "Domain items related to this decision"
+    },
+    "superseded_by": {
+      "type": "string",
+      "pattern": "^adr-\\d{4}$",
+      "description": "ID of the ADR that supersedes this one"
+    }
+  },
+  "required": ["id", "title", "status", "date"],
+  "additionalProperties": false
+}

package/tools/domain-pack/schema/aggregate.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "aggregate.schema.json",
+  "title": "Aggregate",
+  "description": "A domain aggregate that handles commands and emits events",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[A-Za-z][A-Za-z0-9]*$",
+      "description": "PascalCase aggregate name (e.g. Order)"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "What this aggregate represents in the domain"
+    },
+    "handles": {
+      "type": "object",
+      "properties": {
+        "commands": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true,
+          "description": "Command names handled by this aggregate"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Commands handled by this aggregate"
+    },
+    "emits": {
+      "type": "object",
+      "properties": {
+        "events": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true,
+          "description": "Event names emitted by this aggregate"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Events emitted by this aggregate"
+    },
+    "invariants": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Business invariants / rules enforced by this aggregate"
+    },
+    "adr_refs": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+      "uniqueItems": true,
+      "description": "Related ADR identifiers"
+    }
+  },
+  "required": ["name", "description"],
+  "additionalProperties": false
+}

package/tools/domain-pack/schema/command.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "command.schema.json",
+  "title": "Command",
+  "description": "A command handled by an aggregate within a bounded context",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[A-Za-z][A-Za-z0-9]*$",
+      "description": "PascalCase command name (e.g. PlaceOrder)"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "What this command instructs the system to do"
+    },
+    "fields": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "type": { "type": "string", "minLength": 1 },
+          "description": { "type": "string" }
+        },
+        "required": ["name", "type"],
+        "additionalProperties": false
+      },
+      "description": "Input fields for this command"
+    },
+    "actor": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Name of the actor that initiates this command"
+    },
+    "handled_by": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Name of the aggregate that handles this command"
+    },
+    "examples": {
+      "type": "array",
+      "description": "Given/when/then usage scenarios for this command",
+      "items": {
+        "type": "object",
+        "properties": {
+          "description": { "type": "string", "minLength": 1 },
+          "given": { "type": "array", "items": { "type": "string" } },
+          "when": { "type": "array", "items": { "type": "string" } },
+          "then": { "type": "array", "items": { "type": "string" } }
+        },
+        "required": ["description"],
+        "additionalProperties": false
+      }
+    },
+    "preconditions": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Conditions that must be true before this command can be accepted"
+    },
+    "rejections": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Reasons this command may be rejected"
+    },
+    "adr_refs": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+      "uniqueItems": true,
+      "description": "Related ADR identifiers"
+    }
+  },
+  "required": ["name", "description"],
+  "additionalProperties": false
+}

package/tools/domain-pack/schema/context.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "context.schema.json",
+  "title": "Bounded Context",
+  "description": "A bounded context YAML file containing domain items (domain/contexts/<name>.yml)",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Kebab-case context identifier used as the first segment of domain item IDs (e.g. ordering)"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "What this bounded context is responsible for"
+    },
+    "glossary": {
+      "type": "array",
+      "items": { "$ref": "glossary.schema.json" },
+      "description": "Ubiquitous-language terms scoped to this context"
+    },
+    "events": {
+      "type": "array",
+      "items": { "$ref": "event.schema.json" },
+      "description": "Domain events raised within this context"
+    },
+    "commands": {
+      "type": "array",
+      "items": { "$ref": "command.schema.json" },
+      "description": "Commands handled within this context"
+    },
+    "policies": {
+      "type": "array",
+      "items": { "$ref": "policy.schema.json" },
+      "description": "Reactive policies within this context"
+    },
+    "aggregates": {
+      "type": "array",
+      "items": { "$ref": "aggregate.schema.json" },
+      "description": "Aggregates within this context"
+    },
+    "read_models": {
+      "type": "array",
+      "items": { "$ref": "read-model.schema.json" },
+      "description": "Read models (projections) within this context"
+    }
+  },
+  "required": ["name", "description"],
+  "additionalProperties": false
+}

package/tools/domain-pack/schema/event.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "event.schema.json",
+  "title": "Domain Event",
+  "description": "A domain event raised within a bounded context",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[A-Za-z][A-Za-z0-9]*$",
+      "description": "PascalCase event name (e.g. OrderPlaced)"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "What this event signifies in the domain"
+    },
+    "fields": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "type": { "type": "string", "minLength": 1 },
+          "description": { "type": "string" }
+        },
+        "required": ["name", "type"],
+        "additionalProperties": false
+      },
+      "description": "Payload fields carried by this event"
+    },
+    "raised_by": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Name of the aggregate that raises this event"
+    },
+    "examples": {
+      "type": "array",
+      "description": "Given/when/then usage scenarios for this event",
+      "items": {
+        "type": "object",
+        "properties": {
+          "description": { "type": "string", "minLength": 1 },
+          "given": { "type": "array", "items": { "type": "string" } },
+          "when": { "type": "array", "items": { "type": "string" } },
+          "then": { "type": "array", "items": { "type": "string" } }
+        },
+        "required": ["description"],
+        "additionalProperties": false
+      }
+    },
+    "invariants": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Business invariants / rules that must hold when this event is raised"
+    },
+    "adr_refs": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+      "uniqueItems": true,
+      "description": "Related ADR identifiers"
+    }
+  },
+  "required": ["name", "description"],
+  "additionalProperties": false
+}

package/tools/domain-pack/schema/glossary.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "glossary.schema.json",
+  "title": "Glossary Entry",
+  "description": "A ubiquitous-language term within a bounded context",
+  "type": "object",
+  "properties": {
+    "term": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The canonical term name"
+    },
+    "definition": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Plain-language definition of the term"
+    },
+    "aliases": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "Alternative names for this term"
+    },
+    "adr_refs": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^adr-\\d{4}$" },
+      "uniqueItems": true,
+      "description": "Related ADR identifiers (e.g. adr-0001)"
+    }
+  },
+  "required": ["term", "definition"],
+  "additionalProperties": false
+}

package/tools/domain-pack/schema/index.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "index.schema.json",
+  "title": "Domain Index",
+  "description": "Top-level domain index file (domain/index.yml)",
+  "type": "object",
+  "properties": {
+    "contexts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$",
+            "description": "Context identifier matching a file under domain/contexts/"
+          },
+          "description": {
+            "type": "string",
+            "description": "Short summary of the bounded context"
+          }
+        },
+        "required": ["name"],
+        "additionalProperties": false
+      },
+      "description": "Registered bounded contexts"
+    },
+    "flows": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Flow name"
+          },
+          "description": {
+            "type": "string",
+            "description": "What this flow accomplishes"
+          },
+          "steps": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "ref": {
+                  "type": "string",
+                  "pattern": "^[a-z][a-z0-9-]*\\.[A-Za-z][A-Za-z0-9]*$",
+                  "description": "Domain item reference (context.Name)"
+                },
+                "type": {
+                  "type": "string",
+                  "enum": ["command", "event", "policy", "read_model"],
+                  "description": "Type of the referenced item"
+                },
+                "note": {
+                  "type": "string",
+                  "description": "Optional annotation for this step"
+                }
+              },
+              "required": ["ref", "type"],
+              "additionalProperties": false
+            },
+            "description": "Ordered sequence of domain item references forming the flow"
+          }
+        },
+        "required": ["name", "steps"],
+        "additionalProperties": false
+      },
+      "description": "Cross-context flows linking domain items in sequence"
+    }
+  },
+  "required": ["contexts"],
+  "additionalProperties": false
+}