@documentation-robotics/cli 0.1.13 → 0.3.0

package/dist/validators/composed-reference-validator.js

@@ -0,0 +1,240 @@
+import { ValidationResult } from "./types.js";
+import { Validator } from "./validator.js";
+import { parseReferencePath, ReferencePathParseError } from "../utils/reference-path-parser.js";
+import { getErrorMessage } from "../utils/errors.js";
+import { promises as fs } from "fs";
+import path from "path";
+import { parse as parseYAML } from "yaml";
+import { FarmManifest } from "../core/farm-manifest.js";
+import { resolveModelDirectory } from "../utils/project-paths.js";
+class ComposedReferenceValidator {
+  modelPathOverrides;
+  resolvedModels = /* @__PURE__ */ new Map();
+  referencedModels = /* @__PURE__ */ new Set();
+  resolutionDiagnostics = new ValidationResult();
+  constructor(modelPathOverrides = {}) {
+    this.modelPathOverrides = modelPathOverrides;
+  }
+  /**
+   * Create a ComposedReferenceValidator from a farm root
+   * Automatically builds model-path overrides from the farm's project entries
+   * @param farmRoot - Path to the farm root directory
+   * @returns ComposedReferenceValidator instance configured for the farm
+   */
+  static async fromFarm(farmRoot) {
+    const farmYamlPath = path.join(farmRoot, "farm.yaml"), manifest = await FarmManifest.load(farmYamlPath), modelPathOverrides = {};
+    for (const project of manifest.getAllProjects()) {
+      const modelFullPath = path.join(farmRoot, project.model);
+      modelPathOverrides[project.name] = modelFullPath;
+    }
+    return new ComposedReferenceValidator(modelPathOverrides);
+  }
+  async validateModel(model) {
+    const result = await new Validator().validateModel(model), declaredModels = /* @__PURE__ */ new Map();
+    for (const modelName of Object.keys(model.manifest.models || {}))
+      declaredModels.set(modelName.toLowerCase(), modelName);
+    this.referencedModels.clear(), this.resolvedModels.clear(), this.resolutionDiagnostics = new ValidationResult(), this.collectReferencedModels(model);
+    for (const declaredName of declaredModels.values())
+      await this.resolveExternalModel(declaredName);
+    result.merge(this.resolutionDiagnostics);
+    for (const [lowerModelName, declaredName] of declaredModels) {
+      const isReferenced = this.referencedModels.has(lowerModelName);
+      if (!this.resolvedModels.has(declaredName))
+        isReferenced ? result.addError({
+          layer: "manifest",
+          message: `External model '${declaredName}' is referenced in qualified paths but could not be resolved from the configured paths`,
+          category: "reference",
+          fixSuggestion: `Ensure the model exists on disk, or use '--model-path ${declaredName}=/path/to/project-root' to specify its location`
+        }) : result.addWarning({
+          layer: "manifest",
+          message: `External model '${declaredName}' is declared but not referenced in any qualified paths and could not be found on disk`,
+          category: "reference",
+          fixSuggestion: `Remove the declaration if not needed, or use '--model-path ${declaredName}=/path/to/project-root' to specify its location`
+        });
+      else if (isReferenced) {
+        const validationResult = this.validateQualifiedReferencesAgainstModel(model, declaredName);
+        result.merge(validationResult, `[Composed/${declaredName}]`);
+      }
+    }
+    return result;
+  }
+  collectReferencedModels(model) {
+    for (const [, layer] of model.layers)
+      for (const element of layer.listElements())
+        for (const ref of element.references || [])
+          if (ref.target.startsWith("@"))
+            try {
+              const parsed = parseReferencePath(ref.target);
+              parsed.modelName && this.referencedModels.add(parsed.modelName.toLowerCase());
+            } catch (error) {
+              if (error instanceof ReferencePathParseError)
+                continue;
+              throw error;
+            }
+  }
+  async resolveExternalModel(modelName) {
+    let modelPath = this.modelPathOverrides[modelName];
+    if (!modelPath) {
+      const lowerModelName = modelName.toLowerCase();
+      for (const [key, overridePath] of Object.entries(this.modelPathOverrides))
+        if (key.toLowerCase() === lowerModelName) {
+          modelPath = overridePath;
+          break;
+        }
+    }
+    if (modelPath)
+      try {
+        let rootStats;
+        try {
+          rootStats = await fs.stat(modelPath);
+        } catch (err) {
+          if (err?.code !== "ENOENT")
+            throw err;
+        }
+        if (rootStats && !rootStats.isDirectory()) {
+          this.resolutionDiagnostics.addWarning({
+            layer: "manifest",
+            message: `External model '${modelName}' path is not a directory: ${modelPath}`,
+            category: "reference",
+            fixSuggestion: `Ensure '--model-path ${modelName}=${modelPath}' points to a project root containing documentation-robotics/model/`
+          });
+          return;
+        }
+        const resolved = await resolveModelDirectory(modelPath);
+        if (!resolved) {
+          this.addResolutionDiagnostic(modelName, new Error("Model directory not found"), modelPath, !0);
+          return;
+        }
+        const modelDir = resolved.modelDir;
+        if (!resolved.isDirectory) {
+          this.resolutionDiagnostics.addWarning({
+            layer: "manifest",
+            message: `External model '${modelName}' path is not a directory: ${modelDir}`,
+            category: "reference",
+            fixSuggestion: `Ensure '--model-path ${modelName}=${modelPath}' points to a project root or model directory`
+          });
+          return;
+        }
+        const elementIds = /* @__PURE__ */ new Set();
+        let entries = [];
+        try {
+          entries = await fs.readdir(modelDir, { withFileTypes: !0 });
+        } catch (error) {
+          this.addResolutionDiagnostic(modelName, error, modelPath);
+          return;
+        }
+        for (const entry of entries)
+          if (entry.isDirectory() && /^\d+_/.test(entry.name)) {
+            const layerPath = path.join(modelDir, entry.name);
+            await this.collectElementsFromLayer(layerPath, elementIds);
+          }
+        this.resolvedModels.set(modelName, {
+          modelName,
+          elementIds
+        });
+      } catch (error) {
+        this.addResolutionDiagnostic(modelName, error, modelPath);
+      }
+  }
+  async collectElementsFromLayer(layerPath, elementIds) {
+    try {
+      const entries = await fs.readdir(layerPath, { withFileTypes: !0 });
+      for (const entry of entries)
+        if (entry.isFile() && (entry.name.endsWith(".yaml") || entry.name.endsWith(".yml")))
+          try {
+            const content = await fs.readFile(path.join(layerPath, entry.name), "utf-8");
+            this.extractElementPathsFromYAML(content, elementIds, layerPath, entry.name);
+          } catch (error) {
+            const filePath = path.join(layerPath, entry.name);
+            this.resolutionDiagnostics.addWarning({
+              layer: "manifest",
+              message: `Failed to read YAML file at ${filePath}: ${getErrorMessage(error)}`,
+              category: "reference"
+            });
+            continue;
+          }
+    } catch (error) {
+      this.resolutionDiagnostics.addWarning({
+        layer: "manifest",
+        message: `Failed to read layer directory at ${layerPath}: ${getErrorMessage(error)}`,
+        category: "reference"
+      });
+    }
+  }
+  extractElementPathsFromYAML(content, elementIds, layerPath, fileName) {
+    try {
+      const parsed = parseYAML(content);
+      if (!parsed) {
+        this.resolutionDiagnostics.addWarning({
+          layer: "manifest",
+          message: `YAML file at ${path.join(layerPath, fileName)} parsed to empty content`,
+          category: "reference"
+        });
+        return;
+      }
+      const items = [];
+      if (parsed && typeof parsed == "object" && "elements" in parsed) {
+        const elements = parsed.elements;
+        Array.isArray(elements) && items.push(...elements);
+      } else if (Array.isArray(parsed))
+        items.push(...parsed);
+      else if (parsed && typeof parsed == "object" && !Array.isArray(parsed)) {
+        const values = Object.values(parsed);
+        values.length > 0 && values[0] && typeof values[0] == "object" && ("path" in values[0] || "id" in values[0]) ? items.push(...values) : items.push(parsed);
+      }
+      for (const item of items)
+        if (item && typeof item == "object") {
+          const elementPath = item.path || item.id;
+          elementPath && typeof elementPath == "string" && elementIds.add(elementPath.trim());
+        }
+    } catch (error) {
+      this.resolutionDiagnostics.addWarning({
+        layer: "manifest",
+        message: `Failed to parse YAML file at ${path.join(layerPath, fileName)}: ${getErrorMessage(error)}`,
+        category: "reference"
+      });
+    }
+  }
+  validateQualifiedReferencesAgainstModel(model, modelName) {
+    const result = new ValidationResult(), resolvedModel = this.resolvedModels.get(modelName);
+    if (!resolvedModel)
+      return result;
+    for (const [sourceLayerName, layer] of model.layers)
+      for (const element of layer.listElements()) {
+        const elementId = element.path || element.id;
+        for (const ref of element.references || [])
+          if (ref.target.startsWith("@"))
+            try {
+              const parsed = parseReferencePath(ref.target);
+              if (parsed.modelName?.toLowerCase() !== modelName.toLowerCase())
+                continue;
+              resolvedModel.elementIds.has(parsed.segment) || result.addError({
+                layer: sourceLayerName,
+                elementId,
+                message: `Broken qualified reference: target '${parsed.segment}' does not exist in external model '${modelName}'`,
+                category: "reference",
+                fixSuggestion: `Create element '${parsed.segment}' in model '${modelName}' or remove this reference`
+              });
+            } catch (error) {
+              if (error instanceof ReferencePathParseError)
+                continue;
+              throw error;
+            }
+      }
+    return result;
+  }
+  addResolutionDiagnostic(modelName, error, modelPath, isPathError = !1) {
+    const errorMsg = getErrorMessage(error), code = error?.code;
+    let message = "", fixSuggestion = "";
+    code === "EACCES" ? (message = `Permission denied accessing external model '${modelName}' at ${modelPath}. Check file permissions.`, fixSuggestion = `Ensure the model path is readable, or use '--model-path ${modelName}=/path/to/alternative-location' to specify another location`) : code === "EIO" ? (message = `I/O error reading external model '${modelName}' at ${modelPath}. There may be a filesystem or device issue.`, fixSuggestion = `Check the filesystem for errors, or provide an alternative model path via '--model-path ${modelName}=/path/to/alternative-location'`) : code === "ENOENT" || isPathError ? (message = `Could not find external model '${modelName}' \u2014 expected at ${modelPath}/documentation-robotics/model or ${modelPath}/model`, fixSuggestion = `Ensure the model exists at the specified path, or use '--model-path ${modelName}=/path/to/project-root' to specify its location`) : (message = `Failed to resolve external model '${modelName}' at ${modelPath}: ${errorMsg}`, fixSuggestion = `Check the path and filesystem permissions, or use '--model-path ${modelName}=/path/to/project-root' to specify a different location`), this.resolutionDiagnostics.addWarning({
+      layer: "manifest",
+      message,
+      category: "reference",
+      fixSuggestion
+    });
+  }
+}
+export {
+  ComposedReferenceValidator
+};
+//# sourceMappingURL=composed-reference-validator.js.map

