@documentation-robotics/cli 0.1.0 → 0.1.7

package/dist/validators/relationship-schema-validator.js

@@ -0,0 +1,243 @@
+import { ValidationResult } from "./types.js";
+import { fileURLToPath } from "url";
+import path from "path";
+import { readFile } from "../utils/file-io.js";
+import { existsSync } from "fs";
+import { startActiveSpan } from "../telemetry/index.js";
+const isTelemetryEnabled = !1;
+class RelationshipValidator {
+  schemasDir;
+  relationshipSchemas = /* @__PURE__ */ new Map();
+  constructor() {
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    this.schemasDir = path.join(__dirname, "..", "schemas", "bundled");
+  }
+  /**
+   * Initialize and load relationship schemas
+   */
+  async initialize() {
+    await this.loadRelationshipSchemas();
+  }
+  /**
+   * Load relationship schemas from compiled bundled spec (manifest.json + per-layer JSON files)
+   */
+  async loadRelationshipSchemas() {
+    const manifestPath = path.join(this.schemasDir, "manifest.json");
+    if (!existsSync(manifestPath))
+      throw new Error(`Bundled manifest not found at ${manifestPath}`);
+    const manifestContent = await readFile(manifestPath), manifest = JSON.parse(manifestContent);
+    for (const { id: layerId } of manifest.layers) {
+      const layerPath = path.join(this.schemasDir, `${layerId}.json`);
+      if (existsSync(layerPath))
+        try {
+          const layerContent = await readFile(layerPath), layerData = JSON.parse(layerContent);
+          for (const [relId, relSchema] of Object.entries(layerData.relationshipSchemas || {}))
+            this.relationshipSchemas.set(relId, {
+              id: relSchema.id || relId,
+              source_spec_node_id: relSchema.source_spec_node_id || "",
+              source_layer: relSchema.source_layer || "",
+              destination_spec_node_id: relSchema.destination_spec_node_id || "",
+              destination_layer: relSchema.destination_layer || "",
+              predicate: relSchema.predicate || "",
+              cardinality: relSchema.cardinality || "many-to-many",
+              strength: relSchema.strength || "medium",
+              required: relSchema.required || !1,
+              attributes: relSchema.attributes
+            });
+        } catch (error) {
+          throw new Error(`Failed to load relationship schemas for layer '${layerId}': ${error.message}`);
+        }
+    }
+  }
+  /**
+   * Validate relationships in a model with cardinality enforcement
+   */
+  async validateModel(model) {
+    return startActiveSpan("relationship-schema.validate-model", async (span) => {
+      if (this.relationshipSchemas.size === 0)
+        try {
+          await this.initialize();
+        } catch (error) {
+          const result2 = new ValidationResult();
+          return result2.addError({
+            layer: "system",
+            message: `${error.message} Relationship validation is not available.`
+          }), result2;
+        }
+      if (this.relationshipSchemas.size === 0) {
+        const result2 = new ValidationResult();
+        return result2.addError({
+          layer: "system",
+          message: `No relationship schemas loaded from ${path.join(this.schemasDir, "manifest.json")}. Relationship validation is not available.`
+        }), result2;
+      }
+      const result = new ValidationResult(), allRelationships = model.relationships.getAll();
+      if (allRelationships.length === 0)
+        return result;
+      const relationshipsBySource = this.groupRelationshipsBySourceTarget(allRelationships, "source"), relationshipsByTarget = this.groupRelationshipsBySourceTarget(allRelationships, "target");
+      for (const relationship of allRelationships) {
+        const relErrors = await this.validateRelationship(relationship, model, relationshipsBySource, relationshipsByTarget);
+        if (relErrors.length > 0)
+          for (const error of relErrors)
+            result.addError(error);
+      }
+      return isTelemetryEnabled && (span.setAttribute("relationship.error_count", result.errors.length), span.setAttribute("relationship.warning_count", result.warnings.length), span.setAttribute("relationship.validated_count", allRelationships.length)), result;
+    }, { "relationship.layer_count": model.layers.size });
+  }
+  /**
+   * Validate a single relationship
+   */
+  async validateRelationship(relationship, model, relationshipsBySource, relationshipsByTarget) {
+    const errors = [], sourceElement = this.findElementInModel(model, relationship.source), targetElement = this.findElementInModel(model, relationship.target);
+    if (!sourceElement)
+      return errors.push({
+        layer: relationship.layer,
+        elementId: relationship.source,
+        message: `Relationship source element '${relationship.source}' not found`
+      }), errors;
+    if (!targetElement)
+      return errors.push({
+        layer: relationship.layer,
+        elementId: relationship.target,
+        message: `Relationship target element '${relationship.target}' not found`
+      }), errors;
+    const sourceLayer = sourceElement.layer_id || sourceElement.layer || relationship.layer, targetLayer = targetElement.layer_id || targetElement.layer || relationship.layer, sourceSpecId = sourceElement.spec_node_id ? sourceElement.spec_node_id : `${sourceLayer}.${sourceElement.type}`, targetSpecId = targetElement.spec_node_id ? targetElement.spec_node_id : `${targetLayer}.${targetElement.type}`, schemaKey = this.findRelationshipSchemaKeyBySpecId(sourceSpecId, targetSpecId, relationship.predicate);
+    if (!schemaKey) {
+      const sourceType = sourceSpecId.includes(".") ? sourceSpecId.split(".")[1] : sourceElement.type, targetType = targetSpecId.includes(".") ? targetSpecId.split(".")[1] : targetElement.type;
+      return errors.push({
+        layer: relationship.layer,
+        elementId: relationship.source,
+        message: `No schema found for relationship: ${sourceLayer}.${sourceType} --[${relationship.predicate}]--> ${targetLayer}.${targetType}`
+      }), errors;
+    }
+    const schema = this.relationshipSchemas.get(schemaKey);
+    if (!schema)
+      return errors.push({
+        layer: relationship.layer,
+        elementId: relationship.source,
+        message: `Failed to load schema for relationship: ${schemaKey}`
+      }), errors;
+    const cardinalityErrors = this.validateCardinality(relationship, schema, relationshipsBySource, relationshipsByTarget);
+    if (errors.push(...cardinalityErrors), relationship.properties && schema.attributes) {
+      const attrErrors = this.validateRelationshipAttributes(relationship, schema);
+      errors.push(...attrErrors);
+    }
+    return errors;
+  }
+  /**
+   * Validate cardinality constraints for a relationship
+   *
+   * Cardinality constraint semantics:
+   * - "one-to-one": Each source can have at most 1 such relationship, and each target can be involved in at most 1
+   * - "one-to-many": Each target can receive at most 1 such relationship (target is the "one"); source is unconstrained
+   * - "many-to-one": Each source can be involved in at most 1 such relationship (maps to one target); multiple sources may share the same target
+   * - "many-to-many": No cardinality constraints
+   */
+  validateCardinality(relationship, schema, relationshipsBySource, relationshipsByTarget) {
+    const errors = [], cardinality = schema.cardinality, sourceRelCount = relationshipsBySource.get(relationship.source)?.filter(
+      (r) => r.predicate === relationship.predicate && r.target !== relationship.target
+      // Exclude current relationship
+    ).length || 0, targetRelCount = relationshipsByTarget.get(relationship.target)?.filter(
+      (r) => r.predicate === relationship.predicate && r.source !== relationship.source
+      // Exclude current relationship
+    ).length || 0;
+    switch (cardinality) {
+      case "one-to-one":
+        sourceRelCount > 0 && errors.push({
+          layer: relationship.layer,
+          elementId: relationship.source,
+          message: `Cardinality violation: '${relationship.predicate}' has cardinality 'one-to-one', but source '${relationship.source}' already has this relationship`
+        }), targetRelCount > 0 && errors.push({
+          layer: relationship.layer,
+          elementId: relationship.target,
+          message: `Cardinality violation: '${relationship.predicate}' has cardinality 'one-to-one', but target '${relationship.target}' is already involved in this relationship`
+        });
+        break;
+      case "one-to-many":
+        targetRelCount > 0 && errors.push({
+          layer: relationship.layer,
+          elementId: relationship.target,
+          message: `Cardinality violation: '${relationship.predicate}' has cardinality 'one-to-many', but target '${relationship.target}' already has this relationship`
+        });
+        break;
+      case "many-to-one":
+        sourceRelCount > 0 && errors.push({
+          layer: relationship.layer,
+          elementId: relationship.source,
+          message: `Cardinality violation: '${relationship.predicate}' has cardinality 'many-to-one', but source '${relationship.source}' already has this relationship`
+        });
+        break;
+      case "many-to-many":
+        break;
+    }
+    return errors;
+  }
+  /**
+   * Validate relationship attributes against schema
+   */
+  validateRelationshipAttributes(relationship, schema) {
+    const errors = [];
+    if (!schema.attributes || !relationship.properties)
+      return errors;
+    for (const key of Object.keys(relationship.properties))
+      key in schema.attributes || errors.push({
+        layer: relationship.layer,
+        elementId: relationship.source,
+        message: `Relationship property '${key}' not defined in schema for predicate '${relationship.predicate}'`
+      });
+    return errors;
+  }
+  /**
+   * Find relationship schema ID by source/dest spec node IDs and predicate
+   *
+   * Matches relationship schemas by:
+   * 1. Predicate (must match exactly)
+   * 2. Spec node ID pair (source and destination must match exactly)
+   *
+   * Spec node IDs are in the format "layer.type" (e.g., "application.applicationservice")
+   * and uniquely identify an element type across the model.
+   *
+   * Supports both intra-layer (motivation -> motivation) and cross-layer
+   * (motivation -> business) relationships.
+   */
+  findRelationshipSchemaKeyBySpecId(sourceSpecId, destSpecId, predicate) {
+    for (const [schemaId, schema] of this.relationshipSchemas.entries())
+      if (schema.predicate === predicate && schema.source_spec_node_id === sourceSpecId && schema.destination_spec_node_id === destSpecId)
+        return schemaId;
+    return null;
+  }
+  /**
+   * Group relationships by source or target element
+   */
+  groupRelationshipsBySourceTarget(relationships, by) {
+    const grouped = /* @__PURE__ */ new Map();
+    for (const rel of relationships) {
+      const key = by === "source" ? rel.source : rel.target;
+      grouped.has(key) || grouped.set(key, []), grouped.get(key).push(rel);
+    }
+    return grouped;
+  }
+  /**
+   * Find an element in the model by ID
+   *
+   * Performs element lookup using Layer.getElement(), which supports multiple lookup strategies:
+   * - Direct lookup by graph key (path)
+   * - UUID lookup
+   * - Semantic ID lookup (for legacy format elements converted to UUID)
+   * - Element ID lookup
+   *
+   * This comprehensive lookup ensures elements are found regardless of how they were stored.
+   */
+  findElementInModel(model, elementId) {
+    for (const layer of model.layers.values()) {
+      const element = layer.getElement(elementId);
+      if (element)
+        return element;
+    }
+    return null;
+  }
+}
+export {
+  RelationshipValidator
+};
+//# sourceMappingURL=relationship-schema-validator.js.map

