@domainlang/language 0.6.0 → 0.8.0

package/src/services/workspace-manager.ts

@@ -32,9 +32,29 @@ interface LoadedLockFile {
     readonly filePath: string;
 }
 
+/**
+ * Cached context for a single workspace (directory containing model.yaml).
+ * Each workspace root has its own independent state.
+ */
+interface WorkspaceContext {
+    /** The resolved workspace root path */
+    readonly root: string;
+    /** Cached lock file for this workspace */
+    lockFile: LockFile | undefined;
+    /** Cached manifest for this workspace */
+    manifestCache: ManifestCache | undefined;
+    /** Initialization promise for this context */
+    initPromise: Promise<void> | undefined;
+}
+
 /**
  * Coordinates workspace discovery and manifest/lock file reading.
  * 
+ * **Multi-Root Support:**
+ * Maintains separate contexts for each workspace root (directory with model.yaml).
+ * This enables correct resolution in multi-project setups where sub-projects
+ * have their own model.yaml files.
+ * 
  * This is a read-only service for the LSP - it does NOT:
  * - Generate lock files (use CLI: `dlang install`)
  * - Download packages (use CLI: `dlang install`)
@@ -48,23 +68,88 @@ interface LoadedLockFile {
 export class WorkspaceManager {
     private readonly manifestFiles: readonly string[];
     private readonly lockFiles: readonly string[];
-    private workspaceRoot: string | undefined;
-    private lockFile: LockFile | undefined;
-    private initializePromise: Promise<void> | undefined;
-    private manifestCache: ManifestCache | undefined;
+    
+    /** 
+     * Cache of workspace contexts by resolved workspace root path.
+     * Supports multiple independent workspaces in a single session.
+     */
+    private readonly workspaceContexts = new Map<string, WorkspaceContext>();
+    
+    /**
+     * Cache mapping start paths to their resolved workspace roots.
+     * Avoids repeated directory tree walking for the same paths.
+     */
+    private readonly pathToRootCache = new Map<string, string>();
+    
+    /**
+     * The currently active workspace root (set by last initialize() call).
+     * Used by methods like getWorkspaceRoot(), getManifest(), etc.
+     */
+    private activeRoot: string | undefined;
 
     constructor(options: WorkspaceManagerOptions = {}) {
         this.manifestFiles = options.manifestFiles ?? [...DEFAULT_MANIFEST_FILES];
         this.lockFiles = options.lockFiles ?? [...DEFAULT_LOCK_FILES];
     }
 
