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

@@ -142,6 +142,17 @@ export type {
     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';

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