redscript-mc 2.6.0 → 3.0.0

package/src/lsp/server.ts

@@ -48,6 +48,8 @@ import { DiagnosticError } from '../diagnostics'
 import type { Program, FnDecl, Span, TypeNode, Stmt, Block } from '../ast/types'
 import { BUILTIN_METADATA } from '../builtins/metadata'
 import type { BuiltinDef } from '../builtins/metadata'
+import { lintString } from '../lint'
+import type { LintWarning } from '../lint'
 
 // ---------------------------------------------------------------------------
 // Connection and document manager
@@ -181,15 +183,21 @@ function parseDocument(uri: string, source: string): ParsedDoc {
   let program: Program | null = null
 
   try {
-    const lexer = new 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(strippedSource)
     const tokens = lexer.tokenize()
-    const parser = new Parser(tokens, source, uri)
+    const parser = new Parser(tokens, strippedSource, uri)
     program = parser.parse('redscript')
 
     // Type-check (warn mode — collects errors but doesn't throw)
-    const checker = new TypeChecker(source, uri)
-    const typeErrors = checker.check(program)
-    errors.push(...typeErrors)
+    try {
+      const checker = new 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 DiagnosticError) {
       errors.push(err)
@@ -223,23 +231,50 @@ function toDiagnostic(err: DiagnosticError): Diagnostic {
   }
 }
 
+/** Severity mapping for lint rules. */
+const LINT_SEVERITY_MAP: Record<string, DiagnosticSeverity> = {
+  'unused-variable':   DiagnosticSeverity.Information,
+  'magic-number':      DiagnosticSeverity.Hint,
+  'dead-branch':       DiagnosticSeverity.Warning,
+  'unused-import':     DiagnosticSeverity.Information,
+  'function-too-long': DiagnosticSeverity.Warning,
+}
+
+/** Convert a LintWarning to an LSP Diagnostic. */
+function lintWarningToDiagnostic(w: LintWarning): Diagnostic {
+  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] ?? 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: Record<string, string> = {
-  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!") }`',
 }
 
 // ---------------------------------------------------------------------------
@@ -286,6 +321,114 @@ function formatFnSignature(fn: FnDecl): string {
 // ---------------------------------------------------------------------------
 
 /** Build a mapping from identifier name → definition location. */
+// ---------------------------------------------------------------------------
+// Doc comment parsing helpers
+// ---------------------------------------------------------------------------
+
+interface ParsedDocComment {
+  description: string
+  params: Array<{ name: string; doc: string }>
+  returns: string | null
+}
+
+/**
+ * Parse a raw triple-slash or block comment into structured sections.
+ * Supports @param name desc and @returns desc.
+ */
+function parseDocCommentText(raw: string): ParsedDocComment {
+  const result: ParsedDocComment = { description: '', params: [], returns: null }
+  const descLines: string[] = []
+  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: ParsedDocComment): string {
+  const parts: string[] = []
+  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: string, fn: FnDecl): string | null {
+  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: Program, curLine: number): import('../ast/types').FnDecl | null {
+  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: Program, source: string): Map<string, Span> {
   const map = new Map<string, Span>()
 
@@ -334,30 +477,35 @@ const TYPE_COMPLETIONS: CompletionItem[] = [
   kind: 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: CompletionItem[] = [
-  { 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: 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: CompletionItem[] = [
-  { label: '@a',  kind: CompletionItemKind.Value, detail: 'All players',              documentation: 'Targets all online players.' },
-  { label: '@p',  kind: CompletionItemKind.Value, detail: 'Nearest player',           documentation: 'Targets the nearest player to the command source.' },
-  { label: '@s',  kind: CompletionItemKind.Value, detail: 'Executing entity',         documentation: 'Targets the entity currently executing the command.' },
-  { label: '@e',  kind: CompletionItemKind.Value, detail: 'All entities',             documentation: 'Targets all entities (use [type=...] to filter).' },
-  { label: '@r',  kind: CompletionItemKind.Value, detail: 'Random player',            documentation: 'Targets a random online player.' },
-  { label: '@n',  kind: CompletionItemKind.Value, detail: 'Nearest entity',           documentation: 'Targets the nearest entity (any type).' },
+  { label: '@a', insertText: 'a', kind: CompletionItemKind.Value, detail: 'All players',        documentation: 'Targets all online players.' },
+  { label: '@p', insertText: 'p', kind: CompletionItemKind.Value, detail: 'Nearest player',     documentation: 'Targets the nearest player to the command source.' },
+  { label: '@s', insertText: 's', kind: CompletionItemKind.Value, detail: 'Executing entity',   documentation: 'Targets the entity currently executing the command.' },
+  { label: '@e', insertText: 'e', kind: CompletionItemKind.Value, detail: 'All entities',       documentation: 'Targets all entities (use [type=...] to filter).' },
+  { label: '@r', insertText: 'r', kind: CompletionItemKind.Value, detail: 'Random player',      documentation: 'Targets a random online player.' },
+  { label: '@n', insertText: 'n', kind: CompletionItemKind.Value, detail: 'Nearest entity',     documentation: 'Targets the nearest entity (any type).' },
 ]
 
 const BUILTIN_FN_COMPLETIONS: CompletionItem[] = [
@@ -411,6 +559,14 @@ function validateAndPublish(doc: TextDocument): void {
   const source = doc.getText()
   const parsed = parseDocument(doc.uri, source)
   const diagnostics: Diagnostic[] = parsed.errors.map(toDiagnostic)
+
+  // Also run lint rules and push them as lower-severity diagnostics
+  try {
+    const filePath = (() => { try { return fileURLToPath(doc.uri) } catch { return doc.uri } })()
+    const lintWarnings = lintString(source, filePath)
+    diagnostics.push(...lintWarnings.map(lintWarningToDiagnostic))
+  } catch { /* lint is best-effort; don't block diagnostics */ }
+
   connection.sendDiagnostics({ uri: doc.uri, diagnostics })
 }
 
@@ -455,6 +611,35 @@ connection.onHover((params: TextDocumentPositionParams): Hover | null => {
     }
   }
 
+  // ── Selector hover: @a, @p, @s etc ─────────────────────────────────────────
+  const SELECTOR_DOCS: Record<string, string> = {
+    '@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: RegExpExecArray | null
+  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: MarkupKind.Markdown,
+            value: `**${selKey}** — ${selDoc}`,
+          } as MarkupContent,
+        }
+      }
+    }
+  }
+
   const cached = parsedDocs.get(params.textDocument.uri)
   const program = cached?.program ?? null
   if (!program) return null
@@ -462,6 +647,16 @@ connection.onHover((params: TextDocumentPositionParams): Hover | null => {
   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) {
@@ -480,9 +675,16 @@ connection.onHover((params: TextDocumentPositionParams): Hover | null => {
   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: MarkupContent = {
       kind: MarkupKind.Markdown,
-      value: `\`\`\`redscript\n${sig}\n\`\`\``,
+      value: `\`\`\`redscript\n${sig}\n\`\`\`${docSection}`,
     }
     return { contents: content }
   }
@@ -519,6 +721,47 @@ connection.onHover((params: TextDocumentPositionParams): Hover | null => {
     return { contents: content }
   }
 
+  // Check globals
+  const globalDecl = program.globals?.find(g => g.name === word)
+  if (globalDecl) {
+    const content: MarkupContent = {
+      kind: 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: MarkupKind.Markdown,
+            value: `\`\`\`redscript\n(param) ${param.name}: ${typeToString(param.type)}\n\`\`\``,
+          } as MarkupContent,
+        }
+      }
+      // Check locals
+      if (fn.body) {
+        const locals = collectLocals(fn.body as import('../ast/types').Block)
+        const localType = locals.get(word)
+        if (localType) {
+          return {
+            contents: {
+              kind: MarkupKind.Markdown,
+              value: `\`\`\`redscript\nlet ${word}: ${typeToString(localType)}\n\`\`\``,
+            } as MarkupContent,
+          }
+        }
+      }
+    }
+  }
+
   // ── Check imported files (import "stdlib/xxx.mcrs" and import xxx::*) ──────
   try {
     const importedPrograms = getImportedPrograms(source, params.textDocument.uri)
@@ -526,9 +769,12 @@ connection.onHover((params: TextDocumentPositionParams): Hover | null => {
       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: MarkupContent = {
           kind: 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 }
       }
@@ -537,7 +783,7 @@ connection.onHover((params: TextDocumentPositionParams): Hover | null => {
         const fields = importedStruct.fields.map(f => `  ${f.name}: ${typeToString(f.type)}`).join('\n')
         const content: MarkupContent = {
           kind: 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 }
       }
@@ -653,14 +899,70 @@ connection.onDefinition((params: TextDocumentPositionParams): Location | null =>
   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 as import('../ast/types').Block)
+      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: 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: pathToFileURL(resolved).toString(),
         range: { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } },
@@ -668,20 +970,7 @@ connection.onDefinition((params: TextDocumentPositionParams): Location | null =>
     }
   }
 
-  // ── 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
 })
 
 // ---------------------------------------------------------------------------
@@ -698,12 +987,20 @@ const ARRAY_METHOD_COMPLETIONS: CompletionItem[] = [
 /** Collect (name → TypeNode) for all let bindings visible in the function body at offset. */
 function collectLocals(body: Block): Map<string, TypeNode> {
   const map = new Map<string, TypeNode>()
+  // Sentinel type for variables whose type is unknown (e.g. foreach bindings)
+  const ENTITY_TYPE: TypeNode = { kind: 'named', name: 'int' } // placeholder for entity/selector binding
   function walk(stmts: Block): void {
     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 as any).binding, ENTITY_TYPE)
+        if (Array.isArray((s as any).body)) walk((s as any).body as Block)
+        continue
+      } else if (s.kind === 'for') {
+        // for i in range — binding is int
+        if ((s as any).binding) map.set((s as any).binding, { kind: 'named', name: 'int' })
       }
       // Recurse into sub-blocks
       const sub = (s as Record<string, unknown>)
@@ -748,20 +1045,15 @@ connection.onCompletion((params: TextDocumentPositionParams): CompletionItem[] =
   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
   }
 
@@ -773,15 +1065,10 @@ connection.onCompletion((params: TextDocumentPositionParams): CompletionItem[] =
     if (program) {
       // Find which function body contains this line (by span)
       const curLine = params.position.line + 1 // spans are 1-based
-      let locals: Map<string, TypeNode> | null = 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 as Block)
-            break
-          }
-        }
-      }
+      const encFn = findEnclosingFn(program, curLine)
+      const locals: Map<string, TypeNode> | null = encFn?.body
+        ? collectLocals(encFn.body as Block)
+        : null
 
       // Determine type of receiver
       const receiverType: TypeNode | undefined = locals?.get(dotReceiver)
@@ -859,19 +1146,15 @@ connection.onCompletion((params: TextDocumentPositionParams): CompletionItem[] =
     }
 
     // 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 as Block)) {
-            items.push({
-              label: name,
-              kind: 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 as Block)) {
+        items.push({
+          label: name,
+          kind: CompletionItemKind.Variable,
+          detail: typeToString(typ),
+        })
       }
     }
   }
