@domainlang/language 0.6.0 → 0.8.0

package/src/lsp/hover/hover-builders.ts

@@ -0,0 +1,208 @@
+/**
+ * Standalone hover content builder functions.
+ * 
+ * Extracted from DomainLangHoverProvider to reduce class complexity
+ * and enable independent testing of hover content generation.
+ * 
+ * Each builder takes typed AST nodes (not generic AstNode) and the helper
+ * functions needed for formatting, keeping them pure and testable.
+ * 
+ * @module lsp/hover/hover-builders
+ */
+
+import type {
+    BoundedContext,
+    Classification,
+    Domain,
+    Relationship,
+    Team,
+    Type,
+} from '../../generated/ast.js';
+import { effectiveClassification, effectiveTeam } from '../../sdk/resolution.js';
+
+// ============================================================================
+// Shared formatting utilities
+// ============================================================================
+
+/**
+ * Wraps text in a domain-lang fenced code block.
+ */
+export function codeBlock(text: string): string {
+    return `\`\`\`domain-lang\n${text}\n\`\`\``;
+}
+
+/**
+ * Formats hover output with a consistent header/body structure.
+ * 
+ * @param commentBlock - Documentation comment prefix (or empty)
+ * @param emoji - Emoji icon for the type
+ * @param typeName - Lowercase type name
+ * @param name - Element name (optional)
+ * @param fields - Body content fields
+ */
+export function formatHoverContent(
+    commentBlock: string,
+    emoji: string,
+    typeName: string,
+    name: string | undefined,
+    fields: string[]
+): string {
+    const separator = commentBlock ? `${commentBlock}\n\n---\n\n` : '';
+    const nameDisplay = name ? ` ${name}` : '';
+    const header = `${emoji} **\`(${typeName})\`${nameDisplay}**`;
+    const body = fields.length > 0 ? `\n\n${fields.join('\n\n')}` : '';
+    return `${separator}${header}${body}`;
+}
+
+/**
+ * Callback for creating reference links.
+ * Provided by the hover provider which has access to the qualified name provider.
+ */
+export type RefLinkFn = (ref: Type | undefined, label?: string) => string;
+
+// ============================================================================
+// Domain hover builder
+// ============================================================================
+
+/**
+ * Builds a signature string for a domain (e.g., "Domain Sales in Commerce").
+ */
+export function buildDomainSignature(domain: Domain): string {
+    const parts = ['Domain', domain.name];
+    if (domain.parent?.ref?.name) {
+        parts.push('in', domain.parent.ref.name);
+    }
+    return parts.join(' ');
+}
+
+/**
+ * Builds hover fields for a Domain node.
+ * 
+ * @param domain - The domain AST node
+ * @param refLink - Function to create reference links
+ * @returns Array of formatted field strings
+ */
+export function buildDomainFields(domain: Domain, refLink: RefLinkFn): string[] {
+    const description = domain.description ?? '';
+    const vision = domain.vision ?? '';
+    const typeRef = domain.type?.ref;
+
+    const signature = codeBlock(buildDomainSignature(domain));
+    const fields: string[] = [signature];
+
+    if (description) fields.push(description);
+    if (vision || typeRef || domain.parent) fields.push('---');
+    if (vision) fields.push(`**Vision:** ${vision}`);
+    if (typeRef) fields.push(`**Type:** ${refLink(typeRef)}`);
+    if (domain.parent?.ref) fields.push(`**Parent:** ${refLink(domain.parent.ref)}`);
+
+    return fields;
+}
+
+// ============================================================================
+// Bounded context hover builder
+// ============================================================================
+
+/**
+ * Builds a signature string for a bounded context
+ * (e.g., "boundedcontext OrderManagement for Sales as Core by SalesTeam").
+ */
+export function buildBcSignature(bc: BoundedContext): string {
+    const classification = effectiveClassification(bc);
+    const team = effectiveTeam(bc);
+
+    const parts = ['BoundedContext', bc.name];
+    if (bc.domain?.ref?.name) parts.push('for', bc.domain.ref.name);
+    if (classification?.name) parts.push('as', classification.name);
+    if (team?.name) parts.push('by', team.name);
+    return parts.join(' ');
+}
+
+/**
+ * Builds the properties section (domain, classification, team, businessModel, evolution).
+ */
+function buildBcPropertyFields(
+    bc: BoundedContext,
+    classification: Classification | undefined,
+    team: Team | undefined,
+    refLink: RefLinkFn
+): string[] {
+    const fields: string[] = [];
+    const domain = bc.domain?.ref;
+    const businessModel = bc.businessModel?.ref;
+    const evolution = bc.evolution?.ref;
+
+    if (domain || classification || team || businessModel || evolution) fields.push('---');
+    if (domain) fields.push(`📁 **Domain:** ${refLink(domain)}`);
+    if (classification) fields.push(`🔖 **Classification:** ${refLink(classification)}`);
+    if (team) fields.push(`👥 **Team:** ${refLink(team)}`);
+    if (businessModel) fields.push(`💼 **Business Model:** ${refLink(businessModel)}`);
+    if (evolution) fields.push(`🔄 **Evolution:** ${refLink(evolution)}`);
+
+    return fields;
+}
+
+/**
+ * Builds the relationships section for a bounded context hover.
+ */
+function buildBcRelationshipsSection(
+    relationships: readonly Relationship[],
+    formatRelationshipLine: (rel: Relationship) => string
+): string[] {
+    if (relationships.length === 0) return [];
+    const lines = relationships.map(formatRelationshipLine);
+    return [`**Relationships:**\n${lines.join('\n')}`];
+}
+
+/**
+ * Builds the terminology section for a bounded context hover.
+ */
+function buildBcTerminologySection(bc: BoundedContext): string[] {
+    const terminology = bc.terminology ?? [];
+    if (terminology.length === 0) return [];
+    const lines = terminology.map(t => `- \`${t.name}\`: ${t.meaning ?? ''}`);
+    return [`**Terminology:**\n${lines.join('\n')}`];
+}
+
+/**
+ * Builds the decisions section for a bounded context hover.
+ */
+function buildBcDecisionsSection(bc: BoundedContext): string[] {
+    const decisions = bc.decisions ?? [];
+    if (decisions.length === 0) return [];
+    const lines = decisions.map(d => `- \`${d.name}\`: ${d.value ?? ''}`);
+    return [`**Decisions:**\n${lines.join('\n')}`];
+}
+
+/**
+ * Builds hover fields for a BoundedContext node.
+ * 
+ * @param bc - The bounded context AST node
+ * @param refLink - Function to create reference links
+ * @param formatRelationshipLine - Function to format a relationship line
+ * @returns Array of formatted field strings
+ */
+export function buildBcFields(
+    bc: BoundedContext,
+    refLink: RefLinkFn,
+    formatRelationshipLine: (rel: Relationship) => string
+): string[] {
+    const description = bc.description ?? '';
+    const classification = effectiveClassification(bc);
+    const team = effectiveTeam(bc);
+
+    const signature = codeBlock(buildBcSignature(bc));
+    const fields: string[] = [signature];
+
+    if (description) fields.push(description);
+
+    const sections = [
+        ...buildBcPropertyFields(bc, classification, team, refLink),
+        ...buildBcRelationshipsSection(bc.relationships ?? [], formatRelationshipLine),
+        ...buildBcTerminologySection(bc),
+        ...buildBcDecisionsSection(bc),
+    ];
+    fields.push(...sections);
+
+    return fields;
+}

