@domainlang/language 0.5.2 → 0.6.0

package/src/lsp/hover/domain-lang-keywords.ts

@@ -1,50 +1,136 @@
 /**
  * Keyword explanations for DomainLang hover documentation.
  * 
- * This dictionary provides fallback hover content for keywords that don't have
- * JSDoc comments in the grammar file, or for providing richer DDD pattern explanations.
+ * This dictionary provides concise hover content for all DomainLang keywords,
+ * DDD patterns, and special symbols. Uses exact casing from grammar.
  * 
- * Basic keyword documentation (domain, boundedcontext, etc.) is now in the grammar file
- * as JSDoc comments. This dictionary focuses on DDD integration patterns and advanced concepts.
- * 
- * @see src/language/domain-lang.langium for basic keyword JSDoc
- * @see ddd-pattern-explanations.ts for role patterns and relationship types
+ * @see https://domainlang.net/reference/language for full documentation
  */
+
+// Documentation links
+const DOMAIN_LINK = '\n\n[Read more](https://domainlang.net/guide/domains)';
+const BC_LINK = '\n\n[Read more](https://domainlang.net/guide/bounded-contexts)';
+const TEAM_LINK = '\n\n[Read more](https://domainlang.net/guide/teams-classifications)';
+const MAP_LINK = '\n\n[Read more](https://domainlang.net/guide/context-maps)';
+const REL_LINK = '\n\n[Read more](https://domainlang.net/guide/context-maps#relationships)';
+const IMPORT_LINK = '\n\n[Read more](https://domainlang.net/guide/imports)';
+const NS_LINK = '\n\n[Read more](https://domainlang.net/guide/namespaces)';
+const TERM_LINK = '\n\n[Read more](https://domainlang.net/reference/language#terminology)';
+const DECISION_LINK = '\n\n[Read more](https://domainlang.net/reference/language#decisions-policies-rules)';
+const METADATA_LINK = '\n\n[Read more](https://domainlang.net/reference/language#metadata)';
+const SYNTAX_LINK = '\n\n[Read more](https://domainlang.net/reference/language)';
+
 export const keywordExplanations: Record<string, string> = {
-    // Advanced syntax keywords
-    implements: "**implements** - Declares that a Bounded Context or type implements a Domain or interface.",
-    as: "**as** - Used for aliasing or renaming imports or types.",
-    from: "**from** - Specifies the source module or file for an import statement.",
-    type: "**type** - Declares a new type or alias in the model.",
-    map: "**map** - Defines a mapping or transformation between elements.",
-    this: "**this** - Refers to the current context or object.",
-    
-    // DDD Classifiers
-    entity: "**Entity** - Domain object with distinct identity that runs through time.",
-    valueobject: "**Value Object** - Immutable object that describes a characteristic.",
-    aggregate: "**Aggregate** - Cluster of domain objects with a root and boundary.",
-    service: "**Service** - Stateless domain operation.",
-    event: "**Event** - Significant domain occurrence or state change.",
-    businessrule: "**Business Rule** - Rule that constrains business behavior.",
-    
+    // ========================================================================
+    // Primary Constructs
+    // ========================================================================
+    domain: `**Domain** - A sphere of knowledge or activity. Can be nested to show subdomain hierarchy.${DOMAIN_LINK}`,
+    dom: `**Domain** - A sphere of knowledge or activity. Can be nested to show subdomain hierarchy.${DOMAIN_LINK}`,
+    boundedcontext: `**BoundedContext** - A boundary where a domain model is defined. Central DDD pattern for managing complexity.${BC_LINK}`,
+    bc: `**BoundedContext** - A boundary where a domain model is defined. Central DDD pattern for managing complexity.${BC_LINK}`,
+    team: `**Team** - A group responsible for one or more bounded contexts.${TEAM_LINK}`,
+    classification: `**Classification** - Reusable label for categorizing elements (e.g., Core, Supporting, Generic).${TEAM_LINK}`,
+    metadata: `**Metadata** - Defines a key that can be used in metadata blocks.${METADATA_LINK}`,
+    meta: `**Metadata** - Defines a key that can be used in metadata blocks.${METADATA_LINK}`,
+
+    // ========================================================================
+    // Maps
+    // ========================================================================
+    contextmap: `**ContextMap** - Shows relationships between bounded contexts.${MAP_LINK}`,
+    cmap: `**ContextMap** - Shows relationships between bounded contexts.${MAP_LINK}`,
+    domainmap: `**DomainMap** - Visualizes domains and their subdomain structure.${MAP_LINK}`,
+    dmap: `**DomainMap** - Visualizes domains and their subdomain structure.${MAP_LINK}`,
+    contains: `**contains** - Specifies which elements are part of a map.${MAP_LINK}`,
+
+    // ========================================================================
+    // Bounded Context & Domain Properties
+    // ========================================================================
+    for: `**for** - Associates a bounded context with its parent domain.${BC_LINK}`,
+    as: `**as** - Assigns a classification to an element.${BC_LINK}`,
+    by: `**by** - Assigns a team responsible for an element.${BC_LINK}`,
+    in: `**in** - Specifies parent domain for subdomain nesting.${DOMAIN_LINK}`,
+    description: `**description** - Human-readable explanation of the element's purpose.${SYNTAX_LINK}`,
+    vision: `**vision** - Strategic vision statement for a domain.${DOMAIN_LINK}`,
+    type: `**type** - Assigns a classification type to a domain or relationship.${DOMAIN_LINK}`,
+    businessmodel: `**businessModel** - Revenue or engagement model for a context.${BC_LINK}`,
+    evolution: `**evolution** - Maturity stage (Genesis, Custom, Product, Commodity).${BC_LINK}`,
+    archetype: `**archetype** - Behavioral role (Gateway, Execution, etc.).${BC_LINK}`,
+    relationships: `**relationships** - Block defining integration patterns with other contexts.${REL_LINK}`,
+    integrations: `**integrations** - Block defining integration patterns with other contexts.${REL_LINK}`,
+
+    // ========================================================================
+    // Terminology & Glossary
+    // ========================================================================
+    terminology: `**terminology** - Block defining domain-specific terms and definitions.${TERM_LINK}`,
+    glossary: `**glossary** - Block defining domain-specific terms and definitions.${TERM_LINK}`,
+    term: `**Term** - Defines a domain term with its meaning.${TERM_LINK}`,
+    aka: `**aka** - Alternative names (also known as) for a term.${TERM_LINK}`,
+    synonyms: `**synonyms** - Alternative names (also known as) for a term.${TERM_LINK}`,
+    examples: `**examples** - Example usage of a term.${TERM_LINK}`,
+    meaning: `**meaning** - The definition or explanation of a term.${TERM_LINK}`,
+
+    // ========================================================================
+    // Decisions, Policies & Rules
+    // ========================================================================
+    decisions: `**decisions** - Block containing architectural decisions or business rules.${DECISION_LINK}`,
+    rules: `**rules** - Block containing architectural decisions or business rules.${DECISION_LINK}`,
+    decision: `**Decision** - An architectural or domain decision.${DECISION_LINK}`,
+    policy: `**Policy** - A business policy or organizational rule.${DECISION_LINK}`,
+    rule: `**Rule** - A business rule or constraint (also BusinessRule).${DECISION_LINK}`,
+
+    // ========================================================================
+    // Import System
+    // ========================================================================
+    import: `**Import** - Imports definitions from an external model or file.${IMPORT_LINK}`,
+
+    // ========================================================================
+    // Namespaces
+    // ========================================================================
+    namespace: `**Namespace** - Groups elements under a qualified name.${NS_LINK}`,
+    ns: `**Namespace** - Groups elements under a qualified name.${NS_LINK}`,
+
+    // ========================================================================
+    // Assignment Operators
+    // ========================================================================
+    ':': `**:** - Assignment operator (property: value).${SYNTAX_LINK}`,
+    is: `**is** - Assignment operator (property is value).${SYNTAX_LINK}`,
+    '=': `**=** - Assignment operator (property = value).${SYNTAX_LINK}`,
+
+    // ========================================================================
+    // Context Reference
+    // ========================================================================
+    this: `**this** - References the current bounded context in relationships.${REL_LINK}`,
+
+    // ========================================================================
     // DDD Integration Patterns
-    acl: "**ACL (Anti-Corruption Layer)** - Translation layer protecting downstream context from upstream changes.",
-    ohs: "**OHS (Open Host Service)** - Well-defined protocol providing access to a subsystem.",
-    pl: "**PL (Published Language)** - Documented shared language for context communication.",
-    cf: "**CF (Conformist)** - Downstream adopts upstream model without translation.",
-    bbom: "**BBoM (Big Ball of Mud)** - System with tangled architecture and no clear boundaries.",
-    sk: "**SK (Shared Kernel)** - Shared domain model subset requiring coordination.",
-    p: "**P (Partnership)** - Teams collaborate closely with shared success/failure.",
-    
-    // DDD Relationship Types
-    separateways: "**Separate Ways** - No connection between contexts, each solves problems independently.",
-    partnership: "**Partnership** - Teams share risks and rewards with close collaboration.",
-    sharedkernel: "**Shared Kernel** - Shared domain model subset requiring coordination.",
-    customersupplier: "**Customer-Supplier** - Upstream prioritizes downstream needs.",
-    upstreamdownstream: "**Upstream-Downstream** - Upstream changes affect downstream.",
-    
-    // Relationship arrows
-    '<->': "**Bidirectional** - Two contexts connected in both directions.",
-    '->': "**Upstream → Downstream** - Left depends on right.",
-    '<-': "**Downstream ← Upstream** - Right depends on left.",
-}; 
+    // ========================================================================
+    acl: `**ACL** - Anti-Corruption Layer. Protects from external models by translating between domains.${REL_LINK}`,
+    anticorruptionlayer: `**AntiCorruptionLayer** - Protects from external models by translating between domains.${REL_LINK}`,
+    ohs: `**OHS** - Open Host Service. Provides a well-documented API for integration.${REL_LINK}`,
+    openhostservice: `**OpenHostService** - Provides a well-documented API for integration.${REL_LINK}`,
+    pl: `**PL** - Published Language. Documented language for inter-context communication.${REL_LINK}`,
+    publishedlanguage: `**PublishedLanguage** - Documented language for inter-context communication.${REL_LINK}`,
+    cf: `**CF** - Conformist. Adopts upstream model without translation.${REL_LINK}`,
+    conformist: `**Conformist** - Adopts upstream model without translation.${REL_LINK}`,
+    p: `**P** - Partnership. Two teams with mutual dependency and shared goals.${REL_LINK}`,
+    partnership: `**Partnership** - Two teams with mutual dependency and shared goals.${REL_LINK}`,
+    sk: `**SK** - Shared Kernel. Shared code/data requiring careful coordination.${REL_LINK}`,
+    sharedkernel: `**SharedKernel** - Shared code/data requiring careful coordination.${REL_LINK}`,
+    bbom: `**BBoM** - Big Ball of Mud. Legacy area without clear boundaries.${REL_LINK}`,
+    bigballofmud: `**BigBallOfMud** - Legacy area without clear boundaries.${REL_LINK}`,
+
+    // ========================================================================
+    // Relationship Types
+    // ========================================================================
+    customersupplier: `**CustomerSupplier** - Downstream depends on upstream with influence over priorities.${REL_LINK}`,
+    upstreamdownstream: `**UpstreamDownstream** - One context depends on another's model.${REL_LINK}`,
+    separateways: `**SeparateWays** - Contexts with no integration, solving problems independently.${REL_LINK}`,
+
+    // ========================================================================
+    // Relationship Arrows
+    // ========================================================================
+    '->': `**->** - Unidirectional dependency (upstream to downstream).${REL_LINK}`,
+    '<->': `**<->** - Bidirectional dependency (mutual).${REL_LINK}`,
+    '<-': `**<-** - Reverse unidirectional dependency (downstream to upstream).${REL_LINK}`,
+    '><': `**><** - Separate Ways (no integration).${REL_LINK}`,
+};