package/dist/validators/composed-reference-validator.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/validators/composed-reference-validator.ts"],
+  "sourcesContent": ["import { ValidationResult } from \"./types.js\";\nimport type { Model } from \"../core/model.js\";\nimport { Validator } from \"./validator.js\";\nimport { parseReferencePath, ReferencePathParseError } from \"../utils/reference-path-parser.js\";\nimport { getErrorMessage } from \"../utils/errors.js\";\nimport { promises as fs, Dirent, Stats } from \"fs\";\nimport path from \"path\";\nimport { parse as parseYAML } from \"yaml\";\nimport { FarmManifest } from \"../core/farm-manifest.js\";\nimport { resolveModelDirectory } from \"../utils/project-paths.js\";\n\ninterface ResolvedExternalModel {\n  modelName: string;\n  elementIds: Set<string>;\n}\n\nexport class ComposedReferenceValidator {\n  private modelPathOverrides: Record<string, string>;\n  private resolvedModels: Map<string, ResolvedExternalModel> = new Map();\n  private referencedModels: Set<string> = new Set();\n  private resolutionDiagnostics: ValidationResult = new ValidationResult();\n\n  constructor(modelPathOverrides: Record<string, string> = {}) {\n    this.modelPathOverrides = modelPathOverrides;\n  }\n\n  /**\n   * Create a ComposedReferenceValidator from a farm root\n   * Automatically builds model-path overrides from the farm's project entries\n   * @param farmRoot - Path to the farm root directory\n   * @returns ComposedReferenceValidator instance configured for the farm\n   */\n  static async fromFarm(farmRoot: string): Promise<ComposedReferenceValidator> {\n    const farmYamlPath = path.join(farmRoot, \"farm.yaml\");\n    const manifest = await FarmManifest.load(farmYamlPath);\n\n    const modelPathOverrides: Record<string, string> = {};\n\n    // Build model-path overrides for each project in the farm\n    for (const project of manifest.getAllProjects()) {\n      // For detached model layouts, point directly to the model folder.\n      // The validator will look for manifest.yaml within this folder.\n      // If the model is co-located (inside codebase), it will also find it\n      // via the documentation-robotics/model/ path search.\n      const modelFullPath = path.join(farmRoot, project.model);\n      modelPathOverrides[project.name] = modelFullPath;\n    }\n\n    return new ComposedReferenceValidator(modelPathOverrides);\n  }\n\n  async validateModel(model: Model): Promise<ValidationResult> {\n    const fullValidator = new Validator();\n    const result = await fullValidator.validateModel(model);\n\n    const declaredModels = new Map<string, string>();\n    // Map from lowercase model name to declared model name (preserving original casing)\n    for (const modelName of Object.keys(model.manifest.models || {})) {\n      declaredModels.set(modelName.toLowerCase(), modelName);\n    }\n\n    // Clear all state to ensure fresh validation on reuse\n    this.referencedModels.clear();\n    this.resolvedModels.clear();\n    this.resolutionDiagnostics = new ValidationResult();\n    this.collectReferencedModels(model);\n\n    for (const declaredName of declaredModels.values()) {\n      await this.resolveExternalModel(declaredName);\n    }\n\n    // Merge any diagnostics from resolution phase\n    result.merge(this.resolutionDiagnostics);\n\n    for (const [lowerModelName, declaredName] of declaredModels) {\n      // Check if model is referenced using case-insensitive comparison\n      const isReferenced = this.referencedModels.has(lowerModelName);\n      // Check if model is resolved using the declared name\n      const isResolved = this.resolvedModels.has(declaredName);\n\n      if (!isResolved) {\n        if (isReferenced) {\n          // Declared, referenced, but unresolvable \u2192 error with guidance\n          result.addError({\n            layer: \"manifest\",\n            message: `External model '${declaredName}' is referenced in qualified paths but could not be resolved from the configured paths`,\n            category: \"reference\",\n            fixSuggestion: `Ensure the model exists on disk, or use '--model-path ${declaredName}=/path/to/project-root' to specify its location`,\n          });\n        } else {\n          // Declared but unreferenced and unresolvable \u2192 warning only\n          result.addWarning({\n            layer: \"manifest\",\n            message: `External model '${declaredName}' is declared but not referenced in any qualified paths and could not be found on disk`,\n            category: \"reference\",\n            fixSuggestion: `Remove the declaration if not needed, or use '--model-path ${declaredName}=/path/to/project-root' to specify its location`,\n          });\n        }\n      } else if (isReferenced) {\n        // Declared, referenced, and resolvable \u2192 validate qualified references\n        const validationResult = this.validateQualifiedReferencesAgainstModel(model, declaredName);\n        result.merge(validationResult, `[Composed/${declaredName}]`);\n      }\n    }\n\n    return result;\n  }\n\n  private collectReferencedModels(model: Model): void {\n    for (const [, layer] of model.layers) {\n      for (const element of layer.listElements()) {\n        for (const ref of element.references || []) {\n          if (ref.target.startsWith(\"@\")) {\n            try {\n              const parsed = parseReferencePath(ref.target);\n              if (parsed.modelName) {\n                // Store lowercase for case-insensitive comparison with declared models\n                this.referencedModels.add(parsed.modelName.toLowerCase());\n              }\n            } catch (error) {\n              if (error instanceof ReferencePathParseError) {\n                // Parse errors are already handled by base validator\n                continue;\n              } else {\n                throw error;\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n\n  private async resolveExternalModel(modelName: string): Promise<void> {\n    // Try exact match first, then case-insensitive match\n    let modelPath = this.modelPathOverrides[modelName];\n    if (!modelPath) {\n      // Case-insensitive lookup in modelPathOverrides\n      const lowerModelName = modelName.toLowerCase();\n      for (const [key, overridePath] of Object.entries(this.modelPathOverrides)) {\n        if (key.toLowerCase() === lowerModelName) {\n          modelPath = overridePath;\n          break;\n        }\n      }\n    }\n\n    if (!modelPath) {\n      return;\n    }\n\n    try {\n      // Verify modelPath itself is a directory\n      let rootStats: Stats | undefined;\n      try {\n        rootStats = await fs.stat(modelPath);\n      } catch (err) {\n        const errorCode = (err as NodeJS.ErrnoException)?.code;\n        if (errorCode !== \"ENOENT\") {\n          throw err;\n        }\n      }\n\n      if (rootStats && !rootStats.isDirectory()) {\n        this.resolutionDiagnostics.addWarning({\n          layer: \"manifest\",\n          message: `External model '${modelName}' path is not a directory: ${modelPath}`,\n          category: \"reference\",\n          fixSuggestion: `Ensure '--model-path ${modelName}=${modelPath}' points to a project root containing documentation-robotics/model/`,\n        });\n        return;\n      }\n\n      // Standard ({modelPath}/documentation-robotics/model/), legacy ({modelPath}/model/)\n      // and detached (modelPath itself holds the layer directories) layouts, in that order\n      const resolved = await resolveModelDirectory(modelPath);\n\n      if (!resolved) {\n        this.addResolutionDiagnostic(\n          modelName,\n          new Error(\"Model directory not found\"),\n          modelPath,\n          true\n        );\n        return;\n      }\n\n      const modelDir = resolved.modelDir;\n\n      if (!resolved.isDirectory) {\n        this.resolutionDiagnostics.addWarning({\n          layer: \"manifest\",\n          message: `External model '${modelName}' path is not a directory: ${modelDir}`,\n          category: \"reference\",\n          fixSuggestion: `Ensure '--model-path ${modelName}=${modelPath}' points to a project root or model directory`,\n        });\n        return;\n      }\n\n      const elementIds = new Set<string>();\n\n      // Try to load all layer directories\n      let entries: Dirent[] = [];\n      try {\n        entries = await fs.readdir(modelDir, { withFileTypes: true });\n      } catch (error) {\n        this.addResolutionDiagnostic(modelName, error, modelPath);\n        return;\n      }\n\n      // Load elements from each layer directory\n      for (const entry of entries) {\n        if (entry.isDirectory() && /^\\d+_/.test(entry.name)) {\n          // This looks like a layer directory (e.g., \"01_motivation\", \"08_data-model\")\n          const layerPath = path.join(modelDir, entry.name);\n          await this.collectElementsFromLayer(layerPath, elementIds);\n        }\n      }\n\n      // Successfully resolved the model (track it even if empty)\n      this.resolvedModels.set(modelName, {\n        modelName,\n        elementIds,\n      });\n    } catch (error) {\n      // Failed to resolve model\n      this.addResolutionDiagnostic(modelName, error, modelPath);\n    }\n  }\n\n  private async collectElementsFromLayer(layerPath: string, elementIds: Set<string>): Promise<void> {\n    try {\n      const entries = await fs.readdir(layerPath, { withFileTypes: true });\n\n      for (const entry of entries) {\n        if (entry.isFile() && (entry.name.endsWith(\".yaml\") || entry.name.endsWith(\".yml\"))) {\n          // Read the YAML file and extract element paths/IDs\n          try {\n            const content = await fs.readFile(path.join(layerPath, entry.name), \"utf-8\");\n            this.extractElementPathsFromYAML(content, elementIds, layerPath, entry.name);\n          } catch (error) {\n            const filePath = path.join(layerPath, entry.name);\n            this.resolutionDiagnostics.addWarning({\n              layer: \"manifest\",\n              message: `Failed to read YAML file at ${filePath}: ${getErrorMessage(error)}`,\n              category: \"reference\",\n            });\n            continue;\n          }\n        }\n      }\n    } catch (error) {\n      this.resolutionDiagnostics.addWarning({\n        layer: \"manifest\",\n        message: `Failed to read layer directory at ${layerPath}: ${getErrorMessage(error)}`,\n        category: \"reference\",\n      });\n    }\n  }\n\n  private extractElementPathsFromYAML(\n    content: string,\n    elementIds: Set<string>,\n    layerPath: string,\n    fileName: string\n  ): void {\n    try {\n      const parsed = parseYAML(content);\n\n      if (!parsed) {\n        this.resolutionDiagnostics.addWarning({\n          layer: \"manifest\",\n          message: `YAML file at ${path.join(layerPath, fileName)} parsed to empty content`,\n          category: \"reference\",\n        });\n        return;\n      }\n\n      // Collect items to process from various YAML formats\n      const items: unknown[] = [];\n\n      // Format 1: elements: [{ path: \"...\" }, ...]\n      if (parsed && typeof parsed === \"object\" && \"elements\" in parsed) {\n        const elements = parsed.elements;\n        if (Array.isArray(elements)) {\n          items.push(...elements);\n        }\n      }\n      // Format 2: Direct array [{ path: \"...\" }, ...]\n      else if (Array.isArray(parsed)) {\n        items.push(...parsed);\n      }\n      // Format 3: Object-of-objects { \"key\": { path: \"...\" }, ... }\n      else if (parsed && typeof parsed === \"object\" && !Array.isArray(parsed)) {\n        // Check if this looks like an object-of-objects (values have path/id fields)\n        const values = Object.values(parsed);\n        if (values.length > 0 && values[0] && typeof values[0] === \"object\" && (\"path\" in values[0] || \"id\" in values[0])) {\n          items.push(...values);\n        } else {\n          // Object without path/id fields, push as-is for type safety\n          items.push(parsed);\n        }\n      }\n\n      // Extract paths from collected items\n      for (const item of items) {\n        if (item && typeof item === \"object\") {\n          const elementPath = (item as Record<string, unknown>).path || (item as Record<string, unknown>).id;\n          if (elementPath && typeof elementPath === \"string\") {\n            elementIds.add(elementPath.trim());\n          }\n        }\n      }\n    } catch (error) {\n      this.resolutionDiagnostics.addWarning({\n        layer: \"manifest\",\n        message: `Failed to parse YAML file at ${path.join(layerPath, fileName)}: ${getErrorMessage(error)}`,\n        category: \"reference\",\n      });\n    }\n  }\n\n  private validateQualifiedReferencesAgainstModel(\n    model: Model,\n    modelName: string\n  ): ValidationResult {\n    const result = new ValidationResult();\n    const resolvedModel = this.resolvedModels.get(modelName);\n\n    if (!resolvedModel) {\n      return result;\n    }\n\n    for (const [sourceLayerName, layer] of model.layers) {\n      for (const element of layer.listElements()) {\n        const elementId = element.path || element.id;\n\n        for (const ref of element.references || []) {\n          if (!ref.target.startsWith(\"@\")) {\n            continue;\n          }\n\n          try {\n            const parsed = parseReferencePath(ref.target);\n            // Compare model names case-insensitively\n            if (parsed.modelName?.toLowerCase() !== modelName.toLowerCase()) {\n              continue;\n            }\n\n            // Check if target element exists in the resolved external model\n            if (!resolvedModel.elementIds.has(parsed.segment)) {\n              result.addError({\n                layer: sourceLayerName,\n                elementId,\n                message: `Broken qualified reference: target '${parsed.segment}' does not exist in external model '${modelName}'`,\n                category: \"reference\",\n                fixSuggestion: `Create element '${parsed.segment}' in model '${modelName}' or remove this reference`,\n              });\n            }\n          } catch (error) {\n            if (error instanceof ReferencePathParseError) {\n              // Parse errors are already handled by base validator\n              continue;\n            } else {\n              throw error;\n            }\n          }\n        }\n      }\n    }\n\n    return result;\n  }\n\n  private addResolutionDiagnostic(\n    modelName: string,\n    error: unknown,\n    modelPath: string,\n    isPathError: boolean = false\n  ): void {\n    const errorMsg = getErrorMessage(error);\n    const code = (error as NodeJS.ErrnoException)?.code;\n\n    let message = \"\";\n    let fixSuggestion = \"\";\n\n    if (code === \"EACCES\") {\n      message =\n        `Permission denied accessing external model '${modelName}' at ${modelPath}. ` +\n        `Check file permissions.`;\n      fixSuggestion = `Ensure the model path is readable, or use '--model-path ${modelName}=/path/to/alternative-location' to specify another location`;\n    } else if (code === \"EIO\") {\n      message =\n        `I/O error reading external model '${modelName}' at ${modelPath}. ` +\n        `There may be a filesystem or device issue.`;\n      fixSuggestion = `Check the filesystem for errors, or provide an alternative model path via '--model-path ${modelName}=/path/to/alternative-location'`;\n    } else if (code === \"ENOENT\" || isPathError) {\n      message =\n        `Could not find external model '${modelName}' \u2014 expected at ${modelPath}/documentation-robotics/model or ${modelPath}/model`;\n      fixSuggestion = `Ensure the model exists at the specified path, or use '--model-path ${modelName}=/path/to/project-root' to specify its location`;\n    } else {\n      message =\n        `Failed to resolve external model '${modelName}' at ${modelPath}: ${errorMsg}`;\n      fixSuggestion = `Check the path and filesystem permissions, or use '--model-path ${modelName}=/path/to/project-root' to specify a different location`;\n    }\n\n    this.resolutionDiagnostics.addWarning({\n      layer: \"manifest\",\n      message,\n      category: \"reference\",\n      fixSuggestion,\n    });\n  }\n}\n"],
+  "mappings": "AAAA,SAAS,wBAAwB;AAEjC,SAAS,iBAAiB;AAC1B,SAAS,oBAAoB,+BAA+B;AAC5D,SAAS,uBAAuB;AAChC,SAAS,YAAY,UAAyB;AAC9C,OAAO,UAAU;AACjB,SAAS,SAAS,iBAAiB;AACnC,SAAS,oBAAoB;AAC7B,SAAS,6BAA6B;AAOhC,MAAO,2BAA0B;EAC7B;EACA,iBAAqD,oBAAI,IAAG;EAC5D,mBAAgC,oBAAI,IAAG;EACvC,wBAA0C,IAAI,iBAAgB;EAEtE,YAAY,qBAA6C,CAAA,GAAE;AACzD,SAAK,qBAAqB;EAC5B;;;;;;;EAQA,aAAa,SAAS,UAAgB;AACpC,UAAM,eAAe,KAAK,KAAK,UAAU,WAAW,GAC9C,WAAW,MAAM,aAAa,KAAK,YAAY,GAE/C,qBAA6C,CAAA;AAGnD,eAAW,WAAW,SAAS,eAAc,GAAI;AAK/C,YAAM,gBAAgB,KAAK,KAAK,UAAU,QAAQ,KAAK;AACvD,yBAAmB,QAAQ,IAAI,IAAI;IACrC;AAEA,WAAO,IAAI,2BAA2B,kBAAkB;EAC1D;EAEA,MAAM,cAAc,OAAY;AAE9B,UAAM,SAAS,MADO,IAAI,UAAS,EACA,cAAc,KAAK,GAEhD,iBAAiB,oBAAI,IAAG;AAE9B,eAAW,aAAa,OAAO,KAAK,MAAM,SAAS,UAAU,CAAA,CAAE;AAC7D,qBAAe,IAAI,UAAU,YAAW,GAAI,SAAS;AAIvD,SAAK,iBAAiB,MAAK,GAC3B,KAAK,eAAe,MAAK,GACzB,KAAK,wBAAwB,IAAI,iBAAgB,GACjD,KAAK,wBAAwB,KAAK;AAElC,eAAW,gBAAgB,eAAe,OAAM;AAC9C,YAAM,KAAK,qBAAqB,YAAY;AAI9C,WAAO,MAAM,KAAK,qBAAqB;AAEvC,eAAW,CAAC,gBAAgB,YAAY,KAAK,gBAAgB;AAE3D,YAAM,eAAe,KAAK,iBAAiB,IAAI,cAAc;AAI7D,UAAI,CAFe,KAAK,eAAe,IAAI,YAAY;AAGrD,QAAI,eAEF,OAAO,SAAS;UACd,OAAO;UACP,SAAS,mBAAmB,YAAY;UACxC,UAAU;UACV,eAAe,yDAAyD,YAAY;SACrF,IAGD,OAAO,WAAW;UAChB,OAAO;UACP,SAAS,mBAAmB,YAAY;UACxC,UAAU;UACV,eAAe,8DAA8D,YAAY;SAC1F;eAEM,cAAc;AAEvB,cAAM,mBAAmB,KAAK,wCAAwC,OAAO,YAAY;AACzF,eAAO,MAAM,kBAAkB,aAAa,YAAY,GAAG;MAC7D;IACF;AAEA,WAAO;EACT;EAEQ,wBAAwB,OAAY;AAC1C,eAAW,CAAC,EAAE,KAAK,KAAK,MAAM;AAC5B,iBAAW,WAAW,MAAM,aAAY;AACtC,mBAAW,OAAO,QAAQ,cAAc,CAAA;AACtC,cAAI,IAAI,OAAO,WAAW,GAAG;AAC3B,gBAAI;AACF,oBAAM,SAAS,mBAAmB,IAAI,MAAM;AAC5C,cAAI,OAAO,aAET,KAAK,iBAAiB,IAAI,OAAO,UAAU,YAAW,CAAE;YAE5D,SAAS,OAAO;AACd,kBAAI,iBAAiB;AAEnB;AAEA,oBAAM;YAEV;EAKV;EAEQ,MAAM,qBAAqB,WAAiB;AAElD,QAAI,YAAY,KAAK,mBAAmB,SAAS;AACjD,QAAI,CAAC,WAAW;AAEd,YAAM,iBAAiB,UAAU,YAAW;AAC5C,iBAAW,CAAC,KAAK,YAAY,KAAK,OAAO,QAAQ,KAAK,kBAAkB;AACtE,YAAI,IAAI,YAAW,MAAO,gBAAgB;AACxC,sBAAY;AACZ;QACF;IAEJ;AAEA,QAAK;AAIL,UAAI;AAEF,YAAI;AACJ,YAAI;AACF,sBAAY,MAAM,GAAG,KAAK,SAAS;QACrC,SAAS,KAAK;AAEZ,cADmB,KAA+B,SAChC;AAChB,kBAAM;QAEV;AAEA,YAAI,aAAa,CAAC,UAAU,YAAW,GAAI;AACzC,eAAK,sBAAsB,WAAW;YACpC,OAAO;YACP,SAAS,mBAAmB,SAAS,8BAA8B,SAAS;YAC5E,UAAU;YACV,eAAe,wBAAwB,SAAS,IAAI,SAAS;WAC9D;AACD;QACF;AAIA,cAAM,WAAW,MAAM,sBAAsB,SAAS;AAEtD,YAAI,CAAC,UAAU;AACb,eAAK,wBACH,WACA,IAAI,MAAM,2BAA2B,GACrC,WACA,EAAI;AAEN;QACF;AAEA,cAAM,WAAW,SAAS;AAE1B,YAAI,CAAC,SAAS,aAAa;AACzB,eAAK,sBAAsB,WAAW;YACpC,OAAO;YACP,SAAS,mBAAmB,SAAS,8BAA8B,QAAQ;YAC3E,UAAU;YACV,eAAe,wBAAwB,SAAS,IAAI,SAAS;WAC9D;AACD;QACF;AAEA,cAAM,aAAa,oBAAI,IAAG;AAG1B,YAAI,UAAoB,CAAA;AACxB,YAAI;AACF,oBAAU,MAAM,GAAG,QAAQ,UAAU,EAAE,eAAe,GAAI,CAAE;QAC9D,SAAS,OAAO;AACd,eAAK,wBAAwB,WAAW,OAAO,SAAS;AACxD;QACF;AAGA,mBAAW,SAAS;AAClB,cAAI,MAAM,YAAW,KAAM,QAAQ,KAAK,MAAM,IAAI,GAAG;AAEnD,kBAAM,YAAY,KAAK,KAAK,UAAU,MAAM,IAAI;AAChD,kBAAM,KAAK,yBAAyB,WAAW,UAAU;UAC3D;AAIF,aAAK,eAAe,IAAI,WAAW;UACjC;UACA;SACD;MACH,SAAS,OAAO;AAEd,aAAK,wBAAwB,WAAW,OAAO,SAAS;MAC1D;EACF;EAEQ,MAAM,yBAAyB,WAAmB,YAAuB;AAC/E,QAAI;AACF,YAAM,UAAU,MAAM,GAAG,QAAQ,WAAW,EAAE,eAAe,GAAI,CAAE;AAEnE,iBAAW,SAAS;AAClB,YAAI,MAAM,OAAM,MAAO,MAAM,KAAK,SAAS,OAAO,KAAK,MAAM,KAAK,SAAS,MAAM;AAE/E,cAAI;AACF,kBAAM,UAAU,MAAM,GAAG,SAAS,KAAK,KAAK,WAAW,MAAM,IAAI,GAAG,OAAO;AAC3E,iBAAK,4BAA4B,SAAS,YAAY,WAAW,MAAM,IAAI;UAC7E,SAAS,OAAO;AACd,kBAAM,WAAW,KAAK,KAAK,WAAW,MAAM,IAAI;AAChD,iBAAK,sBAAsB,WAAW;cACpC,OAAO;cACP,SAAS,+BAA+B,QAAQ,KAAK,gBAAgB,KAAK,CAAC;cAC3E,UAAU;aACX;AACD;UACF;IAGN,SAAS,OAAO;AACd,WAAK,sBAAsB,WAAW;QACpC,OAAO;QACP,SAAS,qCAAqC,SAAS,KAAK,gBAAgB,KAAK,CAAC;QAClF,UAAU;OACX;IACH;EACF;EAEQ,4BACN,SACA,YACA,WACA,UAAgB;AAEhB,QAAI;AACF,YAAM,SAAS,UAAU,OAAO;AAEhC,UAAI,CAAC,QAAQ;AACX,aAAK,sBAAsB,WAAW;UACpC,OAAO;UACP,SAAS,gBAAgB,KAAK,KAAK,WAAW,QAAQ,CAAC;UACvD,UAAU;SACX;AACD;MACF;AAGA,YAAM,QAAmB,CAAA;AAGzB,UAAI,UAAU,OAAO,UAAW,YAAY,cAAc,QAAQ;AAChE,cAAM,WAAW,OAAO;AACxB,QAAI,MAAM,QAAQ,QAAQ,KACxB,MAAM,KAAK,GAAG,QAAQ;MAE1B,WAES,MAAM,QAAQ,MAAM;AAC3B,cAAM,KAAK,GAAG,MAAM;eAGb,UAAU,OAAO,UAAW,YAAY,CAAC,MAAM,QAAQ,MAAM,GAAG;AAEvE,cAAM,SAAS,OAAO,OAAO,MAAM;AACnC,QAAI,OAAO,SAAS,KAAK,OAAO,CAAC,KAAK,OAAO,OAAO,CAAC,KAAM,aAAa,UAAU,OAAO,CAAC,KAAK,QAAQ,OAAO,CAAC,KAC7G,MAAM,KAAK,GAAG,MAAM,IAGpB,MAAM,KAAK,MAAM;MAErB;AAGA,iBAAW,QAAQ;AACjB,YAAI,QAAQ,OAAO,QAAS,UAAU;AACpC,gBAAM,cAAe,KAAiC,QAAS,KAAiC;AAChG,UAAI,eAAe,OAAO,eAAgB,YACxC,WAAW,IAAI,YAAY,KAAI,CAAE;QAErC;IAEJ,SAAS,OAAO;AACd,WAAK,sBAAsB,WAAW;QACpC,OAAO;QACP,SAAS,gCAAgC,KAAK,KAAK,WAAW,QAAQ,CAAC,KAAK,gBAAgB,KAAK,CAAC;QAClG,UAAU;OACX;IACH;EACF;EAEQ,wCACN,OACA,WAAiB;AAEjB,UAAM,SAAS,IAAI,iBAAgB,GAC7B,gBAAgB,KAAK,eAAe,IAAI,SAAS;AAEvD,QAAI,CAAC;AACH,aAAO;AAGT,eAAW,CAAC,iBAAiB,KAAK,KAAK,MAAM;AAC3C,iBAAW,WAAW,MAAM,aAAY,GAAI;AAC1C,cAAM,YAAY,QAAQ,QAAQ,QAAQ;AAE1C,mBAAW,OAAO,QAAQ,cAAc,CAAA;AACtC,cAAK,IAAI,OAAO,WAAW,GAAG;AAI9B,gBAAI;AACF,oBAAM,SAAS,mBAAmB,IAAI,MAAM;AAE5C,kBAAI,OAAO,WAAW,YAAW,MAAO,UAAU,YAAW;AAC3D;AAIF,cAAK,cAAc,WAAW,IAAI,OAAO,OAAO,KAC9C,OAAO,SAAS;gBACd,OAAO;gBACP;gBACA,SAAS,uCAAuC,OAAO,OAAO,uCAAuC,SAAS;gBAC9G,UAAU;gBACV,eAAe,mBAAmB,OAAO,OAAO,eAAe,SAAS;eACzE;YAEL,SAAS,OAAO;AACd,kBAAI,iBAAiB;AAEnB;AAEA,oBAAM;YAEV;MAEJ;AAGF,WAAO;EACT;EAEQ,wBACN,WACA,OACA,WACA,cAAuB,IAAK;AAE5B,UAAM,WAAW,gBAAgB,KAAK,GAChC,OAAQ,OAAiC;AAE/C,QAAI,UAAU,IACV,gBAAgB;AAEpB,IAAI,SAAS,YACX,UACE,+CAA+C,SAAS,QAAQ,SAAS,6BAE3E,gBAAgB,2DAA2D,SAAS,iEAC3E,SAAS,SAClB,UACE,qCAAqC,SAAS,QAAQ,SAAS,gDAEjE,gBAAgB,2FAA2F,SAAS,qCAC3G,SAAS,YAAY,eAC9B,UACE,kCAAkC,SAAS,wBAAmB,SAAS,oCAAoC,SAAS,UACtH,gBAAgB,uEAAuE,SAAS,sDAEhG,UACE,qCAAqC,SAAS,QAAQ,SAAS,KAAK,QAAQ,IAC9E,gBAAgB,mEAAmE,SAAS,4DAG9F,KAAK,sBAAsB,WAAW;MACpC,OAAO;MACP;MACA,UAAU;MACV;KACD;EACH;;",
+  "names": []
+}