package/dist/validators/relationship-schema-validator.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/validators/relationship-schema-validator.ts"],
+  "sourcesContent": ["/**\n * Relationship Schema Validation with Cardinality Enforcement\n *\n * Validates relationships against their spec relationship schemas, including:\n * - Schema compliance (source/destination node types)\n * - Cardinality constraints (one-to-one, one-to-many, many-to-one, many-to-many)\n * - Predicate validity\n * - Relationship attributes against schema\n */\n\nimport { ValidationResult } from \"./types.js\";\nimport type { Model } from \"../core/model.js\";\nimport type { Relationship } from \"../core/relationships.js\";\nimport { fileURLToPath } from \"url\";\nimport path from \"path\";\nimport { readFile } from \"../utils/file-io.js\";\nimport { existsSync } from \"fs\";\nimport { startActiveSpan } from \"../telemetry/index.js\";\n\ninterface ManifestDistFile {\n  layers: Array<{ id: string }>;\n}\n\ninterface LayerDistFile {\n  relationshipSchemas: Record<string, {\n    id: string;\n    source_spec_node_id: string;\n    source_layer: string;\n    destination_spec_node_id: string;\n    destination_layer: string;\n    predicate: string;\n    cardinality: \"one-to-one\" | \"one-to-many\" | \"many-to-one\" | \"many-to-many\";\n    strength: string;\n    required?: boolean;\n    attributes?: Record<string, unknown>;\n  }>;\n}\n\ndeclare const TELEMETRY_ENABLED: boolean | undefined;\nconst isTelemetryEnabled = typeof TELEMETRY_ENABLED !== \"undefined\" ? TELEMETRY_ENABLED : false;\n\nexport interface RelationshipSchema {\n  id: string;\n  source_spec_node_id: string;\n  source_layer: string;\n  destination_spec_node_id: string;\n  destination_layer: string;\n  predicate: string;\n  cardinality: \"one-to-one\" | \"one-to-many\" | \"many-to-one\" | \"many-to-many\";\n  strength: string;\n  required?: boolean;\n  attributes?: Record<string, unknown>;\n}\n\n/**\n * Validator for relationship schema compliance and cardinality constraints\n *\n * Validates that relationships:\n * 1. Conform to their spec relationship schemas\n * 2. Respect cardinality constraints (e.g., one-to-one means max 1 relationship of that type)\n * 3. Reference valid predicates\n * 4. Have valid source/destination element types\n */\nexport class RelationshipValidator {\n  private schemasDir: string;\n  private relationshipSchemas: Map<string, RelationshipSchema> = new Map();\n\n  constructor() {\n    const __dirname = path.dirname(fileURLToPath(import.meta.url));\n    this.schemasDir = path.join(__dirname, \"..\", \"schemas\", \"bundled\");\n  }\n\n  /**\n   * Initialize and load relationship schemas\n   */\n  async initialize(): Promise<void> {\n    await this.loadRelationshipSchemas();\n  }\n\n  /**\n   * Load relationship schemas from compiled bundled spec (manifest.json + per-layer JSON files)\n   */\n  private async loadRelationshipSchemas(): Promise<void> {\n    const manifestPath = path.join(this.schemasDir, \"manifest.json\");\n\n    if (!existsSync(manifestPath)) {\n      throw new Error(`Bundled manifest not found at ${manifestPath}`);\n    }\n\n    const manifestContent = await readFile(manifestPath);\n    const manifest = JSON.parse(manifestContent) as ManifestDistFile;\n\n    for (const { id: layerId } of manifest.layers) {\n      const layerPath = path.join(this.schemasDir, `${layerId}.json`);\n      if (!existsSync(layerPath)) {\n        continue;\n      }\n\n      try {\n        const layerContent = await readFile(layerPath);\n        const layerData = JSON.parse(layerContent) as LayerDistFile;\n\n        for (const [relId, relSchema] of Object.entries(layerData.relationshipSchemas || {})) {\n          this.relationshipSchemas.set(relId, {\n            id: relSchema.id || relId,\n            source_spec_node_id: relSchema.source_spec_node_id || \"\",\n            source_layer: relSchema.source_layer || \"\",\n            destination_spec_node_id: relSchema.destination_spec_node_id || \"\",\n            destination_layer: relSchema.destination_layer || \"\",\n            predicate: relSchema.predicate || \"\",\n            cardinality: relSchema.cardinality || \"many-to-many\",\n            strength: relSchema.strength || \"medium\",\n            required: relSchema.required || false,\n            attributes: relSchema.attributes,\n          });\n        }\n      } catch (error: any) {\n        throw new Error(`Failed to load relationship schemas for layer '${layerId}': ${error.message}`);\n      }\n    }\n  }\n\n  /**\n   * Validate relationships in a model with cardinality enforcement\n   */\n  async validateModel(model: Model): Promise<ValidationResult> {\n    return startActiveSpan(\n      \"relationship-schema.validate-model\",\n      async (span) => {\n        // Ensure schemas are loaded\n        if (this.relationshipSchemas.size === 0) {\n          try {\n            await this.initialize();\n          } catch (error: any) {\n            const result = new ValidationResult();\n            result.addError({\n              layer: \"system\",\n              message: `${error.message} Relationship validation is not available.`,\n            });\n            return result;\n          }\n        }\n\n        // Verify schemas were loaded. This covers two cases:\n        // 1. initialize() succeeded but the manifest has no layers with relationship schemas\n        // 2. Edge case where manifest exists but is empty\n        // In both cases, relationship validation cannot proceed.\n        if (this.relationshipSchemas.size === 0) {\n          const result = new ValidationResult();\n          result.addError({\n            layer: \"system\",\n            message: `No relationship schemas loaded from ${path.join(this.schemasDir, \"manifest.json\")}. Relationship validation is not available.`,\n          });\n          return result;\n        }\n\n        const result = new ValidationResult();\n        const allRelationships = model.relationships.getAll();\n\n        if (allRelationships.length === 0) {\n          return result;\n        }\n\n        // Group relationships for cardinality validation\n        const relationshipsBySource = this.groupRelationshipsBySourceTarget(\n          allRelationships,\n          \"source\"\n        );\n        const relationshipsByTarget = this.groupRelationshipsBySourceTarget(\n          allRelationships,\n          \"target\"\n        );\n\n        // Validate each relationship\n        for (const relationship of allRelationships) {\n          const relErrors = await this.validateRelationship(\n            relationship,\n            model,\n            relationshipsBySource,\n            relationshipsByTarget\n          );\n\n          if (relErrors.length > 0) {\n            for (const error of relErrors) {\n              result.addError(error);\n            }\n          }\n        }\n\n        if (isTelemetryEnabled) {\n          span.setAttribute(\"relationship.error_count\", result.errors.length);\n          span.setAttribute(\"relationship.warning_count\", result.warnings.length);\n          span.setAttribute(\"relationship.validated_count\", allRelationships.length);\n        }\n\n        return result;\n      },\n      { \"relationship.layer_count\": model.layers.size }\n    );\n  }\n\n  /**\n   * Validate a single relationship\n   */\n  private async validateRelationship(\n    relationship: Relationship,\n    model: Model,\n    relationshipsBySource: Map<string, Relationship[]>,\n    relationshipsByTarget: Map<string, Relationship[]>\n  ): Promise<Array<{ layer: string; message: string; elementId?: string }>> {\n    const errors: Array<{ layer: string; message: string; elementId?: string }> = [];\n\n    // Find source and destination elements\n    const sourceElement = this.findElementInModel(model, relationship.source);\n    const targetElement = this.findElementInModel(model, relationship.target);\n\n    if (!sourceElement) {\n      errors.push({\n        layer: relationship.layer,\n        elementId: relationship.source,\n        message: `Relationship source element '${relationship.source}' not found`,\n      });\n      return errors;\n    }\n\n    if (!targetElement) {\n      errors.push({\n        layer: relationship.layer,\n        elementId: relationship.target,\n        message: `Relationship target element '${relationship.target}' not found`,\n      });\n      return errors;\n    }\n\n    // Extract element types AND layers (CRITICAL FIX for cross-layer relationships)\n    // The source and target elements may be in different layers\n    const sourceLayer = sourceElement.layer_id || sourceElement.layer || relationship.layer;\n    const targetLayer = targetElement.layer_id || targetElement.layer || relationship.layer;\n\n    // Use spec_node_id if present, otherwise construct from layer and type\n    // spec_node_id contains the canonical type (e.g., \"application.applicationservice\")\n    // Guard against empty spec_node_id from older CLI versions or manually authored elements\n    const sourceSpecId = sourceElement.spec_node_id\n      ? sourceElement.spec_node_id\n      : `${sourceLayer}.${sourceElement.type}`;\n    const targetSpecId = targetElement.spec_node_id\n      ? targetElement.spec_node_id\n      : `${targetLayer}.${targetElement.type}`;\n\n    // Find applicable relationship schema using actual source/target layers and spec node IDs\n    // (not relationship.layer for both, which assumes intra-layer relationships)\n    const schemaKey = this.findRelationshipSchemaKeyBySpecId(\n      sourceSpecId,\n      targetSpecId,\n      relationship.predicate\n    );\n\n    if (!schemaKey) {\n      // Extract type names from spec_node_id for error message (e.g., \"applicationservice\" from \"application.applicationservice\")\n      const sourceType = sourceSpecId.includes(\".\") ? sourceSpecId.split(\".\")[1] : sourceElement.type;\n      const targetType = targetSpecId.includes(\".\") ? targetSpecId.split(\".\")[1] : targetElement.type;\n      errors.push({\n        layer: relationship.layer,\n        elementId: relationship.source,\n        message: `No schema found for relationship: ${sourceLayer}.${sourceType} --[${relationship.predicate}]--> ${targetLayer}.${targetType}`,\n      });\n      return errors;\n    }\n\n    const schema = this.relationshipSchemas.get(schemaKey);\n    if (!schema) {\n      errors.push({\n        layer: relationship.layer,\n        elementId: relationship.source,\n        message: `Failed to load schema for relationship: ${schemaKey}`,\n      });\n      return errors;\n    }\n\n    // Validate cardinality constraints\n    const cardinalityErrors = this.validateCardinality(\n      relationship,\n      schema,\n      relationshipsBySource,\n      relationshipsByTarget\n    );\n\n    errors.push(...cardinalityErrors);\n\n    // Validate relationship attributes if schema specifies them\n    if (relationship.properties && schema.attributes) {\n      const attrErrors = this.validateRelationshipAttributes(\n        relationship,\n        schema\n      );\n      errors.push(...attrErrors);\n    }\n\n    return errors;\n  }\n\n  /**\n   * Validate cardinality constraints for a relationship\n   *\n   * Cardinality constraint semantics:\n   * - \"one-to-one\": Each source can have at most 1 such relationship, and each target can be involved in at most 1\n   * - \"one-to-many\": Each target can receive at most 1 such relationship (target is the \"one\"); source is unconstrained\n   * - \"many-to-one\": Each source can be involved in at most 1 such relationship (maps to one target); multiple sources may share the same target\n   * - \"many-to-many\": No cardinality constraints\n   */\n  private validateCardinality(\n    relationship: Relationship,\n    schema: RelationshipSchema,\n    relationshipsBySource: Map<string, Relationship[]>,\n    relationshipsByTarget: Map<string, Relationship[]>\n  ): Array<{ layer: string; message: string; elementId?: string }> {\n    const errors: Array<{ layer: string; message: string; elementId?: string }> = [];\n    const cardinality = schema.cardinality;\n\n    // Count OTHER relationships for this predicate from source and to target\n    // (excluding the current relationship to get accurate violation detection)\n    const sourceRelCount =\n      relationshipsBySource\n        .get(relationship.source)\n        ?.filter(\n          (r) =>\n            r.predicate === relationship.predicate &&\n            r.target !== relationship.target  // Exclude current relationship\n        ).length || 0;\n\n    const targetRelCount =\n      relationshipsByTarget\n        .get(relationship.target)\n        ?.filter(\n          (r) =>\n            r.predicate === relationship.predicate &&\n            r.source !== relationship.source  // Exclude current relationship\n        ).length || 0;\n\n    // Validate based on cardinality type\n    switch (cardinality) {\n      case \"one-to-one\":\n        // Source can have at most 1 such relationship\n        if (sourceRelCount > 0) {\n          errors.push({\n            layer: relationship.layer,\n            elementId: relationship.source,\n            message: `Cardinality violation: '${relationship.predicate}' has cardinality 'one-to-one', but source '${relationship.source}' already has this relationship`,\n          });\n        }\n        // Target can be involved in at most 1 such relationship\n        if (targetRelCount > 0) {\n          errors.push({\n            layer: relationship.layer,\n            elementId: relationship.target,\n            message: `Cardinality violation: '${relationship.predicate}' has cardinality 'one-to-one', but target '${relationship.target}' is already involved in this relationship`,\n          });\n        }\n        break;\n\n      case \"one-to-many\":\n        // Standard ER one-to-many: the \"one\" is at the target end.\n        // Each target can receive at most 1 incoming relationship of this type.\n        // The source is unconstrained \u2014 it may have many outgoing of this type\n        // to different targets.\n        if (targetRelCount > 0) {\n          errors.push({\n            layer: relationship.layer,\n            elementId: relationship.target,\n            message: `Cardinality violation: '${relationship.predicate}' has cardinality 'one-to-many', but target '${relationship.target}' already has this relationship`,\n          });\n        }\n        break;\n\n      case \"many-to-one\":\n        // Standard ER many-to-one: the \"one\" is at the source end.\n        // Each source can be involved in at most 1 relationship of this type\n        // (it maps to exactly one target). Multiple sources CAN share the same\n        // target \u2014 fan-in is allowed and expected for shared services.\n        if (sourceRelCount > 0) {\n          errors.push({\n            layer: relationship.layer,\n            elementId: relationship.source,\n            message: `Cardinality violation: '${relationship.predicate}' has cardinality 'many-to-one', but source '${relationship.source}' already has this relationship`,\n          });\n        }\n        break;\n\n      case \"many-to-many\":\n        // No cardinality constraints\n        break;\n    }\n\n    return errors;\n  }\n\n  /**\n   * Validate relationship attributes against schema\n   */\n  private validateRelationshipAttributes(\n    relationship: Relationship,\n    schema: RelationshipSchema\n  ): Array<{ layer: string; message: string; elementId?: string }> {\n    const errors: Array<{ layer: string; message: string; elementId?: string }> = [];\n\n    if (!schema.attributes || !relationship.properties) {\n      return errors;\n    }\n\n    // Simple validation: check that properties match schema keys\n    for (const key of Object.keys(relationship.properties)) {\n      if (!(key in schema.attributes)) {\n        errors.push({\n          layer: relationship.layer,\n          elementId: relationship.source,\n          message: `Relationship property '${key}' not defined in schema for predicate '${relationship.predicate}'`,\n        });\n      }\n    }\n\n    return errors;\n  }\n\n  /**\n   * Find relationship schema ID by source/dest spec node IDs and predicate\n   *\n   * Matches relationship schemas by:\n   * 1. Predicate (must match exactly)\n   * 2. Spec node ID pair (source and destination must match exactly)\n   *\n   * Spec node IDs are in the format \"layer.type\" (e.g., \"application.applicationservice\")\n   * and uniquely identify an element type across the model.\n   *\n   * Supports both intra-layer (motivation -> motivation) and cross-layer\n   * (motivation -> business) relationships.\n   */\n  private findRelationshipSchemaKeyBySpecId(\n    sourceSpecId: string,\n    destSpecId: string,\n    predicate: string\n  ): string | null {\n    // Search for matching schema\n    for (const [schemaId, schema] of this.relationshipSchemas.entries()) {\n      // First filter: predicate must match exactly\n      if (schema.predicate !== predicate) {\n        continue;\n      }\n\n      // Second filter: spec node ID pair must match exactly\n      // This directly compares canonical forms like \"application.applicationservice\"\n      if (\n        schema.source_spec_node_id === sourceSpecId &&\n        schema.destination_spec_node_id === destSpecId\n      ) {\n        return schemaId;\n      }\n    }\n\n    return null;\n  }\n\n  /**\n   * Group relationships by source or target element\n   */\n  private groupRelationshipsBySourceTarget(\n    relationships: Relationship[],\n    by: \"source\" | \"target\"\n  ): Map<string, Relationship[]> {\n    const grouped = new Map<string, Relationship[]>();\n\n    for (const rel of relationships) {\n      const key = by === \"source\" ? rel.source : rel.target;\n      if (!grouped.has(key)) {\n        grouped.set(key, []);\n      }\n      grouped.get(key)!.push(rel);\n    }\n\n    return grouped;\n  }\n\n  /**\n   * Find an element in the model by ID\n   *\n   * Performs element lookup using Layer.getElement(), which supports multiple lookup strategies:\n   * - Direct lookup by graph key (path)\n   * - UUID lookup\n   * - Semantic ID lookup (for legacy format elements converted to UUID)\n   * - Element ID lookup\n   *\n   * This comprehensive lookup ensures elements are found regardless of how they were stored.\n   */\n  private findElementInModel(model: Model, elementId: string) {\n    for (const layer of model.layers.values()) {\n      const element = layer.getElement(elementId);\n      if (element) {\n        return element;\n      }\n    }\n    return null;\n  }\n\n}\n"],
+  "mappings": "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",
+  "names": ["result"]
+}

