@domainlang/language 0.1.20

package/src/sdk/indexes.ts

@@ -0,0 +1,155 @@
+/**
+ * Index building for O(1) lookups in the Model Query SDK.
+ * Builds maps for FQN, name, team, strategic classification, and metadata lookups.
+ * 
+ * Indexes are built once during model loading and enable fast queries.
+ */
+
+import type { AstNode } from 'langium';
+import { AstUtils } from 'langium';
+import type {
+    BoundedContext,
+    Classification,
+    ContextMap,
+    Domain,
+    DomainMap,
+    Metadata,
+    Model,
+    NamespaceDeclaration,
+    Team,
+} from '../generated/ast.js';
+import {
+    isBoundedContext,
+    isClassification,
+    isContextMap,
+    isDomain,
+    isDomainMap,
+    isMetadata,
+    isNamespaceDeclaration,
+    isTeam,
+} from '../generated/ast.js';
+import { QualifiedNameProvider } from '../lsp/domain-lang-naming.js';
+import type { ModelIndexes } from './types.js';
+import {
+    metadataAsMap,
+    effectiveClassification,
+    effectiveTeam,
+} from './resolution.js';
+
+/**
+ * Builds all indexes for a model.
+ * Called once during model loading.
+ * 
+ * @param model - Root model node
+ * @returns ModelIndexes containing all lookup maps
+ */
+export function buildIndexes(model: Model): ModelIndexes {
+    const byFqn = new Map<string, AstNode>();
+    const byName = new Map<string, AstNode[]>();
+    const byTeam = new Map<string, BoundedContext[]>();
+    const byClassification = new Map<string, BoundedContext[]>();
+    const byMetadataKey = new Map<string, BoundedContext[]>();
+
+    const fqnProvider = new QualifiedNameProvider();
+
+    // Stream all AST nodes and index them
+    for (const node of AstUtils.streamAllContents(model)) {
+        // Index named types only
+        if (!hasName(node)) {
+            continue;
+        }
+
+        const name = node.name;
+        const fqn = fqnProvider.getQualifiedName(node.$container, name);
+
+        // Index by FQN (unique)
+        byFqn.set(fqn, node);
+
+        // Index by simple name (may have duplicates)
+        const nameList = byName.get(name) ?? [];
+        nameList.push(node);
+        byName.set(name, nameList);
+
+        // BoundedContext-specific indexes
+        if (isBoundedContext(node)) {
+            indexBoundedContext(node, byTeam, byClassification, byMetadataKey);
+        }
+    }
+
+    return {
+        byFqn,
+        byName,
+        byTeam,
+        byClassification,
+        byMetadataKey,
+    };
+}
+
+/**
+ * Indexes a BoundedContext by team, strategic classification, and metadata.
+ * 
+ * @param bc - BoundedContext node
+ * @param byTeam - Team index map
+ * @param byClassification - Strategic classification index map
+ * @param byMetadataKey - Metadata key index map
+ */
+function indexBoundedContext(
+    bc: BoundedContext,
+    byTeam: Map<string, BoundedContext[]>,
+    byClassification: Map<string, BoundedContext[]>,
+    byMetadataKey: Map<string, BoundedContext[]>
+): void {
+    // Index by team
+    const team = effectiveTeam(bc);
+    if (team?.name) {
+        const teamList = byTeam.get(team.name) ?? [];
+        teamList.push(bc);
+        byTeam.set(team.name, teamList);
+    }
+
+    // Index by strategic classification
+    const classification = effectiveClassification(bc);
+    if (classification?.name) {
+        const classificationList = byClassification.get(classification.name) ?? [];
+        classificationList.push(bc);
+        byClassification.set(classification.name, classificationList);
+    }
+
+    // Index by metadata keys
+    const metadata = metadataAsMap(bc);
+    for (const key of metadata.keys()) {
+        const metaList = byMetadataKey.get(key) ?? [];
+        metaList.push(bc);
+        byMetadataKey.set(key, metaList);
+    }
+}
+
+/**
+ * Type guard for named AST nodes.
+ * Only these types are indexed by name.
+ */
+function hasName(node: AstNode): node is NamedNode {
+    return (
+        isDomain(node) ||
+        isBoundedContext(node) ||
+        isTeam(node) ||
+        isClassification(node) ||
+        isContextMap(node) ||
+        isDomainMap(node) ||
+        isNamespaceDeclaration(node) ||
+        isMetadata(node)
+    );
+}
+
+/**
+ * Union type of all named AST nodes.
+ */
+type NamedNode =
+    | Domain
+    | BoundedContext
+    | Team
+    | Classification
+    | ContextMap
+    | DomainMap
+    | NamespaceDeclaration
+    | Metadata;