package/src/lsp/manifest-diagnostics.ts

@@ -14,7 +14,7 @@
 
 import type { Connection } from 'vscode-languageserver';
 import { Diagnostic, DiagnosticSeverity, Position, Range } from 'vscode-languageserver-types';
-import YAML, { type Document as YAMLDocument, type YAMLMap, type Pair, isMap, isPair, isScalar } from 'yaml';
+import YAML, { type Document as YAMLDocument, type Pair, isMap, isPair, isScalar } from 'yaml';
 import { ManifestValidator, type ManifestDiagnostic, type ManifestSeverity } from '../validation/manifest.js';
 import type { ModelManifest } from '../services/types.js';
 
@@ -45,16 +45,32 @@ export class ManifestDiagnosticsService {
         content: string,
         options?: { requirePublishable?: boolean }
     ): Promise<void> {
-        if (!this.connection) {
-            return; // No connection, skip diagnostics
-        }
+        try {
+            if (!this.connection) {
+                return; // No connection, skip diagnostics
+            }
 
-        const diagnostics = this.validate(content, options);
-        
-        await this.connection.sendDiagnostics({
-            uri: manifestUri,
-            diagnostics
-        });
+            const diagnostics = this.validate(content, options);
+            
+            await this.connection.sendDiagnostics({
+                uri: manifestUri,
+                diagnostics
+            });
+        } catch (error) {
+            console.error('Error in validateAndSendDiagnostics:', error);
+            // Send minimal error diagnostic instead of crashing
+            if (this.connection) {
+                await this.connection.sendDiagnostics({
+                    uri: manifestUri,
+                    diagnostics: [{
+                        severity: DiagnosticSeverity.Error,
+                        range: Range.create(Position.create(0, 0), Position.create(0, 1)),
+                        message: 'Internal error validating manifest file',
+                        source: 'domainlang'
+                    }]
+                });
+            }
+        }
     }
 
     /**
@@ -68,42 +84,53 @@ export class ManifestDiagnosticsService {
         content: string,
         options?: { requirePublishable?: boolean }
     ): Diagnostic[] {
-        // Parse YAML to get both the manifest object and source map
-        let yamlDoc: YAMLDocument.Parsed;
-        let manifest: ModelManifest;
-        
         try {
-            yamlDoc = YAML.parseDocument(content);
+            // Parse YAML to get both the manifest object and source map
+            let yamlDoc: YAMLDocument.Parsed;
+            let manifest: ModelManifest;
             
-            // Check for YAML parse errors (they're in the errors array, not thrown)
-            if (yamlDoc.errors && yamlDoc.errors.length > 0) {
-                return yamlDoc.errors.map(err => ({
+            try {
+                yamlDoc = YAML.parseDocument(content);
+                
+                // Check for YAML parse errors (they're in the errors array, not thrown)
+                if (yamlDoc.errors && yamlDoc.errors.length > 0) {
+                    return yamlDoc.errors.map(err => ({
+                        severity: DiagnosticSeverity.Error,
+                        range: this.yamlErrorToRange(err, content),
+                        message: `YAML parse error: ${err.message}`,
+                        source: 'domainlang'
+                    }));
+                }
+                
+                manifest = (yamlDoc.toJSON() ?? {}) as ModelManifest;
+            } catch (error) {
+                // Fallback for unexpected errors
+                const message = error instanceof Error ? error.message : 'Invalid YAML syntax';
+                return [{
                     severity: DiagnosticSeverity.Error,
-                    range: this.yamlErrorToRange(err, content),
-                    message: `YAML parse error: ${err.message}`,
+                    range: Range.create(Position.create(0, 0), Position.create(0, 1)),
+                    message: `YAML parse error: ${message}`,
                     source: 'domainlang'
-                }));
+                }];
             }
+
+            // Run manifest validation
+            const result = this.validator.validate(manifest, options);
             
-            manifest = (yamlDoc.toJSON() ?? {}) as ModelManifest;
+            // Convert to LSP diagnostics with source locations
+            return result.diagnostics.map(diag => 
+                this.toVSCodeDiagnostic(diag, yamlDoc)
+            );
         } catch (error) {
-            // Fallback for unexpected errors
-            const message = error instanceof Error ? error.message : 'Invalid YAML syntax';
+            console.error('Error in validate:', error);
+            // Return minimal error diagnostic
             return [{
                 severity: DiagnosticSeverity.Error,
                 range: Range.create(Position.create(0, 0), Position.create(0, 1)),
-                message: `YAML parse error: ${message}`,
+                message: 'Internal error during validation',
                 source: 'domainlang'
             }];
         }
-
-        // Run manifest validation
-        const result = this.validator.validate(manifest, options);
-        
-        // Convert to LSP diagnostics with source locations
-        return result.diagnostics.map(diag => 
-            this.toVSCodeDiagnostic(diag, yamlDoc)
-        );
     }
 
     /**
@@ -130,14 +157,19 @@ export class ManifestDiagnosticsService {
      * Call this when the file is closed or deleted.
      */
     async clearDiagnostics(manifestUri: string): Promise<void> {
-        if (!this.connection) {
-            return;
-        }
+        try {
+            if (!this.connection) {
+                return;
+            }
 
-        await this.connection.sendDiagnostics({
-            uri: manifestUri,
-            diagnostics: []
-        });
+            await this.connection.sendDiagnostics({
+                uri: manifestUri,
+                diagnostics: []
+            });
+        } catch (error) {
+            console.error('Error in clearDiagnostics:', error);
+            // Ignore - don't crash on cleanup
+        }
     }
 
     /**
@@ -147,20 +179,32 @@ export class ManifestDiagnosticsService {
         diag: ManifestDiagnostic,
         yamlDoc: YAMLDocument.Parsed
     ): Diagnostic {
-        const range = this.findRangeForPath(diag.path, yamlDoc);
-        
-        let message = diag.message;
-        if (diag.hint) {
-            message += `\nHint: ${diag.hint}`;
-        }
+        try {
+            const range = this.findRangeForPath(diag.path, yamlDoc);
+            
+            let message = diag.message;
+            if (diag.hint) {
+                message += `\nHint: ${diag.hint}`;
+            }
 
-        return {
-            severity: this.toVSCodeSeverity(diag.severity),
-            range,
-            message,
-            source: 'domainlang',
-            code: diag.code
-        };
+            return {
+                severity: this.toVSCodeSeverity(diag.severity),
+                range,
+                message,
+                source: 'domainlang',
+                code: diag.code
+            };
+        } catch (error) {
+            console.error('Error converting diagnostic:', error);
+            // Return minimal diagnostic at file start
+            return {
+                severity: DiagnosticSeverity.Error,
+                range: Range.create(Position.create(0, 0), Position.create(0, 1)),
+                message: diag.message,
+                source: 'domainlang',
+                code: diag.code
+            };
+        }
     }
 
     /**
@@ -198,8 +242,7 @@ export class ManifestDiagnosticsService {
                 return fallback;
             }
             
-            const mapNode = currentNode as YAMLMap;
-            const item = mapNode.items.find((pair): pair is Pair => 
+            const item = currentNode.items.find((pair): pair is Pair => 
                 isPair(pair) && isScalar(pair.key) && String(pair.key.value) === part
             );
 
@@ -208,7 +251,7 @@ export class ManifestDiagnosticsService {
             }
 
             // If this is the last part, return the range of the key
-            if (part === parts[parts.length - 1]) {
+            if (part === parts.at(-1)) {
                 const keyNode = item.key;
                 if (isScalar(keyNode) && keyNode.range) {
                     const [start, end] = keyNode.range;
@@ -269,9 +312,7 @@ let manifestDiagnosticsService: ManifestDiagnosticsService | undefined;
  * Gets or creates the manifest diagnostics service singleton.
  */
 export function getManifestDiagnosticsService(): ManifestDiagnosticsService {
-    if (!manifestDiagnosticsService) {
-        manifestDiagnosticsService = new ManifestDiagnosticsService();
-    }
+    manifestDiagnosticsService ??= new ManifestDiagnosticsService();
     return manifestDiagnosticsService;
 }
 

