speckeeper 0.1.0

package/dist/index.js

@@ -0,0 +1,1364 @@
+import { z } from 'zod';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { resolve, join, dirname, extname, basename } from 'path';
+import { parse } from 'yaml';
+import { createHash } from 'crypto';
+import { glob } from 'glob';
+
+// src/types/common.ts
+var PhaseSchema = z.enum(["REQ", "HLD", "LLD", "IMPL", "OPS", "CI"]);
+var PrioritySchema = z.enum(["must", "should", "could", "wont"]);
+var createRequirementId = (id) => id;
+var createComponentId = (id) => id;
+var createBoundaryId = (id) => id;
+var createLayerId = (id) => id;
+var createEntityId = (id) => id;
+var createRelationId = (id) => id;
+var createRuleId = (id) => id;
+var createScreenId = (id) => id;
+var createTransitionId = (id) => id;
+var createFormId = (id) => id;
+var createUIComponentId = (id) => id;
+var createProcessFlowId = (id) => id;
+var createUseCaseId = (id) => id;
+var createActorId = (id) => id;
+var createDTORequirementId = (id) => id;
+var createEventRequirementId = (id) => id;
+var createAPIRefId = (id) => id;
+var createTableRefId = (id) => id;
+var createIaCRefId = (id) => id;
+var createBatchRefId = (id) => id;
+var createErrorCaseId = (id) => id;
+var createTermId = (id) => id;
+var createStateId = (id) => id;
+var ID_PATTERNS = {
+  requirement: /^REQ-[A-Z]+-\d{6}-[A-Z0-9]{4}$/,
+  component: /^COMP-[A-Z]+-[A-Z0-9-]+$/,
+  boundary: /^BND-[A-Z]+-[A-Z0-9-]+$/,
+  layer: /^LAYER-[A-Z]+$/,
+  entity: /^ENT-[A-Z]+-?[A-Z0-9-]*$/,
+  relation: /^REL-[A-Z]+-[A-Z0-9-]+$/,
+  rule: /^RULE-[A-Z0-9-]+$/,
+  screen: /^SCR-[A-Z]+-?[A-Z0-9-]*$/,
+  transition: /^TRANS-[A-Z0-9-]+$/,
+  form: /^FORM-[A-Z0-9-]+$/,
+  uiComponent: /^UI-[A-Z0-9-]+$/,
+  processFlow: /^FLOW-[A-Z]+-[A-Z0-9-]+$/,
+  useCase: /^UC-[A-Z]+-\d{3}$/,
+  actor: /^ACTOR-[A-Z]+$/,
+  dtoRequirement: /^DTO-REQ-[A-Z0-9-]+$/,
+  eventRequirement: /^EVT-REQ-[A-Z0-9-]+$/,
+  apiRef: /^API-[A-Z0-9-]+$/,
+  tableRef: /^TBL-[A-Z0-9-]+$/,
+  iacRef: /^IAC-[A-Z0-9-]+$/,
+  batchRef: /^BATCH-[A-Z0-9-]+$/,
+  errorCase: /^ERR-[A-Z]+-\d{3}$/,
+  term: /^TERM-[A-Z0-9-]+$/
+};
+var ConcretizationSlotSchema = z.object({
+  field: z.string(),
+  mustDecideBy: PhaseSchema,
+  value: z.union([z.string(), z.null()]).optional(),
+  description: z.string().optional()
+});
+var LinkSchema = z.object({
+  type: z.enum(["requirement", "component", "entity", "screen", "usecase", "external"]),
+  id: z.string(),
+  label: z.string().optional()
+});
+var ReferenceDefinitionSchema = z.object({
+  field: z.string(),
+  targetModel: z.string(),
+  required: z.boolean().optional(),
+  isArray: z.boolean().optional()
+});
+var LintIssueSchema = z.object({
+  message: z.string(),
+  field: z.string().optional(),
+  suggestion: z.string().optional()
+});
+var CheckErrorSchema = z.object({
+  message: z.string(),
+  modelId: z.string(),
+  externalRef: z.string().optional()
+});
+var CheckWarningSchema = z.object({
+  message: z.string(),
+  modelId: z.string()
+});
+var CheckResultSchema = z.object({
+  success: z.boolean(),
+  errors: z.array(CheckErrorSchema),
+  warnings: z.array(CheckWarningSchema)
+});
+function getLevelIndex(level) {
+  return ["L0", "L1", "L2", "L3"].indexOf(level);
+}
+var RELATION_TYPES = [
+  "dependsOn",
+  "uses",
+  "includes",
+  "implements",
+  "refines",
+  "verifies",
+  "satisfies",
+  "traces",
+  "relatedTo"
+];
+var RelationSchema = z.object({
+  /** Relation type */
+  type: z.enum(RELATION_TYPES),
+  /** Target ID */
+  target: z.string(),
+  /** Description (optional) */
+  description: z.string().optional()
+});
+var RelationsFieldSchema = z.array(RelationSchema).optional();
+var RELATION_CONSTRAINTS = {
+  // Concrete→Abstract (implementation/design fulfills requirements)
+  "implements": {
+    allowedTargetLevels: ["L1"],
+    // Implements requirements
+    levelRule: "source>target",
+    propagation: "forward"
+    // A changes → B needs review
+  },
+  // Concrete→Abstract (design/implementation satisfies business/requirements)
+  "satisfies": {
+    allowedTargetLevels: ["L0", "L1"],
+    // Satisfies business/requirements
+    levelRule: "source>=target",
+    propagation: "backward"
+    // B changes → A needs update
+  },
+  // Concrete→Abstract (refinement: requirements refine business, design refines requirements)
+  "refines": {
+    allowedTargetLevels: ["L0", "L1"],
+    // Refines business/requirements
+    levelRule: "source>target",
+    propagation: "backward"
+    // B changes → A needs update
+  },
+  // Test→Requirements/Business (verification relationship)
+  "verifies": {
+    allowedTargetLevels: ["L0", "L1"],
+    // Verifies business/requirements
+    levelRule: "any",
+    propagation: "backward"
+    // B changes → A needs update
+  },
+  // Dependencies (same level or concrete→abstract)
+  "dependsOn": {
+    levelRule: "source>=target",
+    propagation: "backward"
+    // B changes → A affected
+  },
+  // Usage relationship (no level constraint)
+  "uses": {
+    levelRule: "any",
+    propagation: "backward"
+    // B changes → A affected
+  },
+  // Inclusion relationship (same level only)
+  "includes": {
+    levelRule: "same",
+    propagation: "backward"
+    // B changes → A affected
+  },
+  // Bidirectional tracing
+  "traces": {
+    levelRule: "any",
+    propagation: "both"
+  },
+  // General relation
+  "relatedTo": {
+    levelRule: "any",
+    propagation: "both"
+  }
+};
+function validateRelationLevel(sourceLevel, sourceSpecId, relation, targetLevel) {
+  if (sourceSpecId === relation.target) {
+    return {
+      type: "self_reference",
+      message: `Self-reference is not allowed: ${sourceSpecId} \u2192 ${relation.target}`,
+      relation,
+      sourceId: sourceSpecId
+    };
+  }
+  if (!sourceLevel || !targetLevel) {
+    return null;
+  }
+  const constraint = RELATION_CONSTRAINTS[relation.type];
+  if (constraint.allowedTargetLevels && !constraint.allowedTargetLevels.includes(targetLevel)) {
+    return {
+      type: "target_level_violation",
+      message: `'${relation.type}' relation target must be ${constraint.allowedTargetLevels.join(" or ")}, but target is ${targetLevel}`,
+      relation,
+      sourceId: sourceSpecId
+    };
+  }
+  const srcIdx = getLevelIndex(sourceLevel);
+  const tgtIdx = getLevelIndex(targetLevel);
+  switch (constraint.levelRule) {
+    case "source>target":
+      if (srcIdx <= tgtIdx) {
+        return {
+          type: "level_violation",
+          message: `'${relation.type}' requires source (${sourceLevel}) to be more concrete than target (${targetLevel})`,
+          relation,
+          sourceId: sourceSpecId
+        };
+      }
+      break;
+    case "source>=target":
+      if (srcIdx < tgtIdx) {
+        return {
+          type: "level_violation",
+          message: `'${relation.type}' requires source (${sourceLevel}) to be same or more concrete than target (${targetLevel})`,
+          relation,
+          sourceId: sourceSpecId
+        };
+      }
+      break;
+    case "same":
+      if (srcIdx !== tgtIdx) {
+        return {
+          type: "level_violation",
+          message: `'${relation.type}' requires source (${sourceLevel}) and target (${targetLevel}) to be same level`,
+          relation,
+          sourceId: sourceSpecId
+        };
+      }
+      break;
+  }
+  return null;
+}
+function detectCycles(relations) {
+  const errors = [];
+  const graph = /* @__PURE__ */ new Map();
+  const relationMap = /* @__PURE__ */ new Map();
+  for (const rel of relations) {
+    if (!graph.has(rel.sourceId)) {
+      graph.set(rel.sourceId, /* @__PURE__ */ new Set());
+    }
+    graph.get(rel.sourceId).add(rel.targetId);
+    relationMap.set(`${rel.sourceId}\u2192${rel.targetId}`, { type: rel.type, target: rel.targetId });
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const recursionStack = /* @__PURE__ */ new Set();
+  const cyclePath = [];
+  function dfs(node) {
+    visited.add(node);
+    recursionStack.add(node);
+    cyclePath.push(node);
+    const neighbors = graph.get(node);
+    if (neighbors) {
+      for (const neighbor of neighbors) {
+        if (!visited.has(neighbor)) {
+          if (dfs(neighbor)) {
+            return true;
+          }
+        } else if (recursionStack.has(neighbor)) {
+          const cycleStart = cyclePath.indexOf(neighbor);
+          const cycle = cyclePath.slice(cycleStart);
+          cycle.push(neighbor);
+          errors.push({
+            type: "cycle_detected",
+            message: `Circular reference detected: ${cycle.join(" \u2192 ")}`,
+            relation: relationMap.get(`${node}\u2192${neighbor}`),
+            sourceId: node
+          });
+          return true;
+        }
+      }
+    }
+    cyclePath.pop();
+    recursionStack.delete(node);
+    return false;
+  }
+  for (const node of graph.keys()) {
+    if (!visited.has(node)) {
+      dfs(node);
+    }
+  }
+  return errors;
+}
+function inferModelIdFromSpecId(specId) {
+  const prefixMap = {
+    "REQ": "requirement",
+    "CR": "constraint",
+    "UC": "usecase",
+    "ACTOR": "actor",
+    "TERM": "term",
+    "COMP": "component",
+    "ENT": "entity",
+    "FLOW": "process-flow",
+    "LAYER": "layer",
+    "BND": "boundary",
+    "SCR": "screen",
+    "API": "api-ref",
+    "TBL": "table-ref",
+    "IAC": "iac-ref",
+    "BATCH": "batch-ref"
+  };
+  for (const [prefix, modelId] of Object.entries(prefixMap)) {
+    if (specId.startsWith(prefix + "-")) {
+      return modelId;
+    }
+  }
+  return void 0;
+}
+
+// src/core/model.ts
+var Model = class {
+  /** Singleton instance storage (per subclass) */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  static _instances = /* @__PURE__ */ new WeakMap();
+  /**
+   * Get singleton instance of the model
+   * Usage: RequirementModel.instance
+   */
+  static get instance() {
+    const ctor = this;
+    if (!this._instances.has(ctor)) {
+      this._instances.set(ctor, new ctor());
+    }
+    return this._instances.get(ctor);
+  }
+  /** Model description (optional) */
+  description;
+  /** External SSOT type (optional, e.g. 'OpenAPI', 'DDL/Prisma') */
+  externalSsotType;
+  /** Spec instance type */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  get specType() {
+    return void 0;
+  }
+  /** Lint rules (override in subclass) */
+  lintRules = [];
+  /** Exporters (override in subclass) */
+  exporters = [];
+  /** External checker (optional) */
+  externalChecker;
+  /** Coverage checker (optional) */
+  coverageChecker;
+  /** Model level (set in _models/) */
+  modelLevel;
+  /** Renderers (for embeds, override in subclass) */
+  renderers = [];
+  /**
+   * Get model level
+   * Returns modelLevel set in _models/
+   */
+  get level() {
+    return this.modelLevel;
+  }
+  /**
+   * Execute schema validation
+   */
+  validate(spec) {
+    return this.schema.parse(spec);
+  }
+  /**
+   * Schema validation (safe version, returns error object on failure)
+   */
+  safeParse(spec) {
+    return this.schema.safeParse(spec);
+  }
+  /**
+   * Execute lint
+   */
+  lint(spec) {
+    const specId = spec.id;
+    return this.lintRules.filter((rule) => rule.check(spec)).map((rule) => ({
+      ruleId: rule.id,
+      severity: rule.severity,
+      message: rule.message,
+      specId
+    }));
+  }
+  /**
+   * Execute lint for multiple specs
+   */
+  lintAll(specs) {
+    return specs.flatMap((spec) => this.lint(spec));
+  }
+  /**
+   * Validate level constraints of relations
+   * @param spec - Spec instance (if it has relations property)
+   * @returns Array of validation errors
+   */
+  validateRelations(spec) {
+    const errors = [];
+    const specWithRelations = spec;
+    if (!specWithRelations.relations || !specWithRelations.id) {
+      return errors;
+    }
+    const allModels = getAllModels();
+    const modelLevelMap = /* @__PURE__ */ new Map();
+    for (const model of allModels) {
+      modelLevelMap.set(model.id, model.level);
+    }
+    for (const relation of specWithRelations.relations) {
+      const targetModelId = inferModelIdFromSpecId(relation.target);
+      if (!targetModelId) {
+        continue;
+      }
+      const targetLevel = modelLevelMap.get(targetModelId);
+      const error = validateRelationLevel(
+        this.level,
+        specWithRelations.id,
+        relation,
+        targetLevel
+      );
+      if (error) {
+        errors.push(error);
+      }
+    }
+    return errors;
+  }
+  /**
+   * Validate relations of multiple specs (including circular reference check)
+   */
+  validateAllRelations(specs) {
+    const errors = [];
+    const allRelations = [];
+    for (const spec of specs) {
+      errors.push(...this.validateRelations(spec));
+      const specWithRelations = spec;
+      if (specWithRelations.relations && specWithRelations.id) {
+        for (const rel of specWithRelations.relations) {
+          allRelations.push({
+            sourceId: specWithRelations.id,
+            targetId: rel.target,
+            type: rel.type
+          });
+        }
+      }
+    }
+    errors.push(...detectCycles(allRelations));
+    return errors;
+  }
+  /**
+   * Export in specified format (single spec)
+   */
+  exportSingle(spec, format) {
+    const exporter = this.exporters.find((e) => e.format === format);
+    if (!exporter?.single) return null;
+    return exporter.single(spec);
+  }
+  /**
+   * Export in specified format (index)
+   */
+  exportIndex(specs, format) {
+    const exporter = this.exporters.find((e) => e.format === format);
+    if (!exporter?.index) return null;
+    return exporter.index(specs);
+  }
+  /**
+   * Get exporter output directory
+   */
+  getOutputDir(format) {
+    const exporter = this.exporters.find((e) => e.format === format);
+    return exporter?.outputDir ?? null;
+  }
+  /**
+   * Get filename
+   */
+  getFilename(spec, format) {
+    const exporter = this.exporters.find((e) => e.format === format);
+    if (!exporter?.filename) return null;
+    return exporter.filename(spec);
+  }
+  /**
+   * Check consistency with external SSOT
+   */
+  check(spec, externalData) {
+    if (!this.externalChecker) {
+      return { success: true, errors: [], warnings: [] };
+    }
+    return this.externalChecker.check(spec, externalData);
+  }
+  /**
+   * Get external SSOT path
+   */
+  getExternalSourcePath(spec) {
+    if (!this.externalChecker) return null;
+    return this.externalChecker.sourcePath(spec);
+  }
+  /**
+   * Execute coverage check
+   * @param specs - Array of spec instances for this model
+   * @param registry - Registry of all models
+   */
+  checkCoverage(specs, registry) {
+    if (!this.coverageChecker) return null;
+    return this.coverageChecker.check(specs, registry);
+  }
+  /**
+   * Get coverage checker
+   */
+  getCoverageChecker() {
+    return this.coverageChecker;
+  }
+  /**
+   * Get lint rules
+   */
+  getLintRules() {
+    return this.lintRules;
+  }
+  /**
+   * Get exporters
+   */
+  getExporters() {
+    return this.exporters;
+  }
+  // ============================================================================
+  // Renderer (for embeds)
+  // ============================================================================
+  /**
+   * Render in specified format
+   * @param format - Format ID ('table', 'list', 'detail', etc.)
+   * @param specs - Array of specs to render
+   * @param ctx - Render context
+   * @returns Rendered result (Markdown string), null if no matching renderer
+   */
+  render(format, specs, ctx) {
+    const renderer = this.renderers.find((r) => r.format === format);
+    if (!renderer) return null;
+    return renderer.render(specs, ctx);
+  }
+  /**
+   * Get list of available formats
+   */
+  getAvailableFormats() {
+    return this.renderers.map((r) => r.format);
+  }
+  /**
+   * Get renderers
+   */
+  getRenderers() {
+    return this.renderers;
+  }
+  /**
+   * Check if renderer exists for specific format
+   */
+  hasRenderer(format) {
+    return this.renderers.some((r) => r.format === format);
+  }
+};
+var modelRegistry = /* @__PURE__ */ new Map();
+function registerModel(model) {
+  modelRegistry.set(model.id, model);
+}
+function getModel(id) {
+  return modelRegistry.get(id);
+}
+function getAllModels() {
+  return Array.from(modelRegistry.values());
+}
+function clearModelRegistry() {
+  modelRegistry.clear();
+}
+
+// src/core/model-registry.ts
+var globalRegistry = {
+  definitions: /* @__PURE__ */ new Map(),
+  instances: /* @__PURE__ */ new Map()
+};
+function registerModelDefinition(definition) {
+  if (globalRegistry.definitions.has(definition.id)) {
+    console.warn(`Model definition '${definition.id}' is already registered. Overwriting.`);
+  }
+  globalRegistry.definitions.set(definition.id, definition);
+  if (!globalRegistry.instances.has(definition.id)) {
+    globalRegistry.instances.set(definition.id, /* @__PURE__ */ new Map());
+  }
+}
+function registerModelDefinitions(definitions) {
+  for (const def of definitions) {
+    registerModelDefinition(def);
+  }
+}
+function getModelDefinition(modelId) {
+  return globalRegistry.definitions.get(modelId);
+}
+function getAllModelDefinitions() {
+  return Array.from(globalRegistry.definitions.values());
+}
+function registerModelInstance(modelId, instance) {
+  const definition = globalRegistry.definitions.get(modelId);
+  if (!definition) {
+    throw new Error(`Model definition '${modelId}' not found. Register the definition first.`);
+  }
+  const result = definition.schema.safeParse(instance);
+  if (!result.success) {
+    throw new Error(
+      `Invalid instance for model '${modelId}': ${result.error.message}`
+    );
+  }
+  let instances = globalRegistry.instances.get(modelId);
+  if (!instances) {
+    instances = /* @__PURE__ */ new Map();
+    globalRegistry.instances.set(modelId, instances);
+  }
+  instances.set(instance.id, instance);
+}
+function getModelInstance(modelId, instanceId) {
+  const instances = globalRegistry.instances.get(modelId);
+  return instances?.get(instanceId);
+}
+function getAllModelInstances(modelId) {
+  const instances = globalRegistry.instances.get(modelId);
+  if (!instances) return [];
+  return Array.from(instances.values());
+}
+function getAllInstances() {
+  const result = [];
+  for (const [modelId, instances] of globalRegistry.instances) {
+    for (const instance of instances.values()) {
+      result.push({ modelId, instance });
+    }
+  }
+  return result;
+}
+function getGlobalModelRegistry() {
+  return globalRegistry;
+}
+function resetModelRegistry() {
+  globalRegistry.definitions.clear();
+  globalRegistry.instances.clear();
+}
+function resetModelInstances() {
+  for (const instances of globalRegistry.instances.values()) {
+    instances.clear();
+  }
+}
+function lintModel(modelId, instance, context) {
+  const definition = globalRegistry.definitions.get(modelId);
+  if (!definition || !definition.lintRules) return [];
+  const issues = [];
+  for (const rule of definition.lintRules) {
+    const issue = rule.check(instance, context);
+    if (issue) {
+      issues.push({ rule, issue });
+    }
+  }
+  return issues;
+}
+function lintAllModels(context) {
+  const allIssues = [];
+  for (const [modelId, instances] of globalRegistry.instances) {
+    const definition = globalRegistry.definitions.get(modelId);
+    if (!definition || !definition.lintRules) continue;
+    for (const [instanceId, instance] of instances) {
+      for (const rule of definition.lintRules) {
+        const issue = rule.check(instance, context);
+        if (issue) {
+          allIssues.push({
+            modelId,
+            instanceId,
+            rule,
+            issue
+          });
+        }
+      }
+    }
+  }
+  return allIssues;
+}
+function exportMarkdown(modelId, context) {
+  const definition = globalRegistry.definitions.get(modelId);
+  if (!definition || !definition.exporters?.markdown) return [];
+  const exporter = definition.exporters.markdown;
+  const instances = getAllModelInstances(modelId);
+  const files = [];
+  for (const instance of instances) {
+    const content = exporter.single(instance, context);
+    const filename = exporter.filename ? exporter.filename(instance) : instance.id;
+    files.push({
+      path: `${context.outputDir}/${exporter.outputDir}/${filename}.md`,
+      content
+    });
+  }
+  if (exporter.index && instances.length > 0) {
+    const indexContent = exporter.index(instances, context);
+    files.push({
+      path: `${context.outputDir}/${exporter.outputDir}/index.md`,
+      content: indexContent
+    });
+  }
+  return files;
+}
+function exportMermaid(modelId, context) {
+  const definition = globalRegistry.definitions.get(modelId);
+  if (!definition || !definition.exporters?.mermaid) return [];
+  const exporters = Array.isArray(definition.exporters.mermaid) ? definition.exporters.mermaid : [definition.exporters.mermaid];
+  const instances = getAllModelInstances(modelId);
+  const files = [];
+  for (const exporter of exporters) {
+    const content = exporter.generate(instances, context);
+    files.push({
+      path: `${context.outputDir}/${exporter.outputPath}`,
+      content
+    });
+  }
+  return files;
+}
+function exportAllModels(context) {
+  const files = [];
+  for (const modelId of globalRegistry.definitions.keys()) {
+    files.push(...exportMarkdown(modelId, context));
+    files.push(...exportMermaid(modelId, context));
+  }
+  return files;
+}
+function checkExternalSsot(modelId, externalSource, context) {
+  const definition = globalRegistry.definitions.get(modelId);
+  if (!definition || !definition.externalChecker) {
+    return { success: true, errors: [], warnings: [] };
+  }
+  const checker = definition.externalChecker;
+  const instances = getAllModelInstances(modelId);
+  const allErrors = [];
+  const allWarnings = [];
+  for (const instance of instances) {
+    const result = checker.check(instance, externalSource, context);
+    allErrors.push(...result.errors);
+    allWarnings.push(...result.warnings);
+  }
+  return {
+    success: allErrors.length === 0,
+    errors: allErrors,
+    warnings: allWarnings
+  };
+}
+function resolveReference(modelId, instanceId, field) {
+  const definition = globalRegistry.definitions.get(modelId);
+  if (!definition || !definition.references) return void 0;
+  const refDef = definition.references.find((r) => r.field === field);
+  if (!refDef) return void 0;
+  const instance = getModelInstance(modelId, instanceId);
+  if (!instance) return void 0;
+  const refValue = instance[field];
+  if (!refValue) return void 0;
+  if (refDef.isArray && Array.isArray(refValue)) {
+    return refValue.map((id) => getModelInstance(refDef.targetModel, id));
+  }
+  return getModelInstance(refDef.targetModel, refValue);
+}
+function checkReferenceIntegrity() {
+  const issues = [];
+  for (const [modelId, definition] of globalRegistry.definitions) {
+    if (!definition.references) continue;
+    const instances = globalRegistry.instances.get(modelId);
+    if (!instances) continue;
+    for (const [instanceId, instance] of instances) {
+      const inst = instance;
+      for (const refDef of definition.references) {
+        const refValue = inst[refDef.field];
+        if (!refValue) {
+          if (refDef.required) {
+            issues.push({
+              modelId,
+              instanceId,
+              field: refDef.field,
+              targetModel: refDef.targetModel,
+              missingIds: ["(required but not provided)"]
+            });
+          }
+          continue;
+        }
+        const targetInstances = globalRegistry.instances.get(refDef.targetModel);
+        const missingIds = [];
+        if (refDef.isArray && Array.isArray(refValue)) {
+          for (const id of refValue) {
+            if (!targetInstances?.has(id)) {
+              missingIds.push(id);
+            }
+          }
+        } else {
+          if (!targetInstances?.has(refValue)) {
+            missingIds.push(refValue);
+          }
+        }
+        if (missingIds.length > 0) {
+          issues.push({
+            modelId,
+            instanceId,
+            field: refDef.field,
+            targetModel: refDef.targetModel,
+            missingIds
+          });
+        }
+      }
+    }
+  }
+  return issues;
+}
+function getModelRegistryStats() {
+  const instanceCounts = {};
+  let totalInstances = 0;
+  for (const [modelId, instances] of globalRegistry.instances) {
+    instanceCounts[modelId] = instances.size;
+    totalInstances += instances.size;
+  }
+  return {
+    definitionCount: globalRegistry.definitions.size,
+    instanceCounts,
+    totalInstances
+  };
+}
+
+// src/core/config-api.ts
+function defineConfig(input) {
+  const resolved = {
+    ...input,
+    designDir: input.designDir ?? "design",
+    docsDir: input.docsDir ?? "docs",
+    specsDir: input.specsDir ?? "specs"
+  };
+  if (input.models && input.models.length > 0) {
+    registerModelDefinitions(input.models);
+  }
+  return resolved;
+}
+function defineModel(input) {
+  const definition = {
+    id: input.id,
+    name: input.name,
+    description: input.description,
+    schema: input.schema,
+    idPrefix: input.idPrefix,
+    exporters: input.exporters,
+    lintRules: input.lintRules,
+    externalChecker: input.externalChecker,
+    references: input.references,
+    dslName: input.dslName,
+    phase: input.phase
+  };
+  return definition;
+}
+function createMarkdownExporter(config) {
+  return {
+    single: config.single,
+    index: config.index,
+    outputDir: config.outputDir,
+    filename: config.filename
+  };
+}
+function createMermaidExporter(config) {
+  return {
+    diagramType: config.diagramType,
+    outputPath: config.outputPath,
+    generate: config.generate,
+    title: config.title
+  };
+}
+function createLintRule(config) {
+  return {
+    id: config.id,
+    description: config.description,
+    severity: config.severity,
+    check: config.check
+  };
+}
+async function loadSpeckeeperConfig(configPath) {
+  const possiblePaths = configPath ? [configPath] : [
+    "speckeeper.config.ts",
+    "speckeeper.config.js",
+    "speckeeper.config.mjs"
+  ];
+  for (const path of possiblePaths) {
+    try {
+      const fullPath = path.startsWith("/") ? path : `${process.cwd()}/${path}`;
+      const module = await import(fullPath);
+      const config = module.default || module;
+      if (config && typeof config === "object") {
+        if (config.models && Array.isArray(config.models)) {
+          registerModelDefinitions(config.models);
+        }
+        return {
+          ...config,
+          designDir: config.designDir ?? "design",
+          docsDir: config.docsDir ?? "docs",
+          specsDir: config.specsDir ?? "specs"
+        };
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+var defaultConfig = {
+  srcDir: "src",
+  designDir: "design",
+  // Directory for requirements/design TS models
+  docsDir: "docs",
+  specsDir: "specs"
+};
+function getOutputPaths(config, cwd = process.cwd()) {
+  const docsDir = resolve(cwd, config.docsDir);
+  const specsDir = resolve(cwd, config.specsDir);
+  return {
+    // docs/ subdirectories (compliant with spec section 7.1)
+    requirements: join(docsDir, "requirements"),
+    usecases: join(docsDir, "usecases"),
+    architecture: join(docsDir, "architecture"),
+    dataModel: join(docsDir, "data-model"),
+    screens: join(docsDir, "screens"),
+    flows: join(docsDir, "flows"),
+    glossary: join(docsDir, "glossary"),
+    component: join(docsDir, "component"),
+    // specs/ subdirectories (compliant with spec section 7.1)
+    schemasEntities: join(specsDir, "schemas", "entities")
+  };
+}
+function getExpectedOutputDirs(config, cwd = process.cwd()) {
+  const paths = getOutputPaths(config, cwd);
+  return [
+    paths.requirements,
+    paths.usecases,
+    paths.architecture,
+    paths.dataModel,
+    paths.screens,
+    paths.flows,
+    paths.glossary,
+    paths.component,
+    paths.schemasEntities
+  ];
+}
+function validateOutputPaths(actualPath, config, cwd = process.cwd()) {
+  const expectedDirs = getExpectedOutputDirs(config, cwd);
+  const docsDir = resolve(cwd, config.docsDir);
+  const specsDir = resolve(cwd, config.specsDir);
+  const isUnderDocs = actualPath.startsWith(docsDir);
+  const isUnderSpecs = actualPath.startsWith(specsDir);
+  if (!isUnderDocs && !isUnderSpecs) {
+    return {
+      valid: false,
+      expectedPaths: expectedDirs,
+      message: `Output path "${actualPath}" is not under docs/ or specs/`
+    };
+  }
+  const isValidPath = expectedDirs.some((dir) => actualPath.startsWith(dir));
+  if (!isValidPath) {
+    return {
+      valid: false,
+      expectedPaths: expectedDirs,
+      message: `Output path "${actualPath}" does not match spec-compliant paths. Expected one of: ${expectedDirs.map((d) => d.replace(cwd + "/", "")).join(", ")}`
+    };
+  }
+  return { valid: true, expectedPaths: expectedDirs };
+}
+var CONFIG_FILES = [
+  "speckeeper.config.yaml",
+  "speckeeper.config.yml",
+  "speckeeper.config.json",
+  "speckeeper.config.ts",
+  "speckeeper.config.js"
+];
+function findConfigFile(startDir = process.cwd()) {
+  let currentDir = startDir;
+  while (currentDir !== dirname(currentDir)) {
+    for (const configFile of CONFIG_FILES) {
+      const configPath = resolve(currentDir, configFile);
+      if (existsSync(configPath)) {
+        return configPath;
+      }
+    }
+    currentDir = dirname(currentDir);
+  }
+  return null;
+}
+async function loadConfig(configPath, cwd = process.cwd()) {
+  const resolvedPath = configPath ?? findConfigFile(cwd);
+  if (!resolvedPath) {
+    return { ...defaultConfig };
+  }
+  const ext = resolvedPath.split(".").pop()?.toLowerCase();
+  try {
+    if (ext === "yaml" || ext === "yml") {
+      const content = readFileSync(resolvedPath, "utf-8");
+      const parsed = parse(content);
+      return { ...defaultConfig, ...parsed };
+    }
+    if (ext === "json") {
+      const content = readFileSync(resolvedPath, "utf-8");
+      const parsed = JSON.parse(content);
+      return { ...defaultConfig, ...parsed };
+    }
+    if (ext === "ts" || ext === "js") {
+      const module = await import(resolvedPath);
+      const parsed = module.default ?? module;
+      return { ...defaultConfig, ...parsed };
+    }
+    return { ...defaultConfig };
+  } catch (error) {
+    console.error(`Failed to load config from ${resolvedPath}:`, error);
+    return { ...defaultConfig };
+  }
+}
+function validateConfig(config) {
+  const errors = [];
+  if (!config.srcDir) {
+    errors.push("srcDir is required");
+  }
+  if (!config.docsDir) {
+    errors.push("docsDir is required");
+  }
+  if (!config.specsDir) {
+    errors.push("specsDir is required");
+  }
+  return errors;
+}
+function ensureDir(dirPath) {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirPath, { recursive: true });
+  }
+}
+function writeFile(filePath, content) {
+  const dir = dirname(filePath);
+  ensureDir(dir);
+  const existed = existsSync(filePath);
+  let unchanged = false;
+  if (existed) {
+    const existingContent = readFileSync(filePath, "utf-8");
+    unchanged = existingContent === content;
+  }
+  if (!unchanged) {
+    writeFileSync(filePath, content, "utf-8");
+  }
+  return {
+    path: filePath,
+    created: !existed,
+    updated: existed && !unchanged,
+    unchanged
+  };
+}
+function writeJsonFile(filePath, data, indent = 2) {
+  const content = JSON.stringify(data, null, indent) + "\n";
+  return writeFile(filePath, content);
+}
+function batchWriteFiles(files) {
+  const results = [];
+  for (const { path, content } of files) {
+    results.push(writeFile(path, content));
+  }
+  return {
+    results,
+    created: results.filter((r) => r.created).length,
+    updated: results.filter((r) => r.updated).length,
+    unchanged: results.filter((r) => r.unchanged).length,
+    total: results.length
+  };
+}
+function computeHash(content) {
+  return createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+function checkFileDrift(filePath, expectedContent) {
+  const expectedHash = computeHash(expectedContent);
+  if (!existsSync(filePath)) {
+    return {
+      file: filePath,
+      hasDrift: true,
+      expectedHash,
+      missing: true
+    };
+  }
+  const actualContent = readFileSync(filePath, "utf-8");
+  const actualHash = computeHash(actualContent);
+  return {
+    file: filePath,
+    hasDrift: expectedHash !== actualHash,
+    expectedHash,
+    actualHash
+  };
+}
+function checkBatchDrift(files) {
+  return files.map(({ path, content }) => checkFileDrift(path, content));
+}
+async function findFiles(pattern, cwd = process.cwd()) {
+  return glob(pattern, { cwd, absolute: true });
+}
+async function findTypeScriptFiles(srcDir) {
+  return findFiles("**/*.ts", srcDir);
+}
+async function findDefinitionFiles(srcDir, subDir) {
+  const pattern = join(srcDir, subDir, "**/*.ts");
+  return glob(pattern, { absolute: true, ignore: ["**/*.d.ts", "**/index.ts"] });
+}
+function generateDocsPath(baseDir, category, filename) {
+  return join(baseDir, category, filename);
+}
+function generateSpecsPath(baseDir, category, filename) {
+  return join(baseDir, category, filename);
+}
+function createEmptyRegistry() {
+  return {
+    requirements: /* @__PURE__ */ new Map(),
+    useCases: /* @__PURE__ */ new Map(),
+    actors: /* @__PURE__ */ new Map(),
+    components: /* @__PURE__ */ new Map(),
+    entities: /* @__PURE__ */ new Map(),
+    relations: /* @__PURE__ */ new Map(),
+    rules: /* @__PURE__ */ new Map(),
+    screens: /* @__PURE__ */ new Map(),
+    transitions: /* @__PURE__ */ new Map(),
+    forms: /* @__PURE__ */ new Map(),
+    processFlows: /* @__PURE__ */ new Map(),
+    glossaryTerms: /* @__PURE__ */ new Map(),
+    apiRefs: /* @__PURE__ */ new Map(),
+    tableRefs: /* @__PURE__ */ new Map(),
+    testRefs: /* @__PURE__ */ new Map(),
+    layers: /* @__PURE__ */ new Map(),
+    boundaries: /* @__PURE__ */ new Map(),
+    artifacts: /* @__PURE__ */ new Map()
+  };
+}
+var globalRegistry2 = createEmptyRegistry();
+function getGlobalRegistry() {
+  return globalRegistry2;
+}
+function resetGlobalRegistry() {
+  globalRegistry2 = createEmptyRegistry();
+}
+function isModelInstance(value) {
+  if (!value || typeof value !== "object") return false;
+  const obj = value;
+  return typeof obj.id === "string" && typeof obj.name === "string" && typeof obj.idPrefix === "string" && obj.schema !== void 0 && typeof obj.validate === "function" && typeof obj.lint === "function";
+}
+function registerExportedModels(module) {
+  for (const [exportName, exportValue] of Object.entries(module)) {
+    if (!exportValue || typeof exportValue !== "object") continue;
+    if (isModelInstance(exportValue)) {
+      registerModel(exportValue);
+      continue;
+    }
+    if (Array.isArray(exportValue)) {
+      registerArrayItems(exportName, exportValue);
+      continue;
+    }
+    const value = exportValue;
+    if (value.components && value.layers && value.boundaries && value.relations) {
+      const arch = value;
+      for (const comp of arch.components) {
+        if (comp.id) globalRegistry2.components.set(comp.id, comp);
+      }
+      for (const layer of arch.layers) {
+        if (layer.id) globalRegistry2.layers.set(layer.id, layer);
+      }
+      for (const boundary of arch.boundaries) {
+        if (boundary.id) globalRegistry2.boundaries.set(boundary.id, boundary);
+      }
+      for (const rel of arch.relations) {
+        if (rel.id) globalRegistry2.relations.set(rel.id, rel);
+      }
+      continue;
+    }
+    if (value.entities && value.relations && Array.isArray(value.entities)) {
+      const concept = value;
+      for (const entity of concept.entities) {
+        if (entity.id) globalRegistry2.entities.set(entity.id, entity);
+      }
+      for (const rel of concept.relations) {
+        if (rel.id) globalRegistry2.relations.set(rel.id, rel);
+      }
+      for (const rule of concept.rules || []) {
+        if (rule.id) globalRegistry2.rules.set(rule.id, rule);
+      }
+      continue;
+    }
+    if (value.useCases && value.actors) {
+      const ucModel = value;
+      for (const uc of ucModel.useCases) {
+        if (uc.id) globalRegistry2.useCases.set(uc.id, uc);
+      }
+      for (const actor of ucModel.actors) {
+        if (actor.id) globalRegistry2.actors.set(actor.id, actor);
+      }
+      continue;
+    }
+    if (value.terms && Array.isArray(value.terms)) {
+      const glossary = value;
+      for (const term of glossary.terms) {
+        if (term.id) globalRegistry2.glossaryTerms.set(term.id, term);
+      }
+      continue;
+    }
+    if (value.id && value.title && (value.kind || value.type || value.acceptance)) {
+      globalRegistry2.requirements.set(value.id, value);
+      continue;
+    }
+    if (value.id && value.name && value.attributes && Array.isArray(value.attributes)) {
+      globalRegistry2.entities.set(value.id, value);
+      continue;
+    }
+    if (value.id && value.name && value.actor && value.mainFlow) {
+      globalRegistry2.useCases.set(value.id, value);
+      continue;
+    }
+    if (value.id && value.name && value.type && ["human", "system", "external"].includes(value.type)) {
+      globalRegistry2.actors.set(value.id, value);
+      continue;
+    }
+    if (value.id && (value.term || value.abbreviation) && value.definition) {
+      globalRegistry2.glossaryTerms.set(value.id, value);
+      continue;
+    }
+  }
+}
+function registerArrayItems(exportName, items) {
+  for (const item of items) {
+    if (!item || typeof item !== "object") continue;
+    const obj = item;
+    if (!obj.id || typeof obj.id !== "string") continue;
+    if (exportName.toLowerCase().includes("requirement") || exportName.toLowerCase().includes("constraints") || obj.type && obj.acceptanceCriteria) {
+      globalRegistry2.requirements.set(obj.id, item);
+      continue;
+    }
+    if (exportName.toLowerCase().includes("usecase") || obj.actor && obj.mainFlow) {
+      globalRegistry2.useCases.set(obj.id, item);
+      continue;
+    }
+    if (exportName.toLowerCase().includes("actor") || obj.type && ["human", "system", "external"].includes(obj.type) && !obj.mainFlow) {
+      globalRegistry2.actors.set(obj.id, item);
+      continue;
+    }
+    if (exportName.toLowerCase().includes("component") || exportName.toLowerCase().includes("container") || obj.type && ["person", "system", "container", "component"].includes(obj.type)) {
+      globalRegistry2.components.set(obj.id, item);
+      continue;
+    }
+    if (exportName.toLowerCase().includes("entit") || obj.name && obj.attributes && Array.isArray(obj.attributes)) {
+      globalRegistry2.entities.set(obj.id, item);
+      continue;
+    }
+    if (exportName.toLowerCase().includes("term") || exportName.toLowerCase().includes("acronym") || exportName.toLowerCase().includes("glossary") || obj.term && obj.definition) {
+      globalRegistry2.glossaryTerms.set(obj.id, item);
+      continue;
+    }
+    if (exportName.toLowerCase().includes("relation") || obj.from && obj.to && obj.label) {
+      globalRegistry2.relations.set(obj.id, item);
+      continue;
+    }
+    if (exportName.toLowerCase().includes("layer") || obj.name && typeof obj.order === "number") {
+      globalRegistry2.layers.set(obj.id, item);
+      continue;
+    }
+    if (exportName.toLowerCase().includes("boundar") || obj.type && ["system", "context", "container", "deployment"].includes(obj.type) && obj.description) {
+      globalRegistry2.boundaries.set(obj.id, item);
+      continue;
+    }
+    if (exportName.toLowerCase().includes("screen") || obj.type && ["page", "modal", "drawer", "panel", "wizard"].includes(obj.type) && obj.auth) {
+      globalRegistry2.screens.set(obj.id, item);
+      continue;
+    }
+    if (exportName.toLowerCase().includes("testref") || exportName.toLowerCase().includes("test-ref") || obj.source && obj.verifiesRequirements && Array.isArray(obj.verifiesRequirements)) {
+      globalRegistry2.testRefs.set(obj.id, item);
+      continue;
+    }
+    if (exportName.toLowerCase().includes("artifact") || obj.category && obj.location && obj.purpose && ["ssot", "human-readable", "machine-readable", "implementation"].includes(obj.category)) {
+      globalRegistry2.artifacts.set(obj.id, item);
+      continue;
+    }
+  }
+}
+async function loadModelsFromDirectory(dirPath, options = {}) {
+  const loadedFiles = [];
+  if (!existsSync(dirPath)) {
+    return loadedFiles;
+  }
+  const entries = readdirSync(dirPath);
+  for (const entry of entries) {
+    const fullPath = join(dirPath, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory() && options.recursive) {
+      const subFiles = await loadModelsFromDirectory(fullPath, options);
+      loadedFiles.push(...subFiles);
+    } else if (stat.isFile()) {
+      const ext = extname(entry);
+      if ([".ts", ".js", ".mts", ".mjs"].includes(ext) && !entry.endsWith(".d.ts")) {
+        if (basename(entry, ext) === "index") {
+          continue;
+        }
+        try {
+          const module = await import(fullPath);
+          loadedFiles.push(fullPath);
+          registerExportedModels(module);
+        } catch (error) {
+          console.error(`Failed to load model from ${fullPath}:`, error);
+        }
+      }
+    }
+  }
+  return loadedFiles;
+}
+async function loadAllModels(config, cwd = process.cwd()) {
+  resetGlobalRegistry();
+  const loadedFiles = [];
+  const errors = [];
+  const designDir = resolve(cwd, config.designDir || "design");
+  const modelDirs = [
+    { path: join(designDir, "requirements") },
+    { path: join(designDir, "usecases") },
+    { path: join(designDir, "architecture") },
+    { path: join(designDir, "data-model") },
+    { path: join(designDir, "screens") },
+    { path: join(designDir, "flows") },
+    { path: join(designDir, "glossary") },
+    // Also load files directly under design/ by default (index.ts, etc.)
+    { path: designDir }
+  ];
+  for (const { path: dirPath } of modelDirs) {
+    if (!existsSync(dirPath)) {
+      continue;
+    }
+    try {
+      const files = await loadModelsFromDirectory(dirPath, { recursive: true });
+      loadedFiles.push(...files);
+    } catch (error) {
+      errors.push({ file: dirPath, error });
+    }
+  }
+  return {
+    registry: getGlobalRegistry(),
+    loadedFiles,
+    errors
+  };
+}
+function getRegistryStats(registry) {
+  const stats = {};
+  for (const [key, map] of Object.entries(registry)) {
+    stats[key] = map.size;
+  }
+  return stats;
+}
+function getAllIds(registry) {
+  const allIds = /* @__PURE__ */ new Set();
+  for (const map of Object.values(registry)) {
+    for (const id of map.keys()) {
+      allIds.add(id);
+    }
+  }
+  return allIds;
+}
+function findModelType(registry, id) {
+  for (const [type, map] of Object.entries(registry)) {
+    if (map.has(id)) {
+      return type;
+    }
+  }
+  return null;
+}
+function getModelById(registry, id) {
+  const type = findModelType(registry, id);
+  if (!type) return null;
+  return {
+    type,
+    model: registry[type].get(id)
+  };
+}
+
+export { CheckErrorSchema, CheckResultSchema, CheckWarningSchema, ConcretizationSlotSchema, ID_PATTERNS, LinkSchema, LintIssueSchema, Model, PhaseSchema, PrioritySchema, RELATION_CONSTRAINTS, RELATION_TYPES, ReferenceDefinitionSchema, RelationSchema, RelationsFieldSchema, batchWriteFiles, checkBatchDrift, checkExternalSsot, checkFileDrift, checkReferenceIntegrity, clearModelRegistry, computeHash, createAPIRefId, createActorId, createBatchRefId, createBoundaryId, createComponentId, createDTORequirementId, createEmptyRegistry, createEntityId, createErrorCaseId, createEventRequirementId, createFormId, createIaCRefId, createLayerId, createLintRule, createMarkdownExporter, createMermaidExporter, createProcessFlowId, createRelationId, createRequirementId, createRuleId, createScreenId, createStateId, createTableRefId, createTermId, createTransitionId, createUIComponentId, createUseCaseId, defineConfig, defineModel, detectCycles, ensureDir, exportAllModels, exportMarkdown, exportMermaid, findConfigFile, findDefinitionFiles, findFiles, findModelType, findTypeScriptFiles, generateDocsPath, generateSpecsPath, getAllIds, getAllInstances, getAllModelDefinitions, getAllModelInstances, getAllModels, getExpectedOutputDirs, getGlobalModelRegistry, getGlobalRegistry, getLevelIndex, getModel, getModelById, getModelDefinition, getModelInstance, getModelRegistryStats, getOutputPaths, getRegistryStats, inferModelIdFromSpecId, lintAllModels, lintModel, loadAllModels, loadConfig, loadModelsFromDirectory, loadSpeckeeperConfig, registerModel, registerModelDefinition, registerModelDefinitions, registerModelInstance, resetGlobalRegistry, resetModelInstances, resetModelRegistry, resolveReference, validateConfig, validateOutputPaths, validateRelationLevel, writeFile, writeJsonFile };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map