@domainlang/language 0.5.2 → 0.7.0

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

@@ -1,50 +1,136 @@
 /**
  * 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.
+ * This dictionary provides concise hover content for all DomainLang keywords,
+ * DDD patterns, and special symbols. Uses exact casing from grammar.
  * 
- * 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
+ * @see https://domainlang.net/reference/language for full documentation
  */
+
+// Documentation links
+const DOMAIN_LINK = '\n\n[Read more](https://domainlang.net/guide/domains)';
+const BC_LINK = '\n\n[Read more](https://domainlang.net/guide/bounded-contexts)';
+const TEAM_LINK = '\n\n[Read more](https://domainlang.net/guide/teams-classifications)';
+const MAP_LINK = '\n\n[Read more](https://domainlang.net/guide/context-maps)';
+const REL_LINK = '\n\n[Read more](https://domainlang.net/guide/context-maps#relationships)';
+const IMPORT_LINK = '\n\n[Read more](https://domainlang.net/guide/imports)';
+const NS_LINK = '\n\n[Read more](https://domainlang.net/guide/namespaces)';
+const TERM_LINK = '\n\n[Read more](https://domainlang.net/reference/language#terminology)';
+const DECISION_LINK = '\n\n[Read more](https://domainlang.net/reference/language#decisions-policies-rules)';
+const METADATA_LINK = '\n\n[Read more](https://domainlang.net/reference/language#metadata)';
+const SYNTAX_LINK = '\n\n[Read more](https://domainlang.net/reference/language)';
+
 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.",
-    
+    // ========================================================================
+    // Primary Constructs
+    // ========================================================================
+    domain: `**Domain** - A sphere of knowledge or activity. Can be nested to show subdomain hierarchy.${DOMAIN_LINK}`,
+    dom: `**Domain** - A sphere of knowledge or activity. Can be nested to show subdomain hierarchy.${DOMAIN_LINK}`,
+    boundedcontext: `**BoundedContext** - A boundary where a domain model is defined. Central DDD pattern for managing complexity.${BC_LINK}`,
+    bc: `**BoundedContext** - A boundary where a domain model is defined. Central DDD pattern for managing complexity.${BC_LINK}`,
+    team: `**Team** - A group responsible for one or more bounded contexts.${TEAM_LINK}`,
+    classification: `**Classification** - Reusable label for categorizing elements (e.g., Core, Supporting, Generic).${TEAM_LINK}`,
+    metadata: `**Metadata** - Defines a key that can be used in metadata blocks.${METADATA_LINK}`,
+    meta: `**Metadata** - Defines a key that can be used in metadata blocks.${METADATA_LINK}`,
+
+    // ========================================================================
+    // Maps
+    // ========================================================================
+    contextmap: `**ContextMap** - Shows relationships between bounded contexts.${MAP_LINK}`,
+    cmap: `**ContextMap** - Shows relationships between bounded contexts.${MAP_LINK}`,
+    domainmap: `**DomainMap** - Visualizes domains and their subdomain structure.${MAP_LINK}`,
+    dmap: `**DomainMap** - Visualizes domains and their subdomain structure.${MAP_LINK}`,
+    contains: `**contains** - Specifies which elements are part of a map.${MAP_LINK}`,
+
+    // ========================================================================
+    // Bounded Context & Domain Properties
+    // ========================================================================
+    for: `**for** - Associates a bounded context with its parent domain.${BC_LINK}`,
+    as: `**as** - Assigns a classification to an element.${BC_LINK}`,
+    by: `**by** - Assigns a team responsible for an element.${BC_LINK}`,
+    in: `**in** - Specifies parent domain for subdomain nesting.${DOMAIN_LINK}`,
+    description: `**description** - Human-readable explanation of the element's purpose.${SYNTAX_LINK}`,
+    vision: `**vision** - Strategic vision statement for a domain.${DOMAIN_LINK}`,
+    type: `**type** - Assigns a classification type to a domain or relationship.${DOMAIN_LINK}`,
+    businessmodel: `**businessModel** - Revenue or engagement model for a context.${BC_LINK}`,
+    evolution: `**evolution** - Maturity stage (Genesis, Custom, Product, Commodity).${BC_LINK}`,
+    archetype: `**archetype** - Behavioral role (Gateway, Execution, etc.).${BC_LINK}`,
+    relationships: `**relationships** - Block defining integration patterns with other contexts.${REL_LINK}`,
+    integrations: `**integrations** - Block defining integration patterns with other contexts.${REL_LINK}`,
+
+    // ========================================================================
+    // Terminology & Glossary
+    // ========================================================================
+    terminology: `**terminology** - Block defining domain-specific terms and definitions.${TERM_LINK}`,
+    glossary: `**glossary** - Block defining domain-specific terms and definitions.${TERM_LINK}`,
+    term: `**Term** - Defines a domain term with its meaning.${TERM_LINK}`,
+    aka: `**aka** - Alternative names (also known as) for a term.${TERM_LINK}`,
+    synonyms: `**synonyms** - Alternative names (also known as) for a term.${TERM_LINK}`,
+    examples: `**examples** - Example usage of a term.${TERM_LINK}`,
+    meaning: `**meaning** - The definition or explanation of a term.${TERM_LINK}`,
+
+    // ========================================================================
+    // Decisions, Policies & Rules
+    // ========================================================================
+    decisions: `**decisions** - Block containing architectural decisions or business rules.${DECISION_LINK}`,
+    rules: `**rules** - Block containing architectural decisions or business rules.${DECISION_LINK}`,
+    decision: `**Decision** - An architectural or domain decision.${DECISION_LINK}`,
+    policy: `**Policy** - A business policy or organizational rule.${DECISION_LINK}`,
+    rule: `**Rule** - A business rule or constraint (also BusinessRule).${DECISION_LINK}`,
+
+    // ========================================================================
+    // Import System
+    // ========================================================================
+    import: `**Import** - Imports definitions from an external model or file.${IMPORT_LINK}`,
+
+    // ========================================================================
+    // Namespaces
+    // ========================================================================
+    namespace: `**Namespace** - Groups elements under a qualified name.${NS_LINK}`,
+    ns: `**Namespace** - Groups elements under a qualified name.${NS_LINK}`,
+
+    // ========================================================================
+    // Assignment Operators
+    // ========================================================================
+    ':': `**:** - Assignment operator (property: value).${SYNTAX_LINK}`,
+    is: `**is** - Assignment operator (property is value).${SYNTAX_LINK}`,
+    '=': `**=** - Assignment operator (property = value).${SYNTAX_LINK}`,
+
+    // ========================================================================
+    // Context Reference
+    // ========================================================================
+    this: `**this** - References the current bounded context in relationships.${REL_LINK}`,
+
+    // ========================================================================
     // 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.",