@@ -1004,36 +1287,53 @@ connection.onRequest(
 
     const hints: InlayHint[] = []
 
-    // Walk all let declarations with no explicit type annotation
-    // (where the type was inferred by the type checker)
-    function walkStmt(stmt: Record<string, unknown>): void {
-      if (
-        stmt['kind'] === 'let_decl' &&
-        !stmt['typeAnnotation'] &&
-        stmt['inferredType']
-      ) {
-        const spanVal = stmt['span'] as { end?: number } | undefined
-        const pos = doc!.positionAt(spanVal?.end ?? 0)
-        hints.push({
-          position: { line: pos.line, character: pos.character },
-          label: `: ${typeToString(stmt['inferredType'] as import('../ast/types').TypeNode)}`,
-          kind: 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: import('../ast/types').Stmt[]): void {
+      // Build a locals map for this block (includes inferred types)
+      const locals = collectLocals(stmts as import('../ast/types').Block)
+
+      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 as { span?: { line: number; col: number } }).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: InlayHintKind.Type,
+            paddingLeft: false,
+          })
+        }
+        // Recurse into nested blocks
+        if (stmt.kind === 'if' || stmt.kind === 'while' || stmt.kind === 'for') {
+          const s = stmt as Record<string, unknown>
+          const then_ = s['then'] as import('../ast/types').Stmt[] | undefined
+          if (Array.isArray(then_)) walkBlock(then_)
+          const else_ = s['else_'] as import('../ast/types').Stmt[] | undefined
+          if (Array.isArray(else_)) walkBlock(else_)
+          const body = s['body'] as import('../ast/types').Stmt[] | undefined
+          if (Array.isArray(body)) walkBlock(body)
+        }
+        if (stmt.kind === 'foreach') {
+          const s = stmt as Record<string, unknown>
+          const body = s['body'] as import('../ast/types').Stmt[] | undefined
+          if (Array.isArray(body)) walkBlock(body)
+        }
       }
-      // Recurse into blocks, if/else bodies, etc.
-      const body = stmt['body'] as Record<string, unknown>[] | undefined
-      if (Array.isArray(body)) body.forEach(walkStmt)
-      const then_ = stmt['then'] as Record<string, unknown>[] | undefined
-      if (Array.isArray(then_)) then_.forEach(walkStmt)
-      const else_ = stmt['else_'] as Record<string, unknown>[] | undefined
-      if (Array.isArray(else_)) else_.forEach(walkStmt)
     }
 
+    const source = doc.getText()
     parsed.program.declarations.forEach(top => {
-      if (top.body) {
-        (top.body as Record<string, unknown>[]).forEach(walkStmt)
-      }
+      if (top.body) walkBlock(top.body as import('../ast/types').Stmt[])
     })
 
     return hints