@domainlang/language 0.1.81

package/src/sdk/README.md

@@ -0,0 +1,297 @@
+# Model Query SDK
+
+Fluent, type-safe query API for DomainLang models.
+
+## SDK Architecture
+
+The SDK is **read-only and query-focused**. It provides:
+
+- Augmented AST properties (`effectiveClassification`, `effectiveTeam`, etc.)
+- Fluent query chains with lazy iteration
+- O(1) indexed lookups by FQN/name
+
+The SDK does **NOT** manage:
+
+- Workspace lifecycle (LSP/WorkspaceManager handles this)
+- File watching or change detection (LSP handles this)
+- Cross-file import resolution (DocumentBuilder handles this)
+
+## Entry Points by Deployment Target
+
+| Target | Entry Point | Browser-Safe | Notes |
+| --- | --- | --- | --- |
+| VS Code Extension | `fromDocument()` | ✅ | Zero-copy LSP integration |
+| Web Editor | `fromDocument()`, `loadModelFromText()` | ✅ | Browser-compatible |
+| CLI (Node.js) | `loadModel()` | ❌ | Requires `sdk/loader-node` |
+| Hosted LSP | `fromDocument()`, `fromServices()` | ✅ | Server-side |
+| Testing | `loadModelFromText()` | ✅ | In-memory parsing |
+
+## Installation
+
+The SDK is bundled with the `domain-lang-language` package:
+
+```typescript
+// Browser-safe imports (VS Code, web editor, testing)
+import { loadModelFromText, fromDocument, fromModel } from 'domain-lang-language/sdk';
+
+// Node.js CLI only (NOT browser-safe)
+import { loadModel } from 'domain-lang-language/sdk/loader-node';
+```
+
+## Entry Points
+
+### For Node.js CLI, Scripts
+
+```typescript
+// Note: This import requires Node.js filesystem
+import { loadModel } from 'domain-lang-language/sdk/loader-node';
+
+// Load from file (async)
+const { query, model } = await loadModel('./domains.dlang', {
+  workspaceDir: process.cwd()
+});
+```
+
+### For Testing, REPL, Web Editor
+
+```typescript
+import { loadModelFromText } from 'domain-lang-language/sdk';
+
+// Load from string (async, browser-safe)
+const { query } = await loadModelFromText(`
+  Domain Sales { vision: "Handle sales operations" }
+  bc OrderContext for Sales as Core
+`);
+```
+
+### For LSP, Validation (Zero-Copy)
+
+```typescript
+import { fromModel, fromDocument, fromServices } from 'domain-lang-language/sdk';
+
+// From Model node (sync)
+const query = fromModel(model);
+
+// From LangiumDocument (sync)
+const query = fromDocument(document);
+
+// From services + URI (sync)
+const query = fromServices(services, documentUri);
+```
+
+## Query API
+
+### Collections
+
+```typescript
+// All bounded contexts
+query.boundedContexts()
+
+// All domains
+query.domains()
+
+// All teams
+query.teams()
+
+// All classifications
+query.classifications()
+
+// All relationships
+query.relationships()
+
+// All context maps
+query.contextMaps()
+```
+
+### Fluent Chaining
+
+```typescript
+// Filter by strategic classification
+query.boundedContexts()
+  .withClassification('Core')
+  .withTeam('PaymentTeam')
+  .toArray()
+
+// Filter by domain
+query.boundedContexts()
+  .inDomain('Sales')
+  .withMetadata('Language', 'TypeScript')
+
+// Custom predicates
+query.domains()
+  .where(d => d.parent !== undefined)
+  .where(d => d.type?.ref?.name === 'Core')  // Direct reference access
+```
+
+### Direct Lookups (O(1))
+
+```typescript
+// By FQN
+const bc = query.byFqn<BoundedContext>('Sales.OrderContext');
+
+// By simple name
+const domain = query.domain('Sales');
+const context = query.boundedContext('OrderContext');
+
+// Get FQN
+const fqn = query.fqn(bc);
+```
+
+## SDK-Augmented Properties
+
+The SDK augments AST nodes **only for properties that add value beyond direct access**:
+
+### BoundedContext
+
+**Augmented (precedence resolution, transformation, computed):**
+
+```typescript
+bc.effectiveClassification // Inline header (`as`) → body (`classification:`) precedence
+bc.effectiveTeam         // Inline header (`by`) → body (`team:`) precedence  
+bc.metadataMap           // Metadata entries as ReadonlyMap<string, string>
+bc.fqn                   // Computed fully qualified name
+bc.hasClassification('Core') // Check if classification matches
+bc.hasTeam('SalesTeam')  // Check if team matches
+bc.hasMetadata('Lang')   // Check if metadata key exists
+```
+
+**Direct AST access (no augmentation needed):**
+
+```typescript
+bc.description           // Direct string property
+bc.businessModel?.ref    // Direct reference to Classification
+bc.evolution?.ref        // Direct reference to Classification
+bc.archetype?.ref        // Direct reference to Classification
+bc.relationships         // Direct array of Relationship
+bc.terminology           // Direct array of DomainTerm
+bc.decisions             // Direct array of AbstractDecision
+```
+
+### Domain
+
+**Augmented (computed):**
+
+```typescript
+domain.fqn                    // Computed fully qualified name
+domain.hasType('Core')         // Check type matches
+```
+
+**Direct AST access (no augmentation needed):**
+
+```typescript
+domain.description       // Direct string property
+domain.vision            // Direct string property
+domain.type?.ref         // Direct reference to Classification
+```
+
+## Examples
+
+### Find All Core Contexts with C# Stack
+
+```typescript
+const { query } = await loadModel('./banking.dlang');
+
+const results = query.boundedContexts()
+  .withClassification('Core')
+  .withMetadata('Language', 'CSharp')
+  .toArray();
+
+for (const bc of results) {
+  console.log(`${bc.fqn}: ${bc.description ?? 'n/a'}`);
+  console.log(`  Team: ${bc.effectiveTeam?.name ?? 'unassigned'}`);
+  console.log(`  Evolution: ${bc.evolution?.ref?.name ?? 'n/a'}`);
+}
+```
+
+### List All Relationships for a Domain
+
+```typescript
+const sales = query.domain('Sales');
+
+const relationships = query.relationships()
+  .where(rel =>
+    rel.left.domain?.ref?.name === 'Sales' ||
+    rel.right.domain?.ref?.name === 'Sales'
+  );
+
+for (const rel of relationships) {
+  const type = rel.type ?? rel.inferredType ?? 'unknown';
+  console.log(`${rel.left.name} ${rel.arrow} ${rel.right.name} [${type}]`);
+}
+```
+
+
+### Extract Documentation
+
+```typescript
+const docs = query.boundedContexts()
+  .where(bc => bc.description !== undefined)
+  .toArray()
+  .map(bc => ({
+    fqn: bc.fqn,
+    description: bc.description,
+    team: bc.effectiveTeam?.name,
+    metadata: Object.fromEntries(bc.metadataMap),
+  }));
+
+console.log(JSON.stringify(docs, null, 2));
+```
+
+## Resolution Rules
+
+The SDK provides precedence resolution **only for properties with multiple assignment locations**:
+
+| Augmented Property | Precedence | Why Augmented |
+| --- | --- | --- |
+| `bc.effectiveClassification` | Header inline (`as`) → body (`classification:`) | Array-based precedence |
+| `bc.effectiveTeam` | Header inline (`by`) → body (`team:`) | Array-based precedence |
+| `bc.metadataMap` | Later entries override earlier | Array to Map conversion |
+
+**Direct access (no precedence needed):**
+
+| Property | Access Pattern | Why Direct |
+| --- | --- | --- |
+| `bc.description` | Direct | Single location |
+| `bc.businessModel?.ref` | Direct reference | Single location |
+| `bc.evolution?.ref` | Direct reference | Single location |
+| `bc.archetype?.ref` | Direct reference | Single location |
+| `domain.description` | Direct | Single location |
+| `domain.vision` | Direct | Single location |
+| `domain.type?.ref` | Direct reference | Single location |
+
+## Performance
+
+- **O(1) lookups**: `byFqn()`, indexed team/classification/metadata filters
+- **Lazy iteration**: QueryBuilder chains don't materialize until consumed
+- **Zero-copy**: `fromModel()` / `fromDocument()` reuse existing AST
+
+## Architecture
+
+The SDK is an **internal module** within the language package:
+
+```text
+packages/language/src/sdk/
+├── index.ts          # Public API
+├── types.ts          # Type definitions
+├── query.ts          # Query & QueryBuilder
+├── resolution.ts     # Property resolution (internal)
+├── indexes.ts        # Index building (internal)
+└── loader.ts         # loadModel functions (internal)
+```
+
+### Internal vs Public
+
+**Public** (exported from `sdk/index.ts`):
+
+- `loadModel`, `loadModelFromText`
+- `fromModel`, `fromDocument`, `fromServices`
+- `Query`, `QueryBuilder`, `BcQueryBuilder`
+- Type definitions
+
+**Internal** (not exported):
+
+- `effectiveClassification`, `effectiveTeam`, `metadataAsMap`, etc.
+- `buildIndexes`, `buildFqnIndex`, etc.
+- Implementation classes
+
+Use SDK-augmented properties (`bc.effectiveClassification`) instead of calling resolution functions directly.