package/dist/validators/schema-validator.js

@@ -4,95 +4,177 @@ import { ValidationResult } from "./types.js";
 import { fileURLToPath } from "url";
 import path from "path";
 import { readFile } from "../utils/file-io.js";
-import { startSpan, endSpan } from "../telemetry/index.js";
+import { startActiveSpan } from "../telemetry/index.js";
+import { existsSync } from "fs";
+import { validateSpecNode, validateSpecNodeRelationship, validateSourceReference, validateAttributeSpec } from "../generated/compiled-validators.js";
 const isTelemetryEnabled = !1;
 class SchemaValidator {
+  // Static shared AJV instance to avoid schema registry conflicts
+  // When multiple SchemaValidator instances are created, they all use the same
+  // AJV instance which maintains a single schema registry. This prevents
+  // "schema with key or id already exists" errors when loading the same schemas.
+  static sharedAjv = null;
+  static baseSchemaLoadedInSharedInstance = !1;
+  // Track schema IDs already registered in the shared AJV instance to avoid re-registering
+  static registeredSchemaIds = /* @__PURE__ */ new Set();
+  // Layer-level cache: layer ID → nodeSchemas map (avoids re-reading layer dist files)
+  static layerCache = /* @__PURE__ */ new Map();
   ajv;
   compiledSchemas = /* @__PURE__ */ new Map();
-  schemasLoaded = !1;
+  // Key: layer.type
+  bundledDir;
   constructor() {
-    this.ajv = new Ajv({
+    SchemaValidator.sharedAjv || (SchemaValidator.sharedAjv = new Ajv({
       allErrors: !0,
       strict: !1,
-      validateFormats: !0
-    }), addFormats(this.ajv);
+      validateFormats: !0,
+      verbose: !0
+    }), addFormats(SchemaValidator.sharedAjv)), this.ajv = SchemaValidator.sharedAjv;
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    this.bundledDir = path.join(__dirname, "..", "schemas", "bundled");
   }
   /**
-   * Ensure schemas are precompiled before validation
+   * Extract error message from unknown error type with proper type checking
    */
-  async ensureSchemasLoaded() {
-    this.schemasLoaded || (await this.precompileSchemas(), this.schemasLoaded = !0);
+  static getErrorMessage(error) {
+    if (error instanceof Error)
+      return error.message;
+    if (typeof error == "object" && error !== null && "message" in error) {
+      const msg = error.message;
+      if (typeof msg == "string")
+        return msg;
+    }
+    return "Unknown error";
   }
   /**
-   * Precompile all layer schemas for efficient validation
+   * Ensure base schemas are pre-compiled validators are initialized
+   * Loads base schemas from base.json and registers them with AJV for reference resolution.
+   * This allows per-type schemas to resolve $ref to base schemas during compilation.
    */
-  async precompileSchemas() {
-    const layerMappings = {
-      motivation: "01-motivation-layer.schema.json",
-      business: "02-business-layer.schema.json",
-      security: "03-security-layer.schema.json",
-      application: "04-application-layer.schema.json",
-      technology: "05-technology-layer.schema.json",
-      api: "06-api-layer.schema.json",
-      "data-model": "07-data-model-layer.schema.json",
-      "data-store": "08-datastore-layer.schema.json",
-      ux: "09-ux-layer.schema.json",
-      navigation: "10-navigation-layer.schema.json",
-      apm: "11-apm-observability-layer.schema.json",
-      testing: "12-testing-layer.schema.json"
-    }, __dirname = path.dirname(fileURLToPath(import.meta.url)), schemasDir = path.join(__dirname, "..", "schemas", "bundled"), commonSchemas = [
-      "common/source-references.schema.json",
-      "common/predicates.schema.json",
-      "common/relationships.schema.json",
-      "common/layer-extensions.schema.json"
-    ];
-    for (const commonSchemaFile of commonSchemas)
-      try {
-        const schemaPath = path.join(schemasDir, commonSchemaFile), schemaContent = await readFile(schemaPath), schema = JSON.parse(schemaContent);
-        this.ajv.addSchema(schema);
-      } catch (error) {
-        console.warn(`Warning: Failed to load common schema ${commonSchemaFile}:`, error);
+  async ensureBaseSchemaLoaded() {
+    if (SchemaValidator.baseSchemaLoadedInSharedInstance)
+      return;
+    this.compiledSchemas.set("spec-node", validateSpecNode), this.compiledSchemas.set("spec-node-relationship", validateSpecNodeRelationship), this.compiledSchemas.set("source-references", validateSourceReference), this.compiledSchemas.set("attribute-spec", validateAttributeSpec);
+    const baseJsonPath = path.join(this.bundledDir, "base.json");
+    try {
+      const baseContent = await readFile(baseJsonPath), baseData = JSON.parse(baseContent);
+      for (const [key, schema] of Object.entries(baseData.schemas)) {
+        const s = schema, schemaId = s.$id || `urn:dr:spec:base:${key}`;
+        if (!SchemaValidator.registeredSchemaIds.has(schemaId))
+          try {
+            this.ajv.addSchema(s, schemaId), SchemaValidator.registeredSchemaIds.add(schemaId);
+          } catch (error) {
+            const errorMsg = SchemaValidator.getErrorMessage(error);
+            /schema with key or id [^ ]+ already exists/.test(errorMsg) ? SchemaValidator.registeredSchemaIds.add(schemaId) : console.warn(`[SCHEMA-LOAD-001] Failed to register base schema '${key}': ${errorMsg}`);
+          }
       }
-    for (const [layerName, schemaFileName] of Object.entries(layerMappings))
+    } catch (error) {
+      console.warn(`[SCHEMA-LOAD-001] Failed to load base.json from ${baseJsonPath}: ${SchemaValidator.getErrorMessage(error)}`);
+    }
+    SchemaValidator.baseSchemaLoadedInSharedInstance = !0;
+  }
+  /**
+   * Load the nodeSchemas map for a layer, using a static layer-level cache.
+   * Reads bundled/{layer}.json once per layer and caches the nodeSchemas object.
+   */
+  async loadLayerNodeSchemas(layer) {
+    if (SchemaValidator.layerCache.has(layer))
+      return SchemaValidator.layerCache.get(layer);
+    const layerPath = path.join(this.bundledDir, `${layer}.json`);
+    if (!existsSync(layerPath))
+      return null;
+    try {
+      const content = await readFile(layerPath), nodeSchemas = JSON.parse(content).nodeSchemas || {};
+      return SchemaValidator.layerCache.set(layer, nodeSchemas), nodeSchemas;
+    } catch (error) {
+      return console.warn(`[SCHEMA-LOAD-002] Failed to load layer file for '${layer}': ${SchemaValidator.getErrorMessage(error)}`), null;
+    }
+  }
+  /**
+   * Load and compile a spec node schema for a specific element type
+   */
+  async loadSpecNodeSchema(layer, type) {
+    const cacheKey = `${layer}.${type}`;
+    if (this.compiledSchemas.has(cacheKey))
+      return this.compiledSchemas.get(cacheKey);
+    await this.ensureBaseSchemaLoaded();
+    try {
+      const nodeSchemas = await this.loadLayerNodeSchemas(layer);
+      if (!nodeSchemas || !nodeSchemas[type])
+        return null;
+      const schema = nodeSchemas[type], schemaId = schema.$id || `urn:dr:spec:node:${layer}.${type}`;
+      if (SchemaValidator.registeredSchemaIds.has(schemaId))
+        return this.compiledSchemas.get(cacheKey) || null;
       try {
-        let schemaPath = path.join(schemasDir, schemaFileName), schemaContent;
-        try {
-          schemaContent = await readFile(schemaPath);
-        } catch {
-          schemaPath = path.join(__dirname, "schemas", "bundled", schemaFileName), schemaContent = await readFile(schemaPath);
-        }
-        const schema = JSON.parse(schemaContent), validate = this.ajv.compile(schema);
-        this.compiledSchemas.set(layerName, validate);
-      } catch (error) {
-        console.warn(`Failed to load schema for layer ${layerName}:`, error);
+        const validate = this.ajv.compile(schema);
+        return this.compiledSchemas.set(cacheKey, validate), SchemaValidator.registeredSchemaIds.add(schemaId), validate;
+      } catch (registrationError) {
+        if (SchemaValidator.getErrorMessage(registrationError).includes("already exists"))
+          return SchemaValidator.registeredSchemaIds.add(schemaId), null;
+        throw registrationError;
       }
+    } catch (error) {
+      const errorMsg = SchemaValidator.getErrorMessage(error);
+      return errorMsg.includes("can't resolve reference") || console.warn(`[SCHEMA-LOAD-002] Failed to load spec node schema for ${layer}.${type}: ${errorMsg}`), null;
+    }
   }
   /**
-   * Validate a layer against its schema
+   * Validate a layer against its spec node schemas
+   *
+   * This validates each element in the layer against its corresponding spec node schema.
    */
   async validateLayer(layer) {
-    const span = isTelemetryEnabled ? startSpan("schema.validate", {
-      "schema.layer": layer.name
-    }) : null;
-    try {
+    return startActiveSpan("schema.validate", async (span) => {
       const result = new ValidationResult();
-      await this.ensureSchemasLoaded();
-      const validate = this.compiledSchemas.get(layer.name);
-      if (!validate)
-        return isTelemetryEnabled && span && (span.setAttribute("schema.valid", !0), span.setAttribute("schema.skipped", !0)), result;
-      const layerData = layer.toJSON(), valid = validate(layerData);
-      if (!valid && validate.errors)
-        for (const error of validate.errors)
-          result.addError({
-            layer: layer.name,
-            message: `Schema validation failed: ${this.formatAjvError(error)}`,
-            location: error.instancePath || "/",
-            fixSuggestion: this.generateFixSuggestion(error)
-          });
-      return isTelemetryEnabled && span && (span.setAttribute("schema.valid", valid), span.setAttribute("schema.error_count", validate.errors?.length || 0)), result;
-    } finally {
-      endSpan(span);
+      let validatedCount = 0, skippedCount = 0;
+      for (const element of layer.elements.values()) {
+        const elementResult = await this.validateElement(element, layer.name);
+        if (elementResult.hasErrors)
+          for (const error of elementResult.errors)
+            result.addError({
+              layer: layer.name,
+              elementId: element.path || element.id,
+              message: error.message,
+              location: error.location,
+              fixSuggestion: error.fixSuggestion
+            });
+        elementResult.validated ? validatedCount++ : skippedCount++;
+      }
+      return isTelemetryEnabled && (span.setAttribute("schema.valid", result.isValid()), span.setAttribute("schema.error_count", result.errors.length), span.setAttribute("schema.validated_count", validatedCount), span.setAttribute("schema.skipped_count", skippedCount)), result;
+    }, { "schema.layer": layer.name });
+  }
+  /**
+   * Validate a single element against its spec node schema
+   */
+  async validateElement(element, layerName) {
+    const result = {
+      validated: !1,
+      hasErrors: !1,
+      errors: []
+    }, specNode = element.toSpecNode();
+    if (await this.ensureBaseSchemaLoaded(), !validateSpecNode(specNode) && validateSpecNode.errors) {
+      result.hasErrors = !0, result.validated = !0;
+      for (const error of validateSpecNode.errors)
+        result.errors.push({
+          message: `Element '${element.path || element.id}': ${this.formatAjvError(error)}`,
+          location: error.instancePath || "/",
+          fixSuggestion: this.generateFixSuggestion(error)
+        });
+      return result;
+    }
+    const validate = await this.loadSpecNodeSchema(layerName, element.type);
+    if (!validate)
+      return result.validated = !0, result;
+    if (result.validated = !0, !validate(specNode) && validate.errors) {
+      result.hasErrors = !0;
+      for (const error of validate.errors)
+        result.errors.push({
+          message: `Element '${element.path || element.id}': ${this.formatAjvError(error)}`,
+          location: error.instancePath || "/",
+          fixSuggestion: this.generateFixSuggestion(error)
+        });
     }
+    return result;
   }
   /**
    * Format AJV error message
@@ -101,7 +183,7 @@ class SchemaValidator {
     const keyword = error.keyword, dataPath = error.instancePath || "/";
     switch (keyword) {
       case "type":
-        return `At ${dataPath}: expected ${error.params?.type}, got ${typeof error.data}`;
+        return `At ${dataPath}: expected ${error.params?.type}, got ${error.data === null ? "null" : typeof error.data}`;
       case "required":
         return `At ${dataPath}: missing required property '${error.params?.missingProperty}'`;
       case "enum":
@@ -118,6 +200,8 @@ class SchemaValidator {
         return `At ${dataPath}: value must be <= ${error.params?.limit}`;
       case "additionalProperties":
         return `At ${dataPath}: unexpected property '${error.params?.additionalProperty}'`;
+      case "const":
+        return `At ${dataPath}: value must be ${JSON.stringify(error.params?.allowedValue)}`;
       default:
         return error.message || "Validation failed";
     }
@@ -137,10 +221,26 @@ class SchemaValidator {
         return `Value must match pattern: ${error.params?.pattern}`;
       case "additionalProperties":
         return `Remove unexpected property: ${error.params?.additionalProperty}`;
+      case "const":
+        return `Value must be exactly: ${JSON.stringify(error.params?.allowedValue)}`;
       default:
         return;
     }
   }
+  /**
+   * Reset static state for test isolation
+   *
+   * Clears the shared AJV instance and schema registry, allowing tests
+   * to load schemas from a clean state without conflicts.
+   *
+   * Usage (in test setup):
+   *   beforeEach(() => {
+   *     SchemaValidator.reset();
+   *   });
+   */
+  static reset() {
+    SchemaValidator.sharedAjv = null, SchemaValidator.baseSchemaLoadedInSharedInstance = !1, SchemaValidator.registeredSchemaIds.clear(), SchemaValidator.layerCache.clear();
+  }
 }
 export {
   SchemaValidator