@domainlang/language 0.1.20

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

@@ -0,0 +1,137 @@
+// domain-lang-scope.ts
+// Implements custom scope computation for the DomainLang DSL, supporting FQN disambiguation, nested groups, and cross-file references.
+
+/****************************************************************************
+ * Copyright 2021 TypeFox GmbH
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License, which is available in the project root.
+ ***************************************************************************/
+
+import type { 
+    AstNode, 
+    AstNodeDescription, 
+    LangiumDocument, 
+    LocalSymbols 
+} from 'langium';
+import { 
+    DefaultScopeComputation, 
+    interruptAndCheck, 
+    MultiMap, 
+    AstUtils 
+} from 'langium';
+import { CancellationToken } from 'vscode-jsonrpc';
+import type { NamespaceDeclaration, Model, Container } from '../generated/ast.js';
+import { isType, isNamespaceDeclaration } from '../generated/ast.js';
+import { QualifiedNameProvider } from './domain-lang-naming.js';
+import type { DomainLangServices } from '../domain-lang-module.js';
+
+/**
+ * Computes the scope for DomainLang elements, supporting nested namespaces, FQN disambiguation, and cross-file references.
+ * Extends Langium's DefaultScopeComputation to provide custom export and local scope logic.
+ */
+export class DomainLangScopeComputation extends DefaultScopeComputation {
+    qualifiedNameProvider: QualifiedNameProvider;
+
+    /**
+     * Constructs a new DomainLangScopeComputation with injected services.
+     * @param services - The DomainLangServices instance
+     */
+    constructor(services: DomainLangServices) {
+        super(services);
+        this.qualifiedNameProvider = services.references.QualifiedNameProvider;
+    }
+
+    /**
+    * Computes exported node descriptions for types, using fully qualified names for nested namespaces.
+     * @param document - The LangiumDocument to process
+     * @param cancelToken - Optional cancellation token
+     * @returns A promise resolving to an array of AstNodeDescription
+     */
+    override async collectExportedSymbols(document: LangiumDocument, cancelToken = CancellationToken.None): Promise<AstNodeDescription[]> {
+        const descr: AstNodeDescription[] = [];
+        for (const modelNode of AstUtils.streamAllContents(document.parseResult.value)) {
+            await interruptAndCheck(cancelToken);
+            if (isType(modelNode)) {
+                let name = this.nameProvider.getName(modelNode);
+                if (!name) {
+                    // Defensive: skip unnamed types
+                    continue;
+                }
+                if (isNamespaceDeclaration(modelNode.$container)) {
+                    name = this.qualifiedNameProvider.getQualifiedName(modelNode.$container as NamespaceDeclaration, name);
+                }
+                descr.push(this.descriptions.createDescription(modelNode, name, document));
+            }
+        }
+        return descr;
+    }
+
+    /**
+    * Computes local scopes for all containers, recursively processing nested namespaces.
+     * @param document - The LangiumDocument to process
+     * @param cancelToken - Optional cancellation token
+     * @returns A promise resolving to a LocalSymbols map
+     */
+    override async collectLocalSymbols(document: LangiumDocument, cancelToken = CancellationToken.None): Promise<LocalSymbols> {
+        const model = document.parseResult.value as Model;
+        const scopes = new MultiMap<AstNode, AstNodeDescription>();
+        await this.processContainer(model, scopes, document, cancelToken);
+        return scopes;
+    }
+
+    /**
+     * Recursively processes a container and its children, adding local descriptions and qualified names.
+    * @param container - The container node (Model or NamespaceDeclaration)
+     * @param scopes - The LocalSymbols map to populate
+     * @param document - The LangiumDocument being processed
+     * @param cancelToken - Optional cancellation token
+     * @returns A promise resolving to an array of AstNodeDescription
+     */
+    protected async processContainer(
+        container: Container,
+        scopes: LocalSymbols,
+        document: LangiumDocument,
+        cancelToken: CancellationToken
+    ): Promise<AstNodeDescription[]> {
+        const localDescriptions: AstNodeDescription[] = [];
+        for (const element of container.children) {
+            await interruptAndCheck(cancelToken);
+            if (isType(element) && element.name) {
+                const description = this.descriptions.createDescription(element, element.name, document);
+                localDescriptions.push(description);
+            } else if (isNamespaceDeclaration(element)) {
+                const nestedDescriptions = await this.processContainer(element, scopes, document, cancelToken);
+                for (const description of nestedDescriptions) {
+                    // Add qualified names to the container
+                    const qualified = this.createQualifiedDescription(element, description, document);
+                    localDescriptions.push(qualified);
+                }
+            }
+        }
+        // MultiMap implements LocalSymbols interface with add/addAll methods
+        (scopes as MultiMap<AstNode, AstNodeDescription>).addAll(container, localDescriptions);
+        return localDescriptions;
+    }
+
+    /**
+    * Creates a qualified AstNodeDescription for a node within a namespace.
+     * 
+    * @param namespace - The NamespaceDeclaration containing the node
+     * @param description - The AstNodeDescription to qualify
+     * @param document - The LangiumDocument being processed
+     * @returns A new AstNodeDescription with a fully qualified name
+     * 
+     * @example
+     * // For a Domain "Sales" in namespace "Shared"
+     * // Returns description with name "Shared.Sales"
+     */
+    protected createQualifiedDescription(
+        namespace: NamespaceDeclaration,
+        description: AstNodeDescription,
+        document: LangiumDocument
+    ): AstNodeDescription {
+        const name = this.qualifiedNameProvider.getQualifiedName(namespace.name, description.name);
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        return this.descriptions.createDescription(description.node!, name, document);
+    }
+}