package/src/main.ts

@@ -1,8 +1,9 @@
 import { startLanguageServer } from 'langium/lsp';
 import { NodeFileSystem } from 'langium/node';
-import { createConnection, ProposedFeatures } from 'vscode-languageserver/node.js';
+import { createConnection, ProposedFeatures, FileChangeType } from 'vscode-languageserver/node.js';
 import { createDomainLangServices } from './domain-lang-module.js';
 import { ensureImportGraphFromEntryFile } from './utils/import-utils.js';
+import { DomainLangIndexManager } from './lsp/domain-lang-index-manager.js';
 import { URI } from 'langium';
 
 // Create a connection to the client
@@ -11,29 +12,138 @@ const connection = createConnection(ProposedFeatures.all);
 // Inject the shared services and language-specific services
 const { shared, DomainLang } = createDomainLangServices({ connection, ...NodeFileSystem });
 
-// Initialize workspace on connection
-connection.onInitialize(async (params) => {
-    const workspaceRoot = params.rootUri ? URI.parse(params.rootUri).fsPath : undefined;
+// Initialize workspace manager when language server initializes
+// Uses Langium's LanguageServer.onInitialize hook (not raw connection handler)
+// This integrates properly with Langium's initialization flow
+shared.lsp.LanguageServer.onInitialize((params) => {
+    // Use workspaceFolders (preferred) over deprecated rootUri
+    const folders = params.workspaceFolders;
+    const workspaceRoot = folders?.[0]?.uri
+        ? URI.parse(folders[0].uri).fsPath
+        : undefined;
     
     if (workspaceRoot) {
-        try {
-            // Initialize workspace manager
-            const workspaceManager = DomainLang.imports.WorkspaceManager;
-            await workspaceManager.initialize(workspaceRoot);
-            console.warn(`DomainLang workspace initialized: ${workspaceRoot}`);
-        } catch (error) {
+        // Initialize workspace manager synchronously (just sets root path)
+        // Heavy work happens in initializeWorkspace() called by Langium later
+        const workspaceManager = DomainLang.imports.WorkspaceManager;
+        workspaceManager.initialize(workspaceRoot).catch(error => {
             const message = error instanceof Error ? error.message : String(error);
             console.warn(`Failed to initialize workspace: ${message}`);
             // Continue without workspace - local imports will still work
+        });
+        console.warn(`DomainLang workspace root: ${workspaceRoot}`);
+    }
+});
+
+// Handle file changes for model.yaml and model.lock (PRS-010)
+// Uses Langium's built-in file watcher which already watches **/* in workspace
+// This invalidates caches when config files change externally
+shared.lsp.DocumentUpdateHandler?.onWatchedFilesChange(async (params) => {
+    try {
+        await handleConfigFileChanges(params, DomainLang.imports.WorkspaceManager, shared);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Error handling file change notification: ${message}`);
+        // Continue - don't crash the server
+    }
+});
+
+/**
+ * Handles changes to model.yaml and model.lock files.
+ * Invalidates caches and rebuilds workspace as needed.
+ * Uses incremental updates: only rebuilds if dependencies actually changed.
+ */
+async function handleConfigFileChanges(
+    params: { changes: Array<{ uri: string; type: number }> },
+    workspaceManager: typeof DomainLang.imports.WorkspaceManager,
+    sharedServices: typeof shared
+): Promise<void> {
+    let manifestChanged = false;
+    let lockFileChanged = false;
+
+    for (const change of params.changes) {
+        const uri = URI.parse(change.uri);
+        const fileName = uri.path.split('/').pop() ?? '';
+
+        if (fileName === 'model.yaml') {
+            console.warn(`model.yaml changed: ${change.uri}`);
+            workspaceManager.invalidateManifestCache();
+            DomainLang.imports.ImportResolver.clearCache();
+            // Clear IndexManager import dependencies - resolved paths may have changed
+            const indexManager = sharedServices.workspace.IndexManager as DomainLangIndexManager;
+            indexManager.clearImportDependencies();
+            manifestChanged = true;
+        } else if (fileName === 'model.lock') {
+            await handleLockFileChange(change, workspaceManager);
+            DomainLang.imports.ImportResolver.clearCache();
+            lockFileChanged = true;
         }
     }
+
+    // Only rebuild if dependencies changed, not just any manifest change
+    if (manifestChanged || lockFileChanged) {
+        await rebuildWorkspace(sharedServices, workspaceManager, manifestChanged);
+    }
+}
+
+/**
+ * Handles lock file creation, change, or deletion.
+ */
+async function handleLockFileChange(
+    change: { uri: string; type: number },
+    workspaceManager: typeof DomainLang.imports.WorkspaceManager
+): Promise<void> {
+    console.warn(`model.lock changed: ${change.uri}`);
     
-    return {
-        capabilities: {
-            // Language server capabilities are configured by Langium
+    if (change.type === FileChangeType.Changed || change.type === FileChangeType.Created) {
+        await workspaceManager.refreshLockFile();
+    } else if (change.type === FileChangeType.Deleted) {
+        workspaceManager.invalidateLockCache();
+    }
+}
+
+/**
+ * Rebuilds the workspace after config file changes.
+ * Uses incremental strategy: only full rebuild if dependencies changed.
+ * 
+ * @param sharedServices - Shared Langium services
+ * @param workspaceManager - Workspace manager for manifest access
+ * @param manifestChanged - Whether model.yaml changed (vs just model.lock)
+ */
+async function rebuildWorkspace(
+    sharedServices: typeof shared,
+    workspaceManager: typeof DomainLang.imports.WorkspaceManager,
+    manifestChanged: boolean
+): Promise<void> {
+    try {
+        // If only lock file changed, caches are already invalidated - no rebuild needed
+        // Lock file changes mean resolved versions changed, but import resolver cache is cleared
+        // Documents will re-resolve imports on next access
+        if (!manifestChanged) {
+            console.warn('Lock file changed - caches invalidated, no rebuild needed');
+            return;
         }
-    };
-});
+
+        // For manifest changes, check if dependencies section actually changed
+        // If only metadata changed (name, version, etc.), no rebuild needed
+        const manifest = await workspaceManager.getManifest();
+        const hasDependencies = manifest?.dependencies && Object.keys(manifest.dependencies).length > 0;
+        
+        if (!hasDependencies) {
+            console.warn('Manifest changed but has no dependencies - skipping rebuild');
+            return;
+        }
+
+        // Dependencies exist and manifest changed - do full rebuild
+        const documents = sharedServices.workspace.LangiumDocuments.all.toArray();
+        const uris = documents.map(doc => doc.uri);
+        await sharedServices.workspace.DocumentBuilder.update([], uris);
+        console.warn(`Workspace rebuilt: ${documents.length} documents revalidated`);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Failed to rebuild workspace: ${message}`);
+    }
+}
 
 // Optionally start from a single entry file and follow imports.
 // Configure via env DOMAINLANG_ENTRY (absolute or workspace-relative path)
@@ -63,7 +173,8 @@ if (entryFile) {
     };
 
     // Initial load from entry file, then start the server
-    reloadFromEntry().finally(() => startLanguageServer(shared));
+    await reloadFromEntry();
+    startLanguageServer(shared);
 
     // Any change within the loaded graph should trigger a reload from the entry
     shared.workspace.TextDocuments.onDidChangeContent(async (event) => {