package/src/sdk/ast-augmentation.ts

@@ -0,0 +1,157 @@
+/**
+ * SDK AST Augmentation - Module augmentation for native SDK properties.
+ *
+ * This file uses TypeScript's declaration merging to add computed helpers
+ * directly to the AST types. After importing this module, BoundedContext,
+ * Domain, and Relationship instances expose convenience getters.
+ *
+ * **Only properties that add value beyond direct AST access are augmented:**
+ * - Precedence resolution: `effectiveClassification`, `effectiveTeam` (for array-based properties)
+ * - Data transformation: `metadataMap` (array to Map)
+ * - Computed values: `fqn` (fully qualified name)
+ * - Helper methods: `hasClassification()`, `hasTeam()`, `hasMetadata()`, `hasType()`
+ *
+ * **Direct AST access (no augmentation needed):**
+ * - `bc.description` - Direct string property
+ * - `bc.businessModel?.ref` - Direct reference
+ * - `bc.evolution?.ref` - Direct reference
+ * - `bc.archetype?.ref` - Direct reference
+ * - `domain.description` - Direct string property
+ * - `domain.vision` - Direct string property
+ * - `domain.type?.ref` - Direct reference
+ *
+ * **Usage:**
+ * ```typescript
+ * import '../sdk/ast-augmentation.js'; // Enable augmented properties
+ * import { fromDocument } from '../sdk/index.js';
+ *
+ * fromDocument(document); // Ensures augmentation
+ * const bc: BoundedContext = ...;
+ * console.log(bc.effectiveClassification?.name);
+ * console.log(bc.metadataMap.get('Language'));
+ * // Direct access for simple properties:
+ * console.log(bc.businessModel?.ref?.name);
+ * ```
+ *
+ * **Properties added to BoundedContext:**
+ * - `effectiveClassification` - Inline `as` header → body `classification:`
+ * - `effectiveTeam` - Inline `team` header → body `team:`
+ * - `metadataMap` - Metadata entries exposed as a ReadonlyMap
+ * - `fqn` - Computed fully qualified name
+ * - `hasClassification(name)` - Check if classification matches
+ * - `hasTeam(name)` - Check if team matches
+ * - `hasMetadata(key, value?)` - Check metadata
+ *
+ * **Properties added to Domain:**
+ * - `fqn` - Computed fully qualified name
+ * - `hasType(name)` - Check type matches
+ *
+ * **Properties added to Relationship:**
+ * - `hasPattern(pattern)` - Check if pattern exists on either side
+ * - `hasLeftPattern(pattern)` - Check left patterns
+ * - `hasRightPattern(pattern)` - Check right patterns
+ * - `isUpstream(side)` - Check if side is upstream
+ * - `isDownstream(side)` - Check if side is downstream
+ * - `isBidirectional` - Check if relationship is bidirectional
+ * - `leftContextName` - Resolved name of left context
+ * - `rightContextName` - Resolved name of right context
+ *
+ * @module sdk/ast-augmentation
+ */
+
+// Note: Types are referenced directly via import('...').TypeName in the declare module
+// to avoid importing and re-exporting type-only modules that cause compilation issues
+
+/**
+ * Module augmentation for native SDK properties on AST types.
+ */
+declare module '../generated/ast.js' {
+    /**
+     * Augmented BoundedContext with SDK-computed properties.
+     * 
+    * Note: description, businessModel, evolution, archetype, metadata, relationships,
+     * terminology, and decisions are direct AST properties - use them directly.
+     */
+    interface BoundedContext {
+        /** Effective classification with inline precedence (header `as` > body `classification:`) */
+        readonly effectiveClassification: import('../generated/ast.js').Classification | undefined;
+
+        /** Effective team with inline precedence (header `by` > body `team:`) */
+        readonly effectiveTeam: import('../generated/ast.js').Team | undefined;
+
+        /** Metadata entries exposed as a map for O(1) lookups */
+        readonly metadataMap: ReadonlyMap<string, string>;
+
+        /** SDK-computed fully qualified name */
+        readonly fqn: string;
+
+        /** Checks if this bounded context has the specified classification. */
+        hasClassification(name: string | import('../generated/ast.js').Classification): boolean;
+
+        /** Checks if this bounded context is owned by the specified team. */
+        hasTeam(name: string | import('../generated/ast.js').Team): boolean;
+
+        /** Checks if this bounded context has metadata with the given key (and optionally value). */
+        hasMetadata(key: string, value?: string): boolean;
+    }
+
+    /**
+     * Augmented Domain with SDK-computed properties.
+     * 
+     * Note: description, vision, and type are direct AST properties - use them directly.
+     */
+    interface Domain {
+        /** SDK-computed fully qualified name */
+        readonly fqn: string;
+
+        /** Checks if this domain has the specified type. */
+        hasType(name: string | import('../generated/ast.js').Classification): boolean;
+    }
+
+    /**
+     * Augmented Relationship with SDK helper methods.
+     */
+    interface Relationship {
+        /** Resolved name of left context (handles 'this') */
+        readonly leftContextName: string;
+        /** Resolved name of right context (handles 'this') */
+        readonly rightContextName: string;
+        /** Whether this is a bidirectional relationship (<->) */
+        readonly isBidirectional: boolean;
+        
+        /**
+         * Checks if the relationship has a specific integration pattern on either side.
+         * Accepts both abbreviations (SK, ACL) and full names (SharedKernel, AntiCorruptionLayer).
+         * @param pattern - Pattern abbreviation or full name
+         */
+        hasPattern(pattern: import('./patterns.js').IntegrationPattern | string): boolean;
+        
+        /**
+         * Checks if the left side has a specific integration pattern.
+         * @param pattern - Pattern abbreviation or full name
+         */
+        hasLeftPattern(pattern: import('./patterns.js').IntegrationPattern | string): boolean;
+        
+        /**
+         * Checks if the right side has a specific integration pattern.
+         * @param pattern - Pattern abbreviation or full name
+         */
+        hasRightPattern(pattern: import('./patterns.js').IntegrationPattern | string): boolean;
+        
+        /**
+         * Checks if the specified side is upstream (provider) in this relationship.
+         * @param side - 'left' or 'right'
+         */
+        isUpstream(side: 'left' | 'right'): boolean;
+        
+        /**
+         * Checks if the specified side is downstream (consumer) in this relationship.
+         * @param side - 'left' or 'right'
+         */
+        isDownstream(side: 'left' | 'right'): boolean;
+    }
+}
+
+// Export nothing - this file is purely for type augmentation
+// The actual implementation is in query.ts via Object.defineProperties
+export {};