package/dist/validators/reference-validator.js

@@ -1,5 +1,6 @@
 import { ValidationResult } from "./types.js";
 import { getLayerByNumber, LAYER_HIERARCHY, getAllLayerIds } from "../generated/layer-registry.js";
+import { parseReferencePath, ReferencePathParseError } from "../utils/reference-path-parser.js";
 class ReferenceValidator {
   // Known layer names from generated registry (including hyphenated ones)
   KNOWN_LAYERS = getAllLayerIds();
@@ -20,7 +21,7 @@ class ReferenceValidator {
     const result = new ValidationResult(), allElementIds = this.collectAllElementIds(model);
     for (const [layerName, layer] of model.layers)
       for (const element of layer.listElements())
-        this.validateReferences(element.path || element.id, element.references || [], layerName, allElementIds, result);
+        this.validateReferences(element.path || element.id, element.references || [], layerName, allElementIds, model, result);
     return result;
   }
   /**
@@ -36,24 +37,60 @@ class ReferenceValidator {
   /**
    * Validate references for an element
    */
-  validateReferences(elementId, references, sourceLayerName, validIds, result) {
+  validateReferences(elementId, references, sourceLayerName, validIds, model, result) {
     for (const ref of references) {
-      if (!validIds.has(ref.target)) {
+      let parsedModel, targetSegment = ref.target;
+      if (ref.target.startsWith("@")) {
+        try {
+          const parsed = parseReferencePath(ref.target);
+          parsedModel = parsed.modelName, targetSegment = parsed.segment;
+        } catch (error) {
+          if (error instanceof ReferencePathParseError)
+            result.addError({
+              layer: sourceLayerName,
+              elementId,
+              message: `Malformed qualified reference path: ${error.message}`,
+              fixSuggestion: "Use format '@{model-name}/{layer}.{type}.{name}' for qualified references or '{layer}.{type}.{name}' for unqualified references",
+              category: "reference"
+            });
+          else
+            throw error;
+          continue;
+        }
+        const modelFound = parsedModel && model.manifest.models && this.findManifestModel(model.manifest.models, parsedModel);
+        if (parsedModel && !modelFound) {
+          result.addError({
+            layer: sourceLayerName,
+            elementId,
+            message: `Unknown external model reference: model '${parsedModel}' is not declared in manifest`,
+            fixSuggestion: `Add model '${parsedModel}' to the 'models' section of manifest.yaml`,
+            category: "reference"
+          });
+          continue;
+        }
+      } else if (!validIds.has(ref.target)) {
+        if (model.loadedLayerFilter && model.loadedLayerFilter.length > 0) {
+          const targetLayerName2 = this.extractLayerFromId(ref.target);
+          if (!model.loadedLayerFilter.includes(targetLayerName2))
+            continue;
+        }
         result.addError({
           layer: sourceLayerName,
           elementId,
           message: `Broken reference: target '${ref.target}' does not exist`,
-          fixSuggestion: `Remove reference or create element '${ref.target}'`
+          fixSuggestion: `Remove reference or create element '${ref.target}'`,
+          category: "reference"
         });
         continue;
       }
-      const targetLayerName = this.extractLayerFromId(ref.target), sourceLevel = this.LAYER_HIERARCHY[sourceLayerName], targetLevel = this.LAYER_HIERARCHY[targetLayerName];
+      const targetLayerName = this.extractLayerFromId(targetSegment), sourceLevel = this.LAYER_HIERARCHY[sourceLayerName], targetLevel = this.LAYER_HIERARCHY[targetLayerName];
       if (sourceLevel === void 0) {
         result.addError({
           layer: sourceLayerName,
           elementId,
           message: `Unknown source layer: ${sourceLayerName}`,
-          fixSuggestion: `Use one of the valid layers: ${this.KNOWN_LAYERS.join(", ")}`
+          fixSuggestion: `Use one of the valid layers: ${this.KNOWN_LAYERS.join(", ")}`,
+          category: "reference"
         });
         continue;
       }
@@ -62,16 +99,11 @@ class ReferenceValidator {
           layer: sourceLayerName,
           elementId,
           message: `Target element '${ref.target}' has unknown layer: ${targetLayerName}`,
-          fixSuggestion: `Check that element ID '${ref.target}' uses a valid layer prefix (e.g., motivation-, business-, api-)`
+          fixSuggestion: `Check that element ID '${ref.target}' uses a valid layer prefix (e.g., motivation-, business-, api-)`,
+          category: "reference"
         });
         continue;
       }
-      sourceLevel > targetLevel && result.addError({
-        layer: sourceLayerName,
-        elementId,
-        message: `Invalid reference direction: ${sourceLayerName} (level ${sourceLevel}) cannot reference ${targetLayerName} (level ${targetLevel})`,
-        fixSuggestion: "References must go from higher layers to lower layers (motivation \u2192 testing)"
-      });
     }
   }
   /**
@@ -84,6 +116,18 @@ class ReferenceValidator {
         return layer;
     return elementId.split(separator)[0] || "";
   }
+  /**
+   * Find a model in the manifest using case-insensitive lookup
+   * Handles the case where parseReferencePath normalizes model names to lowercase,
+   * but the manifest may have different casing for the declared model keys.
+   */
+  findManifestModel(models, modelName) {
+    const lowerModelName = modelName.toLowerCase();
+    for (const key of Object.keys(models))
+      if (key.toLowerCase() === lowerModelName)
+        return !0;
+    return !1;
+  }
 }
 export {
   ReferenceValidator

package/dist/validators/reference-validator.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/validators/reference-validator.ts"],
-  "sourcesContent": ["/**\n * Reference validation for cross-layer integrity\n */\n\nimport { ValidationResult } from \"./types.js\";\nimport type { Model } from \"../core/model.js\";\nimport { getLayerByNumber, LAYER_HIERARCHY, getAllLayerIds } from \"../generated/layer-registry.js\";\n\n/**\n * Validator for cross-layer references\n */\nexport class ReferenceValidator {\n  // Known layer names from generated registry (including hyphenated ones)\n  private readonly KNOWN_LAYERS = getAllLayerIds();\n\n  // Build layer hierarchy map at instantiation from generated registry\n  private readonly LAYER_HIERARCHY: Record<string, number> = this.buildLayerHierarchy();\n\n  private buildLayerHierarchy(): Record<string, number> {\n    const hierarchy: Record<string, number> = {};\n    for (const layerNumber of LAYER_HIERARCHY) {\n      const layer = getLayerByNumber(layerNumber);\n      if (layer) {\n        hierarchy[layer.id] = layer.number;\n      }\n    }\n    return hierarchy;\n  }\n\n  /**\n   * Validate all references in a model\n   */\n  validateModel(model: Model): ValidationResult {\n    const result = new ValidationResult();\n    const allElementIds = this.collectAllElementIds(model);\n\n    for (const [layerName, layer] of model.layers) {\n      for (const element of layer.listElements()) {\n        this.validateReferences(\n          element.path || element.id,\n          element.references || [],\n          layerName,\n          allElementIds,\n          result\n        );\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Collect all element IDs across the model\n   */\n  private collectAllElementIds(model: Model): Set<string> {\n    const ids = new Set<string>();\n\n    for (const layer of model.layers.values()) {\n      for (const element of layer.listElements()) {\n        ids.add(element.path || element.id);\n        // Also add raw UUID so references stored by UUID still resolve\n        ids.add(element.id);\n      }\n    }\n\n    return ids;\n  }\n\n  /**\n   * Validate references for an element\n   */\n  private validateReferences(\n    elementId: string,\n    references: Array<{ target: string; type?: string }>,\n    sourceLayerName: string,\n    validIds: Set<string>,\n    result: ValidationResult\n  ): void {\n    for (const ref of references) {\n      // Check target exists\n      if (!validIds.has(ref.target)) {\n        result.addError({\n          layer: sourceLayerName,\n          elementId,\n          message: `Broken reference: target '${ref.target}' does not exist`,\n          fixSuggestion: `Remove reference or create element '${ref.target}'`,\n        });\n        continue;\n      }\n\n      // Check directional constraint (higher \u2192 lower only)\n      const targetLayerName = this.extractLayerFromId(ref.target);\n      const sourceLevel = this.LAYER_HIERARCHY[sourceLayerName];\n      const targetLevel = this.LAYER_HIERARCHY[targetLayerName];\n\n      if (sourceLevel === undefined) {\n        result.addError({\n          layer: sourceLayerName,\n          elementId,\n          message: `Unknown source layer: ${sourceLayerName}`,\n          fixSuggestion:\n            `Use one of the valid layers: ${this.KNOWN_LAYERS.join(\", \")}`,\n        });\n        continue;\n      }\n\n      if (targetLevel === undefined) {\n        result.addError({\n          layer: sourceLayerName,\n          elementId,\n          message: `Target element '${ref.target}' has unknown layer: ${targetLayerName}`,\n          fixSuggestion: `Check that element ID '${ref.target}' uses a valid layer prefix (e.g., motivation-, business-, api-)`,\n        });\n        continue;\n      }\n\n      // References must go from higher layers (lower numbers) to lower layers (higher numbers)\n      // or within the same layer\n      if (sourceLevel > targetLevel) {\n        result.addError({\n          layer: sourceLayerName,\n          elementId,\n          message: `Invalid reference direction: ${sourceLayerName} (level ${sourceLevel}) cannot reference ${targetLayerName} (level ${targetLevel})`,\n          fixSuggestion:\n            \"References must go from higher layers to lower layers (motivation \u2192 testing)\",\n        });\n      }\n    }\n  }\n\n  /**\n   * Extract layer name from element ID, handling both dot-separated and hyphenated layer names\n   */\n  private extractLayerFromId(elementId: string): string {\n    // Determine if using dot-separated format (e.g., motivation.goal.name) or hyphenated (e.g., motivation-goal-name)\n    const isDotSeparated = elementId.includes(\".\");\n    const separator = isDotSeparated ? \".\" : \"-\";\n\n    // Try to match known layers in order of specificity (longest first)\n    const sortedLayers = [...this.KNOWN_LAYERS].sort((a, b) => b.length - a.length);\n\n    for (const layer of sortedLayers) {\n      if (elementId.startsWith(layer + separator)) {\n        return layer;\n      }\n    }\n\n    // Fallback: return first segment (shouldn't reach here with valid element IDs)\n    return elementId.split(separator)[0] || \"\";\n  }\n}\n"],
-  "mappings": "AAIA,SAAS,wBAAwB;AAEjC,SAAS,kBAAkB,iBAAiB,sBAAsB;AAK5D,MAAO,mBAAkB;;EAEZ,eAAe,eAAc;;EAG7B,kBAA0C,KAAK,oBAAmB;EAE3E,sBAAmB;AACzB,UAAM,YAAoC,CAAA;AAC1C,eAAW,eAAe,iBAAiB;AACzC,YAAM,QAAQ,iBAAiB,WAAW;AAC1C,MAAI,UACF,UAAU,MAAM,EAAE,IAAI,MAAM;IAEhC;AACA,WAAO;EACT;;;;EAKA,cAAc,OAAY;AACxB,UAAM,SAAS,IAAI,iBAAgB,GAC7B,gBAAgB,KAAK,qBAAqB,KAAK;AAErD,eAAW,CAAC,WAAW,KAAK,KAAK,MAAM;AACrC,iBAAW,WAAW,MAAM,aAAY;AACtC,aAAK,mBACH,QAAQ,QAAQ,QAAQ,IACxB,QAAQ,cAAc,CAAA,GACtB,WACA,eACA,MAAM;AAKZ,WAAO;EACT;;;;EAKQ,qBAAqB,OAAY;AACvC,UAAM,MAAM,oBAAI,IAAG;AAEnB,eAAW,SAAS,MAAM,OAAO,OAAM;AACrC,iBAAW,WAAW,MAAM,aAAY;AACtC,YAAI,IAAI,QAAQ,QAAQ,QAAQ,EAAE,GAElC,IAAI,IAAI,QAAQ,EAAE;AAItB,WAAO;EACT;;;;EAKQ,mBACN,WACA,YACA,iBACA,UACA,QAAwB;AAExB,eAAW,OAAO,YAAY;AAE5B,UAAI,CAAC,SAAS,IAAI,IAAI,MAAM,GAAG;AAC7B,eAAO,SAAS;UACd,OAAO;UACP;UACA,SAAS,6BAA6B,IAAI,MAAM;UAChD,eAAe,uCAAuC,IAAI,MAAM;SACjE;AACD;MACF;AAGA,YAAM,kBAAkB,KAAK,mBAAmB,IAAI,MAAM,GACpD,cAAc,KAAK,gBAAgB,eAAe,GAClD,cAAc,KAAK,gBAAgB,eAAe;AAExD,UAAI,gBAAgB,QAAW;AAC7B,eAAO,SAAS;UACd,OAAO;UACP;UACA,SAAS,yBAAyB,eAAe;UACjD,eACE,gCAAgC,KAAK,aAAa,KAAK,IAAI,CAAC;SAC/D;AACD;MACF;AAEA,UAAI,gBAAgB,QAAW;AAC7B,eAAO,SAAS;UACd,OAAO;UACP;UACA,SAAS,mBAAmB,IAAI,MAAM,wBAAwB,eAAe;UAC7E,eAAe,0BAA0B,IAAI,MAAM;SACpD;AACD;MACF;AAIA,MAAI,cAAc,eAChB,OAAO,SAAS;QACd,OAAO;QACP;QACA,SAAS,gCAAgC,eAAe,WAAW,WAAW,sBAAsB,eAAe,WAAW,WAAW;QACzI,eACE;OACH;IAEL;EACF;;;;EAKQ,mBAAmB,WAAiB;AAG1C,UAAM,YADiB,UAAU,SAAS,GAAG,IACV,MAAM,KAGnC,eAAe,CAAC,GAAG,KAAK,YAAY,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,SAAS,EAAE,MAAM;AAE9E,eAAW,SAAS;AAClB,UAAI,UAAU,WAAW,QAAQ,SAAS;AACxC,eAAO;AAKX,WAAO,UAAU,MAAM,SAAS,EAAE,CAAC,KAAK;EAC1C;;",
-  "names": []
+  "sourcesContent": ["/**\n * Reference validation for cross-layer integrity\n */\n\nimport { ValidationResult } from \"./types.js\";\nimport type { Model } from \"../core/model.js\";\nimport { getLayerByNumber, LAYER_HIERARCHY, getAllLayerIds } from \"../generated/layer-registry.js\";\nimport { parseReferencePath, ReferencePathParseError } from \"../utils/reference-path-parser.js\";\n\n/**\n * Validator for cross-layer references\n */\nexport class ReferenceValidator {\n  // Known layer names from generated registry (including hyphenated ones)\n  private readonly KNOWN_LAYERS = getAllLayerIds();\n\n  // Build layer hierarchy map at instantiation from generated registry\n  private readonly LAYER_HIERARCHY: Record<string, number> = this.buildLayerHierarchy();\n\n  private buildLayerHierarchy(): Record<string, number> {\n    const hierarchy: Record<string, number> = {};\n    for (const layerNumber of LAYER_HIERARCHY) {\n      const layer = getLayerByNumber(layerNumber);\n      if (layer) {\n        hierarchy[layer.id] = layer.number;\n      }\n    }\n    return hierarchy;\n  }\n\n  /**\n   * Validate all references in a model\n   */\n  validateModel(model: Model): ValidationResult {\n    const result = new ValidationResult();\n    const allElementIds = this.collectAllElementIds(model);\n\n    for (const [layerName, layer] of model.layers) {\n      for (const element of layer.listElements()) {\n        this.validateReferences(\n          element.path || element.id,\n          element.references || [],\n          layerName,\n          allElementIds,\n          model,\n          result\n        );\n      }\n    }\n\n    return result;\n  }\n\n  /**\n   * Collect all element IDs across the model\n   */\n  private collectAllElementIds(model: Model): Set<string> {\n    const ids = new Set<string>();\n\n    for (const layer of model.layers.values()) {\n      for (const element of layer.listElements()) {\n        ids.add(element.path || element.id);\n        // Also add raw UUID so references stored by UUID still resolve\n        ids.add(element.id);\n      }\n    }\n\n    return ids;\n  }\n\n  /**\n   * Validate references for an element\n   */\n  private validateReferences(\n    elementId: string,\n    references: Array<{ target: string; type?: string }>,\n    sourceLayerName: string,\n    validIds: Set<string>,\n    model: Model,\n    result: ValidationResult\n  ): void {\n    for (const ref of references) {\n      let parsedModel: string | undefined;\n      let targetSegment = ref.target;\n\n      // Check if this is a qualified reference (starts with @)\n      if (ref.target.startsWith(\"@\")) {\n        // Try to parse the qualified reference\n        try {\n          const parsed = parseReferencePath(ref.target);\n          parsedModel = parsed.modelName;\n          targetSegment = parsed.segment;\n        } catch (error) {\n          if (error instanceof ReferencePathParseError) {\n            result.addError({\n              layer: sourceLayerName,\n              elementId,\n              message: `Malformed qualified reference path: ${error.message}`,\n              fixSuggestion: `Use format '@{model-name}/{layer}.{type}.{name}' for qualified references or '{layer}.{type}.{name}' for unqualified references`,\n              category: \"reference\",\n            });\n          } else {\n            throw error;\n          }\n          continue;\n        }\n\n        // For qualified references, check if the model is declared\n        // Normalize lookup to handle case-insensitive manifest keys\n        const modelFound = parsedModel && model.manifest.models && this.findManifestModel(model.manifest.models, parsedModel);\n        if (parsedModel && !modelFound) {\n          result.addError({\n            layer: sourceLayerName,\n            elementId,\n            message: `Unknown external model reference: model '${parsedModel}' is not declared in manifest`,\n            fixSuggestion: `Add model '${parsedModel}' to the 'models' section of manifest.yaml`,\n            category: \"reference\",\n          });\n          continue;\n        }\n      } else {\n        // For unqualified references, check if target exists locally\n        if (!validIds.has(ref.target)) {\n          // Skip validation for references to unloaded layers when filter is active\n          if (model.loadedLayerFilter && model.loadedLayerFilter.length > 0) {\n            const targetLayerName = this.extractLayerFromId(ref.target);\n            if (!model.loadedLayerFilter.includes(targetLayerName)) {\n              // Target is in an unloaded layer; skip this reference\n              continue;\n            }\n          }\n\n          result.addError({\n            layer: sourceLayerName,\n            elementId,\n            message: `Broken reference: target '${ref.target}' does not exist`,\n            fixSuggestion: `Remove reference or create element '${ref.target}'`,\n            category: \"reference\",\n          });\n          continue;\n        }\n      }\n\n      // Check that both layers exist\n      // For qualified references, extract layer from the parsed segment\n      // For unqualified references, extract layer from the target directly\n      const targetLayerName = this.extractLayerFromId(targetSegment);\n      const sourceLevel = this.LAYER_HIERARCHY[sourceLayerName];\n      const targetLevel = this.LAYER_HIERARCHY[targetLayerName];\n\n      if (sourceLevel === undefined) {\n        result.addError({\n          layer: sourceLayerName,\n          elementId,\n          message: `Unknown source layer: ${sourceLayerName}`,\n          fixSuggestion:\n            `Use one of the valid layers: ${this.KNOWN_LAYERS.join(\", \")}`,\n          category: \"reference\",\n        });\n        continue;\n      }\n\n      if (targetLevel === undefined) {\n        result.addError({\n          layer: sourceLayerName,\n          elementId,\n          message: `Target element '${ref.target}' has unknown layer: ${targetLayerName}`,\n          fixSuggestion: `Check that element ID '${ref.target}' uses a valid layer prefix (e.g., motivation-, business-, api-)`,\n          category: \"reference\",\n        });\n        continue;\n      }\n\n      // No directional constraint: direction is a property of the predicate, not of the\n      // layers (spec/DESIGN_CHARTER.md). Layer levels are resolved above only to reject\n      // references to unknown layers.\n    }\n  }\n\n  /**\n   * Extract layer name from element ID, handling both dot-separated and hyphenated layer names\n   */\n  private extractLayerFromId(elementId: string): string {\n    // Determine if using dot-separated format (e.g., motivation.goal.name) or hyphenated (e.g., motivation-goal-name)\n    const isDotSeparated = elementId.includes(\".\");\n    const separator = isDotSeparated ? \".\" : \"-\";\n\n    // Try to match known layers in order of specificity (longest first)\n    const sortedLayers = [...this.KNOWN_LAYERS].sort((a, b) => b.length - a.length);\n\n    for (const layer of sortedLayers) {\n      if (elementId.startsWith(layer + separator)) {\n        return layer;\n      }\n    }\n\n    // Fallback: return first segment (shouldn't reach here with valid element IDs)\n    return elementId.split(separator)[0] || \"\";\n  }\n\n  /**\n   * Find a model in the manifest using case-insensitive lookup\n   * Handles the case where parseReferencePath normalizes model names to lowercase,\n   * but the manifest may have different casing for the declared model keys.\n   */\n  private findManifestModel(\n    models: Record<string, unknown>,\n    modelName: string\n  ): boolean {\n    const lowerModelName = modelName.toLowerCase();\n    for (const key of Object.keys(models)) {\n      if (key.toLowerCase() === lowerModelName) {\n        return true;\n      }\n    }\n    return false;\n  }\n}\n"],
+  "mappings": "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",
+  "names": ["targetLayerName"]
 }

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