-}; 
+    // ========================================================================
+    acl: `**ACL** - Anti-Corruption Layer. Protects from external models by translating between domains.${REL_LINK}`,
+    anticorruptionlayer: `**AntiCorruptionLayer** - Protects from external models by translating between domains.${REL_LINK}`,
+    ohs: `**OHS** - Open Host Service. Provides a well-documented API for integration.${REL_LINK}`,
+    openhostservice: `**OpenHostService** - Provides a well-documented API for integration.${REL_LINK}`,
+    pl: `**PL** - Published Language. Documented language for inter-context communication.${REL_LINK}`,
+    publishedlanguage: `**PublishedLanguage** - Documented language for inter-context communication.${REL_LINK}`,
+    cf: `**CF** - Conformist. Adopts upstream model without translation.${REL_LINK}`,
+    conformist: `**Conformist** - Adopts upstream model without translation.${REL_LINK}`,
+    p: `**P** - Partnership. Two teams with mutual dependency and shared goals.${REL_LINK}`,
+    partnership: `**Partnership** - Two teams with mutual dependency and shared goals.${REL_LINK}`,
+    sk: `**SK** - Shared Kernel. Shared code/data requiring careful coordination.${REL_LINK}`,
+    sharedkernel: `**SharedKernel** - Shared code/data requiring careful coordination.${REL_LINK}`,
+    bbom: `**BBoM** - Big Ball of Mud. Legacy area without clear boundaries.${REL_LINK}`,
+    bigballofmud: `**BigBallOfMud** - Legacy area without clear boundaries.${REL_LINK}`,
+
+    // ========================================================================
+    // Relationship Types
+    // ========================================================================
+    customersupplier: `**CustomerSupplier** - Downstream depends on upstream with influence over priorities.${REL_LINK}`,
+    upstreamdownstream: `**UpstreamDownstream** - One context depends on another's model.${REL_LINK}`,
+    separateways: `**SeparateWays** - Contexts with no integration, solving problems independently.${REL_LINK}`,
+
+    // ========================================================================
+    // Relationship Arrows
+    // ========================================================================
+    '->': `**->** - Unidirectional dependency (upstream to downstream).${REL_LINK}`,
+    '<->': `**<->** - Bidirectional dependency (mutual).${REL_LINK}`,
+    '<-': `**<-** - Reverse unidirectional dependency (downstream to upstream).${REL_LINK}`,
+    '><': `**><** - Separate Ways (no integration).${REL_LINK}`,
+};

