@domainlang/language 0.7.0 → 0.9.0

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

@@ -6,12 +6,18 @@
  * - Grammar-aligned: Completions match grammar structure exactly
  * - Simple: Uses parent node to determine context
  * - Maintainable: Clear mapping from grammar to completions
+ * - Import-aware: Provides completions for local paths, aliases, and dependencies
  */
 
-import type { AstNode } from 'langium';
+import type { AstNode, AstNodeDescription, LangiumDocument, ReferenceInfo } from 'langium';
+import { AstUtils, GrammarAST } from 'langium';
 import { CompletionAcceptor, CompletionContext, DefaultCompletionProvider, NextFeature } from 'langium/lsp';
-import { CompletionItemKind, InsertTextFormat } from 'vscode-languageserver';
+import { CompletionItemKind, CompletionList, InsertTextFormat, TextEdit } from 'vscode-languageserver';
+import type { CancellationToken, CompletionItem, CompletionParams } from 'vscode-languageserver-protocol';
 import * as ast from '../generated/ast.js';
+import type { DomainLangServices } from '../domain-lang-module.js';
+import type { WorkspaceManager } from '../services/workspace-manager.js';
+import type { ModelManifest, DependencySpec } from '../services/types.js';
 
 /**
  * Top-level snippet templates for creating new AST nodes.
@@ -118,33 +124,446 @@ const TOP_LEVEL_SNIPPETS = [
 ] as const;
 
 export class DomainLangCompletionProvider extends DefaultCompletionProvider {
-    protected override completionFor(
+    private readonly workspaceManager: WorkspaceManager;
+
+    override readonly completionOptions = {
+        triggerCharacters: ['.']
+    };
+
+    constructor(services: DomainLangServices) {
+        super(services);
+        this.workspaceManager = services.imports.WorkspaceManager;
+    }
+
+    /**
+     * Override getCompletion to handle import string completions for incomplete strings.
+     *
+     * **Why this override is necessary:**
+     * When the cursor sits inside an incomplete string token (e.g. `import "partial`)
+     * Langium's lexer cannot produce a valid STRING token, so `completionFor()` never
+     * fires for the `uri` property.  This override detects the incomplete-string case
+     * via regex and returns completions directly.  For all other positions the parent
+     * implementation (which routes through `completionFor`) is used.
+     */
+    override async getCompletion(
+        document: LangiumDocument,
+        params: CompletionParams,
+        cancelToken?: CancellationToken
+    ): Promise<CompletionList | undefined> {
+        const text = document.textDocument.getText();
+        const offset = document.textDocument.offsetAt(params.position);
+        const textBefore = text.substring(0, offset);
+
+        // Pattern: import "partial_text (opening quote, no closing quote)
+        const importStringPattern = /\b(import|Import)\s+"([^"]*)$/;
+        const match = importStringPattern.exec(textBefore);
+
+        if (match) {
+            const currentInput = match[2];
+            const items = await this.collectImportItems(currentInput);
+            return CompletionList.create(items, true);
+        }
+
+        const result = await super.getCompletion(document, params, cancelToken);
+        return this.segmentDottedCompletions(result, text, offset, document);
+    }
+
+    /**
+     * Post-process completion results to replace full-FQN items with segmented items
+     * when the cursor is at a dotted path.
+     *
+     * **Why this is necessary:**
+     * Langium's `buildContexts` creates a "data type rule" context that triggers our
+     * `completionForCrossReference` override, which correctly produces segmented items.
+     * However, when the CST is broken (e.g., partial `Core.B` doesn't fully parse as
+     * a QualifiedName), `findDataTypeRuleStart` returns `undefined` and only token-based
+     * contexts fire. These contexts have features that are ID terminals (not cross-references),
+     * so `completionForCrossReference` is never called. Langium's default pipeline then
+     * produces full-FQN items like `Core.Baunwalls.Jannie`.
+     *
+     * This post-processing step catches those FQN items and segments them,
+     * ensuring consistent behavior regardless of parse state.
+     */
+    private segmentDottedCompletions(
+        result: CompletionList | undefined,
+        text: string,
+        offset: number,
+        _document: LangiumDocument
+    ): CompletionList | undefined {
+        if (!result?.items?.length) return result;
+
+        // Detect dotted path at cursor by scanning backwards
+        const dottedPath = this.extractDottedPathAtCursor(text, offset);
+        if (!dottedPath) return result;
+
+        const { fullTyped, fullStart } = dottedPath;
+        const lastDotIndex = fullTyped.lastIndexOf('.');
+        const prefix = fullTyped.substring(0, lastDotIndex + 1);
+        const partial = fullTyped.substring(lastDotIndex + 1);
+
+        // If completionForCrossReference already produced segmented items, just clean up
+        if (this.hasSegmentedItems(result.items, prefix)) {
+            return this.removeLeakedFqnItems(result, prefix);
+        }
+
+        // No segmented items — transform FQN items into segmented items
+        const positions = this.calculateTextPositions(text, offset, fullStart);
+        const newItems = this.transformToSegmentedItems(
+            result.items, prefix, partial, fullTyped, positions
+        );
+        return CompletionList.create(newItems, true);
+    }
+
+    /** Check if any items are already segmented by our completionForCrossReference. */
+    private hasSegmentedItems(items: CompletionItem[], prefix: string): boolean {
+        return items.some(item =>
+            !item.label.includes('.') && item.filterText?.startsWith(prefix)
+        );
+    }
+
+    /** Remove full-FQN items that leaked alongside segmented items. */
+    private removeLeakedFqnItems(
+        result: CompletionList,
+        prefix: string
+    ): CompletionList {
+        const prefixRoot = prefix.substring(0, prefix.length - 1);
+        result.items = result.items.filter(item =>
+            !item.label.includes('.') || !item.label.startsWith(prefixRoot)
+        );
+        return result;
+    }
+
+    /** Calculate line/character positions from text offsets. */
+    private calculateTextPositions(
+        text: string,
+        offset: number,
+        fullStart: number
+    ): { startPos: { line: number; character: number }; endPos: { line: number; character: number } } {
+        const startPos = { line: 0, character: 0 };
+        const endPos = { line: 0, character: 0 };
+        let line = 0;
+        let col = 0;
+        for (let i = 0; i < text.length && i <= offset; i++) {
+            if (i === fullStart) { startPos.line = line; startPos.character = col; }
+            if (i === offset) { endPos.line = line; endPos.character = col; }
+            if (text[i] === '\n') { line++; col = 0; } else { col++; }
+        }
+        if (offset === text.length) { endPos.line = line; endPos.character = col; }
+        return { startPos, endPos };
+    }
+
+    /** Transform FQN completion items into segmented (next-segment-only) items. */
+    private transformToSegmentedItems(
+        items: CompletionItem[],
+        prefix: string,
+        partial: string,
+        fullTyped: string,
+        positions: { startPos: { line: number; character: number }; endPos: { line: number; character: number } }
+    ): CompletionItem[] {
+        const seenSegments = new Set<string>();
+        const newItems: CompletionItem[] = [];
+
+        for (const item of items) {
+            const segmented = this.segmentSingleItem(
+                item, prefix, partial, fullTyped, positions, seenSegments
+            );
+            if (segmented) newItems.push(segmented);
+        }
+        return newItems;
+    }
+
+    /** Transform a single FQN item into a segmented item, or keep non-matching items. */
+    private segmentSingleItem(
+        item: CompletionItem,
+        prefix: string,
+        partial: string,
+        fullTyped: string,
+        positions: { startPos: { line: number; character: number }; endPos: { line: number; character: number } },
+        seenSegments: Set<string>
+    ): CompletionItem | undefined {
+        const itemName = item.label;
+
+        // Keep non-matching items (keywords, snippets, etc.)
+        if (!itemName.startsWith(prefix)) {
+            if (!itemName.includes('.') || !this.sharesDottedPrefix(itemName, fullTyped)) {
+                return item;
+            }
+            return undefined;
+        }
+
+        const remainder = itemName.substring(prefix.length);
+        const dotIndex = remainder.indexOf('.');
+        const segment = dotIndex === -1 ? remainder : remainder.substring(0, dotIndex);
+
+        if (!segment || seenSegments.has(segment)) return undefined;
+        if (partial && !segment.toLowerCase().startsWith(partial.toLowerCase())) return undefined;
+
+        seenSegments.add(segment);
+
+        const isLeaf = dotIndex === -1;
+        const fullInsertText = prefix + segment;
+        return {
+            label: segment,
+            kind: isLeaf ? (item.kind ?? CompletionItemKind.Reference) : CompletionItemKind.Module,
+            detail: isLeaf ? itemName : 'Namespace',
+            sortText: segment,
+            filterText: fullInsertText,
+            textEdit: TextEdit.replace(
+                { start: positions.startPos, end: positions.endPos },
+                fullInsertText
+            ),
+        };
+    }
+
+    /**
+     * Check if two dotted names share a common prefix up to the first differing segment.
+     */
+    private sharesDottedPrefix(a: string, b: string): boolean {
+        const aParts = a.split('.');
+        const bParts = b.split('.');
+        return aParts.length > 0 && bParts.length > 0 && aParts[0] === bParts[0];
+    }
+
+    /**
+     * Scan backwards from cursor to find a dotted identifier path.
+     * Returns the full typed text and start position, or undefined if no dots found.
+     *
+     * This is intentionally cursor-based (not tokenOffset-based) to be robust
+     * across all Langium completion contexts.
+     */
+    private extractDottedPathAtCursor(
+        text: string,
+        offset: number
+    ): { fullTyped: string; fullStart: number } | undefined {
+        // Walk backwards from cursor through the current partial identifier
+        let pos = offset - 1;
+        while (pos >= 0 && /\w/.test(text[pos])) pos--;
+
+        // Walk backwards through `.ID` pairs to find start of dotted path
+        pos = this.walkBackThroughDotIdPairs(text, pos);
+
+        const fullStart = pos + 1;
+        const fullTyped = text.substring(fullStart, offset);
+
+        if (!fullTyped.includes('.')) return undefined;
+        return { fullTyped, fullStart };
+    }
+
+    /** Walk backwards through `.ID` pairs from the given position. */
+    private walkBackThroughDotIdPairs(text: string, pos: number): number {
+        while (pos >= 0) {
+            const preSpace = pos;
+            while (pos >= 0 && text[pos] === ' ') pos--;
+            if (pos < 0 || text[pos] !== '.') return preSpace;
+            pos--; // skip dot
+            while (pos >= 0 && text[pos] === ' ') pos--;
+            if (pos < 0 || !/\w/.test(text[pos])) return preSpace;
+            while (pos >= 0 && /\w/.test(text[pos])) pos--;
+        }
+        return pos;
+    }
+
+    /**
+     * Collect import completion items for a given partial input string.
+     *
+     * Shared by both the `getCompletion` override (incomplete string case)
+     * and the `completionFor` path (normal Langium feature-based routing).
+     */
+    private async collectImportItems(currentInput: string): Promise<CompletionItem[]> {
+        let manifest: ModelManifest | undefined;
+        try {
+            manifest = await this.workspaceManager.ensureManifestLoaded();
+        } catch {
+            // Continue with undefined manifest – will show basic starters
+        }
+
+        const items: CompletionItem[] = [];
+        const collector = (_ctx: unknown, item: CompletionItem): void => { items.push(item); };
+
+        // Re-use the acceptor-based helpers by wrapping the collector
+        // We pass `undefined as unknown` for context since the collector ignores it
+        const ctx = undefined as unknown as CompletionContext;
+        const accept = ((_context: CompletionContext, item: CompletionItem): void => {
+            collector(undefined, item);
+        }) as CompletionAcceptor;
+
+        if (currentInput === '' || !currentInput) {
+            this.addAllStarterOptions(ctx, accept, manifest);
+        } else if (currentInput.startsWith('@')) {
+            this.addAliasCompletions(ctx, accept, currentInput, manifest);
+        } else if (currentInput.startsWith('./') || currentInput.startsWith('../')) {
+            this.addLocalPathStarters(ctx, accept);
+        } else if (currentInput.includes('/') && !currentInput.startsWith('.')) {
+            this.addDependencyCompletions(ctx, accept, currentInput, manifest);
+        } else {
+            this.addFilteredOptions(ctx, accept, currentInput, manifest);
+        }
+
+        return items;
+    }
+
+    protected override async completionFor(
         context: CompletionContext,
         next: NextFeature,
         acceptor: CompletionAcceptor
-    ): void {
+    ): Promise<void> {
         try {
-            this.safeCompletionFor(context, next, acceptor);
+            await this.safeCompletionFor(context, next, acceptor);
         } catch (error) {
             console.error('Error in completionFor:', error);
             // Fall back to default completion on error
-            super.completionFor(context, next, acceptor);
+            await super.completionFor(context, next, acceptor);
         }
     }
 
