@domainlang/language 0.8.0 → 0.10.0

package/src/lsp/tool-handlers.ts

@@ -0,0 +1,443 @@
+/**
+ * LSP Custom Request Handlers for VS Code Language Model Tools (PRS-015)
+ * 
+ * These handlers respond to custom LSP requests from the VS Code extension
+ * and return serialized model data suitable for Language Model Tools.
+ * 
+ * Architecture:
+ * - Extension calls `client.sendRequest('domainlang/validate', params)`
+ * - LSP receives via `connection.onRequest('domainlang/validate', handler)`
+ * - Handler uses SDK `fromServices()` for zero-copy AST access
+ * - Handler returns plain JSON (no circular refs, no class instances)
+ * 
+ * @module lsp/tool-handlers
+ */
+
+import type { Connection } from 'vscode-languageserver';
+import type { LangiumDocument } from 'langium';
+import type { LangiumSharedServices } from 'langium/lsp';
+import { URI } from 'langium';
+import { fromDocument } from '../sdk/query.js';
+import type { Query } from '../sdk/types.js';
+import {
+    serializeNode,
+    serializeRelationship,
+    normalizeEntityType,
+} from '../sdk/serializers.js';
+import type { QueryEntityType, QueryFilters } from '../sdk/serializers.js';
+import type { Model } from '../generated/ast.js';
+import { generateExplanation } from './explain.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Request/Response Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Request parameters for domainlang/validate.
+ * No parameters needed - validates entire workspace.
+ */
+export interface ValidateParams {
+    /** Optional: filter by file URI */
+    file?: string;
+}
+
+/**
+ * Response from domainlang/validate.
+ */
+export interface ValidateResponse {
+    /** Total number of validation diagnostics */
+    count: number;
+    /** Validation diagnostics grouped by severity */
+    diagnostics: {
+        errors: DiagnosticInfo[];
+        warnings: DiagnosticInfo[];
+        info: DiagnosticInfo[];
+    };
+}
+
+/**
+ * Diagnostic information for validation response.
+ */
+export interface DiagnosticInfo {
+    /** File URI */
+    file: string;
+    /** Line number (1-indexed) */
+    line: number;
+    /** Column number (1-indexed) */
+    column: number;
+    /** Diagnostic message */
+    message: string;
+    /** Severity level */
+    severity: 'error' | 'warning' | 'info';
+    /** Optional diagnostic code */
+    code?: string | number;
+}
+
+/**
+ * Request parameters for domainlang/list.
+ */
+export interface ListParams {
+    /** Entity type to query */
+    type: string;
+    /** Optional filters */
+    filters?: QueryFilters;
+}
+
+/**
+ * Response from domainlang/list.
+ */
+export interface ListResponse {
+    /** Entity type queried */
+    entityType: QueryEntityType;
+    /** Number of results */
+    count: number;
+    /** Serialized results */
+    results: Record<string, unknown>[];
+}
+
+/**
+ * Request parameters for domainlang/get.
+ */
+export interface GetParams {
+    /** Fully qualified name of element to retrieve */
+    fqn?: string;
+    /** If true, return model summary instead of single element */
+    summary?: boolean;
+}
+
+/**
+ * Response from domainlang/get.
+ */
+export interface GetResponse {
+    /** Serialized element or model summary */
+    result: Record<string, unknown> | null;
+}
+
+/**
+ * Request parameters for domainlang/explain.
+ */
+export interface ExplainParams {
+    /** Fully qualified name of element to explain */
+    fqn: string;
+}
+
+/**
+ * Response from domainlang/explain.
+ */
+export interface ExplainResponse {
+    /** Rich markdown explanation */
+    explanation: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Handler Registration
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Registers all custom request handlers on the LSP connection.
+ * Call this from main.ts after creating the connection.
+ * 
+ * @param connection - LSP connection
+ * @param sharedServices - Langium shared services for workspace access
+ */
+export function registerToolHandlers(
+    connection: Connection,
+    sharedServices: LangiumSharedServices
+): void {
+    connection.onRequest('domainlang/validate', async (params: ValidateParams) => {
+        return handleValidate(params, sharedServices);
+    });
+
+    connection.onRequest('domainlang/list', async (params: ListParams) => {
+        return handleList(params, sharedServices);
+    });
+
+    connection.onRequest('domainlang/get', async (params: GetParams) => {
+        return handleGet(params, sharedServices);
+    });
+
+    connection.onRequest('domainlang/explain', async (params: ExplainParams) => {
+        return handleExplain(params, sharedServices);
+    });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Handler Implementations
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Handles domainlang/validate requests.
+ * Aggregates all validation diagnostics from the workspace.
+ */
+async function handleValidate(
+    params: ValidateParams,
+    sharedServices: LangiumSharedServices
+): Promise<ValidateResponse> {
+    try {
+        const langiumDocs = sharedServices.workspace.LangiumDocuments;
+        const documents = params.file
+            ? [langiumDocs.getDocument(URI.parse(params.file))]
+            : Array.from(langiumDocs.all);
+
+    const errors: DiagnosticInfo[] = [];
+    const warnings: DiagnosticInfo[] = [];
+    const info: DiagnosticInfo[] = [];
+
+    for (const doc of documents) {
+        if (!doc) continue;
+
+        const diagnostics = doc.diagnostics ?? [];
+        for (const diag of diagnostics) {
+            const diagInfo: DiagnosticInfo = {
+                file: doc.uri.toString(),
+                line: diag.range.start.line + 1, // 1-indexed
+                column: diag.range.start.character + 1, // 1-indexed
+                message: diag.message,
+                severity: severityToString(diag.severity ?? 1),
+                code: diag.code,
+            };
+
+            if (diag.severity === 1) {
+                errors.push(diagInfo);
+            } else if (diag.severity === 2) {
+                warnings.push(diagInfo);
+            } else {
+                info.push(diagInfo);
+            }
+        }
+    }
+
+    return {
+        count: errors.length + warnings.length + info.length,
+        diagnostics: { errors, warnings, info },
+    };
+    } catch (error) {
+        console.error('domainlang/validate handler error:', error);
+        return { count: 0, diagnostics: { errors: [], warnings: [], info: [] } };
+    }
+}
+
+/**
+ * Handles domainlang/list requests.
+ * Queries entities of a specific type and returns serialized results.
+ */
+async function handleList(
+    params: ListParams,
+    sharedServices: LangiumSharedServices
+): Promise<ListResponse> {
+    try {
+        const entityType = normalizeEntityType(params.type);
+    const filters = params.filters ?? {};
+
+    // Get all documents and merge results
+    const langiumDocs = sharedServices.workspace.LangiumDocuments;
+    const documents = Array.from(langiumDocs.all);
+
+    const allResults: Record<string, unknown>[] = [];
+    const seen = new Set<string>(); // Deduplicate by FQN
+
+    for (const doc of documents) {
+        const query = fromDocument(doc as LangiumDocument<Model>);
+        const results = executeListQuery(query, entityType, filters);
+
+        for (const result of results) {
+            const fqn = result.fqn as string | undefined;
+            if (fqn && seen.has(fqn)) continue;
+            if (fqn) seen.add(fqn);
+            allResults.push(result);
+        }
+    }
+
+    return {
+        entityType,
+        count: allResults.length,
+        results: allResults,
+    };
+    } catch (error) {
+        console.error('domainlang/list handler error:', error);
+        return { entityType: normalizeEntityType(params.type), count: 0, results: [] };
+    }
+}
+
+/**
+ * Handles domainlang/get requests.
+ * Retrieves a single element by FQN or returns a model summary.
+ */
+async function handleGet(
+    params: GetParams,
+    sharedServices: LangiumSharedServices
+): Promise<GetResponse> {
+    try {
+        if (params.summary) {
+        return { result: await getModelSummary(sharedServices) };
+    }
+
+    if (!params.fqn) {
+        return { result: null };
+    }
+
+    // Search all documents for the element
+    const langiumDocs = sharedServices.workspace.LangiumDocuments;
+    const documents = Array.from(langiumDocs.all);
+
+    for (const doc of documents) {
+        const query = fromDocument(doc as LangiumDocument<Model>);
+        const element = query.byFqn(params.fqn);
+        if (element) {
+            return { result: serializeNode(element, query) };
+        }
+    }
+
+    return { result: null };
+    } catch (error) {
+        console.error('domainlang/get handler error:', error);
+        return { result: null };
+    }
+}
+
+/**
+ * Handles domainlang/explain requests.
+ * Returns rich markdown explanation of a model element.
+ */
+async function handleExplain(
+    params: ExplainParams,
+    sharedServices: LangiumSharedServices
+): Promise<ExplainResponse> {
+    try {
+        const langiumDocs = sharedServices.workspace.LangiumDocuments;
+        const documents = Array.from(langiumDocs.all);
+
+        for (const doc of documents) {
+            const query = fromDocument(doc as LangiumDocument<Model>);
+            const element = query.byFqn(params.fqn);
+            if (element) {
+                const explanation = generateExplanation(element);
+                return { explanation };
+            }
+        }
+
+        return {
+            explanation: `Element not found: ${params.fqn}`,
+        };
+    } catch (error) {
+        console.error('domainlang/explain handler error:', error);
+        return { explanation: `Error explaining element: ${params.fqn}` };
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helper Functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Executes a list query for a specific entity type.
+ */
+function executeListQuery(
+    query: Query,
+    entityType: QueryEntityType,
+    filters: QueryFilters
+): Record<string, unknown>[] {
+    switch (entityType) {
+        case 'domains': {
+            let builder = query.domains();
+            if (filters.name) builder = builder.withName(filters.name);
+            if (filters.fqn) builder = builder.withFqn(filters.fqn);
+            return builder.toArray().map((d) => serializeNode(d, query));
+        }
+        case 'bcs': {
+            let builder = query.boundedContexts();
+            if (filters.domain) builder = builder.inDomain(filters.domain);
+            if (filters.team) builder = builder.withTeam(filters.team);
+            if (filters.classification)
+                builder = builder.withClassification(filters.classification);
+            if (filters.metadata) {
+                const [key, value] = filters.metadata.split('=');
+                builder = builder.withMetadata(key, value);
+            }
+            if (filters.name) builder = builder.withName(filters.name) as ReturnType<Query['boundedContexts']>;
+            if (filters.fqn) builder = builder.withFqn(filters.fqn) as ReturnType<Query['boundedContexts']>;
+            return builder.toArray().map((bc) => serializeNode(bc, query));
+        }
+        case 'teams': {
+            let builder = query.teams();
+            if (filters.name) builder = builder.withName(filters.name);
+            return builder.toArray().map((t) => serializeNode(t, query));
+        }
+        case 'classifications': {
+            let builder = query.classifications();
+            if (filters.name) builder = builder.withName(filters.name);
+            return builder.toArray().map((c) => serializeNode(c, query));
+        }
+        case 'relationships': {
+            const rels = query.relationships().toArray();
+            return rels.map((r) => serializeRelationship(r));
+        }
+        case 'context-maps': {
+            let builder = query.contextMaps();
+            if (filters.name) builder = builder.withName(filters.name);
+            return builder.toArray().map((cm) => serializeNode(cm, query));
+        }
+        case 'domain-maps': {
+            let builder = query.domainMaps();
+            if (filters.name) builder = builder.withName(filters.name);
+            return builder.toArray().map((dm) => serializeNode(dm, query));
+        }
+        default:
+            return [];
+    }
+}
+
+/**
+ * Generates a model summary with counts of major entities.
+ */
+async function getModelSummary(
+    sharedServices: LangiumSharedServices
+): Promise<Record<string, unknown>> {
+    const langiumDocs = sharedServices.workspace.LangiumDocuments;
+    const documents = Array.from(langiumDocs.all);
+
+    let domains = 0;
+    let bcs = 0;
+    let teams = 0;
+    let classifications = 0;
+    let relationships = 0;
+    let contextMaps = 0;
+    let domainMaps = 0;
+
+    for (const doc of documents) {
+        const query = fromDocument(doc as LangiumDocument<Model>);
+        domains += query.domains().count();
+        bcs += query.boundedContexts().count();
+        teams += query.teams().count();
+        classifications += query.classifications().count();
+        relationships += query.relationships().count();
+        contextMaps += query.contextMaps().count();
+        domainMaps += query.domainMaps().count();
+    }
+
+    return {
+        $type: 'ModelSummary',
+        documentCount: documents.length,
+        domains,
+        boundedContexts: bcs,
+        teams,
+        classifications,
+        relationships,
+        contextMaps,
+        domainMaps,
+    };
+}
+
+/**
+ * Converts diagnostic severity number to string.
+ */
+function severityToString(severity: number): 'error' | 'warning' | 'info' {
+    switch (severity) {
+        case 1:
+            return 'error';
+        case 2:
+            return 'warning';
+        default:
+            return 'info';
+    }
+}

package/src/main.ts

@@ -4,6 +4,7 @@ import { createConnection, ProposedFeatures, FileChangeType } from 'vscode-langu
 import { createDomainLangServices } from './domain-lang-module.js';
 import { ensureImportGraphFromEntryFile } from './utils/import-utils.js';
 import { DomainLangIndexManager } from './lsp/domain-lang-index-manager.js';
+import { registerToolHandlers } from './lsp/tool-handlers.js';
 import { URI } from 'langium';
 
 // Create a connection to the client
@@ -12,6 +13,9 @@ const connection = createConnection(ProposedFeatures.all);
 // Inject the shared services and language-specific services
 const { shared, DomainLang } = createDomainLangServices({ connection, ...NodeFileSystem });
 
+// Register custom LSP request handlers for VS Code Language Model Tools (PRS-015)
+registerToolHandlers(connection, shared);
+
 // 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

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';
  * 
@@ -125,3 +141,19 @@ export type {
     BcQueryBuilder,
     RelationshipView,
 } from './types.js';
+
+// Serializers for tool responses (browser-safe)
+export {
+    serializeNode,
+    serializeRelationship,
+    resolveName,
+    resolveMultiReference,
+    normalizeEntityType,
+    ENTITY_ALIASES,
+} from './serializers.js';
+export type { QueryEntityType, QueryEntityInput, QueryFilters } from './serializers.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

@@ -145,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';