package/src/lsp/domain-lang-workspace-manager.ts

@@ -0,0 +1,104 @@
+import path from 'node:path';
+import YAML from 'yaml';
+import { DefaultWorkspaceManager, URI, UriUtils, type FileSystemNode, type LangiumDocument, type LangiumSharedCoreServices, type WorkspaceFolder } from 'langium';
+import type { CancellationToken } from 'vscode-languageserver-protocol';
+import { ensureImportGraphFromDocument } from '../utils/import-utils.js';
+
+/**
+ * Langium WorkspaceManager override implementing manifest-centric import loading per PRS-010.
+ *
+ * Behavior:
+ * - Skips pre-loading *.dlang during workspace scan (only entry graph is loaded when manifest exists).
+ * - Mode A (with manifest): find nearest model.yaml in folder, load entry (default index.dlang) and its import graph.
+ * - Mode B (no manifest): no pre-loading; imports resolved on-demand when a document is opened.
+ * - Never performs network fetches; relies on cached dependencies/lock files. Missing cache produces diagnostics upstream.
+ */
+export class DomainLangWorkspaceManager extends DefaultWorkspaceManager {
+    constructor(services: LangiumSharedCoreServices) {
+        super(services);
+    }
+
+    override shouldIncludeEntry(entry: FileSystemNode): boolean {
+        // Prevent auto-including .dlang files; we'll load via entry/import graph
+        const name = UriUtils.basename(entry.uri);
+        if (name.toLowerCase().endsWith('.dlang')) {
+            return false;
+        }
+        return super.shouldIncludeEntry(entry);
+    }
+
+    override async initializeWorkspace(folders: WorkspaceFolder[], cancelToken?: CancellationToken): Promise<void> {
+        await super.initializeWorkspace(folders, cancelToken);
+    }
+
+    protected override async loadAdditionalDocuments(folders: WorkspaceFolder[], collector: (document: LangiumDocument) => void): Promise<void> {
+        const manifestInfo = await this.findManifestInFolders(folders);
+        if (!manifestInfo) {
+            return; // Mode B: no manifest
+        }
+
+        const entryUri = URI.file(manifestInfo.entryPath);
+        const entryDoc = await this.langiumDocuments.getOrCreateDocument(entryUri);
+        collector(entryDoc);
+
+        const uris = await ensureImportGraphFromDocument(entryDoc, this.langiumDocuments);
+        for (const uriString of uris) {
+            const uri = URI.parse(uriString);
+            const doc = await this.langiumDocuments.getOrCreateDocument(uri);
+            collector(doc);
+        }
+    }
+
+    private async findManifestInFolders(folders: WorkspaceFolder[]): Promise<{ manifestPath: string; entryPath: string } | undefined> {
+        for (const folder of folders) {
+            const manifestPath = await this.findNearestManifest(folder.uri);
+            if (manifestPath) {
+                const entry = await this.readEntryFromManifest(manifestPath) ?? 'index.dlang';
+                const entryPath = path.resolve(path.dirname(manifestPath), entry);
+                return { manifestPath, entryPath };
+            }
+        }
+        return undefined;
+    }
+
+    private async findNearestManifest(startUri: string): Promise<string | undefined> {
+        let current = path.resolve(URI.parse(startUri).fsPath);
+        const { root } = path.parse(current);
+
+        while (true) {
+            const candidate = path.join(current, 'model.yaml');
+            if (await this.pathExists(candidate)) {
+                return candidate;
+            }
+
+            if (current === root) {
+                return undefined;
+            }
+
+            const parent = path.dirname(current);
+            if (parent === current) {
+                return undefined;
+            }
+            current = parent;
+        }
+    }
+
+    private async readEntryFromManifest(manifestPath: string): Promise<string | undefined> {
+        try {
+            const content = await this.fileSystemProvider.readFile(URI.file(manifestPath));
+            const manifest = (YAML.parse(content) ?? {}) as { model?: { entry?: string } };
+            return manifest.model?.entry;
+        } catch {
+            return undefined;
+        }
+    }
+
+    private async pathExists(target: string): Promise<boolean> {
+        try {
+            await this.fileSystemProvider.stat(URI.file(target));
+            return true;
+        } catch {
+            return false;
+        }
+    }
+}