package/src/sdk/index.ts

@@ -0,0 +1,128 @@
+/**
+ * Model Query SDK - Public API
+ * 
+ * Provides fluent, type-safe query operations on DomainLang models.
+ * 
+ * ## Architecture: SDK vs LSP Responsibilities
+ * 
+ * The SDK is **read-only and query-focused**. It does NOT manage:
+ * - Workspace lifecycle (LSP/WorkspaceManager handles this)
+ * - File watching or change detection (LSP/TextDocuments handles this)
+ * - Cross-file import resolution (LSP/DocumentBuilder handles this)
+ * - Document validation scheduling (LSP handles this)
+ * 
+ * **SDK responsibilities:**
+ * - Augmented AST properties (transparent property access with precedence rules)
+ * - Fluent query chains with lazy iteration
+ * - O(1) indexed lookups by FQN/name
+ * - Resolution rules (which block wins for 0..1 properties)
+ * 
+ * **Entry points for different deployment targets:**
+ * 
+ * | Target | Entry Point | Browser-Safe | Notes |
+ * |--------|-------------|--------------|-------|
+ * | 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 |
+ * | 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
+ * 
+ * For file-based loading in Node.js CLI tools:
+ * ```typescript
+ * import { loadModel } from 'domain-lang-language/sdk/loader-node';
+ * ```
+ * 
+ * @packageDocumentation
+ * 
+ * @example
+ * ```typescript
+ * // Node.js CLI: Load from file (requires sdk/loader-node)
+ * import { loadModel } from 'domain-lang-language/sdk/loader-node';
+ * 
+ * const { query } = await loadModel('./domains.dlang', {
+ *   workspaceDir: process.cwd()
+ * });
+ * 
+ * const coreContexts = query.boundedContexts()
+ *   .withClassification('Core')
+ *   .withTeam('PaymentTeam');
+ * 
+ * for (const bc of coreContexts) {
+ *   console.log(`${bc.name}: ${bc.description ?? 'n/a'}`);
+ * }
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // Browser/Testing: Load from text (browser-safe)
+ * import { loadModelFromText } from '@domainlang/language/sdk';
+ * 
+ * const { query } = await loadModelFromText(`
+ *   Domain Sales { vision: "Handle sales" }
+ *   bc OrderContext for Sales
+ * `);
+ * 
+ * const sales = query.domain('Sales');
+ * console.log(sales?.vision);
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // LSP Integration: Zero-copy access to existing AST (browser-safe)
+ * import { fromDocument } from '@domainlang/language/sdk';
+ * 
+ * export class HoverProvider {
+ *   getHover(document: LangiumDocument<Model>) {
+ *     // SDK wraps existing AST - no reloading, no file I/O
+ *     const query = fromDocument(document);
+ *     const bc = query.boundedContext('OrderContext');
+ *     return bc?.description;
+ *   }
+ * }
+ * ```
+ */
+
+// Browser-safe entry points
+export { loadModelFromText } from './loader.js';
+export { fromModel, fromDocument, fromServices, augmentModel } from './query.js';
+
+// Note: loadModel() is NOT exported here - it requires Node.js filesystem
+// For CLI/Node.js usage: import { loadModel } from '@domainlang/language/sdk/loader-node';
+
+// Integration patterns for type-safe pattern matching (no magic strings)
+export {
+    Pattern,
+    PatternFullName,
+    PatternAliases,
+    matchesPattern,
+    isUpstreamPattern,
+    isDownstreamPattern,
+    isMutualPattern,
+    UpstreamPatterns,
+    DownstreamPatterns,
+    MutualPatterns,
+} from './patterns.js';
+
+export type { IntegrationPattern } from './patterns.js';
+
+// AST augmentation - import for type declarations
+// Usage: import '@domainlang/language/sdk/ast-augmentation';
+// This enables native SDK properties on AST types via declaration merging
+
+// Public types
+export type {
+    Query,
+    QueryBuilder,
+    QueryContext,
+    LoadOptions,
+    BcQueryBuilder,
+    RelationshipView,
+    AugmentedBoundedContext,
+    AugmentedDomain,
+} from './types.js';