@domainlang/language 0.1.81

package/src/lsp/hover/domain-lang-hover.ts

@@ -0,0 +1,340 @@
+import type {
+    AstNode,
+    CommentProvider,
+    DocumentationProvider,
+    LangiumDocument,
+    MaybePromise,
+    Reference
+} from 'langium';
+import { CstUtils, isAstNodeWithComment, isJSDoc, isReference, parseJSDoc } from 'langium';
+import type { LangiumServices } from 'langium/lsp';
+import { AstNodeHoverProvider } from 'langium/lsp';
+import type { Hover, HoverParams } from 'vscode-languageserver';
+import * as ast from '../../generated/ast.js';
+import type { DomainLangServices } from '../../domain-lang-module.js';
+import { QualifiedNameProvider } from '../domain-lang-naming.js';
+import { keywordExplanations } from './domain-lang-keywords.js';
+import { effectiveClassification, effectiveTeam } from '../../sdk/resolution.js';
+
+/**
+ * Provides hover information for DomainLang elements.
+ */
+export class DomainLangHoverProvider extends AstNodeHoverProvider {
+    protected readonly documentationProvider: DocumentationProvider;
+    protected readonly commentProvider: CommentProvider;
+    protected readonly qualifiedNameProvider: QualifiedNameProvider;
+
+    constructor(services: LangiumServices) {
+        super(services);
+        this.documentationProvider = services.documentation.DocumentationProvider;
+        this.commentProvider = services.documentation.CommentProvider;
+        const domainServices = services as DomainLangServices;
+        this.qualifiedNameProvider = domainServices.references.QualifiedNameProvider;
+    }
+
+    override async getHoverContent(document: LangiumDocument, params: HoverParams): Promise<Hover | undefined> {
+        try {
+            const rootNode = document.parseResult?.value?.$cstNode;
+            if (!rootNode) {
+                return undefined;
+            }
+
+            const offset = document.textDocument.offsetAt(params.position);
+            const cstNode = CstUtils.findDeclarationNodeAtOffset(rootNode, offset, this.grammarConfig.nameRegexp);
+            if (!cstNode || cstNode.offset + cstNode.length <= offset) {
+                return undefined;
+            }
+
+            const targetNodes = this.references.findDeclarations(cstNode);
+            const targetNode = targetNodes?.[0];
+            if (targetNode) {
+                const content = await this.getAstNodeHoverContent(targetNode);
+                if (content) {
+                    return { contents: { kind: 'markdown', value: content } };
+                }
+            }
+
+            if (cstNode.astNode && ast.isThisRef(cstNode.astNode)) {
+                const content = await this.getAstNodeHoverContent(cstNode.astNode);
+                if (content) {
+                    return { contents: { kind: 'markdown', value: content } };
+                }
+            }
+
+            if (cstNode.grammarSource?.$type === 'Keyword') {
+                const keywordHover = this.getKeywordHoverContent(cstNode.grammarSource);
+                if (keywordHover) {
+                    return keywordHover;
+                }
+
+                const explanation = keywordExplanations[cstNode.text.toLowerCase()];
+                if (explanation) {
+                    return { contents: { kind: 'markdown', value: `💡 ${explanation}` } };
+                }
+            }
+        } catch (error) {
+            console.error('Error in getHoverContent:', error);
+        }
+
+        return undefined;
+    }
+
+    protected getAstNodeHoverContent(node: AstNode): MaybePromise<string | undefined> {
+        try {
+            const content = this.documentationProvider.getDocumentation(node);
+            const commentBlock = content ? `*${content}*\n\n` : '';
+
+            if (ast.isDomain(node)) {
+                const description = node.description ?? '';
+                const vision = node.vision ?? '';
+                const typeRef = node.type?.ref;
+                const type = this.getRefName(typeRef);
+
+                const signatureParts = ['Domain', node.name];
+                if (node.parent?.ref?.name) signatureParts.push('in', node.parent.ref.name);
+                const signature = `\`\`\`domain-lang\n${signatureParts.join(' ')}\n\`\`\``;
+
+                const fields: string[] = [signature];
+                if (description) fields.push(description);
+                if (vision || type || node.parent) fields.push('---');
+                if (vision) fields.push(`**Vision:** ${vision}`);
+                if (type) fields.push(`**Type:** ${this.refLink(typeRef, type)}`);
+                if (node.parent) fields.push(`**Parent:** ${this.refLink(node.parent)}`);
+
+                return (commentBlock ? `${commentBlock}\n\n---\n\n` : '') +
+                    `📁 **\`(domain)\` ${node.name}**\n\n` +
+                    fields.join('\n\n');
+            }
+
+            if (ast.isThisRef(node)) {
+                let parent = node.$container;
+                while (parent) {
+                    if (
+                        ast.isDomain(parent) ||
+                        ast.isBoundedContext(parent) ||
+                        ast.isNamespaceDeclaration(parent) ||
+                        ast.isContextMap(parent) ||
+                        ast.isDomainMap(parent) ||
+                        ast.isModel(parent)
+                    ) {
+                        return this.getAstNodeHoverContent(parent);
+                    }
+                    parent = parent.$container;
+                }
+
+                return '*this* refers to the current context';
+            }
+
+            if (ast.isBoundedContext(node)) {
+                const description = node.description ?? '';
+                const classification = effectiveClassification(node);
+                const team = effectiveTeam(node);
+                const businessModel = node.businessModel?.ref;
+                const evolution = node.evolution?.ref;
+                const relationships = node.relationships ?? [];
+                const terminology = node.terminology ?? [];
+                const decisions = node.decisions ?? [];
+                const classificationName = classification?.name;
+                const teamName = team?.name;
+
+                const signatureParts = ['boundedcontext', node.name];
+                if (node.domain?.ref?.name) signatureParts.push('for', node.domain.ref.name);
+                if (classificationName) signatureParts.push('as', classificationName);
+                if (teamName) signatureParts.push('by', teamName);
+                const signature = `\`\`\`domain-lang\n${signatureParts.join(' ')}\n\`\`\``;
+
+                const fields: string[] = [signature];
+                if (description) fields.push(description);
+                if (classification || team || businessModel || evolution) fields.push('---');
+                if (classification) fields.push(`🔖 **Classification:** ${this.refLink(classification)}`);
+                if (team) fields.push(`👥 **Team:** ${this.refLink(team)}`);
+                if (businessModel) fields.push(`💼 **Business Model:** ${this.refLink(businessModel)}`);
+                if (evolution) fields.push(`🔄 **Evolution:** ${this.refLink(evolution)}`);
+                if (relationships.length) {
+                    const relationshipLines = relationships.map(rel => `- ${this.refLink(rel.left?.link)} ${rel.arrow} ${this.refLink(rel.right?.link)}${rel.type ? ` \`${rel.type}\`` : ''}`);
+                    fields.push(`**Relationships:**\n${relationshipLines.join('\n')}`);
+                }
+                if (terminology.length) {
+                    const termLines = terminology.map(t => `- \`${t.name}\`: ${t.meaning ?? ''}`);
+                    fields.push(`**Terminology:**\n${termLines.join('\n')}`);
+                }
+                if (decisions.length) {
+                    const decisionLines = decisions.map(d => `- \`${d.name}\`: ${d.value ?? ''}`);
+                    fields.push(`**Decisions:**\n${decisionLines.join('\n')}`);
+                }
+
+                return (commentBlock ? `${commentBlock}\n\n---\n\n` : '') +
+                    `📕 **\`(boundedcontext)\` ${node.name}**\n\n` +
+                    fields.join('\n\n');
+            }
+
+            if (ast.isNamespaceDeclaration && ast.isNamespaceDeclaration(node)) {
+                const fields: string[] = [`Contains ${node.children.length} elements.`];
+                return (commentBlock ? `${commentBlock}\n\n---\n\n` : '') +
+                    `🧭 **\`(namespace)\` ${node.name}**\n\n` +
+                    fields.join('\n\n');
+            }
+
+            if (ast.isContextMap && ast.isContextMap(node)) {
+                const fields: string[] = [];
+                if (node.boundedContexts.length) {
+                    fields.push('---');
+                    fields.push(`**📕 Bounded Contexts**\n${node.boundedContexts.flatMap(bc => bc.items.map(item => `- ${this.refLink(item.ref)}`)).join('\n')}`);
+                }
+                if (node.relationships.length) {
+                    fields.push('---');
+                    fields.push(`**🔗 Relationships**\n${node.relationships.map(r => `- ${this.refLink(r.left?.link)} ${r.arrow} ${this.refLink(r.right?.link)}${r.type ? ` \`${r.type}\`` : ''}`).join('\n')}`);
+                }
+                return (commentBlock ? `${commentBlock}\n\n---\n\n` : '') +
+                    `🗺️ **\`(contextmap)\` ${node.name}**\n\n` +
+                    fields.join('\n\n');
+            }
+
+            if (ast.isDomainMap && ast.isDomainMap(node)) {
+                const fields: string[] = [];
+                if (node.domains.length) {
+                    fields.push('---');
+                    fields.push(`**📁 Domains**\n${node.domains.flatMap(d => d.items.map(item => `- ${this.refLink(item.ref)}`)).join('\n')}`);
+                }
+                return (commentBlock ? `${commentBlock}\n\n---\n\n` : '') +
+                    `🗺️ **\`(domainmap)\` ${node.name}**\n\n` +
+                    fields.join('\n\n');
+            }
+
+            if (ast.isDecision && ast.isDecision(node)) {
+                const fields: string[] = [];
+                if (node.value) {
+                    fields.push('---');
+                    fields.push(`*Definition:* ${node.value}`);
+                }
+                return (commentBlock ? `${commentBlock}\n\n---\n\n` : '') +
+                    `⚖️ **\`(decision)\` ${node.name}**\n\n` +
+                    fields.join('\n\n');
+            }
+
+            if (ast.isPolicy && ast.isPolicy(node)) {
+                const fields: string[] = [];
+                if (node.value) {
+                    fields.push('---');
+                    fields.push(`*Definition:* ${node.value}`);
+                }
+                return (commentBlock ? `${commentBlock}\n\n---\n\n` : '') +
+                    `📜 **\`(policy)\` ${node.name}**\n\n` +
+                    fields.join('\n\n');
+            }
+
+            if (ast.isBusinessRule && ast.isBusinessRule(node)) {
+                const fields: string[] = [];
+                if (node.value) {
+                    fields.push('---');
+                    fields.push(`*Definition:* ${node.value}`);
+                }
+                return (commentBlock ? `${commentBlock}\n\n---\n\n` : '') +
+                    `⚖️ **\`(rule)\` ${node.name}**\n\n` +
+                    fields.join('\n\n');
+            }
+
+            if (ast.isDomainTerm && ast.isDomainTerm(node)) {
+                const fields: string[] = [];
+                if (node.meaning) {
+                    fields.push('---');
+                    fields.push(`*${node.meaning}*`);
+                }
+                return (commentBlock ? `${commentBlock}\n\n---\n\n` : '') +
+                    `🗝️ **\`(term)\` ${node.name}**\n\n` +
+                    fields.join('\n\n');
+            }
+
+            if (ast.isTeam && ast.isTeam(node)) {
+                return (commentBlock ? `${commentBlock}\n\n---\n\n` : '') +
+                    `👥 **\`(team)\` ${node.name}**`;
+            }
+
+            if (ast.isClassification && ast.isClassification(node)) {
+                return (commentBlock ? `${commentBlock}\n\n---\n\n` : '') +
+                    `🏷️ **\`(classification)\` ${node.name}**`;
+            }
+
+            if (ast.isMetadata && ast.isMetadata(node)) {
+                return (commentBlock ? `${commentBlock}\n\n---\n\n` : '') +
+                    `🔖 **\`(metadata)\` ${node.name}**`;
+            }
+
+            if (ast.isRelationship && ast.isRelationship(node)) {
+                const leftPatterns = node.leftPatterns.join(', ');
+                const rightPatterns = node.rightPatterns.join(', ');
+                const fields: string[] = [];
+                fields.push(`${this.refLink(node.left.link)} ${node.arrow} ${this.refLink(node.right.link)}`);
+                if (node.type) fields.push(`**Type:** \`${node.type}\``);
+                if (leftPatterns) fields.push(`**Left patterns:** ${leftPatterns}`);
+                if (rightPatterns) fields.push(`**Right patterns:** ${rightPatterns}`);
+                return (commentBlock ? `${commentBlock}\n\n---\n\n` : '') +
+                    `🔗 **\`(relationship)\`**\n\n` +
+                    fields.join('\n\n');
+            }
+
+            if (ast.isImportStatement && ast.isImportStatement(node)) {
+                const fields: string[] = [];
+                fields.push(`**URI:** \`${node.uri}\``);
+                if (node.symbols.length) fields.push(`**Imports:** ${node.symbols.map(s => `\`${s}\``).join(', ')}`);
+                if (node.alias) fields.push(`**Alias:** \`${node.alias}\``);
+                if (node.integrity) fields.push(`**Integrity:** \`${node.integrity}\``);
+                return (commentBlock ? `${commentBlock}\n\n---\n\n` : '') +
+                    `📦 **\`(import)\`**\n\n` +
+                    fields.join('\n\n');
+            }
+
+            const title = ast.isType(node) ? node.name : node.$type.toLowerCase();
+            return (commentBlock ? `${commentBlock}\n\n---\n\n` : '') +
+                `ℹ️ **\`(${node.$type.toLowerCase()})\`${ast.isType(node) ? ` ${title}` : ''}**`;
+        } catch (error) {
+            console.error('Error in getAstNodeHoverContent:', error);
+            return 'Unable to display complete information.';
+        }
+    }
+
+    private getRefName(ref: ast.Type | Reference<ast.Type> | undefined): string {
+        const node = isReference(ref) ? ref.ref : ref;
+        if (node && ast.isType(node)) {
+            return node.name;
+        }
+        return '';
+    }
+
+    private refLink(ref: Reference<ast.Type> | ast.Type | undefined, label?: string): string {
+        if (label) {
+            return `[${label}](#${encodeURIComponent(label)})`;
+        }
+
+        const node = isReference(ref) ? ref.ref : ref;
+
+        if (node && ast.isType(node)) {
+            let linkLabel = node.name;
+            try {
+                linkLabel = this.qualifiedNameProvider.getQualifiedName(node.$container, node.name);
+            } catch {
+                // fallback to name
+            }
+            return `[${linkLabel}](#${encodeURIComponent(linkLabel)})`;
+        }
+        return '';
+    }
+
+    protected override getKeywordHoverContent(node: AstNode): MaybePromise<Hover | undefined> {
+        let comment = isAstNodeWithComment(node) ? node.$comment : undefined;
+
+        if (!comment) {
+            comment = CstUtils.findCommentNode(node.$cstNode, ['ML_COMMENT'])?.text;
+        }
+
+        if (comment && isJSDoc(comment)) {
+            const markdown = parseJSDoc(comment).toMarkdown();
+            if (markdown) {
+                return { contents: { kind: 'markdown', value: markdown } };
+            }
+        }
+
+        return undefined;
+    }
+}
+