package/src/lsp/hover/ddd-pattern-explanations.ts

@@ -0,0 +1,237 @@
+/**
+ * DDD Pattern Explanations for Hover Documentation
+ * 
+ * Provides plain-English explanations for DDD integration patterns,
+ * relationship types, and decision categories.
+ */
+
+/**
+ * Explanations for DDD integration role patterns (e.g., PL, ACL, SK).
+ */
+export const rolePatternExplanations: Record<string, string> = {
+    'PL': `**Published Language (PL)**
+
+The upstream context provides a well-documented, stable API/model that downstream contexts consume.
+
+\`\`\`domain-lang
+[PL] UpstreamContext -> DownstreamContext
+\`\`\`
+
+*Use when:* Multiple consumers need a shared, stable interface.`,
+    
+    'ACL': `**Anti-Corruption Layer (ACL)**
+
+Protects downstream from upstream changes by translating between models.
+
+\`\`\`domain-lang
+UpstreamContext -> [ACL] DownstreamContext
+\`\`\`
+
+*Use when:* You don't trust upstream stability or want isolation.`,
+    
+    'SK': `**Shared Kernel (SK)**
+
+Both contexts share common domain model code requiring coordination.
+
+\`\`\`domain-lang
+[SK] Context1 <-> [SK] Context2 : SharedKernel
+\`\`\`
+
+*Use when:* Contexts are tightly coupled and teams can coordinate.`,
+    
+    'CF': `**Conformist (CF)**
+
+Downstream accepts upstream model without translation.
+
+\`\`\`domain-lang
+UpstreamContext -> [CF] DownstreamContext
+\`\`\`
+
+*Use when:* Upstream model is acceptable and translation isn't worth it.`,
+    
+    'OHS': `**Open Host Service (OHS)**
+
+Upstream defines a protocol/API for easy integration.
+
+\`\`\`domain-lang
+[OHS, PL] ApiContext -> ConsumerContext
+\`\`\`
+
+*Use when:* Multiple downstream contexts need integration.`,
+    
+    'P': `**Partnership (P)**
+
+Teams coordinate development and align releases.
+
+\`\`\`domain-lang
+Context1 <-> Context2 : Partnership
+\`\`\`
+
+*Use when:* Mutual success dependency exists.`,
+    
+    'BBoM': `**Big Ball of Mud (BBoM)**
+
+No clear boundaries - tangled models needing refactoring.
+
+\`\`\`domain-lang
+[BBoM] LegacySystem -> ModernContext
+\`\`\`
+
+*Use when:* Documenting legacy systems.`
+};
+
+/**
+ * Explanations for relationship types (e.g., Partnership, CustomerSupplier).
+ */
+export const relationshipTypeExplanations: Record<string, string> = {
+    'Partnership': '**Partnership**\n\nTwo contexts with mutual success dependency. Teams plan together and coordinate releases.\n\n*Example:* Sales and Order Fulfillment contexts that must evolve in sync.',
+    
+    'SharedKernel': '**Shared Kernel**\n\nTwo contexts share a subset of code/model. Changes require agreement from both teams.\n\n*Example:* Two closely related contexts sharing common domain entities.',
+    
+    'CustomerSupplier': '**Customer/Supplier**\n\nDownstream (customer) context depends on upstream (supplier) context. Supplier meets customer\'s needs through negotiation.\n\n*Example:* Payment context (customer) depends on Billing context (supplier).',
+    
+    'UpstreamDownstream': '**Upstream/Downstream**\n\nUpstream context influences downstream context, but not vice versa. Downstream adapts to upstream changes.\n\n*Example:* Inventory (upstream) provides data to Reporting (downstream).',
+    
+    'SeparateWays': '**Separate Ways**\n\nNo connection between contexts - they duplicate functionality rather than integrate.\n\n*Use when:* Integration cost exceeds benefit of sharing.'
+};
+
+/**
+ * Explanations for relationship arrows.
+ */
+export const arrowExplanations: Record<string, string> = {
+    '<->': 'Bidirectional relationship - both contexts influence each other',
+    '->': 'Downstream dependency - right depends on left (left is upstream)',
+    '<-': 'Upstream dependency - left depends on right (right is upstream)',
+    '><': 'Separate Ways - no integration between contexts',
+    'U/D': 'Upstream/Downstream - shorthand for upstream → downstream flow',
+    'u/d': 'Upstream/Downstream - shorthand for upstream → downstream flow',
+    'C/S': 'Customer/Supplier - shorthand for customer ← supplier relationship',
+    'c/s': 'Customer/Supplier - shorthand for customer ← supplier relationship'
+};
+
+/**
+ * Explanations for decision categories.
+ */
+export const decisionCategoryExplanations: Record<string, string> = {
+    'architectural': '**Architectural Decision**\n\nConcerns system structure, technology choices, or cross-cutting patterns.\n\n*Examples:* Microservices vs monolith, event sourcing, CQRS',
+    'arch': 'Short for "architectural" - concerns system structure and technology choices',
+    
+    'business': '**Business Decision**\n\nConcerns business rules, policies, or domain logic.\n\n*Examples:* Pricing rules, refund policies, eligibility criteria',
+    'biz': 'Short for "business" - concerns business rules and domain logic',
+    
+    'technical': '**Technical Decision**\n\nConcerns implementation details, algorithms, or technical constraints.\n\n*Examples:* Caching strategy, data structures, optimization approach',
+    'tech': 'Short for "technical" - concerns implementation details',
+    
+    'compliance': '**Compliance Decision**\n\nConcerns legal, regulatory, or compliance requirements.\n\n*Examples:* GDPR data retention, SOX audit trails, HIPAA privacy',
+    
+    'security': '**Security Decision**\n\nConcerns security, authentication, authorization, or data protection.\n\n*Examples:* OAuth vs JWT, encryption at rest, access control',
+    
+    'operational': '**Operational Decision**\n\nConcerns deployment, monitoring, or operational procedures.\n\n*Examples:* Blue/green deployment, monitoring strategy, backup policy',
+    'ops': 'Short for "operational" - concerns deployment and operations'
+};
+
+/**
+ * Explanations for common DDD classifications.
+ */
+export const classificationExplanations: Record<string, string> = {
+    'Core': '**Core Domain**\n\nThe primary differentiator for your business - this is where you create unique value.\n\n*Invest heavily:* Best team, careful design, deep modeling.\n\n*Example:* Recommendation engine for Netflix, search for Google',
+    
+    'Supporting': '**Supporting Subdomain**\n\nNecessary for the business but not a differentiator. Custom implementation needed but not the main focus.\n\n*Invest moderately:* Good team, solid implementation.\n\n*Example:* Inventory management, invoicing',
+    
+    'Generic': '**Generic Subdomain**\n\nSolved problem - could use off-the-shelf solution. No competitive advantage.\n\n*Buy or reuse:* Use existing solutions when possible.\n\n*Example:* User authentication, email sending, payment processing',
+    
+    'Strategic': '**Strategic** (Wardley Evolution)\n\nNovel, custom-built, competitive advantage. High value, low maturity.\n\n*Similar to Core Domain.*',
+    
+    'Custom': '**Custom-Built** (Wardley Evolution)\n\nSpecialized solution, some precedent exists. Medium-high value, medium maturity.',
+    
+    'Product': '**Product/Rental** (Wardley Evolution)\n\nStandardized product with features. Medium value, medium-high maturity.\n\n*Example:* SaaS tools, commercial software',
+    
+    'Commodity': '**Commodity/Utility** (Wardley Evolution)\n\nUbiquitous, interchangeable, fully standardized. Low value, high maturity.\n\n*Example:* Cloud compute, email services'
+};
+
+/**
+ * Get explanation for a role pattern.
+ */
+export function explainRolePattern(role: string): string | undefined {
+    return rolePatternExplanations[role];
+}
+
+/**
+ * Get explanation for a relationship type.
+ */
+export function explainRelationshipType(type: string): string | undefined {
+    return relationshipTypeExplanations[type];
+}
+
+/**
+ * Get explanation for an arrow symbol.
+ */
+export function explainArrow(arrow: string): string | undefined {
+    return arrowExplanations[arrow];
+}
+
+/**
+ * Get explanation for a decision category.
+ */
+export function explainDecisionCategory(category: string): string | undefined {
+    return decisionCategoryExplanations[category];
+}
+
+/**
+ * Get explanation for a classification.
+ */
+export function explainClassification(name: string): string | undefined {
+    return classificationExplanations[name];
+}
+
+/**
+ * Generate relationship explanation from roles and type.
+ */
+export function generateRelationshipExplanation(
+    leftRoles: string[] | undefined,
+    arrow: string | undefined,
+    rightRoles: string[] | undefined,
+    type: string | undefined
+): string {
+    const parts: string[] = [];
+    
+    // Arrow explanation
+    if (arrow) {
+        const arrowExp = explainArrow(arrow);
+        if (arrowExp) {
+            parts.push(`**Arrow:** ${arrowExp}`);
+        }
+    }
+    
+    // Left roles
+    if (leftRoles && leftRoles.length > 0) {
+        parts.push('**Left Context Patterns:**');
+        leftRoles.forEach(role => {
+            const exp = explainRolePattern(role);
+            if (exp) {
+                parts.push(exp);
+            }
+        });
+    }
+    
+    // Right roles
+    if (rightRoles && rightRoles.length > 0) {
+        parts.push('**Right Context Patterns:**');
+        rightRoles.forEach(role => {
+            const exp = explainRolePattern(role);
+            if (exp) {
+                parts.push(exp);
+            }
+        });
+    }
+    
+    // Relationship type
+    if (type) {
+        const typeExp = explainRelationshipType(type);
+        if (typeExp) {
+            parts.push(typeExp);
+        }
+    }
+    
+    return parts.join('\n\n---\n\n');
+}