package/src/sdk/loader-node.ts

@@ -0,0 +1,146 @@
+/**
+ * Node.js-specific loader for DomainLang models.
+ * 
+ * **WARNING: This module is NOT browser-compatible.**
+ * 
+ * For browser environments, use:
+ * - `fromDocument()` with documents from the LSP
+ * - `fromModel()` with pre-parsed models
+ * - `loadModelFromText()` for in-memory parsing
+ * 
+ * This loader creates **isolated Langium services** for standalone CLI usage.
+ * It does NOT integrate with an existing LSP workspace.
+ * 
+ * For full workspace management with cross-file imports:
+ * - Use the WorkspaceManager service
+ * - Or host the LSP server and use its services
+ * 
+ * @module sdk/loader-node
+ */
+
+import { DocumentState, URI } from 'langium';
+import { NodeFileSystem } from 'langium/node';
+import type { Model } from '../generated/ast.js';
+import { isModel } from '../generated/ast.js';
+import { createDomainLangServices } from '../domain-lang-module.js';
+import type { LoadOptions, QueryContext } from './types.js';
+import { fromModel, augmentModel } from './query.js';
+import { ensureImportGraphFromDocument } from '../utils/import-utils.js';
+
+/**
+ * Loads a DomainLang model from a file on disk.
+ * 
+ * **Node.js only** - uses file system APIs.
+ * 
+ * Supports multi-file models with imports: all imported files are
+ * automatically loaded and linked. Use `documents` in the result
+ * to see all loaded files.
+ * 
+ * @param entryFile - Path to the entry .dlang file
+ * @param options - Optional load configuration
+ * @returns QueryContext with model, documents, and query API
+ * @throws Error if file cannot be loaded or parsing fails
+ * 
+ * @example
+ * ```typescript
+ * import { loadModel } from '@domainlang/language/sdk/loader-node';
+ * 
+ * const { query, model, documents } = await loadModel('./domains.dlang', {
+ *   workspaceDir: process.cwd()
+ * });
+ * 
+ * // Query spans all imported files
+ * for (const bc of query.boundedContexts()) {
+ *   console.log(bc.name);
+ * }
+ * 
+ * console.log(`Loaded ${documents.length} files`);
+ * ```
+ */
+export async function loadModel(
+    entryFile: string,
+    options?: LoadOptions
+): Promise<QueryContext> {
+    // Resolve absolute path
+    const path = await import('path');
+    const absolutePath = path.isAbsolute(entryFile) 
+        ? entryFile 
+        : path.resolve(options?.workspaceDir ?? process.cwd(), entryFile);
+    
+    // Create or reuse services
+    const servicesObj = options?.services 
+        ? { shared: options.services.shared, DomainLang: options.services }
+        : createDomainLangServices(NodeFileSystem);
+    
+    const services = servicesObj.DomainLang;
+    const shared = servicesObj.shared;
+    
+    // Initialize workspace if directory provided
+    if (options?.workspaceDir) {
+        const workspaceManager = services.imports.WorkspaceManager;
+        await workspaceManager.initialize(options.workspaceDir);
+    }
+    
+    // Read file content and create document
+    const fs = await import('fs/promises');
+    const fileContent = await fs.readFile(absolutePath, 'utf-8');
+    const uri = URI.file(absolutePath);
+    
+    // Use proper Langium document creation
+    const document = shared.workspace.LangiumDocumentFactory.fromString<Model>(
+        fileContent, 
+        uri
+    );
+    
+    // Register document and build it
+    shared.workspace.LangiumDocuments.addDocument(document);
+    await shared.workspace.DocumentBuilder.build([document], { validation: false });
+    
+    // Traverse import graph to load all imported files
+    const importedUris = await ensureImportGraphFromDocument(
+        document, 
+        shared.workspace.LangiumDocuments
+    );
+    
+    // Build all imported documents with validation
+    const allDocuments = Array.from(shared.workspace.LangiumDocuments.all);
+    await shared.workspace.DocumentBuilder.build(allDocuments, { validation: true });
+    
+    // Wait for entry document to be fully processed
+    if (document.state < DocumentState.Validated) {
+        throw new Error(`Document not fully processed: ${absolutePath}`);
+    }
+    
+    // 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 in ${entryFile}:\n  ${errors}`);
+    }
+    
+    if (document.parseResult.parserErrors.length > 0) {
+        const errors = document.parseResult.parserErrors.map(e => e.message).join('\n  ');
+        throw new Error(`Parser errors in ${entryFile}:\n  ${errors}`);
+    }
+    
+    const model = document.parseResult.value;
+    if (!isModel(model)) {
+        throw new Error(`Document root is not a Model: ${entryFile}`);
+    }
+    
+    // Augment AST nodes with SDK properties for all loaded models
+    for (const doc of allDocuments) {
+        const docModel = doc.parseResult.value;
+        if (isModel(docModel)) {
+            augmentModel(docModel);
+        }
+    }
+    
+    // Collect all document URIs from the import graph
+    const documentUris: URI[] = Array.from(importedUris).map(uriStr => URI.parse(uriStr));
+    
+    return {
+        model,
+        documents: documentUris,
+        query: fromModel(model),
+    };
+}