+    /**
+     * Returns the active workspace context, or undefined if not initialized.
+     * All methods that need context should call this after ensureInitialized().
+     */
+    private getActiveContext(): WorkspaceContext | undefined {
+        if (!this.activeRoot) return undefined;
+        return this.workspaceContexts.get(this.activeRoot);
+    }
+
     /**
      * Finds the workspace root and loads any existing lock file.
-     * Repeated calls await the same initialization work.
+     * 
+     * **Multi-Root Support:**
+     * Each call may switch to a different workspace context based on the startPath.
+     * The workspace root is the nearest ancestor directory containing model.yaml.
+     * 
+     * @param startPath - Directory to start searching from (usually document directory)
      */
     async initialize(startPath: string): Promise<void> {
-        this.initializePromise ??= this.performInitialization(startPath);
-        await this.initializePromise;
+        const normalizedStart = path.resolve(startPath);
+        
+        // Fast path: check if we've already resolved this path
+        let workspaceRoot = this.pathToRootCache.get(normalizedStart);
+        
+        if (!workspaceRoot) {
+            // Find workspace root by walking up directory tree
+            workspaceRoot = await this.findWorkspaceRoot(normalizedStart) ?? normalizedStart;
+            this.pathToRootCache.set(normalizedStart, workspaceRoot);
+        }
+        
+        // Switch to this workspace's context
+        this.activeRoot = workspaceRoot;
+        
+        // Get or create context for this workspace
+        let context = this.workspaceContexts.get(workspaceRoot);
+        if (!context) {
+            context = {
+                root: workspaceRoot,
+                lockFile: undefined,
+                manifestCache: undefined,
+                initPromise: undefined
+            };
+            this.workspaceContexts.set(workspaceRoot, context);
+        }
+        
+        // Initialize this context (lazy, once per context)
+        context.initPromise ??= this.initializeContext(context);
+        await context.initPromise;
+    }
+    
+    /**
+     * Initializes a workspace context by loading its lock file.
+     */
+    private async initializeContext(context: WorkspaceContext): Promise<void> {
+        const loaded = await this.loadLockFileFromDisk(context.root);
+        if (loaded) {
+            context.lockFile = loaded.lockFile;
+        }
     }
 
     /**
@@ -72,21 +157,53 @@ export class WorkspaceManager {
      * @throws Error if {@link initialize} has not completed successfully.
      */
     getWorkspaceRoot(): string {
-        if (!this.workspaceRoot) {
+        if (!this.activeRoot) {
             throw new Error('WorkspaceManager not initialized. Call initialize() first.');
         }
-        return this.workspaceRoot;
+        return this.activeRoot;
     }
 
     /**
      * Returns the project-local package cache directory.
      * Per PRS-010: .dlang/packages/
+     * 
+     * If the current workspace root is inside a cached package,
+     * walks up to find the actual project root's cache directory.
      */
     getCacheDir(): string {
-        if (!this.workspaceRoot) {
+        if (!this.activeRoot) {
             throw new Error('WorkspaceManager not initialized. Call initialize() first.');
         }
-        return path.join(this.workspaceRoot, '.dlang', 'packages');
+        
+        // If workspace root is inside .dlang/packages, find the project root
+        const projectRoot = this.findProjectRootFromCache(this.activeRoot);
+        return path.join(projectRoot, '.dlang', 'packages');
+    }
+    
+    /**
+     * Finds the actual project root when inside a cached package.
+     * 
+     * Cached packages are stored in: <project>/.dlang/packages/<owner>/<repo>/<commit>/
+     * If workspaceRoot is inside this structure, returns <project>
+     * Otherwise returns workspaceRoot unchanged.
+     */
+    private findProjectRootFromCache(currentRoot: string): string {
+        // Normalize path for cross-platform compatibility
+        const normalized = currentRoot.split(path.sep);
+        
+        // Find last occurrence of .dlang in the path
+        const dlangIndex = normalized.lastIndexOf('.dlang');
+        
+        // Check if we're inside .dlang/packages/...
+        if (dlangIndex !== -1 && 
+            dlangIndex + 1 < normalized.length && 
+            normalized[dlangIndex + 1] === 'packages') {
+            // Return the directory containing .dlang (the project root)
+            return normalized.slice(0, dlangIndex).join(path.sep);
+        }
+        
+        // Not in a cached package, return as-is
+        return currentRoot;
     }
 
     /**
@@ -94,7 +211,7 @@ export class WorkspaceManager {
      */
     async getManifestPath(): Promise<string | undefined> {
         await this.ensureInitialized();
-        const root = this.workspaceRoot;
+        const root = this.activeRoot;
         if (!root) {
             return undefined;
         }
@@ -118,13 +235,39 @@ export class WorkspaceManager {
         return this.loadManifest();
     }
 
+    /**
+     * Returns the cached manifest synchronously (if available).
+     * Used by LSP features that need synchronous access (like completion).
+     * Returns undefined if manifest hasn't been loaded yet.
+     */
+    getCachedManifest(): ModelManifest | undefined {
+        return this.getActiveContext()?.manifestCache?.manifest;
+    }
+
+    /**
+     * Ensures the manifest is loaded and returns it.
+     * Use this over getCachedManifest() when you need to guarantee the manifest
+     * is available (e.g., in async LSP operations like completions).
+     * 
+     * @returns The manifest or undefined if no model.yaml exists
+     */
+    async ensureManifestLoaded(): Promise<ModelManifest | undefined> {
+        // If we already have a cached manifest, return it immediately
+        const context = this.getActiveContext();
+        if (context?.manifestCache?.manifest) {
+            return context.manifestCache.manifest;
+        }
+        // Otherwise load it (this also populates the cache)
+        return this.getManifest();
+    }
+
     /**
      * Gets the currently cached lock file.
      * Returns undefined if no lock file exists (run `dlang install` to create one).
      */
     async getLockFile(): Promise<LockFile | undefined> {
         await this.ensureInitialized();
-        return this.lockFile;
+        return this.getActiveContext()?.lockFile;
     }
 
     /**
@@ -132,13 +275,12 @@ export class WorkspaceManager {
      */
     async refreshLockFile(): Promise<LockFile | undefined> {
         await this.ensureInitialized();
+        const context = this.getActiveContext();
         const loaded = await this.loadLockFileFromDisk();
-        if (loaded) {
-            this.lockFile = loaded.lockFile;
-        } else {
-            this.lockFile = undefined;
+        if (context) {
+            context.lockFile = loaded?.lockFile;
         }
-        return this.lockFile;
+        return loaded?.lockFile;
     }
 
     /**
@@ -149,8 +291,11 @@ export class WorkspaceManager {
      * will re-read from disk.
      */
     invalidateCache(): void {
-        this.manifestCache = undefined;
-        this.lockFile = undefined;
+        const context = this.getActiveContext();
+        if (context) {
+            context.manifestCache = undefined;
+            context.lockFile = undefined;
+        }
     }
 
     /**
@@ -158,7 +303,10 @@ export class WorkspaceManager {
      * Call this when model.yaml changes.
      */
     invalidateManifestCache(): void {
-        this.manifestCache = undefined;
+        const context = this.getActiveContext();
+        if (context) {
+            context.manifestCache = undefined;
+        }
     }
 
     /**
@@ -166,7 +314,10 @@ export class WorkspaceManager {
      * Call this when model.lock changes.
      */
     invalidateLockCache(): void {
-        this.lockFile = undefined;
+        const context = this.getActiveContext();
+        if (context) {
+            context.lockFile = undefined;
+        }
     }
 
     /**
@@ -209,7 +360,8 @@ export class WorkspaceManager {
     async resolveDependencyPath(specifier: string): Promise<string | undefined> {
         await this.ensureInitialized();
         
-        if (!this.lockFile) {
+        const context = this.getActiveContext();
+        if (!context?.lockFile) {
             return undefined;
         }
 
@@ -236,7 +388,7 @@ export class WorkspaceManager {
             // Match if specifier equals key or starts with key/
             if (specifier === key || specifier.startsWith(`${key}/`)) {
                 // Find in lock file
-                const locked = this.lockFile.dependencies[normalized.source];
+                const locked = context.lockFile.dependencies[normalized.source];
                 if (!locked) {
                     return undefined;
                 }
@@ -275,36 +427,34 @@ export class WorkspaceManager {
         }
     }
 
-    private async performInitialization(startPath: string): Promise<void> {
-        this.workspaceRoot = await this.findWorkspaceRoot(startPath) ?? path.resolve(startPath);
-        const loaded = await this.loadLockFileFromDisk();
-        if (loaded) {
-            this.lockFile = loaded.lockFile;
-        }
-    }
-
     private async ensureInitialized(): Promise<void> {
-        if (this.initializePromise) {
-            await this.initializePromise;
-        } else if (!this.workspaceRoot) {
-            throw new Error('WorkspaceManager not initialized. Call initialize() first.');
+        // Check if we have an active workspace context
+        if (this.activeRoot) {
+            const context = this.workspaceContexts.get(this.activeRoot);
+            if (context?.initPromise) {
+                await context.initPromise;
+                return;
+            }
         }
+        
+        throw new Error('WorkspaceManager not initialized. Call initialize() first.');
     }
 
-    private async loadLockFileFromDisk(): Promise<LoadedLockFile | undefined> {
-        if (!this.workspaceRoot) {
+    private async loadLockFileFromDisk(root?: string): Promise<LoadedLockFile | undefined> {
+        const workspaceRoot = root ?? this.activeRoot;
+        if (!workspaceRoot) {
             return undefined;
         }
 
         // Try performance optimizer cache first
         const optimizer = getGlobalOptimizer();
-        const cached = await optimizer.getCachedLockFile(this.workspaceRoot);
+        const cached = await optimizer.getCachedLockFile(workspaceRoot);
         if (cached) {
-            return { lockFile: cached, filePath: path.join(this.workspaceRoot, 'model.lock') };
+            return { lockFile: cached, filePath: path.join(workspaceRoot, 'model.lock') };
         }
 
         for (const filename of this.lockFiles) {
-            const filePath = path.join(this.workspaceRoot, filename);
+            const filePath = path.join(workspaceRoot, filename);
             const lockFile = await this.tryReadLockFile(filePath);
             if (lockFile) {
                 return { lockFile, filePath };
@@ -327,37 +477,84 @@ export class WorkspaceManager {
     }
 
     private async loadManifest(): Promise<ModelManifest | undefined> {
+        const context = this.getActiveContext();
         const manifestPath = await this.getManifestPath();
         if (!manifestPath) {
-            this.manifestCache = undefined;
+            this.clearManifestCache(context);
             return undefined;
         }
 
         try {
-            const stat = await fs.stat(manifestPath);
-            if (this.manifestCache?.path === manifestPath &&
-                this.manifestCache.mtimeMs === stat.mtimeMs) {
-                return this.manifestCache.manifest;
-            }
+            return await this.readAndCacheManifest(manifestPath, context);
+        } catch (error) {
+            return this.handleManifestError(error, manifestPath, context);
+        }
+    }
 
-            const content = await fs.readFile(manifestPath, 'utf-8');
-            const manifest = (YAML.parse(content) ?? {}) as ModelManifest;
-            
-            // Validate manifest structure
-            this.validateManifest(manifest, manifestPath);
-            
-            this.manifestCache = {
+    /**
+     * Reads, validates, and caches a manifest file.
+     */
+    private async readAndCacheManifest(
+        manifestPath: string, 
+        context: WorkspaceContext | undefined
+    ): Promise<ModelManifest> {
+        const stat = await fs.stat(manifestPath);
+        if (context?.manifestCache?.path === manifestPath &&
+            context.manifestCache.mtimeMs === stat.mtimeMs) {
+            return context.manifestCache.manifest;
+        }
+
+        const content = await fs.readFile(manifestPath, 'utf-8');
+        const manifest = (YAML.parse(content) ?? {}) as ModelManifest;
+        
+        // Validate manifest structure
+        this.validateManifest(manifest, manifestPath);
+        
+        if (context) {
+            context.manifestCache = {
                 manifest,
                 path: manifestPath,
                 mtimeMs: stat.mtimeMs,
             };
-            return manifest;
-        } catch (error) {
-            if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') {
-                this.manifestCache = undefined;
-                return undefined;
-            }
-            throw error;
+        }
+        return manifest;
+    }
+
+    /**
+     * Handles errors from manifest loading, distinguishing recoverable
+     * errors (missing file, parse errors) from unexpected ones.
+     */
+    private handleManifestError(
+        error: unknown,
+        manifestPath: string,
+        context: WorkspaceContext | undefined
+    ): ModelManifest | undefined {
+        if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') {
+            this.clearManifestCache(context);
+            return undefined;
+        }
+        // YAML parse errors should not crash the LSP
+        if (error instanceof Error && 
+            (error.name === 'YAMLParseError' || error.name === 'YAMLSyntaxError')) {
+            console.error(`Invalid model.yaml at ${manifestPath}: ${error.message}`);
+            this.clearManifestCache(context);
+            return undefined;
+        }
+        // Validation errors from validateManifest should not crash the LSP
+        if (error instanceof Error) {
+            console.error(`Manifest validation error at ${manifestPath}: ${error.message}`);
+            this.clearManifestCache(context);
+            return undefined;
+        }
+        throw error;
+    }
+
+    /**
+     * Clears the manifest cache on the given context, if available.
+     */
+    private clearManifestCache(context: WorkspaceContext | undefined): void {
+        if (context) {
+            context.manifestCache = undefined;
         }
     }
 
@@ -451,7 +648,7 @@ export class WorkspaceManager {
         // Resolve path relative to manifest directory
         const manifestDir = path.dirname(manifestPath);
         const resolvedPath = path.resolve(manifestDir, localPath);
-        const workspaceRoot = this.workspaceRoot || manifestDir;
+        const workspaceRoot = this.activeRoot || manifestDir;
 
         // Check if resolved path is within workspace
         const relativePath = path.relative(workspaceRoot, resolvedPath);

package/src/utils/import-utils.ts

@@ -7,7 +7,11 @@ import type { DomainLangServices } from '../domain-lang-module.js';
 
 /**
  * Lazily initialized workspace manager for standalone (non-LSP) usage.
- * Used by import graph building when services aren't available from DI.
+ * Used by import graph building when no DI-injected ImportResolver is available.
+ * 
+ * @deprecated Prefer passing an ImportResolver from the DI container.
+ * These singletons exist only for backwards compatibility with callers
+ * that haven't been updated to pass through DI services.
  */
 let standaloneWorkspaceManager: WorkspaceManager | undefined;
 let standaloneImportResolver: ImportResolver | undefined;
@@ -17,9 +21,7 @@ let lastInitializedDir: string | undefined;
  * Gets or creates a standalone import resolver for non-LSP contexts.
  * Creates its own WorkspaceManager if not previously initialized for this directory.
  *
- * NOTE: In LSP contexts, prefer using services.imports.ImportResolver directly.
- * This function exists for utilities that don't have access to the service container.
- *
+ * @deprecated Prefer using services.imports.ImportResolver directly.
  * @param startDir - Directory to start workspace search from
  * @returns Promise resolving to the import resolver
  */
@@ -44,10 +46,8 @@ async function getStandaloneImportResolver(startDir: string): Promise<ImportReso
 /**
  * Resolves an import path to an absolute file URI.
  * 
- * Delegates to ImportResolver which implements PRS-010 semantics:
- * - File imports (with .dlang extension): Direct file access
- * - Module imports (no extension): Requires model.yaml in directory
- * - External dependencies: Resolved via manifest and lock file
+ * @deprecated Prefer using ImportResolver.resolveForDocument() from the DI container.
+ * This function creates standalone instances outside the DI system.
  * 
  * @param importingDoc - The document containing the import statement
  * @param rawImportPath - The raw import path from the import statement
@@ -68,16 +68,19 @@ export async function resolveImportPath(
  * 
  * @param entryFilePath - Absolute or workspace-relative path to entry file
  * @param langiumDocuments - The Langium documents manager
+ * @param importResolver - Optional DI-injected ImportResolver. When provided,
+ *   uses it instead of creating standalone instances. Recommended for LSP contexts.
  * @returns Set of URIs (as strings) for all documents in the import graph
  * @throws {Error} If entry file cannot be resolved or loaded
  */
 export async function ensureImportGraphFromEntryFile(
   entryFilePath: string,
-  langiumDocuments: LangiumDocuments
+  langiumDocuments: LangiumDocuments,
+  importResolver?: ImportResolver
 ): Promise<Set<string>> {
   const entryUri = URI.file(path.resolve(entryFilePath));
   const entryDoc = await langiumDocuments.getOrCreateDocument(entryUri);
-  return ensureImportGraphFromDocument(entryDoc, langiumDocuments);
+  return ensureImportGraphFromDocument(entryDoc, langiumDocuments, importResolver);
 }
 
 /**
@@ -85,11 +88,14 @@ export async function ensureImportGraphFromEntryFile(
  * 
  * @param document - The starting document
  * @param langiumDocuments - The Langium documents manager
+ * @param importResolver - Optional DI-injected ImportResolver. When provided,
+ *   uses it instead of creating standalone instances. Recommended for LSP contexts.
  * @returns Set of URIs (as strings) for all documents in the import graph
  */
 export async function ensureImportGraphFromDocument(
   document: LangiumDocument,
-  langiumDocuments: LangiumDocuments
+  langiumDocuments: LangiumDocuments,
+  importResolver?: ImportResolver
 ): Promise<Set<string>> {
   const visited = new Set<string>();
 
@@ -102,10 +108,16 @@ export async function ensureImportGraphFromDocument(
     for (const imp of model.imports ?? []) {
       if (!imp.uri) continue;
       
-      // Use new resolveImportPath that supports external dependencies
-      const resolvedUri = await resolveImportPath(doc, imp.uri);
-      const childDoc = await langiumDocuments.getOrCreateDocument(resolvedUri);
-      await visit(childDoc);
+      try {
+        // Use DI-injected resolver when available, falling back to standalone
+        const resolvedUri = importResolver
+          ? await importResolver.resolveForDocument(doc, imp.uri)
+          : await resolveImportPath(doc, imp.uri);
+        const childDoc = await langiumDocuments.getOrCreateDocument(resolvedUri);
+        await visit(childDoc);
+      } catch {
+        // Import resolution failed — validation will report the error
+      }
     }
   }
 

package/src/validation/constants.ts

@@ -34,6 +34,7 @@ export const IssueCodes = {
     ImportMissingRef: 'import-missing-ref',
     ImportAbsolutePath: 'import-absolute-path',
     ImportEscapesWorkspace: 'import-escapes-workspace',
+    ImportUnresolved: 'import-unresolved',
     
     // Domain Issues
     DomainNoVision: 'domain-no-vision',
@@ -54,8 +55,12 @@ export const IssueCodes = {
     // Context/Domain Map Issues
     ContextMapNoContexts: 'context-map-no-contexts',
     ContextMapNoRelationships: 'context-map-no-relationships',
+    ContextMapDuplicateRelationship: 'context-map-duplicate-relationship',
     DomainMapNoDomains: 'domain-map-no-domains',
     
+    // Reference Issues
+    UnresolvedReference: 'unresolved-reference',
+    
     // Metadata Issues
     MetadataMissingName: 'metadata-missing-name',
     
@@ -77,8 +82,10 @@ const DOCS_BASE = `${REPO_BASE}/dsl/domain-lang/docs`;
  * @param docPath - Relative path from docs/ folder
  * @param anchor - Optional section anchor (without #)
  */
-const buildDocLink = (docPath: string, anchor?: string): string => 
-    `${DOCS_BASE}/${docPath}${anchor ? `#${anchor}` : ''}`;
+const buildDocLink = (docPath: string, anchor?: string): string => {
+    const anchorPart = anchor ? `#${anchor}` : '';
+    return `${DOCS_BASE}/${docPath}${anchorPart}`;
+};
 
 /**
  * Creates a CodeDescription for clickable documentation links in VS Code.
@@ -129,8 +136,11 @@ export const ValidationMessages = {
      * @param inlineClassification - The inline classification name (from 'as')
      * @param blockClassification - The block classification name (from 'classification:')
      */
-    BOUNDED_CONTEXT_CLASSIFICATION_CONFLICT: (bcName: string, inlineClassification?: string, blockClassification?: string) =>
-        `Classification specified both inline${inlineClassification ? ` ('as ${inlineClassification}')` : ''} and in block${blockClassification ? ` ('classification: ${blockClassification}')` : ''}. Inline value takes precedence.`,
+    BOUNDED_CONTEXT_CLASSIFICATION_CONFLICT: (bcName: string, inlineClassification?: string, blockClassification?: string) => {
+        const inlinePart = inlineClassification ? ` ('as ${inlineClassification}')` : '';
+        const blockPart = blockClassification ? ` ('classification: ${blockClassification}')` : '';
+        return `Classification specified both inline${inlinePart} and in block${blockPart}. Inline value takes precedence.`;
+    },
     
     /**
      * Warning when team is specified both inline and in a block.
@@ -139,8 +149,11 @@ export const ValidationMessages = {
      * @param inlineTeam - The inline team name (from 'by')
      * @param blockTeam - The block team name (from 'team:')
      */
-    BOUNDED_CONTEXT_TEAM_CONFLICT: (bcName: string, inlineTeam?: string, blockTeam?: string) =>
-        `Team specified both inline${inlineTeam ? ` ('by ${inlineTeam}')` : ''} and in block${blockTeam ? ` ('team: ${blockTeam}')` : ''}. Inline value takes precedence.`,
+    BOUNDED_CONTEXT_TEAM_CONFLICT: (bcName: string, inlineTeam?: string, blockTeam?: string) => {
+        const inlinePart = inlineTeam ? ` ('by ${inlineTeam}')` : '';
+        const blockPart = blockTeam ? ` ('team: ${blockTeam}')` : '';
+        return `Team specified both inline${inlinePart} and in block${blockPart}. Inline value takes precedence.`;
+    },
     
     /**
      * Error message when an element is defined multiple times.
@@ -262,6 +275,14 @@ export const ValidationMessages = {
         `Local path dependency '${alias}' escapes workspace boundary.\n` +
         `Hint: Local dependencies must be within the workspace. Consider moving the dependency or using a git-based source.`,
 
+    /**
+     * Error when import path cannot be resolved to a file.
+     * @param uri - The import URI that couldn't be resolved
+     */
+    IMPORT_UNRESOLVED: (uri: string) =>
+        `Cannot resolve import '${uri}'.\n` +
+        `Hint: Check that the file exists and the path is correct.`,
+
     // ========================================================================
     // Context Map & Domain Map Validation
     // ========================================================================
@@ -283,6 +304,14 @@ export const ValidationMessages = {
         `Context Map '${name}' contains ${count} contexts but no documented relationships.\n` +
         `Hint: Add relationships to show how contexts integrate (e.g., '[OHS] A -> [CF] B').`,
 
+    /**
+     * Warning when a context map contains duplicate relationships.
+     * @param leftContext - Name of the left context
+     * @param rightContext - Name of the right context
+     */
+    CONTEXT_MAP_DUPLICATE_RELATIONSHIP: (leftContext: string, rightContext: string) =>
+        `Duplicate relationship between '${leftContext}' and '${rightContext}' in context map.`,
+
     /**
      * Warning when domain map contains no domains.
      * @param name - The domain map name
@@ -291,6 +320,18 @@ export const ValidationMessages = {
         `Domain Map '${name}' contains no domains.\n` +
         `Hint: Use 'contains DomainA, DomainB' to specify which domains are in the map.`,
 
+    // ========================================================================
+    // Reference Resolution Validation
+    // ========================================================================
+
+    /**
+     * Error when a reference cannot be resolved (for MultiReferences).
+     * @param type - The type being referenced (e.g., 'BoundedContext')
+     * @param name - The unresolved name
+     */
+    UNRESOLVED_REFERENCE: (type: string, name: string) =>
+        `Could not resolve reference to ${type} named '${name}'.`,
+
     // ========================================================================
     // Metadata Validation
     // ========================================================================