-    private safeCompletionFor(
+    /**
+     * Override cross-reference completion to provide dot-segmented completions.
+     *
+     * When the user types a dotted prefix (e.g., `Core.`), only the next
+     * namespace segment is shown instead of the full qualified name —
+     * matching how modern IDEs handle hierarchical completions.
+     *
+     * Example: Scope contains `Core.CoreDomain`, `Core.BaunWalls.Jannie`, `Core.BaunWalls.Anna`
+     * - No dots typed → default FQN labels: `Core.CoreDomain`, `Core.BaunWalls.Jannie`, ...
+     * - `Core.` typed → segmented: `CoreDomain`, `BaunWalls`
+     * - `Core.BaunWalls.` typed → segmented: `Jannie`, `Anna`
+     */
+    protected override completionForCrossReference(
         context: CompletionContext,
-        next: NextFeature,
+        next: NextFeature<GrammarAST.CrossReference>,
+        acceptor: CompletionAcceptor
+    ): void | Promise<void> {
+        const text = context.textDocument.getText();
+        const fullStart = this.findDottedPathStart(text, context.tokenOffset);
+        const fullTyped = text.substring(fullStart, context.offset);
+
+        // Without dots, use Langium's default FQN-based completion
+        if (!fullTyped.includes('.')) {
+            return super.completionForCrossReference(context, next, acceptor);
+        }
+
+        // Build ReferenceInfo to query the scope — replicating what super does
+        // but without going through super's fuzzy-matching pipeline.
+        const assignment = AstUtils.getContainerOfType(
+            next.feature, GrammarAST.isAssignment
+        );
+        if (!assignment || !context.node) return;
+
+        let node: AstNode = context.node;
+        if (next.type) {
+            node = {
+                $type: next.type,
+                $container: node,
+                $containerProperty: next.property,
+            } as AstNode;
+            AstUtils.assignMandatoryProperties(this.astReflection, node);
+        }
+        const reference = { $refText: '' } as unknown;
+        const refInfo: ReferenceInfo = {
+            reference: reference as ReferenceInfo['reference'],
+            container: node,
+            property: assignment.feature,
+        };
+
+        const candidates = this.getReferenceCandidates(refInfo, context);
+        this.acceptSegmentedCandidates(context, candidates, fullTyped, fullStart, acceptor);
+    }
+
+    /**
+     * Walk backwards from `tokenOffset` through preceding `.ID` pairs
+     * to find the start of the full dotted path.
+     * QualifiedName = ID ('.' ID)* — Langium tokenises each ID separately.
+     */
+    private findDottedPathStart(text: string, tokenOffset: number): number {
+        let fullStart = tokenOffset;
+        while (fullStart > 0) {
+            let pos = fullStart - 1;
+            while (pos >= 0 && text[pos] === ' ') pos--;
+            if (pos < 0 || text[pos] !== '.') break;
+            const idEnd = pos;
+            pos--;
+            while (pos >= 0 && text[pos] === ' ') pos--;
+            while (pos >= 0 && /\w/.test(text[pos])) pos--;
+            pos++;
+            if (pos >= idEnd) break;
+            fullStart = pos;
+        }
+        return fullStart;
+    }
+
+    /**
+     * Iterate scope candidates and emit segmented completion items.
+     * Splits FQN candidates by the typed prefix, extracting only the next segment.
+     */
+    private acceptSegmentedCandidates(
+        context: CompletionContext,
+        candidates: ReturnType<DefaultCompletionProvider['getReferenceCandidates']>,
+        fullTyped: string,
+        fullStart: number,
         acceptor: CompletionAcceptor
     ): void {
+        const lastDotIndex = fullTyped.lastIndexOf('.');
+        const prefix = fullTyped.substring(0, lastDotIndex + 1);
+        const partial = fullTyped.substring(lastDotIndex + 1);
+
+        const seenSegments = new Set<string>();
+        const startPos = context.textDocument.positionAt(fullStart);
+        const endPos = context.textDocument.positionAt(context.offset);
+
+        candidates.forEach((candidate: AstNodeDescription) => {
+            const fullName = candidate.name;
+            if (!fullName.startsWith(prefix)) return;
+
+            const remainder = fullName.substring(prefix.length);
+            const dotIndex = remainder.indexOf('.');
+            const segment = dotIndex === -1 ? remainder : remainder.substring(0, dotIndex);
+
+            if (!segment || seenSegments.has(segment)) return;
+            if (partial && !segment.toLowerCase().startsWith(partial.toLowerCase())) return;
+
+            seenSegments.add(segment);
+
+            const isLeaf = dotIndex === -1;
+            const fullInsertText = prefix + segment;
+            acceptor(context, {
+                label: segment,
+                kind: isLeaf ? this.nodeKindProvider.getCompletionItemKind(candidate) : CompletionItemKind.Module,
+                detail: isLeaf ? fullName : 'Namespace',
+                sortText: segment,
+                // filterText MUST include the full dotted prefix so VS Code's
+                // client-side filter can match "Core.B" against "Core.BaunWalls".
+                // Without this, VS Code uses `label` ('BaunWalls') for filtering,
+                // which fails to match the typed text 'Core.B'.
+                filterText: fullInsertText,
+                textEdit: {
+                    newText: fullInsertText,
+                    range: { start: startPos, end: endPos },
+                },
+            });
+        });
+    }
+
+    private async safeCompletionFor(
+        context: CompletionContext,
+        next: NextFeature,
+        acceptor: CompletionAcceptor
+    ): Promise<void> {
         const node = context.node;
         if (!node) {
-            super.completionFor(context, next, acceptor);
+            await super.completionFor(context, next, acceptor);
             return;
         }
 
         // Strategy: Check node type and container to determine what's allowed at cursor position
         
+        // Handle import statement completions
+        if (this.isImportUriCompletion(node, context, next)) {
+            // Add async import completions (ensures manifest is loaded)
+            await this.addImportCompletions(context, acceptor, node);
+            // Don't call super - we handle import string completions ourselves
+            return;
+        }
+        
         // Check if cursor is after the node (for top-level positioning)
         const offset = context.offset;
         const nodeEnd = node.$cstNode?.end ?? 0;
@@ -154,76 +573,366 @@ export class DomainLangCompletionProvider extends DefaultCompletionProvider {
         if ((ast.isBoundedContext(node) || ast.isDomain(node)) && isAfterNode) {
             this.addTopLevelSnippets(acceptor, context);
             // Let Langium provide keywords like "bc", "Domain", etc.
-            super.completionFor(context, next, acceptor);
+            await super.completionFor(context, next, acceptor);
             return;
         }
         
         // Handle node-level completions
-        if (this.handleNodeCompletions(node, acceptor, context, next)) {
+        if (await this.handleNodeCompletions(node, acceptor, context, next)) {
             return;
         }
 
         // Handle container-level completions
         const container = node.$container;
-        if (this.handleContainerCompletions(container, node, acceptor, context, next)) {
+        if (await this.handleContainerCompletions(container, node, acceptor, context, next)) {
             return;
         }
 
         // Let Langium handle default completions
-        super.completionFor(context, next, acceptor);
+        await super.completionFor(context, next, acceptor);
     }
 
-    private handleNodeCompletions(
+    /**
+     * Detect if we're completing inside an import statement's uri property.
+     * 
+     * This checks:
+     * 1. The NextFeature's type and property (when completing STRING for uri)
+     * 2. The current AST node (when inside an ImportStatement)
+     * 3. Text-based pattern matching (fallback for edge cases)
+     */
+    private isImportUriCompletion(
         node: AstNode,
-        acceptor: CompletionAcceptor,
         context: CompletionContext,
         next: NextFeature
     ): boolean {
+        // Check 1: NextFeature indicates we're completing uri property of ImportStatement
+        if (next.type === 'ImportStatement' && next.property === 'uri') {
+            return true;
+        }
+        
+        // Check 2: The feature is an Assignment to 'uri' property
+        if (GrammarAST.isAssignment(next.feature) && next.feature.feature === 'uri') {
+            return true;
+        }
+        
+        // Check 3: Any ancestor (including self) is ImportStatement
+        if (this.isInImportStatementHierarchy(node)) {
+            return true;
+        }
+        
+        // Check 4: Text-based pattern matching (fallback for edge cases)
+        return this.isImportTextPattern(context);
+    }
+
+    /** Check if the node or any ancestor is an ImportStatement. */
+    private isInImportStatementHierarchy(node: AstNode): boolean {
+        let current: AstNode | undefined = node;
+        while (current) {
+            if (ast.isImportStatement(current)) return true;
+            current = current.$container;
+        }
+        return false;
+    }
+
+    /** Check if text before cursor matches an import string pattern. */
+    private isImportTextPattern(context: CompletionContext): boolean {
+        if (typeof context.textDocument?.getText !== 'function') return false;
+        try {
+            const textBefore = context.textDocument.getText().substring(0, context.offset);
+            return /\bimport\s+"[^"]*$/i.test(textBefore);
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * Add import completions asynchronously.
+     * This method ensures the manifest is loaded before providing completions.
+     */
+    private async addImportCompletions(
+        context: CompletionContext,
+        acceptor: CompletionAcceptor,
+        _node: AstNode
+    ): Promise<void> {
+        // Extract what user has typed inside the import string
+        const currentInput = this.extractImportInput(context);
+
+        // Ensure manifest is loaded (async)
+        let manifest: ModelManifest | undefined;
+        try {
+            manifest = await this.workspaceManager.ensureManifestLoaded();
+        } catch {
+            // Continue with undefined manifest – will show basic starters
+        }
+        
+        if (currentInput.startsWith('@')) {
+            // Alias completions
+            this.addAliasCompletions(context, acceptor, currentInput, manifest);
+        } else if (currentInput.startsWith('./') || currentInput.startsWith('../')) {
+            // Local path completions
+            this.addLocalPathStarters(context, acceptor);
+        } else if (currentInput === '' || !currentInput) {
+            // Show all starter options
+            this.addAllStarterOptions(context, acceptor, manifest);
+        } else if (currentInput.includes('/') && !currentInput.startsWith('.')) {
+            // External dependency - filter by partial input
+            this.addDependencyCompletions(context, acceptor, currentInput, manifest);
+        } else {
+            // Show all options for partial input (e.g., typing 'l' should show matching items)
+            this.addFilteredOptions(context, acceptor, currentInput, manifest);
+        }
+    }
+
+    /**
+     * Extract the current input inside the import string.
+     */
+    private extractImportInput(context: CompletionContext): string {
+        try {
+            const text = context.textDocument.getText();
+            const offset = context.offset;
+            const textBefore = text.substring(0, offset);
+            
+            const importPattern = /\bimport\s+"([^"]*)$/i;
+            const match = importPattern.exec(textBefore);
+            return match ? match[1] : '';
+        } catch {
+            return '';
+        }
+    }
+
+    /**
+     * Add local path starters.
+     */
+    private addLocalPathStarters(context: CompletionContext, acceptor: CompletionAcceptor): void {
+        // Would need async fs access to list directories
+        // For now, just acknowledge the path exists
+        acceptor(context, {
+            label: '(type path)',
+            kind: CompletionItemKind.Text,
+            insertText: '',
+            documentation: 'Continue typing the file path',
+            sortText: 'z_'
+        });
+    }
+
+    /**
+     * Add all starter options when input is empty.
+     */
+    private addAllStarterOptions(
+        context: CompletionContext,
+        acceptor: CompletionAcceptor,
+        manifest?: ModelManifest
+    ): void {
+        // Local starters
+        acceptor(context, {
+            label: './',
+            kind: CompletionItemKind.Folder,
+            insertText: './',
+            documentation: 'Import from current directory',
+            sortText: '0_local_current'
+        });
+        acceptor(context, {
+            label: '../',
+            kind: CompletionItemKind.Folder,
+            insertText: '../',
+            documentation: 'Import from parent directory',
+            sortText: '0_local_parent'
+        });
+
+        // Add aliases if available
+        if (manifest?.paths) {
+            for (const alias of Object.keys(manifest.paths)) {
+                acceptor(context, {
+                    label: alias,
+                    kind: CompletionItemKind.Module,
+                    detail: `→ ${manifest.paths[alias]}`,
+                    documentation: `Path alias from model.yaml`,
+                    insertText: alias,
+                    sortText: `1_alias_${alias}`
+                });
+            }
+        }
+
+        // Add dependencies if available
+        if (manifest?.dependencies) {
+            for (const [depKey, depSpec] of Object.entries(manifest.dependencies)) {
+                const dep: DependencySpec = depSpec;
+                const depName = typeof dep === 'string' ? depKey : (dep.source ?? depKey);
+                const version = typeof dep === 'string' ? dep : (dep.ref ?? 'latest');
+                
+                acceptor(context, {
+                    label: depName,
+                    kind: CompletionItemKind.Module,
+                    detail: `📦 ${version}`,
+                    documentation: `External dependency from model.yaml`,
+                    insertText: depName,
+                    sortText: `2_dep_${depName}`
+                });
+            }
+        }
+    }
+
+    /**
+     * Add alias completions that match the current input.
+     */
+    private addAliasCompletions(
+        context: CompletionContext,
+        acceptor: CompletionAcceptor,
+        currentInput: string,
+        manifest?: ModelManifest
+    ): void {
+        if (!manifest?.paths) {
+            return;
+        }
+
+        const inputLower = currentInput.toLowerCase();
+
+        for (const [alias, targetPath] of Object.entries(manifest.paths)) {
+            if (alias.toLowerCase().startsWith(inputLower)) {
+                acceptor(context, {
+                    label: alias,
+                    kind: CompletionItemKind.Module,
+                    detail: `→ ${targetPath}`,
+                    documentation: `Path alias defined in model.yaml\nMaps to: ${targetPath}`,
+                    insertText: alias,
+                    sortText: `1_alias_${alias}`
+                });
+            }
+        }
+    }
+
+    /**
+     * Add dependency completions that match the current input.
+     */
+    private addDependencyCompletions(
+        context: CompletionContext,
+        acceptor: CompletionAcceptor,
+        currentInput: string,
+        manifest?: ModelManifest
+    ): void {
+        if (!manifest?.dependencies) {
+            return;
+        }
+
+        const inputLower = currentInput.toLowerCase();
+
+        for (const [depKey, depSpec] of Object.entries(manifest.dependencies)) {
+            const dep: DependencySpec = depSpec;
+            const depName = typeof dep === 'string' ? depKey : (dep.source ?? depKey);
+            const version = typeof dep === 'string' ? dep : (dep.ref ?? 'latest');
+            
+            if (depName.toLowerCase().startsWith(inputLower)) {
+                acceptor(context, {
+                    label: depName,
+                    kind: CompletionItemKind.Module,
+                    detail: `📦 ${version}`,
+                    documentation: `External dependency from model.yaml\nVersion: ${version}`,
+                    insertText: depName,
+                    sortText: `2_dep_${depName}`
+                });
+            }
+        }
+    }
+
+    /**
+     * Add filtered options for partial input that doesn't start with special characters.
+     * Shows aliases and dependencies that match the user's partial input.
+     */
+    private addFilteredOptions(
+        context: CompletionContext,
+        acceptor: CompletionAcceptor,
+        currentInput: string,
+        manifest?: ModelManifest
+    ): void {
+        // Offer local path starters when the partial input could match ./ or ../
+        if ('./'.startsWith(currentInput) || '../'.startsWith(currentInput)) {
+            acceptor(context, {
+                label: './',
+                kind: CompletionItemKind.Folder,
+                insertText: './',
+                documentation: 'Import from current directory',
+                sortText: '0_local_current'
+            });
+            acceptor(context, {
+                label: '../',
+                kind: CompletionItemKind.Folder,
+                insertText: '../',
+                documentation: 'Import from parent directory',
+                sortText: '0_local_parent'
+            });
+        }
+
+        // Delegate to existing helpers for alias and dependency filtering
+        this.addAliasCompletions(context, acceptor, currentInput, manifest);
+        this.addDependencyCompletions(context, acceptor, currentInput, manifest);
+    }
+
+    private async handleNodeCompletions(
+        node: AstNode,
+        acceptor: CompletionAcceptor,
+        context: CompletionContext,
+        next: NextFeature
+    ): Promise<boolean> {
         // If we're AT a BoundedContext node: only BC documentation blocks
         if (ast.isBoundedContext(node)) {
             this.addBoundedContextCompletions(node, acceptor, context);
-            super.completionFor(context, next, acceptor);
+            await super.completionFor(context, next, acceptor);
             return true;
         }
 
         // If we're AT a Domain node: only Domain documentation blocks
         if (ast.isDomain(node)) {
             this.addDomainCompletions(node, acceptor, context);
-            super.completionFor(context, next, acceptor);
+            await super.completionFor(context, next, acceptor);
             return true;
         }
 
         // If we're AT a ContextMap node: relationships and contains
         if (ast.isContextMap(node)) {
             this.addContextMapCompletions(node, acceptor, context);
-            super.completionFor(context, next, acceptor);
+            await super.completionFor(context, next, acceptor);
             return true;
         }
 
         // If we're AT a DomainMap node: contains
         if (ast.isDomainMap(node)) {
             this.addDomainMapCompletions(node, acceptor, context);
-            super.completionFor(context, next, acceptor);
+            await super.completionFor(context, next, acceptor);
             return true;
         }
 
         // If we're AT the Model or NamespaceDeclaration level: all top-level constructs
         if (ast.isModel(node) || ast.isNamespaceDeclaration(node)) {
             this.addTopLevelSnippets(acceptor, context);
-            super.completionFor(context, next, acceptor);
+            this.addImportSnippet(acceptor, context);
+            await super.completionFor(context, next, acceptor);
             return true;
         }
 
         return false;
     }
 
-    private handleContainerCompletions(
+    /**
+     * Add import statement snippet at top level.
+     */
+    private addImportSnippet(acceptor: CompletionAcceptor, context: CompletionContext): void {
+        acceptor(context, {
+            label: '⚡ import',
+            kind: CompletionItemKind.Snippet,
+            insertText: 'import "${1:./path}"',
+            insertTextFormat: InsertTextFormat.Snippet,
+            documentation: '📝 Snippet: Import another DomainLang file',
+            sortText: '0_snippet_import'
+        });
+    }
+
+    private async handleContainerCompletions(
         container: AstNode | undefined,
         node: AstNode,
         acceptor: CompletionAcceptor,
         context: CompletionContext,
         next: NextFeature
-    ): boolean {
+    ): Promise<boolean> {
         if (!container) {
             return false;
         }
@@ -231,34 +940,34 @@ export class DomainLangCompletionProvider extends DefaultCompletionProvider {
         // Inside BoundedContext body: suggest missing scalar properties and collections
         if (ast.isBoundedContext(container)) {
             this.addBoundedContextCompletions(container, acceptor, context);
-            super.completionFor(context, next, acceptor);
+            await super.completionFor(context, next, acceptor);
             return true;
         }
 
         // Inside Domain body: suggest missing scalar properties
         if (ast.isDomain(container)) {
             this.addDomainCompletions(container, acceptor, context);
-            super.completionFor(context, next, acceptor);
+            await super.completionFor(context, next, acceptor);
             return true;
         }
 
         // Inside ContextMap body: relationships and contains
         if (ast.isContextMap(container)) {
             this.addContextMapCompletions(container, acceptor, context);
-            super.completionFor(context, next, acceptor);
+            await super.completionFor(context, next, acceptor);
             return true;
         }
 
         // Inside DomainMap body: contains
         if (ast.isDomainMap(container)) {
             this.addDomainMapCompletions(container, acceptor, context);
-            super.completionFor(context, next, acceptor);
+            await super.completionFor(context, next, acceptor);
             return true;
         }
 
         if (ast.isRelationship(node) || ast.isRelationship(container)) {
             this.addRelationshipCompletions(acceptor, context);
-            super.completionFor(context, next, acceptor);
+            await super.completionFor(context, next, acceptor);
             return true;
         }