@domainlang/language 0.6.0 → 0.8.0

package/src/sdk/query.ts

@@ -137,9 +137,7 @@ class QueryImpl implements Query {
      * Lazily builds and caches indexes on first access.
      */
     private getIndexes(): ModelIndexes {
-        if (!this.indexes) {
-            this.indexes = buildIndexes(this.model);
-        }
+        this.indexes ??= buildIndexes(this.model);
         return this.indexes;
     }
 
@@ -202,7 +200,12 @@ class QueryImpl implements Query {
 
     /** @internal Generator for relationship iteration */
     private *iterateRelationships(): Generator<RelationshipView> {
-        // Collect relationships defined on bounded contexts
+        yield* this.collectBoundedContextRelationships();
+        yield* this.collectContextMapRelationships();
+    }
+
+    /** @internal Collects relationships from bounded contexts */
+    private *collectBoundedContextRelationships(): Generator<RelationshipView> {
         for (const node of AstUtils.streamAllContents(this.model)) {
             if (isBoundedContext(node)) {
                 for (const rel of node.relationships) {
@@ -213,8 +216,10 @@ class QueryImpl implements Query {
                 }
             }
         }
+    }
 
-        // Collect from ContextMap.relationships
+    /** @internal Collects relationships from context maps */
+    private *collectContextMapRelationships(): Generator<RelationshipView> {
         for (const node of AstUtils.streamAllContents(this.model)) {
             if (isContextMap(node)) {
                 for (const rel of node.relationships) {
@@ -442,10 +447,9 @@ class QueryBuilderImpl<T> implements QueryBuilder<T> {
     }
 
     first(): T | undefined {
-        for (const item of this) {
-            return item;
-        }
-        return undefined;
+        const iterator = this[Symbol.iterator]();
+        const result = iterator.next();
+        return result.done ? undefined : result.value;
     }
 
     toArray(): T[] {
@@ -554,7 +558,7 @@ class BcQueryBuilderImpl extends QueryBuilderImpl<BoundedContext> implements BcQ
  * Escapes special regex characters in a string.
  */
 function escapeRegex(str: string): string {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return str.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
 }
 
 /**
@@ -780,7 +784,7 @@ function augmentModelInternal(model: Model): void {
         } else if (isContextMap(node)) {
             // Augment relationships in context maps (no containing BC)
             for (const rel of node.relationships) {
-                augmentRelationship(rel, undefined);
+                augmentRelationship(rel);
             }
         }
     }

package/src/services/import-resolver.ts

@@ -1,10 +1,16 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { URI, type LangiumDocument } from 'langium';
+import { DocumentState, SimpleCache, WorkspaceCache, URI, type LangiumDocument, type LangiumSharedCoreServices } from 'langium';
 import { WorkspaceManager } from './workspace-manager.js';
 import type { DomainLangServices } from '../domain-lang-module.js';
 import type { LockFile } from './types.js';
 
+/**
+ * Cache interface for import resolution.
+ * Uses WorkspaceCache in LSP mode (clears on ANY document change) or SimpleCache in standalone mode.
+ */
+type ResolverCache = WorkspaceCache<string, URI> | SimpleCache<string, URI>;
+
 /**
  * ImportResolver resolves import statements using manifest-centric rules (PRS-010).
  *
@@ -17,21 +23,66 @@ import type { LockFile } from './types.js';
  * - ./types → ./types/index.dlang → ./types.dlang
  * - Module entry defaults to index.dlang (no model.yaml required)
  * 
- * Performance:
- * - Resolution results are cached per (document URI + specifier) pair
- * - Cache is invalidated when model.yaml or model.lock changes
+ * Caching Strategy (uses Langium standard infrastructure):
+ * - LSP mode: Uses `WorkspaceCache` - clears on ANY document change in workspace
+ *   This is necessary because file moves/deletes affect resolution of OTHER documents
+ * - Standalone mode: Uses `SimpleCache` - manual invalidation via clearCache()
+ * 
+ * Why WorkspaceCache (not DocumentCache)?
+ * - DocumentCache only invalidates when the KEYED document changes
+ * - But import resolution can break when IMPORTED files are moved/deleted
+ * - Example: index.dlang imports @domains → domains/index.dlang
+ *   If domains/index.dlang is moved, index.dlang's cache entry must be cleared
+ *   DocumentCache wouldn't clear it (index.dlang didn't change)
+ *   WorkspaceCache clears on ANY change, ensuring correct re-resolution
+ * 
+ * @see https://langium.org/docs/recipes/caching/ for Langium caching patterns
  */
 export class ImportResolver {
     private readonly workspaceManager: WorkspaceManager;
-    private readonly resolverCache = new Map<string, URI>();
+    /**
+     * Workspace-level cache for resolved import URIs.
+     * In LSP mode: WorkspaceCache - clears when ANY document changes (correct for imports)
+     * In standalone mode: SimpleCache - manual invalidation via clearCache()
+     */
+    private readonly resolverCache: ResolverCache;
 
+    /**
+     * Creates an ImportResolver.
+     * 
+     * @param services - DomainLang services. If `services.shared` is present, uses WorkspaceCache
+     *                   for automatic invalidation. Otherwise uses SimpleCache for standalone mode.
+     */
     constructor(services: DomainLangServices) {
         this.workspaceManager = services.imports.WorkspaceManager;
+        
+        // Use Langium's WorkspaceCache when shared services are available (LSP mode)
+        // Fall back to SimpleCache for standalone utilities (SDK, CLI)
+        const shared = (services as DomainLangServices & { shared?: LangiumSharedCoreServices }).shared;
+        if (shared) {
+            // LSP mode: WorkspaceCache with DocumentState.Linked
+            // 
+            // This follows the standard pattern used by TypeScript, rust-analyzer, gopls:
+            // - Cache is valid for a "workspace snapshot"
+            // - Invalidates after a batch of changes completes linking (debounced ~300ms)
+            // - Invalidates immediately on file deletion
+            // - Does NOT invalidate during typing (would be too expensive)
+            //
+            // DocumentState.Linked is the right phase because:
+            // - Import resolution is needed during linking
+            // - By the time linking completes, we know which files exist
+            // - File renames appear as delete+create, triggering immediate invalidation
+            this.resolverCache = new WorkspaceCache(shared, DocumentState.Linked);
+        } else {
+            // Standalone mode: simple key-value cache, manual invalidation
+            this.resolverCache = new SimpleCache<string, URI>();
+        }
     }
 
     /**
-     * Clears the import resolution cache.
-     * Call this when model.yaml or model.lock changes.
+     * Clears the entire import resolution cache.
+     * In LSP mode, this is also triggered automatically by WorkspaceCache on any document change.
+     * Call explicitly when model.yaml or model.lock changes.
      */
     clearCache(): void {
         this.resolverCache.clear();
@@ -39,10 +90,10 @@ export class ImportResolver {
 
     /**
      * Resolve an import specifier relative to a Langium document.
-     * Results are cached for performance.
+     * Results are cached using WorkspaceCache (clears on any workspace change).
      */
     async resolveForDocument(document: LangiumDocument, specifier: string): Promise<URI> {
-        // Check cache first (key: document URI + specifier)
+        // Cache key combines document URI + specifier for uniqueness
         const cacheKey = `${document.uri.toString()}|${specifier}`;
         const cached = this.resolverCache.get(cacheKey);
         if (cached) {

package/src/services/package-boundary-detector.ts

@@ -0,0 +1,238 @@
+/**
+ * Package Boundary Detector
+ * 
+ * Determines package boundaries for import scoping.
+ * Per ADR-003, package boundaries are defined by:
+ * - External packages: Files within .dlang/packages/ sharing the same model.yaml
+ * - Local files: Each file is its own boundary (non-transitive)
+ * 
+ * Used by DomainLangScopeProvider to enable transitive imports within
+ * package boundaries while keeping local file imports non-transitive.
+ */
+
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+import { URI } from 'langium';
+
+/**
+ * Detects and caches package boundaries for efficient scope resolution.
+ */
+export class PackageBoundaryDetector {
+    /**
+     * Cache mapping document URI to its package root path.
+     * - External packages: path to directory containing model.yaml
+     * - Local files: null (no package boundary)
+     */
+    private readonly packageRootCache = new Map<string, string | null>();
+
+    /**
+     * Determines if a document is part of an external package.
+     * 
+     * External packages are stored in .dlang/packages/owner/repo/commit/
+     * 
+     * @param documentUri - The URI of the document to check
+     * @returns true if document is in an external package
+     */
+    isExternalPackage(documentUri: URI | string): boolean {
+        const fsPath = this.toFsPath(documentUri);
+        const normalized = fsPath.split(path.sep);
+        
+        // Check if path contains .dlang/packages/
+        const dlangIndex = normalized.indexOf('.dlang');
+        if (dlangIndex === -1) {
+            return false;
+        }
+        
+        return dlangIndex + 1 < normalized.length && 
+               normalized[dlangIndex + 1] === 'packages';
+    }
+
+    /**
+     * Gets the package root for a document.
+     * 
+     * For external packages (.dlang/packages/), walks up from the document
+     * to find the nearest model.yaml file within the package structure.
+     * 
+     * For local files, returns null (no package boundary).
+     * 
+     * @param documentUri - The URI of the document
+     * @returns Absolute path to package root, or null if not in a package
+     */
+    async getPackageRoot(documentUri: URI | string): Promise<string | null> {
+        const uriString = documentUri.toString();
+        
+        // Check cache first
+        if (this.packageRootCache.has(uriString)) {
+            return this.packageRootCache.get(uriString) ?? null;
+        }
+        
+        // If not an external package, it has no package boundary
+        if (!this.isExternalPackage(documentUri)) {
+            this.packageRootCache.set(uriString, null);
+            return null;
+        }
+        
+        const fsPath = this.toFsPath(documentUri);
+        const packageRoot = await this.findPackageRootForExternal(fsPath);
+        this.packageRootCache.set(uriString, packageRoot);
+        return packageRoot;
+    }
+
+    /**
+     * Checks if two documents are in the same package (synchronous heuristic).
+     * 
+     * This is a fast, synchronous check that compares package commit directories
+     * without filesystem access. Documents are in the same package if:
+     * - Both are in .dlang/packages/ AND
+     * - They share the same owner/repo/commit path
+     * 
+     * This is used by the scope provider which needs synchronous access.
+     * 
+     * Structure: .dlang/packages/owner/repo/commit/...
+     * 
+     * @param doc1Uri - URI of first document
+     * @param doc2Uri - URI of second document
+     * @returns true if both are in the same package commit directory
+     */
+    areInSamePackageSync(doc1Uri: URI | string, doc2Uri: URI | string): boolean {
+        // Both must be external packages
+        if (!this.isExternalPackage(doc1Uri) || !this.isExternalPackage(doc2Uri)) {
+            return false;
+        }
+        
+        const path1 = this.toFsPath(doc1Uri);
+        const path2 = this.toFsPath(doc2Uri);
+        
+        const root1 = this.getPackageCommitDirectory(path1);
+        const root2 = this.getPackageCommitDirectory(path2);
+        
+        return root1 !== null && root1 === root2;
+    }
+
+    /**
+     * Gets the package commit directory (owner/repo/commit) from a path.
+     * 
+     * @param fsPath - Filesystem path
+     * @returns Commit directory path or null
+     */
+    private getPackageCommitDirectory(fsPath: string): string | null {
+        const normalized = fsPath.split(path.sep);
+        const dlangIndex = normalized.indexOf('.dlang');
+        
+        if (dlangIndex === -1) {
+            return null;
+        }
+        
+        const packagesIndex = dlangIndex + 1;
+        if (packagesIndex >= normalized.length || normalized[packagesIndex] !== 'packages') {
+            return null;
+        }
+        
+        // Commit directory is at: .dlang/packages/owner/repo/commit
+        const commitIndex = packagesIndex + 3;
+        if (commitIndex >= normalized.length) {
+            return null;
+        }
+        
+        // Return the path up to and including the commit directory
+        return normalized.slice(0, commitIndex + 1).join(path.sep);
+    }
+
+    /**
+     * Checks if two documents are in the same package.
+     * 
+     * Documents are in the same package if:
+     * - Both are external packages AND
+     * - They share the same package root (model.yaml location)
+     * 
+     * Local files are never in the same package (each is isolated).
+     * 
+     * @param doc1Uri - URI of first document
+     * @param doc2Uri - URI of second document
+     * @returns true if both documents are in the same package
+     */
+    async areInSamePackage(doc1Uri: URI | string, doc2Uri: URI | string): Promise<boolean> {
+        const root1 = await this.getPackageRoot(doc1Uri);
+        const root2 = await this.getPackageRoot(doc2Uri);
+        
+        // If either is not in a package, they can't be in the same package
+        if (!root1 || !root2) {
+            return false;
+        }
+        
+        return root1 === root2;
+    }
+
+    /**
+     * Finds the package root for an external package by walking up to find model.yaml.
+     * 
+     * External packages have structure: .dlang/packages/owner/repo/commit/...
+     * The model.yaml should be at the commit level or just below it.
+     * 
+     * @param fsPath - Filesystem path of the document
+     * @returns Path to directory containing model.yaml, or null
+     */
+    private async findPackageRootForExternal(fsPath: string): Promise<string | null> {
+        const normalized = fsPath.split(path.sep);
+        const dlangIndex = normalized.indexOf('.dlang');
+        
+        if (dlangIndex === -1) {
+            return null;
+        }
+        
+        // Find the packages directory
+        const packagesIndex = dlangIndex + 1;
+        if (packagesIndex >= normalized.length || normalized[packagesIndex] !== 'packages') {
+            return null;
+        }
+        
+        // Start from the commit directory level
+        // Structure: .dlang/packages/owner/repo/commit/
+        const commitIndex = packagesIndex + 3;
+        if (commitIndex >= normalized.length) {
+            return null;
+        }
+        
+        // Walk up from the document path to the commit directory
+        let currentPath = path.dirname(fsPath);
+        const commitPath = normalized.slice(0, commitIndex + 1).join(path.sep);
+        
+        // Search upward for model.yaml, but don't go above the commit directory
+        while (currentPath.length >= commitPath.length) {
+            const manifestPath = path.join(currentPath, 'model.yaml');
+            try {
+                await fs.access(manifestPath);
+                return currentPath;
+            } catch {
+                // model.yaml not found at this level, continue upward
+            }
+            
+            const parent = path.dirname(currentPath);
+            if (parent === currentPath) {
+                // Reached filesystem root without finding model.yaml
+                break;
+            }
+            currentPath = parent;
+        }
+        
+        return null;
+    }
+
+    /**
+     * Converts a URI to a filesystem path.
+     */
+    private toFsPath(uri: URI | string): string {
+        if (typeof uri === 'string') {
+            uri = URI.parse(uri);
+        }
+        return uri.fsPath;
+    }
+
+    /**
+     * Clears the package root cache.
+     * Call this when packages are installed/removed.
+     */
+    clearCache(): void {
+        this.packageRootCache.clear();
+    }
+}

package/src/services/performance-optimizer.ts

@@ -76,7 +76,8 @@ export class PerformanceOptimizer {
 
         try {
             const content = await fs.readFile(manifestPath, 'utf-8');
-            const manifest = JSON.parse(content);
+            const { parse } = await import('yaml');
+            const manifest: unknown = parse(content);
 
             this.manifestCache.set(cacheKey, {
                 value: manifest,
@@ -127,7 +128,10 @@ export class PerformanceOptimizer {
                 const stat = await fs.stat(lockPath);
                 const cached = this.lockFileCache.get(workspaceRoot);
                 
-                if (cached && stat.mtimeMs > cached.timestamp) {
+                // Floor mtimeMs to integer precision to match Date.now() —
+                // some filesystems (e.g. APFS) report sub-millisecond mtime,
+                // which can exceed the integer timestamp from Date.now().
+                if (cached && Math.floor(stat.mtimeMs) > cached.timestamp) {
                     stale.push(workspaceRoot);
                 }
             } catch {

package/src/services/types.ts

@@ -42,6 +42,31 @@
 // Core Building Blocks
 // ============================================================================
 
+/**
+ * Information about an import statement tracked during indexing.
+ * 
+ * Used by IndexManager to track both the import's resolved location
+ * and its alias (if any) for scope resolution.
+ * 
+ * @example
+ * ```typescript
+ * // import "larsbaunwall/ddd-types" as ddd
+ * const info: ImportInfo = {
+ *   specifier: "larsbaunwall/ddd-types",
+ *   alias: "ddd",
+ *   resolvedUri: "file:///.dlang/packages/larsbaunwall/ddd-types/abc123/index.dlang"
+ * };
+ * ```
+ */
+export interface ImportInfo {
+    /** The import specifier as written in source (e.g., "./file.dlang", "owner/repo") */
+    readonly specifier: string;
+    /** Optional alias from 'as' clause (e.g., "ddd" in 'import "pkg" as ddd') */
+    readonly alias?: string;
+    /** Resolved absolute URI of the imported document */
+    readonly resolvedUri: string;
+}
+
 /**
  * Type of git reference for version pinning.
  *