@domainlang/language 0.8.0 → 0.10.0

package/src/sdk/serializers.ts

@@ -0,0 +1,213 @@
+/**
+ * AST Serialization Utilities
+ * 
+ * Converts Langium AST nodes to plain JSON objects suitable for:
+ * - LSP custom requests (JSON-RPC transport)
+ * - MCP tool responses (stdio JSON)
+ * - CLI output (JSON/YAML formats)
+ * 
+ * ## Strategy
+ * 
+ * Rather than maintaining a parallel DTO type hierarchy (DomainDto, BoundedContextDto, etc.),
+ * we use a **generic serializer** that:
+ * - Strips Langium internal properties ($container, $cstNode, $document)
+ * - Preserves $type for discriminated output
+ * - Resolves Reference<T> to referenced name strings
+ * - Resolves MultiReference<T> to arrays of names
+ * - Recursively serializes child AstNodes
+ * - Adds FQN for named elements via Query
+ * 
+ * For types with SDK-augmented properties (computed values not on raw AST),
+ * use augmentation functions that enrich the generic output.
+ * 
+ * @packageDocumentation
+ */
+
+import type { AstNode, Reference } from 'langium';
+import { isAstNode, isReference } from 'langium';
+import type { Query, RelationshipView } from './types.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Canonical entity types that can be queried.
+ * Moved from CLI to SDK for sharing with LSP tools.
+ */
+export type QueryEntityType = 
+    | 'domains'
+    | 'bcs'
+    | 'teams'
+    | 'classifications'
+    | 'relationships'
+    | 'context-maps'
+    | 'domain-maps';
+
+/**
+ * All accepted entity type names, including aliases.
+ * Aliases are normalized to canonical types before query execution.
+ */
+export type QueryEntityInput = QueryEntityType
+    | 'bounded-contexts' | 'contexts'
+    | 'rels'
+    | 'cmaps'
+    | 'dmaps';
+
+/**
+ * Query filter options.
+ * Moved from CLI to SDK for sharing with LSP tools.
+ */
+export interface QueryFilters {
+    /** Filter by name (string or regex) */
+    name?: string;
+    /** Filter by fully qualified name */
+    fqn?: string;
+    /** Filter BCs by domain */
+    domain?: string;
+    /** Filter BCs by team */
+    team?: string;
+    /** Filter BCs by classification */
+    classification?: string;
+    /** Filter BCs by metadata key=value */
+    metadata?: string;
+}
+
+/**
+ * Map of entity type aliases to their canonical form.
+ */
+export const ENTITY_ALIASES: Record<string, QueryEntityType> = {
+    'bounded-contexts': 'bcs',
+    'contexts': 'bcs',
+    'rels': 'relationships',
+    'cmaps': 'context-maps',
+    'dmaps': 'domain-maps',
+};
+
+/**
+ * Normalize an entity type input (which may be an alias) to its canonical form.
+ */
+export function normalizeEntityType(input: string): QueryEntityType {
+    if (input in ENTITY_ALIASES) {
+        return ENTITY_ALIASES[input];
+    }
+    return input as QueryEntityType;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Generic AST Serialization
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Serialize any Langium AST node to a plain JSON object.
+ * 
+ * - Strips $-prefixed internal properties ($container, $cstNode, $document)
+ * - Preserves $type for discriminated output
+ * - Resolves Reference<T> to the referenced name (string)
+ * - Resolves MultiReference<T> to an array of names
+ * - Recursively serializes child AstNode properties
+ * - Serializes arrays of AstNodes/values
+ * - Adds FQN for named elements
+ * 
+ * @param node - AST node to serialize
+ * @param query - Query instance for FQN resolution
+ * @returns Plain JSON object
+ */
+export function serializeNode(node: AstNode, query: Query): Record<string, unknown> {
+    const result: Record<string, unknown> = { $type: node.$type };
+    
+    for (const [key, value] of Object.entries(node)) {
+        // Skip Langium internals (but preserve $type)
+        if (key.startsWith('$') && key !== '$type') {
+            continue;
+        }
+        
+        if (isReference(value)) {
+            // Reference<T> → name string
+            const ref = value.ref;
+            result[key] = (ref && 'name' in ref) ? (ref as { name?: string }).name : value.$refText;
+        } else if (isAstNode(value)) {
+            // Nested AstNode → recurse
+            result[key] = serializeNode(value, query);
+        } else if (Array.isArray(value)) {
+            // Array → map each item
+            result[key] = value.map(item => {
+                if (isReference(item)) {
+                    const itemRef = item.ref;
+                    return (itemRef && 'name' in itemRef) ? (itemRef as { name?: string }).name : item.$refText;
+                } else if (isAstNode(item)) {
+                    return serializeNode(item, query);
+                } else {
+                    return item; // primitive
+                }
+            });
+        } else {
+            // Primitives pass through
+            result[key] = value;
+        }
+    }
+    
+    // Always include FQN for named elements
+    if ('name' in node && typeof (node as { name?: unknown }).name === 'string') {
+        result.fqn = query.fqn(node);
+    }
+    
+    return result;
+}
+
+/**
+ * Augment a serialized RelationshipView with computed properties.
+ * 
+ * RelationshipView is already a clean DTO (not an AstNode), but we format it
+ * consistently with other serialized types.
+ * 
+ * @param view - RelationshipView from query.relationships()
+ * @returns Serialized relationship object
+ */
+export function serializeRelationship(view: RelationshipView): Record<string, unknown> {
+    // RelationshipView.left and .right are BoundedContext (which have name property)
+    const leftName = view.left.name;
+    const rightName = view.right.name;
+    return {
+        $type: 'Relationship',
+        name: `${leftName} ${view.arrow} ${rightName}`,
+        left: leftName,
+        right: rightName,
+        arrow: view.arrow,
+        leftPatterns: view.leftPatterns,
+        rightPatterns: view.rightPatterns,
+        inferredType: view.inferredType,
+    };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helper: Resolve Reference
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve a Reference<T> to its name string.
+ * Returns undefined if reference is unresolved.
+ * 
+ * @param ref - Reference to resolve
+ * @returns Referenced name or undefined
+ */
+export function resolveName<T extends AstNode & { name?: string }>(ref: Reference<T> | undefined): string | undefined {
+    if (!ref) return undefined;
+    return ref.ref?.name ?? ref.$refText;
+}
+
+/**
+ * Resolve a MultiReference (array of items with refs) to an array of names.
+ * Filters out unresolved references.
+ * 
+ * @param multiRef - Array of items with ref property
+ * @returns Array of resolved names
+ */
+export function resolveMultiReference<T extends { ref?: Reference<AstNode & { name?: string }> }>(
+    multiRef: T[] | undefined
+): string[] {
+    if (!multiRef) return [];
+    return multiRef
+        .map(item => item.ref?.ref?.name)
+        .filter((name): name is string => name !== undefined);
+}

package/src/sdk/validator.ts

@@ -0,0 +1,358 @@
+/**
+ * Model validation utilities for Node.js environments.
+ * 
+ * **WARNING: This module is NOT browser-compatible.**
+ * 
+ * Provides validation capabilities that leverage the LSP infrastructure
+ * for workspace initialization, import resolution, and document building.
+ * 
+ * @module sdk/validator
+ */
+
+import { NodeFileSystem } from 'langium/node';
+import { URI } from 'langium';
+import { createDomainLangServices } from '../domain-lang-module.js';
+import { ensureImportGraphFromDocument } from '../utils/import-utils.js';
+import { isModel } from '../generated/ast.js';
+import { dirname, resolve, join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+/**
+ * Validation diagnostic with file context.
+ */
+export interface ValidationDiagnostic {
+    /** Diagnostic severity (1=error, 2=warning, 3=info, 4=hint) */
+    severity: number;
+    /** Diagnostic message */
+    message: string;
+    /** File path where diagnostic occurred */
+    file: string;
+    /** Line number (1-based) */
+    line: number;
+    /** Column number (1-based) */
+    column: number;
+}
+
+/**
+ * Result of model validation.
+ */
+export interface ValidationResult {
+    /** Whether the model is valid (no errors) */
+    valid: boolean;
+    /** Number of files validated */
+    fileCount: number;
+    /** Number of domains in the model */
+    domainCount: number;
+    /** Number of bounded contexts in the model */
+    bcCount: number;
+    /** Validation errors */
+    errors: ValidationDiagnostic[];
+    /** Validation warnings */
+    warnings: ValidationDiagnostic[];
+}
+
+/**
+ * Options for validation.
+ */
+export interface ValidationOptions {
+    /** Workspace directory (defaults to file's directory) */
+    workspaceDir?: string;
+}
+
+/**
+ * Convert Langium diagnostic to ValidationDiagnostic.
+ */
+function toValidationDiagnostic(
+    diagnostic: { severity?: number; message: string; range: { start: { line: number; character: number } } },
+    file: string
+): ValidationDiagnostic {
+    return {
+        severity: diagnostic.severity ?? 1,
+        message: diagnostic.message,
+        file,
+        line: diagnostic.range.start.line + 1,
+        column: diagnostic.range.start.character + 1,
+    };
+}
+
+/**
+ * Validates a DomainLang model file and all its imports.
+ * 
+ * Uses the LSP infrastructure to:
+ * - Initialize the workspace
+ * - Resolve and load imports
+ * - Build and validate all documents
+ * 
+ * @param filePath - Path to the entry .dlang file
+ * @param options - Validation options
+ * @returns Validation result with errors, warnings, and model statistics
+ * @throws Error if file doesn't exist or has invalid extension
+ * 
+ * @example
+ * ```typescript
+ * import { validateFile } from '@domainlang/language/sdk';
+ * 
+ * const result = await validateFile('./index.dlang');
+ * 
+ * if (!result.valid) {
+ *   for (const err of result.errors) {
+ *     console.error(`${err.file}:${err.line}:${err.column}: ${err.message}`);
+ *   }
+ *   process.exit(1);
+ * }
+ * 
+ * console.log(`✓ Validated ${result.fileCount} files`);
+ * console.log(`  ${result.domainCount} domains, ${result.bcCount} bounded contexts`);
+ * ```
+ */
+export async function validateFile(
+    filePath: string,
+    options: ValidationOptions = {}
+): Promise<ValidationResult> {
+    // Resolve absolute path
+    const absolutePath = resolve(filePath);
+    
+    // Check file exists
+    if (!existsSync(absolutePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+
+    // Create services with workspace support
+    const servicesObj = createDomainLangServices(NodeFileSystem);
+    const shared = servicesObj.shared;
+    const services = servicesObj.DomainLang;
+    
+    // Check file extension
+    const extensions = services.LanguageMetaData.fileExtensions;
+    if (!extensions.some(ext => absolutePath.endsWith(ext))) {
+        throw new Error(`Invalid file extension. Expected: ${extensions.join(', ')}`);
+    }
+
+    // Initialize workspace with the specified directory or file's directory
+    const workspaceDir = options.workspaceDir ?? dirname(absolutePath);
+    const workspaceManager = services.imports.WorkspaceManager;
+    await workspaceManager.initialize(workspaceDir);
+
+    // Load and parse the document
+    const uri = URI.file(absolutePath);
+    const document = await shared.workspace.LangiumDocuments.getOrCreateDocument(uri);
+    
+    // Build document initially without validation to load imports
+    await shared.workspace.DocumentBuilder.build([document], { validation: false });
+    
+    // Load all imported documents via the import graph
+    const importResolver = services.imports.ImportResolver;
+    await ensureImportGraphFromDocument(
+        document,
+        shared.workspace.LangiumDocuments,
+        importResolver
+    );
+    
+    // Build all documents with validation enabled
+    const allDocuments = Array.from(shared.workspace.LangiumDocuments.all);
+    await shared.workspace.DocumentBuilder.build(allDocuments, { validation: true });
+
+    // Collect diagnostics from the entry document
+    const diagnostics = document.diagnostics ?? [];
+    const errors: ValidationDiagnostic[] = [];
+    const warnings: ValidationDiagnostic[] = [];
+
+    for (const diagnostic of diagnostics) {
+        const validationDiag = toValidationDiagnostic(diagnostic, absolutePath);
+        if (diagnostic.severity === 1) {
+            errors.push(validationDiag);
+        } else if (diagnostic.severity === 2) {
+            warnings.push(validationDiag);
+        }
+    }
+
+    // Count model elements across all documents
+    let domainCount = 0;
+    let bcCount = 0;
+
+    for (const doc of allDocuments) {
+        const model = doc.parseResult?.value;
+        if (isModel(model)) {
+            for (const element of model.children ?? []) {
+                if (element.$type === 'Domain') {
+                    domainCount++;
+                } else if (element.$type === 'BoundedContext') {
+                    bcCount++;
+                }
+            }
+        }
+    }
+
+    return {
+        valid: errors.length === 0,
+        fileCount: allDocuments.length,
+        domainCount,
+        bcCount,
+        errors,
+        warnings,
+    };
+}
+
+/**
+ * Workspace validation result with diagnostics grouped by file.
+ */
+export interface WorkspaceValidationResult {
+    /** Whether the workspace is valid (no errors in any file) */
+    valid: boolean;
+    /** Number of files validated */
+    fileCount: number;
+    /** Number of domains across all files */
+    domainCount: number;
+    /** Number of bounded contexts across all files */
+    bcCount: number;
+    /** Validation errors grouped by file path */
+    errors: ValidationDiagnostic[];
+    /** Validation warnings grouped by file path */
+    warnings: ValidationDiagnostic[];
+    /** Total number of diagnostics across all files */
+    totalDiagnostics: number;
+}
+
+/**
+ * Validates an entire DomainLang workspace.
+ * 
+ * Uses the LSP infrastructure to:
+ * - Initialize the workspace from a directory containing model.yaml
+ * - Load the entry file (from manifest or default index.dlang)
+ * - Resolve and load all imports
+ * - Build and validate all documents in the workspace
+ * - Collect diagnostics from ALL documents (like VS Code Problems pane)
+ * 
+ * @param workspaceDir - Path to the workspace directory (containing model.yaml)
+ * @returns Validation result with diagnostics from all files
+ * @throws Error if workspace directory doesn't exist or cannot be loaded
+ * 
+ * @example
+ * ```typescript
+ * import { validateWorkspace } from '@domainlang/language/sdk';
+ * 
+ * const result = await validateWorkspace('./my-workspace');
+ * 
+ * if (!result.valid) {
+ *   console.error(`Found ${result.errors.length} errors in ${result.fileCount} files`);
+ *   
+ *   for (const err of result.errors) {
+ *     console.error(`${err.file}:${err.line}:${err.column}: ${err.message}`);
+ *   }
+ *   process.exit(1);
+ * }
+ * 
+ * console.log(`✓ Validated ${result.fileCount} files`);
+ * console.log(`  ${result.domainCount} domains, ${result.bcCount} bounded contexts`);
+ * console.log(`  0 errors, ${result.warnings.length} warnings`);
+ * ```
+ */
+export async function validateWorkspace(
+    workspaceDir: string
+): Promise<WorkspaceValidationResult> {
+    // Resolve absolute path
+    const absolutePath = resolve(workspaceDir);
+    
+    // Check directory exists
+    if (!existsSync(absolutePath)) {
+        throw new Error(`Workspace directory not found: ${workspaceDir}`);
+    }
+
+    // Create services with workspace support
+    const servicesObj = createDomainLangServices(NodeFileSystem);
+    const shared = servicesObj.shared;
+    const services = servicesObj.DomainLang;
+    const workspaceManager = services.imports.WorkspaceManager;
+
+    try {
+        // Initialize workspace - this will find and load model.yaml
+        await workspaceManager.initialize(absolutePath);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to initialize workspace at ${workspaceDir}: ${message}`);
+    }
+
+    // Get the manifest to find the entry file
+    const manifest = await workspaceManager.getManifest();
+    let entryFile = 'index.dlang';
+    
+    if (manifest?.model?.entry) {
+        entryFile = manifest.model.entry;
+    }
+
+    const entryPath = join(absolutePath, entryFile);
+    
+    // Check if entry file exists
+    if (!existsSync(entryPath)) {
+        throw new Error(
+            `Entry file not found: ${entryFile}\n` +
+            `Expected at: ${entryPath}\n` +
+            (manifest ? `Specified in manifest` : `Using default entry file`)
+        );
+    }
+
+    // Load and parse the entry document
+    const uri = URI.file(entryPath);
+    const document = await shared.workspace.LangiumDocuments.getOrCreateDocument(uri);
+    
+    // Build document initially without validation to load imports
+    await shared.workspace.DocumentBuilder.build([document], { validation: false });
+    
+    // Load all imported documents via the import graph
+    const importResolver = services.imports.ImportResolver;
+    await ensureImportGraphFromDocument(
+        document,
+        shared.workspace.LangiumDocuments,
+        importResolver
+    );
+    
+    // Build all documents with validation enabled
+    const allDocuments = Array.from(shared.workspace.LangiumDocuments.all);
+    await shared.workspace.DocumentBuilder.build(allDocuments, { validation: true });
+
+    // Collect diagnostics from ALL documents (not just entry)
+    const errors: ValidationDiagnostic[] = [];
+    const warnings: ValidationDiagnostic[] = [];
+
+    for (const doc of allDocuments) {
+        const diagnostics = doc.diagnostics ?? [];
+        const docPath = doc.uri.fsPath;
+        
+        for (const diagnostic of diagnostics) {
+            const validationDiag = toValidationDiagnostic(diagnostic, docPath);
+            
+            if (diagnostic.severity === 1) {
+                errors.push(validationDiag);
+            } else if (diagnostic.severity === 2) {
+                warnings.push(validationDiag);
+            }
+        }
+    }
+
+    // Count model elements across all documents
+    let domainCount = 0;
+    let bcCount = 0;
+
+    for (const doc of allDocuments) {
+        const model = doc.parseResult?.value;
+        if (isModel(model)) {
+            for (const element of model.children ?? []) {
+                if (element.$type === 'Domain') {
+                    domainCount++;
+                } else if (element.$type === 'BoundedContext') {
+                    bcCount++;
+                }
+            }
+        }
+    }
+
+    return {
+        valid: errors.length === 0,
+        fileCount: allDocuments.length,
+        domainCount,
+        bcCount,
+        errors,
+        warnings,
+        totalDiagnostics: errors.length + warnings.length,
+    };
+}