package/src/lsp/manifest-diagnostics.ts

@@ -14,7 +14,7 @@
 
 import type { Connection } from 'vscode-languageserver';
 import { Diagnostic, DiagnosticSeverity, Position, Range } from 'vscode-languageserver-types';
-import YAML, { type Document as YAMLDocument, type YAMLMap, type Pair, isMap, isPair, isScalar } from 'yaml';
+import YAML, { type Document as YAMLDocument, type Pair, isMap, isPair, isScalar } from 'yaml';
 import { ManifestValidator, type ManifestDiagnostic, type ManifestSeverity } from '../validation/manifest.js';
 import type { ModelManifest } from '../services/types.js';
 
@@ -45,16 +45,32 @@ export class ManifestDiagnosticsService {
         content: string,
         options?: { requirePublishable?: boolean }
     ): Promise<void> {
-        if (!this.connection) {
-            return; // No connection, skip diagnostics
-        }
+        try {
+            if (!this.connection) {
+                return; // No connection, skip diagnostics
+            }
 
-        const diagnostics = this.validate(content, options);
-        
-        await this.connection.sendDiagnostics({
-            uri: manifestUri,
-            diagnostics
-        });
+            const diagnostics = this.validate(content, options);
+            
+            await this.connection.sendDiagnostics({
+                uri: manifestUri,
+                diagnostics
+            });
+        } catch (error) {
+            console.error('Error in validateAndSendDiagnostics:', error);
+            // Send minimal error diagnostic instead of crashing
+            if (this.connection) {
+                await this.connection.sendDiagnostics({
+                    uri: manifestUri,
+                    diagnostics: [{
+                        severity: DiagnosticSeverity.Error,
+                        range: Range.create(Position.create(0, 0), Position.create(0, 1)),
+                        message: 'Internal error validating manifest file',
+                        source: 'domainlang'
+                    }]
+                });
+            }
+        }
     }
 
     /**
@@ -68,42 +84,53 @@ export class ManifestDiagnosticsService {
         content: string,
         options?: { requirePublishable?: boolean }
     ): Diagnostic[] {
-        // Parse YAML to get both the manifest object and source map
-        let yamlDoc: YAMLDocument.Parsed;
-        let manifest: ModelManifest;
-        
         try {
-            yamlDoc = YAML.parseDocument(content);
+            // Parse YAML to get both the manifest object and source map
+            let yamlDoc: YAMLDocument.Parsed;
+            let manifest: ModelManifest;
             
-            // Check for YAML parse errors (they're in the errors array, not thrown)
-            if (yamlDoc.errors && yamlDoc.errors.length > 0) {
-                return yamlDoc.errors.map(err => ({
+            try {
+                yamlDoc = YAML.parseDocument(content);
+                
+                // Check for YAML parse errors (they're in the errors array, not thrown)
+                if (yamlDoc.errors && yamlDoc.errors.length > 0) {
+                    return yamlDoc.errors.map(err => ({
+                        severity: DiagnosticSeverity.Error,
+                        range: this.yamlErrorToRange(err, content),
+                        message: `YAML parse error: ${err.message}`,
+                        source: 'domainlang'
+                    }));
+                }
+                
+                manifest = (yamlDoc.toJSON() ?? {}) as ModelManifest;
+            } catch (error) {
+                // Fallback for unexpected errors
+                const message = error instanceof Error ? error.message : 'Invalid YAML syntax';
+                return [{
                     severity: DiagnosticSeverity.Error,
-                    range: this.yamlErrorToRange(err, content),
-                    message: `YAML parse error: ${err.message}`,
+                    range: Range.create(Position.create(0, 0), Position.create(0, 1)),
+                    message: `YAML parse error: ${message}`,
                     source: 'domainlang'
-                }));
+                }];
             }
+
+            // Run manifest validation
+            const result = this.validator.validate(manifest, options);
             
-            manifest = (yamlDoc.toJSON() ?? {}) as ModelManifest;
+            // Convert to LSP diagnostics with source locations
+            return result.diagnostics.map(diag => 
+                this.toVSCodeDiagnostic(diag, yamlDoc)
+            );
         } catch (error) {
-            // Fallback for unexpected errors
-            const message = error instanceof Error ? error.message : 'Invalid YAML syntax';
+            console.error('Error in validate:', error);
+            // Return minimal error diagnostic
             return [{
                 severity: DiagnosticSeverity.Error,
                 range: Range.create(Position.create(0, 0), Position.create(0, 1)),
-                message: `YAML parse error: ${message}`,
+                message: 'Internal error during validation',
                 source: 'domainlang'
             }];
         }
-
-        // Run manifest validation
-        const result = this.validator.validate(manifest, options);
-        
-        // Convert to LSP diagnostics with source locations
-        return result.diagnostics.map(diag => 
-            this.toVSCodeDiagnostic(diag, yamlDoc)
-        );
     }
 
     /**
@@ -130,14 +157,19 @@ export class ManifestDiagnosticsService {
      * Call this when the file is closed or deleted.
      */
     async clearDiagnostics(manifestUri: string): Promise<void> {
-        if (!this.connection) {
-            return;
-        }
+        try {
+            if (!this.connection) {
+                return;
+            }
 
-        await this.connection.sendDiagnostics({
-            uri: manifestUri,
-            diagnostics: []
-        });
+            await this.connection.sendDiagnostics({
+                uri: manifestUri,
+                diagnostics: []
+            });
+        } catch (error) {
+            console.error('Error in clearDiagnostics:', error);
+            // Ignore - don't crash on cleanup
+        }
     }
 
     /**
@@ -147,20 +179,32 @@ export class ManifestDiagnosticsService {
         diag: ManifestDiagnostic,
         yamlDoc: YAMLDocument.Parsed
     ): Diagnostic {
-        const range = this.findRangeForPath(diag.path, yamlDoc);
-        
-        let message = diag.message;
-        if (diag.hint) {
-            message += `\nHint: ${diag.hint}`;
-        }
+        try {
+            const range = this.findRangeForPath(diag.path, yamlDoc);
+            
+            let message = diag.message;
+            if (diag.hint) {
+                message += `\nHint: ${diag.hint}`;
+            }
 
-        return {
-            severity: this.toVSCodeSeverity(diag.severity),
-            range,
-            message,
-            source: 'domainlang',
-            code: diag.code
-        };
+            return {
+                severity: this.toVSCodeSeverity(diag.severity),
+                range,
+                message,
+                source: 'domainlang',
+                code: diag.code
+            };
+        } catch (error) {
+            console.error('Error converting diagnostic:', error);
+            // Return minimal diagnostic at file start
+            return {
+                severity: DiagnosticSeverity.Error,
+                range: Range.create(Position.create(0, 0), Position.create(0, 1)),
+                message: diag.message,
+                source: 'domainlang',
+                code: diag.code
+            };
+        }
     }
 
     /**
@@ -198,8 +242,7 @@ export class ManifestDiagnosticsService {
                 return fallback;
             }
             
-            const mapNode = currentNode as YAMLMap;
-            const item = mapNode.items.find((pair): pair is Pair => 
+            const item = currentNode.items.find((pair): pair is Pair => 
                 isPair(pair) && isScalar(pair.key) && String(pair.key.value) === part
             );
 
@@ -208,7 +251,7 @@ export class ManifestDiagnosticsService {
             }
 
             // If this is the last part, return the range of the key
-            if (part === parts[parts.length - 1]) {
+            if (part === parts.at(-1)) {
                 const keyNode = item.key;
                 if (isScalar(keyNode) && keyNode.range) {
                     const [start, end] = keyNode.range;
@@ -269,9 +312,7 @@ let manifestDiagnosticsService: ManifestDiagnosticsService | undefined;
  * Gets or creates the manifest diagnostics service singleton.
  */
 export function getManifestDiagnosticsService(): ManifestDiagnosticsService {
-    if (!manifestDiagnosticsService) {
-        manifestDiagnosticsService = new ManifestDiagnosticsService();
-    }
+    manifestDiagnosticsService ??= new ManifestDiagnosticsService();
     return manifestDiagnosticsService;
 }