package/src/sdk/loader.ts

@@ -0,0 +1,99 @@
+/**
+ * Browser-safe loader for in-memory model parsing.
+ * 
+ * This module provides `loadModelFromText()` which works in both
+ * browser and Node.js environments by using Langium's EmptyFileSystem.
+ * 
+ * For file-based loading in Node.js CLI tools, use:
+ * ```typescript
+ * import { loadModel } from '@domainlang/language/sdk/loader-node';
+ * ```
+ * 
+ * For LSP/validation code that already has a linked AST, use the sync entry points:
+ * - `fromDocument()` - from a LangiumDocument
+ * - `fromModel()` - from a Model AST node  
+ * - `fromServices()` - from DomainLangServices container
+ * 
+ * @module sdk/loader
+ */
+
+import { EmptyFileSystem, URI } from 'langium';
+import type { Model } from '../generated/ast.js';
+import { isModel } from '../generated/ast.js';
+import { createDomainLangServices } from '../domain-lang-module.js';
+import type { LoadOptions, QueryContext } from './types.js';
+import { augmentModel, fromModel } from './query.js';
+
+/**
+ * Loads a DomainLang model from a text string.
+ * 
+ * **Browser-safe** - uses in-memory file system (EmptyFileSystem).
+ * 
+ * Useful for:
+ * - Testing
+ * - REPL environments  
+ * - Web-based editors
+ * - Any environment without file system access
+ * 
+ * @param text - DomainLang source code
+ * @param options - Optional load configuration
+ * @returns QueryContext with model and query API
+ * @throws Error if parsing fails
+ * 
+ * @example
+ * ```typescript
+ * import { loadModelFromText } from '@domainlang/language/sdk';
+ * 
+ * const { query } = await loadModelFromText(`
+ *   Domain Sales { vision: "Handle sales" }
+ *   bc OrderContext for Sales
+ * `);
+ * 
+ * const sales = query.domain('Sales');
+ * console.log(sales?.resolvedVision);
+ * ```
+ */
+export async function loadModelFromText(
+    text: string,
+    options?: LoadOptions
+): Promise<QueryContext> {
+    // Create or reuse services (use EmptyFileSystem for in-memory parsing)
+    const servicesObj = options?.services
+        ? { shared: options.services.shared, DomainLang: options.services }
+        : createDomainLangServices(EmptyFileSystem);
+    
+    const shared = servicesObj.shared;
+    
+    // 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),
+    };
+}

package/src/sdk/patterns.ts