@@ -88,8 +88,32 @@ class RelationshipValidator {
    * 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)
+    const errors = [];
+    let sourceElement = null, targetElement = null, bothInFilterAndFound = !1;
+    if (model.loadedLayerFilter && model.loadedLayerFilter.length > 0) {
+      const sourceLayer2 = this.extractLayerFromElementId(relationship.source), targetLayer2 = this.extractLayerFromElementId(relationship.target);
+      if (sourceLayer2 && targetLayer2) {
+        const sourceInFilter = model.loadedLayerFilter.includes(sourceLayer2), targetInFilter = model.loadedLayerFilter.includes(targetLayer2);
+        if (!sourceInFilter && !targetInFilter)
+          return errors;
+        if (sourceInFilter && (sourceElement = this.findElementInModel(model, relationship.source), !sourceElement))
+          return errors.push({
+            layer: relationship.layer,
+            elementId: relationship.source,
+            message: `Relationship source element '${relationship.source}' not found`
+          }), errors;
+        if (targetInFilter && (targetElement = this.findElementInModel(model, relationship.target), !targetElement))
+          return errors.push({
+            layer: relationship.layer,
+            elementId: relationship.target,
+            message: `Relationship target element '${relationship.target}' not found`
+          }), errors;
+        if (!sourceInFilter || !targetInFilter)
+          return errors;
+        bothInFilterAndFound = !0;
+      }
+    }
+    if (bothInFilterAndFound || (sourceElement = this.findElementInModel(model, relationship.source), targetElement = this.findElementInModel(model, relationship.target)), !sourceElement)
       return errors.push({
         layer: relationship.layer,
         elementId: relationship.source,
@@ -107,7 +131,7 @@ class RelationshipValidator {
       return errors.push({
         layer: relationship.layer,
         elementId: relationship.source,
-        message: `No schema found for relationship: ${sourceLayer}.${sourceType} --[${relationship.predicate}]--> ${targetLayer}.${targetType}`
+        message: `No schema found for relationship: ${relationship.source} --[${relationship.predicate}]--> ${relationship.target} (${sourceLayer}.${sourceType} --[${relationship.predicate}]--> ${targetLayer}.${targetType})`
       }), errors;
     }
     const schema = this.relationshipSchemas.get(schemaKey);
@@ -115,7 +139,7 @@ class RelationshipValidator {
       return errors.push({
         layer: relationship.layer,
         elementId: relationship.source,
-        message: `Failed to load schema for relationship: ${schemaKey}`
+        message: `Failed to load schema for relationship: ${relationship.source} --[${relationship.predicate}]--> ${relationship.target} (${schemaKey})`
       }), errors;
     const cardinalityErrors = this.validateCardinality(relationship, schema, relationshipsBySource, relationshipsByTarget);
     if (errors.push(...cardinalityErrors), relationship.properties && schema.attributes) {
@@ -183,7 +207,7 @@ class RelationshipValidator {
       key in schema.attributes || errors.push({
         layer: relationship.layer,
         elementId: relationship.source,
-        message: `Relationship property '${key}' not defined in schema for predicate '${relationship.predicate}'`
+        message: `Relationship property '${key}' on ${relationship.source} --[${relationship.predicate}]--> ${relationship.target} not defined in schema for predicate '${relationship.predicate}'`
       });
     return errors;
   }
@@ -236,6 +260,10 @@ class RelationshipValidator {
     }
     return null;
   }
+  extractLayerFromElementId(elementId) {
+    const parts = elementId.split(".");
+    return parts.length < 2 ? null : parts[0];
+  }
 }
 export {
   RelationshipValidator