package/src/lsp/hover/domain-lang-keywords.ts

@@ -0,0 +1,50 @@
+/**
+ * Keyword explanations for DomainLang hover documentation.
+ * 
+ * This dictionary provides fallback hover content for keywords that don't have
+ * JSDoc comments in the grammar file, or for providing richer DDD pattern explanations.
+ * 
+ * Basic keyword documentation (domain, boundedcontext, etc.) is now in the grammar file
+ * as JSDoc comments. This dictionary focuses on DDD integration patterns and advanced concepts.
+ * 
+ * @see src/language/domain-lang.langium for basic keyword JSDoc
+ * @see ddd-pattern-explanations.ts for role patterns and relationship types
+ */
+export const keywordExplanations: Record<string, string> = {
+    // Advanced syntax keywords
+    implements: "**implements** - Declares that a Bounded Context or type implements a Domain or interface.",
+    as: "**as** - Used for aliasing or renaming imports or types.",
+    from: "**from** - Specifies the source module or file for an import statement.",
+    type: "**type** - Declares a new type or alias in the model.",
+    map: "**map** - Defines a mapping or transformation between elements.",
+    this: "**this** - Refers to the current context or object.",
+    
+    // DDD Classifiers
+    entity: "**Entity** - Domain object with distinct identity that runs through time.",
+    valueobject: "**Value Object** - Immutable object that describes a characteristic.",
+    aggregate: "**Aggregate** - Cluster of domain objects with a root and boundary.",
+    service: "**Service** - Stateless domain operation.",
+    event: "**Event** - Significant domain occurrence or state change.",
+    businessrule: "**Business Rule** - Rule that constrains business behavior.",
+    
+    // DDD Integration Patterns
+    acl: "**ACL (Anti-Corruption Layer)** - Translation layer protecting downstream context from upstream changes.",
+    ohs: "**OHS (Open Host Service)** - Well-defined protocol providing access to a subsystem.",
+    pl: "**PL (Published Language)** - Documented shared language for context communication.",
+    cf: "**CF (Conformist)** - Downstream adopts upstream model without translation.",
+    bbom: "**BBoM (Big Ball of Mud)** - System with tangled architecture and no clear boundaries.",
+    sk: "**SK (Shared Kernel)** - Shared domain model subset requiring coordination.",
+    p: "**P (Partnership)** - Teams collaborate closely with shared success/failure.",
+    
+    // DDD Relationship Types
+    separateways: "**Separate Ways** - No connection between contexts, each solves problems independently.",
+    partnership: "**Partnership** - Teams share risks and rewards with close collaboration.",
+    sharedkernel: "**Shared Kernel** - Shared domain model subset requiring coordination.",
+    customersupplier: "**Customer-Supplier** - Upstream prioritizes downstream needs.",
+    upstreamdownstream: "**Upstream-Downstream** - Upstream changes affect downstream.",
+    
+    // Relationship arrows
+    '<->': "**Bidirectional** - Two contexts connected in both directions.",
+    '->': "**Upstream → Downstream** - Left depends on right.",
+    '<-': "**Downstream ← Upstream** - Right depends on left.",
+}; 

