redscript-mc 2.6.0 → 3.0.0

package/dist/src/lsp/server.js

@@ -53,6 +53,7 @@ const parser_1 = require("../parser");
 const typechecker_1 = require("../typechecker");
 const diagnostics_1 = require("../diagnostics");
 const metadata_1 = require("../builtins/metadata");
+const lint_1 = require("../lint");
 // ---------------------------------------------------------------------------
 // Connection and document manager
 // ---------------------------------------------------------------------------
@@ -166,14 +167,21 @@ function parseDocument(uri, source) {
     const errors = [];
     let program = null;
     try {
-        const lexer = new lexer_1.Lexer(source);
+        // Strip path-based imports ("import "stdlib/xxx.mcrs"") before parsing,
+        // since the Parser only understands import module::symbol syntax.
+        // These are handled at compile time by pre-processing, not by the parser.
+        const strippedSource = source.replace(/^import\s+"[^"]*"\s*;?\s*$/gm, '// (import stripped for LSP)');
+        const lexer = new lexer_1.Lexer(strippedSource);
         const tokens = lexer.tokenize();
-        const parser = new parser_1.Parser(tokens, source, uri);
+        const parser = new parser_1.Parser(tokens, strippedSource, uri);
         program = parser.parse('redscript');
         // Type-check (warn mode — collects errors but doesn't throw)
-        const checker = new typechecker_1.TypeChecker(source, uri);
-        const typeErrors = checker.check(program);
-        errors.push(...typeErrors);
+        try {
+            const checker = new typechecker_1.TypeChecker(source, uri);
+            const typeErrors = checker.check(program);
+            errors.push(...typeErrors);
+        }
+        catch { /* type errors are non-fatal; keep the parsed program */ }
     }
     catch (err) {
         if (err instanceof diagnostics_1.DiagnosticError) {
@@ -202,22 +210,47 @@ function toDiagnostic(err) {
         source: 'redscript',
     };
 }
+/** Severity mapping for lint rules. */
+const LINT_SEVERITY_MAP = {
+    'unused-variable': node_1.DiagnosticSeverity.Information,
+    'magic-number': node_1.DiagnosticSeverity.Hint,
+    'dead-branch': node_1.DiagnosticSeverity.Warning,
+    'unused-import': node_1.DiagnosticSeverity.Information,
+    'function-too-long': node_1.DiagnosticSeverity.Warning,
+};
+/** Convert a LintWarning to an LSP Diagnostic. */
+function lintWarningToDiagnostic(w) {
+    const line = Math.max(0, (w.line ?? 1) - 1);
+    const col = Math.max(0, (w.col ?? 1) - 1);
+    const severity = LINT_SEVERITY_MAP[w.rule] ?? node_1.DiagnosticSeverity.Warning;
+    return {
+        severity,
+        range: {
+            start: { line, character: col },
+            end: { line, character: col + 80 },
+        },
+        message: w.message,
+        source: 'redscript-lint',
+        code: w.rule,
+    };
+}
 // ---------------------------------------------------------------------------
 // Decorator hover docs
 // ---------------------------------------------------------------------------
 const DECORATOR_DOCS = {
-    tick: 'Runs every MC game tick (~20 Hz). No arguments.',
-    load: 'Runs on `/reload`. Use for initialization logic.',
-    coroutine: 'Splits loops into tick-spread continuations. Arg: `batch=N` (steps per tick, default 1).',
-    schedule: 'Schedules the function to run after N ticks. Arg: `ticks=N`.',
-    on_trigger: 'Runs when a trigger scoreboard objective is set by a player. Arg: trigger name.',
-    keep: 'Prevents the compiler from dead-code-eliminating this function.',
-    on: 'Generic event handler decorator.',
-    on_advancement: 'Runs when a player earns an advancement. Arg: advancement id.',
-    on_craft: 'Runs when a player crafts an item. Arg: item id.',
-    on_death: 'Runs when a player dies.',
-    on_join_team: 'Runs when a player joins a team. Arg: team name.',
-    on_login: 'Runs when a player logs in.',
+    tick: 'Runs every game tick.\n\n**Optional args:** `rate=N` (every N ticks, e.g. `@tick(rate=20)` = once per second)\n\nExample: `@tick fn every_tick() {}` or `@tick(rate=20) fn every_second() {}`',
+    load: 'Runs once on `/reload`. Use for initialization.\n\nExample: `@load fn init() { scoreboard_create(...) }`',
+    watch: 'Runs when a scoreboard objective changes for a player.\n\n**Required arg:** objective name.\n\nExample: `@watch("rs.kills") fn on_kill_change() {}`',
+    coroutine: 'Wraps a loop to spread execution across multiple ticks.\n\n**Required arg:** `batch=N` — iterations per tick.\n\nExample: `@coroutine(batch=10) fn scan_blocks() { for i in 0..1000 { ... } }`',
+    schedule: 'Schedules the function to run after a delay.\n\n**Required arg:** `ticks=N`\n\nExample: `@schedule(ticks=100) fn delayed() {}`',
+    on_trigger: 'Runs when a player executes `/trigger <name>`.\n\n**Required arg:** trigger objective name.\n\nExample: `@on_trigger("shop") fn open_shop() {}`',
+    keep: 'Prevents dead-code elimination. Use for exported entry points not referenced in the same file.\n\nExample: `@keep fn public_api() {}`',
+    on: 'Generic event handler. Arg: event name.\n\nExample: `@on("custom:event") fn handler() {}`',
+    on_advancement: 'Runs when a player earns an advancement.\n\n**Arg:** advancement id (e.g. `"story/mine_diamond"`).\n\nExample: `@on_advancement("story/mine_diamond") fn reward() {}`',
+    on_craft: 'Runs when a player crafts an item.\n\n**Arg:** item id (e.g. `"minecraft:diamond_sword"`).\n\nExample: `@on_craft("minecraft:diamond_sword") fn on_craft_sword() {}`',
+    on_death: 'Runs when a player dies.\n\nExample: `@on_death fn on_player_death() {}`',
+    on_join_team: 'Runs when a player joins a team.\n\n**Arg:** team name.\n\nExample: `@on_join_team("red") fn joined_red() {}`',
+    on_login: 'Runs when a player logs into the server.\n\nExample: `@on_login fn welcome() { tell(@s, f"Welcome back!") }`',
 };
 // ---------------------------------------------------------------------------
 // Hover helpers
@@ -258,10 +291,107 @@ function formatFnSignature(fn) {
     const typeParams = fn.typeParams?.length ? `<${fn.typeParams.join(', ')}>` : '';
     return `fn ${fn.name}${typeParams}(${params}): ${ret}`;
 }
-// ---------------------------------------------------------------------------
-// Go-to-definition helpers
-// ---------------------------------------------------------------------------
-/** Build a mapping from identifier name → definition location. */
+/**
+ * Parse a raw triple-slash or block comment into structured sections.
+ * Supports @param name desc and @returns desc.
+ */
+function parseDocCommentText(raw) {
+    const result = { description: '', params: [], returns: null };
+    const descLines = [];
+    for (const line of raw.split('\n')) {
+        const paramMatch = line.match(/^@param\s+(\w+)\s+(.+)$/);
+        if (paramMatch) {
+            result.params.push({ name: paramMatch[1], doc: paramMatch[2].trim() });
+            continue;
+        }
+        const retMatch = line.match(/^@returns?\s+(.+)$/);
+        if (retMatch) {
+            result.returns = retMatch[1].trim();
+            continue;
+        }
+        // Skip @since / @example etc
+        if (/^@\w+/.test(line.trim()))
+            continue;
+        descLines.push(line);
+    }
+    result.description = descLines.join('\n').trim();
+    return result;
+}
+/**
+ * Format a ParsedDocComment into Markdown for LSP hover.
+ */
+function formatDocCommentMarkdown(doc) {
+    const parts = [];
+    if (doc.description)
+        parts.push(doc.description);
+    if (doc.params.length > 0) {
+        parts.push('\n**Parameters:**');
+        for (const p of doc.params) {
+            parts.push(`- \`${p.name}\` — ${p.doc}`);
+        }
+    }
+    if (doc.returns) {
+        parts.push(`\n**Returns:** ${doc.returns}`);
+    }
+    return parts.join('\n');
+}
+/**
+ * Extract the leading doc comment (/** ... *\/) immediately before a function
+ * declaration, returning it as plain text (tags stripped).
+ */
+function extractDocComment(source, fn) {
+    if (!fn.span)
+        return null;
+    const lines = source.split('\n');
+    // fn.span.line is 1-based; scan upward from fn declaration line
+    let endLine = fn.span.line - 2; // 0-based index of line before fn
+    if (endLine < 0)
+        return null;
+    // Skip blank lines
+    while (endLine >= 0 && lines[endLine].trim() === '')
+        endLine--;
+    if (endLine < 0)
+        return null;
+    // Case 1: /** ... */ block comment
+    if (lines[endLine].trim().endsWith('*/')) {
+        let startLine = endLine;
+        while (startLine >= 0 && !lines[startLine].trim().startsWith('/**'))
+            startLine--;
+        if (startLine < 0)
+            return null;
+        const commentLines = lines.slice(startLine, endLine + 1);
+        return commentLines
+            .map(l => l.replace(/^\s*\/\*\*\s?/, '').replace(/^\s*\*\/\s?$/, '').replace(/^\s*\*\s?/, '').trimEnd())
+            .filter(l => l.length > 0)
+            .join('\n') || null;
+    }
+    // Case 2: consecutive // or /// line comments
+    if (lines[endLine].trim().startsWith('//')) {
+        let startLine = endLine;
+        while (startLine > 0 && lines[startLine - 1].trim().startsWith('//'))
+            startLine--;
+        return lines.slice(startLine, endLine + 1)
+            .map(l => l.replace(/^\s*\/\/\/?\/?\s?/, '').trimEnd())
+            .filter(l => l.length > 0)
+            .join('\n') || null;
+    }
+    return null;
+}
+/**
+ * Find which function declaration contains the given 1-based line number.
+ * Uses the next fn's start line as the implicit end when span.endLine is missing.
+ */
+function findEnclosingFn(program, curLine) {
+    const fns = program.declarations.filter(f => f.span);
+    for (let i = 0; i < fns.length; i++) {
+        const fn = fns[i];
+        const startLine = fn.span.line;
+        const endLine = fn.span.endLine ?? (fns[i + 1]?.span?.line ? fns[i + 1].span.line - 1 : Infinity);
+        if (curLine >= startLine && curLine <= endLine)
+            return fn;
+    }
+    return null;
+}
 function buildDefinitionMap(program, source) {
     const map = new Map();
     for (const fn of program.declarations) {
@@ -311,29 +441,34 @@ const TYPE_COMPLETIONS = [
     label: t,
     kind: node_1.CompletionItemKind.TypeParameter,
 }));
+// Decorator completions — triggered when '@' is typed at line start context.
+// insertText is the full token WITHOUT '@' because '@' is already on screen.
+// VSCode will keep the completion open as user types more letters (filter by label).
 const DECORATOR_COMPLETIONS = [
-    { label: '@tick', detail: 'Run every game tick (~20 Hz)' },
-    { label: '@load', detail: 'Run on /reload (initialization)' },
-    { label: '@on_trigger', detail: 'Run when a player uses /trigger' },
-    { label: '@schedule', detail: 'Schedule function after N ticks' },
-    { label: '@coroutine', detail: 'Spread loop across ticks (batch=N)' },
-    { label: '@keep', detail: 'Prevent dead-code elimination' },
-    { label: '@on', detail: 'Generic event handler' },
-    { label: '@on_advancement', detail: 'Run on advancement earned' },
-    { label: '@on_craft', detail: 'Run on item craft' },
-    { label: '@on_death', detail: 'Run on player death' },
-    { label: '@on_join_team', detail: 'Run on team join' },
-    { label: '@on_login', detail: 'Run on player login' },
-    { label: '@require_on_load', detail: 'Ensure a fn runs on load (stdlib)' },
+    { label: '@tick', detail: 'Run every game tick (~20 Hz)', insertText: 'tick' },
+    { label: '@watch', detail: 'Run when a scoreboard objective changes', insertText: 'watch' },
+    { label: '@load', detail: 'Run on /reload (initialization)', insertText: 'load' },
+    { label: '@on_trigger', detail: 'Run when a player uses /trigger', insertText: 'on_trigger' },
+    { label: '@schedule', detail: 'Schedule function after N ticks', insertText: 'schedule' },
+    { label: '@coroutine', detail: 'Spread loop across ticks (batch=N)', insertText: 'coroutine' },
+    { label: '@keep', detail: 'Prevent dead-code elimination', insertText: 'keep' },
+    { label: '@on', detail: 'Generic event handler', insertText: 'on' },
+    { label: '@on_advancement', detail: 'Run on advancement earned', insertText: 'on_advancement' },
+    { label: '@on_craft', detail: 'Run on item craft', insertText: 'on_craft' },
+    { label: '@on_death', detail: 'Run on player death', insertText: 'on_death' },
+    { label: '@on_join_team', detail: 'Run on team join', insertText: 'on_join_team' },
+    { label: '@on_login', detail: 'Run on player login', insertText: 'on_login' },
+    { label: '@require_on_load', detail: 'Ensure a fn runs on load (stdlib)', insertText: 'require_on_load' },
 ].map(d => ({ ...d, kind: node_1.CompletionItemKind.Event }));
-/** Entity selector completions triggered by @ inside expressions */
+/** Entity selector completions triggered by @ inside expressions.
+ *  insertText is without '@' (already typed). label has '@' for display. */
 const SELECTOR_COMPLETIONS = [
-    { label: '@a', kind: node_1.CompletionItemKind.Value, detail: 'All players', documentation: 'Targets all online players.' },
-    { label: '@p', kind: node_1.CompletionItemKind.Value, detail: 'Nearest player', documentation: 'Targets the nearest player to the command source.' },
-    { label: '@s', kind: node_1.CompletionItemKind.Value, detail: 'Executing entity', documentation: 'Targets the entity currently executing the command.' },
-    { label: '@e', kind: node_1.CompletionItemKind.Value, detail: 'All entities', documentation: 'Targets all entities (use [type=...] to filter).' },
-    { label: '@r', kind: node_1.CompletionItemKind.Value, detail: 'Random player', documentation: 'Targets a random online player.' },
-    { label: '@n', kind: node_1.CompletionItemKind.Value, detail: 'Nearest entity', documentation: 'Targets the nearest entity (any type).' },
+    { label: '@a', insertText: 'a', kind: node_1.CompletionItemKind.Value, detail: 'All players', documentation: 'Targets all online players.' },
+    { label: '@p', insertText: 'p', kind: node_1.CompletionItemKind.Value, detail: 'Nearest player', documentation: 'Targets the nearest player to the command source.' },
+    { label: '@s', insertText: 's', kind: node_1.CompletionItemKind.Value, detail: 'Executing entity', documentation: 'Targets the entity currently executing the command.' },
+    { label: '@e', insertText: 'e', kind: node_1.CompletionItemKind.Value, detail: 'All entities', documentation: 'Targets all entities (use [type=...] to filter).' },
+    { label: '@r', insertText: 'r', kind: node_1.CompletionItemKind.Value, detail: 'Random player', documentation: 'Targets a random online player.' },
+    { label: '@n', insertText: 'n', kind: node_1.CompletionItemKind.Value, detail: 'Nearest entity', documentation: 'Targets the nearest entity (any type).' },
 ];
 const BUILTIN_FN_COMPLETIONS = [
     'say', 'tell', 'give', 'kill', 'teleport', 'summon', 'setblock',
@@ -381,6 +516,18 @@ function validateAndPublish(doc) {
     const source = doc.getText();
     const parsed = parseDocument(doc.uri, source);
     const diagnostics = parsed.errors.map(toDiagnostic);
+    // Also run lint rules and push them as lower-severity diagnostics
+    try {
+        const filePath = (() => { try {
+            return (0, url_1.fileURLToPath)(doc.uri);
+        }
+        catch {
+            return doc.uri;
+        } })();
+        const lintWarnings = (0, lint_1.lintString)(source, filePath);
+        diagnostics.push(...lintWarnings.map(lintWarningToDiagnostic));
+    }
+    catch { /* lint is best-effort; don't block diagnostics */ }
     connection.sendDiagnostics({ uri: doc.uri, diagnostics });
 }
 documents.onDidOpen(e => validateAndPublish(e.document));
@@ -420,6 +567,34 @@ connection.onHover((params) => {
             }
         }
     }
+    // ── Selector hover: @a, @p, @s etc ─────────────────────────────────────────
+    const SELECTOR_DOCS = {
+        '@a': 'All online players',
+        '@p': 'Nearest player to the command source',
+        '@s': 'The entity currently executing the command (self)',
+        '@e': 'All entities (use [type=...] to filter)',
+        '@r': 'A random online player',
+        '@n': 'The nearest entity of any type',
+    };
+    // Match @x or @x[...] token at cursor
+    const selRe = /@([a-zA-Z])/g;
+    let sm;
+    while ((sm = selRe.exec(lineText)) !== null) {
+        const selStart = sm.index;
+        const selEnd = selStart + sm[0].length;
+        if (ch >= selStart && ch <= selEnd) {
+            const selKey = sm[0]; // e.g. '@a'
+            const selDoc = SELECTOR_DOCS[selKey];
+            if (selDoc) {
+                return {
+                    contents: {
+                        kind: node_1.MarkupKind.Markdown,
+                        value: `**${selKey}** — ${selDoc}`,
+                    },
+                };
+            }
+        }
+    }
     const cached = parsedDocs.get(params.textDocument.uri);
     const program = cached?.program ?? null;
     if (!program)
@@ -427,6 +602,17 @@ connection.onHover((params) => {
     const word = wordAt(source, params.position);
     if (!word)
         return null;
+    // If cursor is on a selector like @s/@a/@p, the word is just 's'/'a'/'p'.
+    // Detect this by checking the character before the word start.
+    const hovLines = source.split('\n');
+    const hovLine = hovLines[params.position.line] ?? '';
+    const hovCh = params.position.character;
+    // Find start of current word
+    let hovWordStart = hovCh;
+    while (hovWordStart > 0 && /\w/.test(hovLine[hovWordStart - 1]))
+        hovWordStart--;
+    if (hovWordStart > 0 && hovLine[hovWordStart - 1] === '@')
+        return null; // It's a selector, no hover
     // Check builtins
     const builtin = ALL_BUILTINS[word];
     if (builtin) {
@@ -444,9 +630,17 @@ connection.onHover((params) => {
     const fn = findFunction(program, word);
     if (fn) {
         const sig = formatFnSignature(fn);
+        const rawDoc = extractDocComment(source, fn);
+        let docSection = '';
+        if (rawDoc) {
+            const parsed = parseDocCommentText(rawDoc);
+            const md = formatDocCommentMarkdown(parsed);
+            if (md)
+                docSection = `\n\n${md}`;
+        }
         const content = {
             kind: node_1.MarkupKind.Markdown,
-            value: `\`\`\`redscript\n${sig}\n\`\`\``,
+            value: `\`\`\`redscript\n${sig}\n\`\`\`${docSection}`,
         };
         return { contents: content };
     }
@@ -479,6 +673,45 @@ connection.onHover((params) => {
         };
         return { contents: content };
     }
+    // Check globals
+    const globalDecl = program.globals?.find(g => g.name === word);
+    if (globalDecl) {
+        const content = {
+            kind: node_1.MarkupKind.Markdown,
+            value: `\`\`\`redscript\nlet ${globalDecl.name}: ${typeToString(globalDecl.type)}\n\`\`\`\n*global variable*`,
+        };
+        return { contents: content };
+    }
+    // Check locals and params in the enclosing function
+    {
+        const curLine = params.position.line + 1;
+        const fn = findEnclosingFn(program, curLine);
+        if (fn) {
+            // Check params
+            const param = fn.params.find(p => p.name === word);
+            if (param) {
+                return {
+                    contents: {
+                        kind: node_1.MarkupKind.Markdown,
+                        value: `\`\`\`redscript\n(param) ${param.name}: ${typeToString(param.type)}\n\`\`\``,
+                    },
+                };
+            }
+            // Check locals
+            if (fn.body) {
+                const locals = collectLocals(fn.body);
+                const localType = locals.get(word);
+                if (localType) {
+                    return {
+                        contents: {
+                            kind: node_1.MarkupKind.Markdown,
+                            value: `\`\`\`redscript\nlet ${word}: ${typeToString(localType)}\n\`\`\``,
+                        },
+                    };
+                }
+            }
+        }
+    }
     // ── Check imported files (import "stdlib/xxx.mcrs" and import xxx::*) ──────
     try {
         const importedPrograms = getImportedPrograms(source, params.textDocument.uri);
@@ -486,9 +719,12 @@ connection.onHover((params) => {
             const importedFn = findFunction(prog, word);
             if (importedFn) {
                 const sig = formatFnSignature(importedFn);
+                // Extract leading /** ... */ comment from the source file
+                const docComment = extractDocComment(fs.readFileSync(filePath, 'utf-8'), importedFn);
+                const docLine = docComment ? `\n\n${docComment}` : '';
                 const content = {
                     kind: node_1.MarkupKind.Markdown,
-                    value: `\`\`\`redscript\n${sig}\n\`\`\`\n*from ${path.basename(filePath)}*`,
+                    value: `\`\`\`redscript\n${sig}\n\`\`\`${docLine}\n\n*from ${path.basename(filePath)}*`,
                 };
                 return { contents: content };
             }
@@ -497,7 +733,7 @@ connection.onHover((params) => {
                 const fields = importedStruct.fields.map(f => `  ${f.name}: ${typeToString(f.type)}`).join('\n');
                 const content = {
                     kind: node_1.MarkupKind.Markdown,
-                    value: `\`\`\`redscript\nstruct ${importedStruct.name} {\n${fields}\n}\n\`\`\`\n*from ${path.basename(filePath)}*`,
+                    value: `\`\`\`redscript\nstruct ${importedStruct.name} {\n${fields}\n}\n\`\`\`\n\n*from ${path.basename(filePath)}*`,
                 };
                 return { contents: content };
             }
@@ -619,34 +855,79 @@ connection.onDefinition((params) => {
     const word = wordAt(source, params.position);
     if (!word)
         return null;
-    // ── import module::symbol — jump to the symbol in the imported module ───────
-    // Check if word is a known import symbol; try to resolve its module file
-    const importDecl = program.imports?.find(im => im.symbol === word || im.symbol === '*');
+    // If cursor is on a selector like @s/@a, the word is 's'/'a' — no F12.
+    let defWordStart = params.position.character;
+    while (defWordStart > 0 && /\w/.test(lineText[defWordStart - 1]))
+        defWordStart--;
+    if (defWordStart > 0 && lineText[defWordStart - 1] === '@')
+        return null;
+    // ── Normal in-file definition (top-level fn/struct/const/global) ────────────
+    const defMap = buildDefinitionMap(program, source);
+    const span = defMap.get(word);
+    if (span) {
+        const line = Math.max(0, span.line - 1);
+        const col = Math.max(0, span.col - 1);
+        return {
+            uri: params.textDocument.uri,
+            range: {
+                start: { line, character: col },
+                end: { line, character: col + word.length },
+            },
+        };
+    }
+    // ── If word is a local/param in the enclosing fn, don't fall through to imports ──
+    const defCurLine = params.position.line + 1; // 1-based
+    const enclosingFn = findEnclosingFn(program, defCurLine);
+    if (enclosingFn) {
+        if (enclosingFn.params.some(p => p.name === word))
+            return null;
+        if (enclosingFn.body) {
+            const locals = collectLocals(enclosingFn.body);
+            if (locals.has(word))
+                return null;
+        }
+    }
+    // Struct fields — clicking on .phase, .active etc. should not jump to stdlib
+    for (const s of program.structs ?? []) {
+        if (s.fields.some(f => f.name === word))
+            return null;
+    }
+    // ── Imported symbol F12 — jump to definition inside the imported file ────────
+    // Only reached if word is not a local. Avoids false matches for short names like 'p', 'k'.
+    try {
+        const importedPrograms = getImportedPrograms(source, params.textDocument.uri);
+        for (const { prog, filePath } of importedPrograms) {
+            const importedDefMap = buildDefinitionMap(prog, fs.readFileSync(filePath, 'utf-8'));
+            const importedSpan = importedDefMap.get(word);
+            if (importedSpan) {
+                const line = Math.max(0, importedSpan.line - 1);
+                const col = Math.max(0, importedSpan.col - 1);
+                return {
+                    uri: (0, url_1.pathToFileURL)(filePath).toString(),
+                    range: {
+                        start: { line, character: col },
+                        end: { line, character: col + word.length },
+                    },
+                };
+            }
+        }
+    }
+    catch { /* ignore */ }
+    // ── import module::symbol (legacy AST imports) — open module file ONLY for explicit symbols ──
+    // NOTE: do NOT match im.symbol === '*' — that would cause any word to jump to the first import!
+    const importDecl = program.imports?.find(im => im.symbol === word);
     if (importDecl) {
-        const resolved = resolveImportPath(importDecl.moduleName, params.textDocument.uri)
+        const resolved = resolveImportPath(`stdlib/${importDecl.moduleName}.mcrs`, params.textDocument.uri)
+            ?? resolveImportPath(importDecl.moduleName, params.textDocument.uri)
             ?? resolveImportPath(importDecl.moduleName + '.mcrs', params.textDocument.uri);
         if (resolved) {
-            // Open file at start; could later search for the symbol definition
             return {
                 uri: (0, url_1.pathToFileURL)(resolved).toString(),
                 range: { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } },
             };
         }
     }
-    // ── Normal in-file definition ──────────────────────────────────────────────
-    const defMap = buildDefinitionMap(program, source);
-    const span = defMap.get(word);
-    if (!span)
-        return null;
-    const line = Math.max(0, span.line - 1);
-    const col = Math.max(0, span.col - 1);
-    return {
-        uri: params.textDocument.uri,
-        range: {
-            start: { line, character: col },
-            end: { line, character: col + word.length },
-        },
-    };
+    return null;
 });
 // ---------------------------------------------------------------------------
 // Completion helpers
@@ -660,13 +941,24 @@ const ARRAY_METHOD_COMPLETIONS = [
 /** Collect (name → TypeNode) for all let bindings visible in the function body at offset. */
 function collectLocals(body) {
     const map = new Map();
+    // Sentinel type for variables whose type is unknown (e.g. foreach bindings)
+    const ENTITY_TYPE = { kind: 'named', name: 'int' }; // placeholder for entity/selector binding
     function walk(stmts) {
         for (const s of stmts) {
             if (s.kind === 'let' && s.type) {
                 map.set(s.name, s.type);
             }
-            else if (s.kind === 'let_destruct') {
-                // no type info per-binding easily; skip
+            else if (s.kind === 'foreach') {
+                // foreach binding is an entity/selector variable
+                map.set(s.binding, ENTITY_TYPE);
+                if (Array.isArray(s.body))
+                    walk(s.body);
+                continue;
+            }
+            else if (s.kind === 'for') {
+                // for i in range — binding is int
+                if (s.binding)
+                    map.set(s.binding, { kind: 'named', name: 'int' });
             }
             // Recurse into sub-blocks
             const sub = s;
@@ -712,20 +1004,15 @@ connection.onCompletion((params) => {
     const cached = parsedDocs.get(params.textDocument.uri);
     const program = cached?.program ?? null;
     // ── @ trigger: selector (@a/@p/@s/@e/@r/@n) vs decorator (@tick etc) ────────
-    // Check if current token starts with '@': prevChar='@' OR there's '@xxx' partial token
+    // Only fires when the character just typed is '@' (triggerCharacter).
+    // insertText includes the full @xxx so VSCode replaces the '@' already on screen.
     const prevChar = lineText[charPos - 1];
-    const atMatch = lineText.slice(0, charPos).match(/@([a-zA-Z_]*)$/);
-    if (prevChar === '@' || atMatch) {
-        // Heuristic: if there's a non-whitespace non-keyword char before '@'
-        // on the same line it's likely an expression context (selector).
-        // If line is only whitespace before '@', it's a decorator.
-        const atStart = atMatch ? charPos - atMatch[0].length : charPos - 1;
-        const before = lineText.slice(0, atStart).trim();
+    if (prevChar === '@') {
+        const before = lineText.slice(0, charPos - 1).trim();
         const isExprContext = before.length > 0 && !/^(fn|let|if|while|for|return|@)/.test(before.split(/\s+/).pop() ?? '');
         if (isExprContext) {
             return SELECTOR_COMPLETIONS;
         }
-        // Decorator context — return decorator completions only
         return DECORATOR_COMPLETIONS;
     }
     // ── Dot-access completion ──────────────────────────────────────────────────
@@ -735,15 +1022,10 @@ connection.onCompletion((params) => {
         if (program) {
             // Find which function body contains this line (by span)
             const curLine = params.position.line + 1; // spans are 1-based
-            let locals = null;
-            for (const fn of program.declarations) {
-                if (fn.body && fn.span) {
-                    if (curLine >= fn.span.line && curLine <= (fn.span.endLine ?? Infinity)) {
-                        locals = collectLocals(fn.body);
-                        break;
-                    }
-                }
-            }
+            const encFn = findEnclosingFn(program, curLine);
+            const locals = encFn?.body
+                ? collectLocals(encFn.body)
+                : null;
             // Determine type of receiver
             const receiverType = locals?.get(dotReceiver)
                 ?? program.consts?.find(c => c.name === dotReceiver)?.type
@@ -817,19 +1099,15 @@ connection.onCompletion((params) => {
             items.push({ label: g.name, kind: node_1.CompletionItemKind.Variable });
         }
         // Locals from the enclosing function
-        const curLine = params.position.line + 1;
-        for (const fn of program.declarations) {
-            if (fn.body && fn.span) {
-                if (curLine >= fn.span.line && curLine <= (fn.span.endLine ?? Infinity)) {
-                    for (const [name, typ] of collectLocals(fn.body)) {
-                        items.push({
-                            label: name,
-                            kind: node_1.CompletionItemKind.Variable,
-                            detail: typeToString(typ),
-                        });
-                    }
-                    break;
-                }
+        const curLine2 = params.position.line + 1;
+        const encFn2 = findEnclosingFn(program, curLine2);
+        if (encFn2?.body) {
+            for (const [name, typ] of collectLocals(encFn2.body)) {
+                items.push({
+                    label: name,
+                    kind: node_1.CompletionItemKind.Variable,
+                    detail: typeToString(typ),
+                });
             }
         }
     }
@@ -951,36 +1229,58 @@ connection.onRequest('textDocument/inlayHint', (params) => {
     if (!doc)
         return [];
     const hints = [];
-    // Walk all let declarations with no explicit type annotation
-    // (where the type was inferred by the type checker)
-    function walkStmt(stmt) {
-        if (stmt['kind'] === 'let_decl' &&
-            !stmt['typeAnnotation'] &&
-            stmt['inferredType']) {
-            const spanVal = stmt['span'];
-            const pos = doc.positionAt(spanVal?.end ?? 0);
-            hints.push({
-                position: { line: pos.line, character: pos.character },
-                label: `: ${typeToString(stmt['inferredType'])}`,
-                kind: node_1.InlayHintKind.Type,
-                paddingLeft: true,
-            });
+    // Walk all let declarations with no explicit type annotation and emit inlay hints.
+    // Since TypeChecker doesn't attach inferredType to AST nodes, we use collectLocals
+    // which already infers types from init expressions.
+    function walkBlock(stmts) {
+        // Build a locals map for this block (includes inferred types)
+        const locals = collectLocals(stmts);
+        for (const stmt of stmts) {
+            if (stmt.kind === 'let' && !stmt.type) {
+                // No explicit type annotation — show inferred type as inlay hint
+                const inferredType = locals.get(stmt.name);
+                if (!inferredType)
+                    continue;
+                const spanVal = stmt.span;
+                if (!spanVal)
+                    continue;
+                // Position hint after the variable name: line is 1-based in span, col is 1-based
+                const line = Math.max(0, spanVal.line - 1);
+                // Find the position after the variable name on that line
+                const lineText = source.split('\n')[line] ?? '';
+                const nameEnd = lineText.indexOf(stmt.name) + stmt.name.length;
+                hints.push({
+                    position: { line, character: nameEnd },
+                    label: `: ${typeToString(inferredType)}`,
+                    kind: node_1.InlayHintKind.Type,
+                    paddingLeft: false,
+                });
+            }
+            // Recurse into nested blocks
+            if (stmt.kind === 'if' || stmt.kind === 'while' || stmt.kind === 'for') {
+                const s = stmt;
+                const then_ = s['then'];
+                if (Array.isArray(then_))
+                    walkBlock(then_);
+                const else_ = s['else_'];
+                if (Array.isArray(else_))
+                    walkBlock(else_);
+                const body = s['body'];
+                if (Array.isArray(body))
+                    walkBlock(body);
+            }
+            if (stmt.kind === 'foreach') {
+                const s = stmt;
+                const body = s['body'];
+                if (Array.isArray(body))
+                    walkBlock(body);
+            }
         }
-        // Recurse into blocks, if/else bodies, etc.
-        const body = stmt['body'];
-        if (Array.isArray(body))
-            body.forEach(walkStmt);
-        const then_ = stmt['then'];
-        if (Array.isArray(then_))
-            then_.forEach(walkStmt);
-        const else_ = stmt['else_'];
-        if (Array.isArray(else_))
-            else_.forEach(walkStmt);
     }
+    const source = doc.getText();
     parsed.program.declarations.forEach(top => {
-        if (top.body) {
-            top.body.forEach(walkStmt);
-        }
+        if (top.body)
+            walkBlock(top.body);
     });
     return hints;
 });