package/src/main.ts

@@ -40,7 +40,7 @@ shared.lsp.LanguageServer.onInitialize((params) => {
 // This invalidates caches when config files change externally
 shared.lsp.DocumentUpdateHandler?.onWatchedFilesChange(async (params) => {
     try {
-        await handleConfigFileChanges(params, DomainLang.imports.WorkspaceManager, shared);
+        await handleFileChanges(params, DomainLang.imports.WorkspaceManager, shared, DomainLang);
     } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         console.error(`Error handling file change notification: ${message}`);
@@ -48,41 +48,175 @@ shared.lsp.DocumentUpdateHandler?.onWatchedFilesChange(async (params) => {
     }
 });
 
+/** Categorized file changes */
+interface CategorizedChanges {
+    manifestChanged: boolean;
+    lockFileChanged: boolean;
+    changedDlangUris: Set<string>;
+    deletedDlangUris: Set<string>;
+    createdDlangUris: Set<string>;
+}
+
 /**
- * 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.
+ * Categorizes file changes by type.
  */
-async function handleConfigFileChanges(
+function categorizeChanges(
     params: { changes: Array<{ uri: string; type: number }> },
     workspaceManager: typeof DomainLang.imports.WorkspaceManager,
-    sharedServices: typeof shared
-): Promise<void> {
-    let manifestChanged = false;
-    let lockFileChanged = false;
+    langServices: typeof DomainLang,
+    indexManager: DomainLangIndexManager
+): CategorizedChanges {
+    const result: CategorizedChanges = {
+        manifestChanged: false,
+        lockFileChanged: false,
+        changedDlangUris: new Set(),
+        deletedDlangUris: new Set(),
+        createdDlangUris: new Set()
+    };
 
     for (const change of params.changes) {
         const uri = URI.parse(change.uri);
         const fileName = uri.path.split('/').pop() ?? '';
+        const uriString = change.uri;
 
         if (fileName === 'model.yaml') {
-            console.warn(`model.yaml changed: ${change.uri}`);
+            console.warn(`model.yaml changed: ${uriString}`);
             workspaceManager.invalidateManifestCache();
-            DomainLang.imports.ImportResolver.clearCache();
-            // Clear IndexManager import dependencies - resolved paths may have changed
-            const indexManager = sharedServices.workspace.IndexManager as DomainLangIndexManager;
+            langServices.imports.ImportResolver.clearCache();
             indexManager.clearImportDependencies();
-            manifestChanged = true;
+            result.manifestChanged = true;
         } else if (fileName === 'model.lock') {
-            await handleLockFileChange(change, workspaceManager);
-            DomainLang.imports.ImportResolver.clearCache();
-            lockFileChanged = true;
+            console.warn(`model.lock changed: ${uriString}`);
+            langServices.imports.ImportResolver.clearCache();
+            indexManager.clearImportDependencies();
+            result.lockFileChanged = true;
+        } else if (fileName.endsWith('.dlang')) {
+            if (change.type === FileChangeType.Deleted) {
+                result.deletedDlangUris.add(uriString);
+                console.warn(`DomainLang file deleted: ${uriString}`);
+            } else if (change.type === FileChangeType.Created) {
+                result.createdDlangUris.add(uriString);
+                console.warn(`DomainLang file created: ${uriString}`);
+            } else {
+                result.changedDlangUris.add(uriString);
+                console.warn(`DomainLang file changed: ${uriString}`);
+            }
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Rebuilds documents that depend on changed/deleted/created .dlang files.
+ */
+async function rebuildAffectedDocuments(
+    changes: CategorizedChanges,
+    indexManager: DomainLangIndexManager,
+    sharedServices: typeof shared,
+    langServices: typeof DomainLang
+): Promise<void> {
+    const hasChanges = changes.changedDlangUris.size > 0 || 
+                       changes.deletedDlangUris.size > 0 || 
+                       changes.createdDlangUris.size > 0;
+    if (!hasChanges) {
+        return;
+    }
+
+    // CRITICAL: Clear ImportResolver cache BEFORE rebuilding.
+    // The WorkspaceCache only clears AFTER linking, but resolution happens
+    // DURING linking. Without this, stale cached resolutions would be used.
+    langServices.imports.ImportResolver.clearCache();
+
+    const affectedUris = collectAffectedDocuments(changes, indexManager);
+
+    if (affectedUris.size === 0) {
+        return;
+    }
+
+    console.warn(`Rebuilding ${affectedUris.size} documents affected by file changes`);
+
+    const langiumDocuments = sharedServices.workspace.LangiumDocuments;
+    const affectedDocs: URI[] = [];
+
+    for (const uriString of affectedUris) {
+        const uri = URI.parse(uriString);
+        if (langiumDocuments.hasDocument(uri)) {
+            affectedDocs.push(uri);
+            indexManager.markForReprocessing(uriString);
+        }
+    }
+
+    const deletedUriObjects = [...changes.deletedDlangUris].map(u => URI.parse(u));
+    if (affectedDocs.length > 0 || deletedUriObjects.length > 0) {
+        await sharedServices.workspace.DocumentBuilder.update(affectedDocs, deletedUriObjects);
+    }
+}
+
+/**
+ * Collects all document URIs that should be rebuilt based on the changes.
+ * 
+ * Uses targeted matching to avoid expensive full rebuilds:
+ * - For edits: rebuild documents that import the changed file (by resolved URI)
+ * - For all changes: rebuild documents whose import specifiers match the path
+ * 
+ * The specifier matching handles renamed/moved/created files by comparing
+ * import specifiers against path segments (filename, parent/filename, etc.).
+ */
+function collectAffectedDocuments(
+    changes: CategorizedChanges,
+    indexManager: DomainLangIndexManager
+): Set<string> {
+    const allChangedUris = new Set([
+        ...changes.changedDlangUris, 
+        ...changes.deletedDlangUris,
+        ...changes.createdDlangUris
+    ]);
+    
+    // Get documents affected by resolved URI changes (edits to imported files)
+    const affectedByUri = indexManager.getAllAffectedDocuments(allChangedUris);
+    
+    // Get documents with import specifiers that match changed paths
+    // This catches:
+    // - File moves/renames: specifiers that previously resolved but now won't
+    // - File creations: specifiers that previously failed but might now resolve
+    // Uses fuzzy matching on path segments rather than rebuilding all imports
+    const affectedBySpecifier = indexManager.getDocumentsWithPotentiallyAffectedImports(allChangedUris);
+    
+    return new Set([...affectedByUri, ...affectedBySpecifier]);
+}
+
+/**
+ * Handles all file changes including .dlang files, model.yaml, and model.lock.
+ * 
+ * For .dlang files: rebuilds all documents that import the changed file.
+ * For config files: invalidates caches and rebuilds workspace as needed.
+ */
+async function handleFileChanges(
+    params: { changes: Array<{ uri: string; type: number }> },
+    workspaceManager: typeof DomainLang.imports.WorkspaceManager,
+    sharedServices: typeof shared,
+    langServices: typeof DomainLang
+): Promise<void> {
+    const indexManager = sharedServices.workspace.IndexManager as DomainLangIndexManager;
+
+    // Categorize and process changes
+    const changes = categorizeChanges(params, workspaceManager, langServices, indexManager);
+
+    // Handle lock file changes
+    if (changes.lockFileChanged) {
+        const lockChange = params.changes.find(c => c.uri.endsWith('model.lock'));
+        if (lockChange) {
+            await handleLockFileChange(lockChange, workspaceManager);
         }
     }
 
-    // Only rebuild if dependencies changed, not just any manifest change
-    if (manifestChanged || lockFileChanged) {
-        await rebuildWorkspace(sharedServices, workspaceManager, manifestChanged);
+    // Rebuild documents affected by .dlang file changes
+    await rebuildAffectedDocuments(changes, indexManager, sharedServices, langServices);
+
+    // Handle config file changes
+    if (changes.manifestChanged || changes.lockFileChanged) {
+        await rebuildWorkspace(sharedServices, workspaceManager, changes.manifestChanged);
     }
 }
 
@@ -93,8 +227,6 @@ async function handleLockFileChange(
     change: { uri: string; type: number },
     workspaceManager: typeof DomainLang.imports.WorkspaceManager
 ): Promise<void> {
-    console.warn(`model.lock changed: ${change.uri}`);
-    
     if (change.type === FileChangeType.Changed || change.type === FileChangeType.Created) {
         await workspaceManager.refreshLockFile();
     } else if (change.type === FileChangeType.Deleted) {
@@ -159,7 +291,8 @@ if (entryFile) {
         try {
             currentGraph = await ensureImportGraphFromEntryFile(
                 entryFile, 
-                shared.workspace.LangiumDocuments
+                shared.workspace.LangiumDocuments,
+                DomainLang.imports.ImportResolver
             );
             console.warn(`Successfully loaded import graph from ${entryFile}`);
         } catch (error) {

package/src/sdk/index.ts

@@ -89,7 +89,8 @@
  */
 
 // Browser-safe entry points
-export { loadModelFromText } from './loader.js';
+export { loadModelFromText, createModelLoader } from './loader.js';
+export type { ModelLoader } from './loader.js';
 export { fromModel, fromDocument, fromServices, augmentModel } from './query.js';
 
 // Note: loadModel() is NOT exported here - it requires Node.js filesystem

package/src/sdk/loader-node.ts

@@ -99,7 +99,8 @@ export async function loadModel(
     // Traverse import graph to load all imported files
     const importedUris = await ensureImportGraphFromDocument(
         document, 
-        shared.workspace.LangiumDocuments
+        shared.workspace.LangiumDocuments,
+        services.imports.ImportResolver
     );
     
     // Build all imported documents with validation

package/src/sdk/loader.ts

@@ -4,6 +4,14 @@
  * This module provides `loadModelFromText()` which works in both
  * browser and Node.js environments by using Langium's EmptyFileSystem.
  * 
+ * For repeated parsing (e.g., web playgrounds, REPLs), use `createModelLoader()`
+ * to reuse Langium services across multiple parse calls:
+ * ```typescript
+ * const loader = createModelLoader();
+ * const result1 = await loader.loadFromText('Domain A {}');
+ * const result2 = await loader.loadFromText('Domain B {}');
+ * ```
+ * 
  * For file-based loading in Node.js CLI tools, use:
  * ```typescript
  * import { loadModel } from '@domainlang/language/sdk/loader-node';
@@ -18,21 +26,134 @@
  */
 
 import { EmptyFileSystem, URI } from 'langium';
+import type { LangiumSharedServices } from 'langium/lsp';
 import type { Model } from '../generated/ast.js';
 import { isModel } from '../generated/ast.js';
 import { createDomainLangServices } from '../domain-lang-module.js';
+import type { DomainLangServices } from '../domain-lang-module.js';
 import type { LoadOptions, QueryContext } from './types.js';
 import { augmentModel, fromModel } from './query.js';
 
+/**
+ * A reusable model loader that maintains Langium services across multiple parse calls.
+ * 
+ * Use this when calling `loadFromText()` repeatedly (e.g., web playgrounds, REPLs,
+ * batch processing) to avoid the overhead of recreating Langium services each time.
+ */
+export interface ModelLoader {
+    /**
+     * Loads a DomainLang model from a text string, reusing internal services.
+     * 
+     * Each call creates a fresh document but shares the underlying parser,
+     * linker, and validator infrastructure.
+     * 
+     * @param text - DomainLang source code
+     * @returns QueryContext with model and query API
+     * @throws Error if parsing fails
+     */
+    loadFromText(text: string): Promise<QueryContext>;
+
+    /** The underlying DomainLang services (for advanced use). */
+    readonly services: DomainLangServices;
+}
+
+/** Internal counter for unique document URIs within a loader. */
+let documentCounter = 0;
+
+/**
+ * Parses text into a QueryContext using the provided services.
+ * Shared implementation for both `loadModelFromText` and `ModelLoader.loadFromText`.
+ */
+async function parseTextToContext(
+    text: string,
+    langServices: DomainLangServices,
+    shared: LangiumSharedServices
+): Promise<QueryContext> {
+    // Use unique URI per parse to avoid document conflicts
+    const uri = URI.parse(`memory:///model-${documentCounter++}.dlang`);
+    const document = shared.workspace.LangiumDocumentFactory.fromString<Model>(text, uri);
+
+    // Register and build document
+    shared.workspace.LangiumDocuments.addDocument(document);
+    try {
+        await shared.workspace.DocumentBuilder.build([document], { validation: true });
+
+        // Check for parsing errors
+        if (document.parseResult.lexerErrors.length > 0) {
+            const errors = document.parseResult.lexerErrors.map(e => e.message).join('\n  ');
+            throw new Error(`Lexer errors:\n  ${errors}`);
+        }
+
+        if (document.parseResult.parserErrors.length > 0) {
+            const errors = document.parseResult.parserErrors.map(e => e.message).join('\n  ');
+            throw new Error(`Parser errors:\n  ${errors}`);
+        }
+
+        const model = document.parseResult.value;
+        if (!isModel(model)) {
+            throw new Error(`Document root is not a Model`);
+        }
+
+        // Augment AST nodes with SDK properties
+        augmentModel(model);
+
+        return {
+            model,
+            documents: [document.uri],
+            query: fromModel(model),
+        };
+    } finally {
+        // Clean up the document to prevent memory leaks across repeated calls
+        shared.workspace.LangiumDocuments.deleteDocument(uri);
+    }
+}
+
+/**
+ * Creates a reusable model loader that shares Langium services across parse calls.
+ * 
+ * **Browser-safe** - uses in-memory file system (EmptyFileSystem).
+ * 
+ * For applications that parse multiple texts (web playgrounds, REPLs, batch tools),
+ * this avoids the overhead of creating new Langium services for each parse call.
+ * 
+ * @returns A ModelLoader instance that can be used repeatedly
+ * 
+ * @example
+ * ```typescript
+ * import { createModelLoader } from '@domainlang/language/sdk';
+ * 
+ * const loader = createModelLoader();
+ * 
+ * // Parse multiple texts efficiently - services are reused
+ * const result1 = await loader.loadFromText('Domain Sales { vision: "Sales" }');
+ * const result2 = await loader.loadFromText('Domain Billing { vision: "Billing" }');
+ * ```
+ */
+export function createModelLoader(): ModelLoader {
+    const servicesObj = createDomainLangServices(EmptyFileSystem);
+    const shared = servicesObj.shared;
+    const langServices = servicesObj.DomainLang;
+
+    return {
+        async loadFromText(text: string): Promise<QueryContext> {
+            return parseTextToContext(text, langServices, shared);
+        },
+        get services(): DomainLangServices {
+            return langServices;
+        }
+    };
+}
+
 /**
  * Loads a DomainLang model from a text string.
  * 
  * **Browser-safe** - uses in-memory file system (EmptyFileSystem).
  * 
+ * For repeated parsing, prefer {@link createModelLoader} to reuse services.
+ * 
  * Useful for:
  * - Testing
- * - REPL environments  
- * - Web-based editors
+ * - One-off parsing
  * - Any environment without file system access
  * 
  * @param text - DomainLang source code
@@ -63,37 +184,7 @@ export async function loadModelFromText(
         : createDomainLangServices(EmptyFileSystem);
     
     const shared = servicesObj.shared;
+    const langServices = servicesObj.DomainLang;
     
-    // Create document from text with a virtual URI
-    const uri = URI.parse('memory:///model.dlang');
-    const document = shared.workspace.LangiumDocumentFactory.fromString<Model>(text, uri);
-    
-    // Register and build document
-    shared.workspace.LangiumDocuments.addDocument(document);
-    await shared.workspace.DocumentBuilder.build([document], { validation: true });
-    
-    // Check for parsing errors
-    if (document.parseResult.lexerErrors.length > 0) {
-        const errors = document.parseResult.lexerErrors.map(e => e.message).join('\n  ');
-        throw new Error(`Lexer errors:\n  ${errors}`);
-    }
-    
-    if (document.parseResult.parserErrors.length > 0) {
-        const errors = document.parseResult.parserErrors.map(e => e.message).join('\n  ');
-        throw new Error(`Parser errors:\n  ${errors}`);
-    }
-    
-    const model = document.parseResult.value;
-    if (!isModel(model)) {
-        throw new Error(`Document root is not a Model`);
-    }
-    
-    // Augment AST nodes with SDK properties
-    augmentModel(model);
-    
-    return {
-        model,
-        documents: [document.uri],
-        query: fromModel(model),
-    };
+    return parseTextToContext(text, langServices, shared);
 }