@@ -0,0 +1,147 @@
+/**
+ * Integration Patterns - Type-safe constants for DDD integration patterns.
+ * 
+ * Use these constants instead of magic strings when checking relationship patterns.
+ * 
+ * @example
+ * ```typescript
+ * import { Pattern } from '../sdk/patterns.js';
+ * 
+ * // Instead of: hasPattern('SK') or hasPattern('SharedKernel')
+ * // Use:
+ * if (relationship.hasPattern(Pattern.SharedKernel)) {
+ *     // ...
+ * }
+ * ```
+ */
+
+/**
+ * Integration pattern abbreviations as used in the grammar.
+ * These are the canonical abbreviations recognized by DomainLang.
+ */
+export const Pattern = {
+    // Upstream patterns (provider side)
+    /** Open Host Service - exposes a clean API for consumers */
+    OHS: 'OHS',
+    /** Published Language - shared data format/protocol */
+    PL: 'PL',
+    
+    // Downstream patterns (consumer side)
+    /** Conformist - accepts upstream model without translation */
+    CF: 'CF',
+    /** Anti-Corruption Layer - translates upstream model */
+    ACL: 'ACL',
+    
+    // Mutual patterns (both sides)
+    /** Shared Kernel - shared code/model ownership */
+    SK: 'SK',
+    /** Partnership - coordinated development */
+    P: 'P',
+    
+    // Relationship types
+    /** Customer/Supplier - negotiated contract */
+    CustomerSupplier: 'Customer/Supplier',
+    /** Separate Ways - no integration */
+    SeparateWays: 'Separate Ways',
+    /** Big Ball of Mud - legacy or unstructured */
+    BigBallOfMud: 'Big Ball of Mud',
+} as const;
+
+/**
+ * Full names for integration patterns.
+ * Used when patterns are spelled out in documentation blocks.
+ */
+export const PatternFullName = {
+    OHS: 'OpenHostService',
+    PL: 'PublishedLanguage',
+    CF: 'Conformist',
+    ACL: 'AntiCorruptionLayer',
+    SK: 'SharedKernel',
+    P: 'Partnership',
+} as const;
+
+/**
+ * Mapping from abbreviations to full names and vice versa.
+ */
+export const PatternAliases: Record<string, readonly string[]> = {
+    // Abbreviation -> [abbreviation, fullName]
+    OHS: ['OHS', 'OpenHostService'],
+    PL: ['PL', 'PublishedLanguage'],
+    CF: ['CF', 'Conformist'],
+    ACL: ['ACL', 'AntiCorruptionLayer'],
+    SK: ['SK', 'SharedKernel'],
+    P: ['P', 'Partnership'],
+    
+    // Full names map to same
+    OpenHostService: ['OHS', 'OpenHostService'],
+    PublishedLanguage: ['PL', 'PublishedLanguage'],
+    Conformist: ['CF', 'Conformist'],
+    AntiCorruptionLayer: ['ACL', 'AntiCorruptionLayer'],
+    SharedKernel: ['SK', 'SharedKernel'],
+    Partnership: ['P', 'Partnership'],
+};
+
+/**
+ * Type representing any valid integration pattern (abbreviation or full name).
+ */
+export type IntegrationPattern = 
+    | typeof Pattern[keyof typeof Pattern]
+    | typeof PatternFullName[keyof typeof PatternFullName];
+
+/**
+ * Checks if a pattern string matches any of the expected aliases.
+ * Handles both abbreviations and full names case-insensitively.
+ * 
+ * @param actual - Pattern string from the AST
+ * @param expected - Pattern to match (abbreviation or full name)
+ * @returns true if patterns match
+ */
+export function matchesPattern(actual: string, expected: string): boolean {
+    const normalizedActual = actual.trim();
+    const aliases = PatternAliases[expected];
+    
+    if (aliases) {
+        return aliases.some(alias => 
+            alias.toLowerCase() === normalizedActual.toLowerCase()
+        );
+    }
+    
+    // Fallback: direct comparison
+    return normalizedActual.toLowerCase() === expected.toLowerCase();
+}
+
+/**
+ * Patterns that are typically on the upstream (provider) side.
+ */
+export const UpstreamPatterns: readonly string[] = ['OHS', 'OpenHostService', 'PL', 'PublishedLanguage'];
+
+/**
+ * Patterns that are typically on the downstream (consumer) side.
+ */
+export const DownstreamPatterns: readonly string[] = ['CF', 'Conformist', 'ACL', 'AntiCorruptionLayer'];
+
+/**
+ * Patterns that require mutual/bidirectional relationships.
+ */
+export const MutualPatterns: readonly string[] = ['SK', 'SharedKernel', 'P', 'Partnership'];
+
+/**
+ * Checks if a pattern is typically an upstream pattern.
+ */
+export function isUpstreamPattern(pattern: string): boolean {
+    return UpstreamPatterns.some(p => matchesPattern(pattern, p));
+}
+
+/**
+ * Checks if a pattern is typically a downstream pattern.
+ */
+export function isDownstreamPattern(pattern: string): boolean {
+    return DownstreamPatterns.some(p => matchesPattern(pattern, p));
+}
+
+/**
+ * Checks if a pattern requires bidirectional relationships.
+ */
+export function isMutualPattern(pattern: string): boolean {
+    return MutualPatterns.some(p => matchesPattern(pattern, p));
+}