package/src/main-browser.ts

@@ -0,0 +1,15 @@
+import { EmptyFileSystem } from 'langium';
+import { startLanguageServer } from 'langium/lsp';
+import { BrowserMessageReader, BrowserMessageWriter, createConnection } from 'vscode-languageserver/browser.js';
+import { createDomainLangServices } from './domain-lang-module.js';
+
+// declare const self: DedicatedWorkerGlobalScope;
+
+const messageReader = new BrowserMessageReader(self);
+const messageWriter = new BrowserMessageWriter(self);
+
+const connection = createConnection(messageReader, messageWriter);
+
+const { shared } = createDomainLangServices({ connection, ...EmptyFileSystem });
+
+startLanguageServer(shared);

package/src/main.ts

@@ -0,0 +1,85 @@
+import { startLanguageServer } from 'langium/lsp';
+import { NodeFileSystem } from 'langium/node';
+import { createConnection, ProposedFeatures } from 'vscode-languageserver/node.js';
+import { createDomainLangServices } from './domain-lang-module.js';
+import { ensureImportGraphFromEntryFile } from './utils/import-utils.js';
+import { URI } from 'langium';
+
+// Create a connection to the client
+const connection = createConnection(ProposedFeatures.all);
+
+// Inject the shared services and language-specific services
+const { shared, DomainLang } = createDomainLangServices({ connection, ...NodeFileSystem });
+
+// Initialize workspace on connection
+connection.onInitialize(async (params) => {
+    const workspaceRoot = params.rootUri ? URI.parse(params.rootUri).fsPath : undefined;
+    
+    if (workspaceRoot) {
+        try {
+            // Initialize workspace manager
+            const workspaceManager = DomainLang.imports.WorkspaceManager;
+            await workspaceManager.initialize(workspaceRoot);
+            console.warn(`DomainLang workspace initialized: ${workspaceRoot}`);
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`Failed to initialize workspace: ${message}`);
+            // Continue without workspace - local imports will still work
+        }
+    }
+    
+    return {
+        capabilities: {
+            // Language server capabilities are configured by Langium
+        }
+    };
+});
+
+// Optionally start from a single entry file and follow imports.
+// Configure via env DOMAINLANG_ENTRY (absolute or workspace-relative path)
+const entryFile = process.env.DOMAINLANG_ENTRY;
+if (entryFile) {
+    let currentGraph = new Set<string>();
+
+    /**
+     * Reloads the import graph from the entry file.
+     * Handles errors gracefully and notifies the LSP client.
+     */
+    const reloadFromEntry = async (): Promise<void> => {
+        try {
+            currentGraph = await ensureImportGraphFromEntryFile(
+                entryFile, 
+                shared.workspace.LangiumDocuments
+            );
+            console.warn(`Successfully loaded import graph from ${entryFile}`);
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`Failed to preload import graph from ${entryFile}: ${message}`);
+            // Notify LSP client of the error
+            connection.console.error(
+                `DomainLang: Could not load entry file ${entryFile}. Error: ${message}`
+            );
+        }
+    };
+
+    // Initial load from entry file, then start the server
+    reloadFromEntry().finally(() => startLanguageServer(shared));
+
+    // Any change within the loaded graph should trigger a reload from the entry
+    shared.workspace.TextDocuments.onDidChangeContent(async (event) => {
+        const changed = event.document.uri;
+        if (currentGraph.has(changed)) {
+            await reloadFromEntry();
+        }
+    });
+
+    // If the entry file itself is opened/changed, also reload
+    shared.workspace.TextDocuments.onDidOpen(async (event) => {
+        if (URI.parse(event.document.uri).fsPath === URI.file(entryFile).fsPath) {
+            await reloadFromEntry();
+        }
+    });
+} else {
+    // No entry file configured: start normally
+    startLanguageServer(shared);
+}