@domainlang/language 0.7.0 → 0.9.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

@@ -88,6 +88,7 @@ function categorizeChanges(
         } else if (fileName === 'model.lock') {
             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) {
@@ -290,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

@@ -16,6 +16,7 @@
  * - Fluent query chains with lazy iteration
  * - O(1) indexed lookups by FQN/name
  * - Resolution rules (which block wins for 0..1 properties)
+ * - File validation (Node.js only, via `validateFile()`)
  * 
  * **Entry points for different deployment targets:**
  * 
@@ -23,27 +24,24 @@
  * |--------|-------------|--------------|-------|
  * | VS Code Extension | `fromDocument()` | ✅ | Zero-copy LSP integration |
  * | Web Editor | `fromDocument()`, `loadModelFromText()` | ✅ | Browser-compatible |
- * | CLI (Node.js) | `loadModel()` from `sdk/loader-node` | ❌ | File system access |
+ * | CLI (Node.js) | `loadModel()`, `validateFile()` | ❌ | File system access |
  * | Hosted LSP | `fromDocument()`, `fromServices()` | ✅ | Server-side only |
  * | Testing | `loadModelFromText()` | ✅ | In-memory parsing |
  * 
  * ## Browser vs Node.js
  * 
- * This module (`sdk/index`) is **browser-safe** and exports only:
- * - `loadModelFromText()` - uses EmptyFileSystem
- * - `fromModel()`, `fromDocument()`, `fromServices()` - zero-copy wrappers
+ * Most of this module is **browser-safe**, but Node.js-specific functions are exported as well:
+ * - `loadModel()` - requires Node.js file system (uses NodeFileSystem)
+ * - `validateFile()` - requires Node.js file system (uses NodeFileSystem)
  * 
- * For file-based loading in Node.js CLI tools:
- * ```typescript
- * import { loadModel } from 'domain-lang-language/sdk/loader-node';
- * ```
+ * These will fail at runtime in browser environments.
  * 
  * @packageDocumentation
  * 
  * @example
  * ```typescript
- * // Node.js CLI: Load from file (requires sdk/loader-node)
- * import { loadModel } from 'domain-lang-language/sdk/loader-node';
+ * // Node.js CLI: Load from file
+ * import { loadModel } from '@domainlang/language/sdk';
  * 
  * const { query } = await loadModel('./domains.dlang', {
  *   workspaceDir: process.cwd()
@@ -60,6 +58,24 @@
  * 
  * @example
  * ```typescript
+ * // Node.js CLI: Validate a model (requires sdk/loader-node)
+ * import { validateFile } from '@domainlang/language/sdk';
+ * 
+ * const result = await validateFile('./domains.dlang');
+ * 
+ * if (!result.valid) {
+ *   for (const error of result.errors) {
+ *     console.error(`${error.file}:${error.line}: ${error.message}`);
+ *   }
+ *   process.exit(1);
+ * }
+ * 
+ * console.log(`✓ Validated ${result.fileCount} files`);
+ * console.log(`  ${result.domainCount} domains, ${result.bcCount} bounded contexts`);
+ * ```
+ * 
+ * @example
+ * ```typescript
  * // Browser/Testing: Load from text (browser-safe)
  * import { loadModelFromText } from '@domainlang/language/sdk';
  * 
@@ -89,7 +105,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
@@ -124,3 +141,8 @@ export type {
     BcQueryBuilder,
     RelationshipView,
 } from './types.js';
+
+// Node.js-specific exports (will fail in browser environments)
+export { loadModel } from './loader-node.js';
+export { validateFile, validateWorkspace } from './validator.js';
+export type { ValidationResult, ValidationDiagnostic, ValidationOptions, WorkspaceValidationResult } from './validator.js';

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
@@ -144,3 +145,7 @@ export async function loadModel(
         query: fromModel(model),
     };
 }
+
+// Re-export validation utilities
+export { validateFile } from './validator.js';
+export type { ValidationResult, ValidationDiagnostic, ValidationOptions } from './validator.js';

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);
 }

package/src/sdk/query.ts

@@ -137,9 +137,7 @@ class QueryImpl implements Query {
      * Lazily builds and caches indexes on first access.
      */
     private getIndexes(): ModelIndexes {
-        if (!this.indexes) {
-            this.indexes = buildIndexes(this.model);
-        }
+        this.indexes ??= buildIndexes(this.model);
         return this.indexes;
     }
 
@@ -202,7 +200,12 @@ class QueryImpl implements Query {
 
     /** @internal Generator for relationship iteration */
     private *iterateRelationships(): Generator<RelationshipView> {
-        // Collect relationships defined on bounded contexts
+        yield* this.collectBoundedContextRelationships();
+        yield* this.collectContextMapRelationships();
+    }
+
+    /** @internal Collects relationships from bounded contexts */
+    private *collectBoundedContextRelationships(): Generator<RelationshipView> {
         for (const node of AstUtils.streamAllContents(this.model)) {
             if (isBoundedContext(node)) {
                 for (const rel of node.relationships) {
@@ -213,8 +216,10 @@ class QueryImpl implements Query {
                 }
             }
         }
+    }
 
-        // Collect from ContextMap.relationships
+    /** @internal Collects relationships from context maps */
+    private *collectContextMapRelationships(): Generator<RelationshipView> {
         for (const node of AstUtils.streamAllContents(this.model)) {
             if (isContextMap(node)) {
                 for (const rel of node.relationships) {
@@ -442,10 +447,9 @@ class QueryBuilderImpl<T> implements QueryBuilder<T> {
     }
 
     first(): T | undefined {
-        for (const item of this) {
-            return item;
-        }
-        return undefined;
+        const iterator = this[Symbol.iterator]();
+        const result = iterator.next();
+        return result.done ? undefined : result.value;
     }
 
     toArray(): T[] {
@@ -554,7 +558,7 @@ class BcQueryBuilderImpl extends QueryBuilderImpl<BoundedContext> implements BcQ
  * Escapes special regex characters in a string.
  */
 function escapeRegex(str: string): string {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return str.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
 }
 
 /**
@@ -780,7 +784,7 @@ function augmentModelInternal(model: Model): void {
         } else if (isContextMap(node)) {
             // Augment relationships in context maps (no containing BC)
             for (const rel of node.relationships) {
-                augmentRelationship(rel, undefined);
+                augmentRelationship(rel);
             }
         }
     }