xq-lsp 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.5.0](https://github.com/DrRataplan/xq-lsp/compare/lsp-v1.4.1...lsp-v1.5.0) (2026-06-18)
+
+
+### Features
+
+* **completion:** add function param completions with proper scope isolation ([dab41a3](https://github.com/DrRataplan/xq-lsp/commit/dab41a349ae1d387f1b32b530e476b1d30da8f07))
+* **diagnostics:** report undeclared variable references as XPST0008 ([6ff1fa9](https://github.com/DrRataplan/xq-lsp/commit/6ff1fa9d5a9ecfb4d440119f3efa9e3f96204e05))
+* eXist-db pre-declared namespaces suppress false XQST0081 diagnostics ([cd94650](https://github.com/DrRataplan/xq-lsp/commit/cd94650db968d727717de62e6a60411481a7fb16))
+
+
+### Bug Fixes
+
+* inject W3C predeclared namespaces in qt4-worker ([4c93ad6](https://github.com/DrRataplan/xq-lsp/commit/4c93ad677db0eb266e04f080ee1a1ad986dfc03a))
+* **variable-diagnostics:** add explicit type annotation to fix TS build ([5867d7e](https://github.com/DrRataplan/xq-lsp/commit/5867d7ea549026cda98559b8d980f3bdf561f32f))
+* **vscode:** make extension work by shimming import.meta.url ([fca848a](https://github.com/DrRataplan/xq-lsp/commit/fca848af51ee17a0dba8e7b95f4767c4d1ce974f))
+
 ## [1.4.1](https://github.com/DrRataplan/xq-lsp/compare/lsp-v1.4.0...lsp-v1.4.1) (2026-06-10)
 
 

package/README.md

@@ -59,24 +59,70 @@ For files with syntax errors (common while editing), the server falls back to re
 
 Use the `lib` key to load built-in definitions for a specific runtime:
 
-| Value     | Runtime                                                             |
-| --------- | ------------------------------------------------------------------- |
-| `"fonto"` | [Fonto XML editor](https://www.fontoxml.com/) — `fonto:*` functions |
+| Value       | Runtime                                                                   |
+| ----------- | ------------------------------------------------------------------------- |
+| `"fonto"`   | [Fonto XML editor](https://www.fontoxml.com/) — `fonto:*` functions       |
+| `"existdb"` | [eXist-db](https://exist-db.org/) — all extension module functions        |
 
 ```xquery
-map {"glob": "src/**/*.xq", "lib": "fonto"}
+map {"glob": "src/**/*.xq", "lib": "existdb"}
 ```
 
-Then import the namespace in your XQuery files as usual — the server resolves completions, hover, and go-to-definition against the bundled definitions:
+Multiple libs use an XPath sequence:
 
 ```xquery
-import module namespace fonto="http://www.fontoxml.com/functions";
+map {"glob": "src/**/*.xq", "lib": ("fonto", "other")}
 ```
 
-Multiple libs use an XPath sequence:
+#### eXist-db runtime
+
+The `"existdb"` runtime bundles stub definitions for every eXist-db extension
+module (`util`, `xmldb`, `request`, `sm`, `ft`, `compression`, …).
+
+eXist-db automatically pre-declares a large set of namespace prefixes — you can
+call `util:log(…)`, `xmldb:store(…)`, `process:execute(…)`, etc. without any
+`import module namespace` statement. When the `existdb` runtime is active the
+server knows about these pre-declared prefixes and:
+
+- **suppresses** false `XQST0081` ("namespace prefix not declared") diagnostics
+  for all pre-declared namespaces
+- **provides completions, hover, and go-to-definition** for those modules
+  without requiring an explicit `import module namespace` in your source
+
+If you do choose to write explicit imports (e.g. for editor portability), the
+server handles those correctly too:
 
 ```xquery
-map {"glob": "src/**/*.xq", "lib": ("fonto", "other")}
+(: explicit import — also fine :)
+import module namespace util = "http://exist-db.org/xquery/util";
+util:uuid()
+```
+
+Modules that require explicit import even in eXist-db (e.g. `datetime`,
+`httpclient`, `console`, `crypto`, `kwic`) still need a `import module
+namespace` declaration; the server offers quick-fix code actions to insert it.
+
+```xquery
+(: lsp-config.xq in your project root :)
+map {
+    "glob": "src/**/*.xq",
+    "lib": "existdb",
+    "import": map {
+        "generateLocationHints": false()
+    }
+}
+```
+
+The `generateLocationHints: false()` setting prevents the server from appending
+`at "…"` paths to generated imports, which eXist-db does not need (it resolves
+modules by namespace URI).
+
+#### Fonto runtime
+
+Then import the namespace in your XQuery files as usual — the server resolves completions, hover, and go-to-definition against the bundled definitions:
+
+```xquery
+import module namespace fonto="http://www.fontoxml.com/functions";
 ```
 
 ### Location hints

package/dist/completion-core.d.ts

@@ -14,4 +14,4 @@ export interface CompletionEntry {
     isSnippet: boolean;
 }
 export declare function functionDoc(fn: FunctionSymbol): string;
-export declare function getCompletions(ctx: CompletionContext, currentAnalysis: FileAnalysis, importedAnalyses: Map<string, FileAnalysis>, snippets?: boolean): CompletionEntry[];
+export declare function getCompletions(ctx: CompletionContext, currentAnalysis: FileAnalysis, importedAnalyses: Map<string, FileAnalysis>, snippets?: boolean, lastValidAnalysis?: FileAnalysis): CompletionEntry[];

package/dist/completion-core.js

@@ -1,5 +1,5 @@
 import { formatQName } from "./types.js";
-import { resolvePrefix } from "./analyzer.js";
+import { resolvePrefix, nodeStackAtOffset, findAll } from "./analyzer.js";
 function parseToken(textBefore) {
     const match = textBefore.match(/\$([\w:\-]*)$|(?:([\w\-]+):)([\w\-]*)$|([\w\-]+)$/);
     if (!match)
@@ -41,6 +41,31 @@ function buildVariableEntry(v, filter) {
         return null;
     return { label, kind: "variable", insertText: label, isSnippet: false };
 }
+function buildParamEntry(p, filter) {
+    if (filter && !p.name.toLowerCase().startsWith(filter.toLowerCase()))
+        return null;
+    return {
+        label: `$${p.name}`,
+        kind: "variable",
+        detail: p.type ? `as ${p.type}` : undefined,
+        insertText: `$${p.name}`,
+        isSnippet: false,
+    };
+}
+/** Find the function symbol enclosing the cursor using the AST. */
+function findEnclosingFunction(ast, cursorOffset, functions) {
+    const stack = nodeStackAtOffset(ast, cursorOffset);
+    const bodyNode = stack.slice().reverse().find((n) => n.type === "FunctionBody");
+    if (!bodyNode || bodyNode.start === undefined || bodyNode.end == null)
+        return null;
+    const annotatedNode = stack.find((n) => n.type === "AnnotatedDecl");
+    if (!annotatedNode || annotatedNode.start === undefined)
+        return null;
+    const fn = functions.find((f) => f.sourceOffset === annotatedNode.start);
+    if (!fn)
+        return null;
+    return { fn, bodyStart: bodyNode.start, bodyEnd: bodyNode.end };
+}
 function buildFunctionEntry(fn, label, snippets) {
     return {
         label,
@@ -51,23 +76,63 @@ function buildFunctionEntry(fn, label, snippets) {
         isSnippet: snippets && fn.params.length > 0,
     };
 }
-export function getCompletions(ctx, currentAnalysis, importedAnalyses, snippets = false) {
+export function getCompletions(ctx, currentAnalysis, importedAnalyses, snippets = false, lastValidAnalysis) {
     const token = parseToken(ctx.textBeforeCursor);
     const items = [];
     if (token.kind === "variable") {
         const filter = token.prefix;
+        // Module-level variables are always visible
         for (const v of currentAnalysis.moduleVariables) {
             const e = buildVariableEntry(v, filter);
             if (e)
                 items.push(e);
         }
-        for (const v of currentAnalysis.localBindings) {
-            if (v.offset < ctx.cursorOffset) {
-                const e = buildVariableEntry(v, filter);
-                if (e)
-                    items.push(e);
+        // Prefer the current AST; fall back to the last successfully-parsed one for scope analysis
+        const scopeAst = currentAnalysis.ast ?? lastValidAnalysis?.ast;
+        if (scopeAst) {
+            const enclosing = findEnclosingFunction(scopeAst, ctx.cursorOffset, currentAnalysis.functions);
+            if (enclosing) {
+                // Inside a function body: params + local bindings within this body before cursor
+                for (const p of enclosing.fn.params) {
+                    const e = buildParamEntry(p, filter);
+                    if (e)
+                        items.push(e);
+                }
+                for (const v of currentAnalysis.localBindings) {
+                    if (v.offset > enclosing.bodyStart && v.offset < ctx.cursorOffset && v.offset < enclosing.bodyEnd) {
+                        const e = buildVariableEntry(v, filter);
+                        if (e)
+                            items.push(e);
+                    }
+                }
+            }
+            else {
+                // In query body: exclude local bindings that live inside function bodies
+                const functionBodyRanges = findAll(scopeAst, "FunctionBody")
+                    .filter((b) => b.start !== undefined && b.end != null)
+                    .map((b) => ({ start: b.start, end: b.end }));
+                for (const v of currentAnalysis.localBindings) {
+                    if (v.offset >= ctx.cursorOffset)
+                        continue;
+                    if (functionBodyRanges.some((r) => v.offset >= r.start && v.offset <= r.end))
+                        continue;
+                    const e = buildVariableEntry(v, filter);
+                    if (e)
+                        items.push(e);
+                }
+            }
+        }
+        else {
+            // No AST ever available: simple offset-based filter, no function-param completions
+            for (const v of currentAnalysis.localBindings) {
+                if (v.offset < ctx.cursorOffset) {
+                    const e = buildVariableEntry(v, filter);
+                    if (e)
+                        items.push(e);
+                }
             }
         }
+        // Imported module-level variables are always visible
         for (const analysis of importedAnalyses.values()) {
             for (const v of analysis.moduleVariables) {
                 const e = buildVariableEntry(v, filter);

package/dist/runtimes.d.ts

@@ -1,2 +1,15 @@
-import type { FileAnalysis } from "./types.ts";
+import type { FileAnalysis, NamespaceDecl } from "./types.ts";
+/**
+ * Returns all namespace declarations that are in scope without any explicit
+ * `import module namespace` or `declare namespace` statement. Includes the
+ * standard XQuery 3.1 predeclared namespaces (math, map, array) and any
+ * runtime-specific additions (e.g. eXist-db's util, xmldb, …).
+ */
+export declare function getRuntimePredeclaredNamespaces(runtimes: string[]): NamespaceDecl[];
+/**
+ * Return a copy of `analysis` with the given predeclared namespace declarations
+ * merged into `namespaceDecls`. Prefixes already visible via imports, the
+ * module's own prefix, or an existing `declare namespace` are skipped.
+ */
+export declare function withPredeclaredNs(analysis: FileAnalysis, predeclaredNs: NamespaceDecl[]): FileAnalysis;
 export declare function getRuntimeAnalyses(runtimes: string[]): FileAnalysis[];

package/dist/runtimes.js

@@ -3,6 +3,14 @@ import * as fs from "fs";
 import { fileURLToPath } from "url";
 import { analyze } from "./analyzer.js";
 const runtimesDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "runtimes");
+function toNamespaceDecls(raw) {
+    return Object.entries(raw).map(([prefix, namespaceUri]) => ({ prefix, namespaceUri }));
+}
+// Lazily loaded predeclared namespace list for the existdb runtime.
+let existdbPredeclared = null;
+function loadExistdbPredeclared() {
+    return (existdbPredeclared ??= toNamespaceDecls(JSON.parse(fs.readFileSync(path.join(runtimesDir, "existdb", "predeclared-namespaces.json"), "utf-8"))));
+}
 const RUNTIME_FILES = {
     fonto: [path.join(runtimesDir, "fonto", "fonto.xq")],
     existdb: [
@@ -39,6 +47,35 @@ const RUNTIME_FILES = {
     ],
 };
 const runtimeAnalysisCache = new Map();
+/**
+ * Returns all namespace declarations that are in scope without any explicit
+ * `import module namespace` or `declare namespace` statement. Includes the
+ * standard XQuery 3.1 predeclared namespaces (math, map, array) and any
+ * runtime-specific additions (e.g. eXist-db's util, xmldb, …).
+ */
+export function getRuntimePredeclaredNamespaces(runtimes) {
+    if (!runtimes.includes("existdb"))
+        return [];
+    return loadExistdbPredeclared();
+}
+/**
+ * Return a copy of `analysis` with the given predeclared namespace declarations
+ * merged into `namespaceDecls`. Prefixes already visible via imports, the
+ * module's own prefix, or an existing `declare namespace` are skipped.
+ */
+export function withPredeclaredNs(analysis, predeclaredNs) {
+    if (predeclaredNs.length === 0)
+        return analysis;
+    const known = new Set([
+        ...analysis.imports.map((i) => i.prefix),
+        ...analysis.namespaceDecls.map((nd) => nd.prefix),
+        ...(analysis.modulePrefix ? [analysis.modulePrefix] : []),
+    ]);
+    const toAdd = predeclaredNs.filter((nd) => !known.has(nd.prefix));
+    if (toAdd.length === 0)
+        return analysis;
+    return { ...analysis, namespaceDecls: [...analysis.namespaceDecls, ...toAdd] };
+}
 export function getRuntimeAnalyses(runtimes) {
     const results = [];
     for (const runtime of runtimes) {

package/dist/server.js

@@ -14,11 +14,13 @@ import { checkFunctionCalls } from "./functioncall-diagnostics.js";
 import { findConfig, expandGlobs } from "./config.js";
 import { findUndeclaredPrefixUsages, findImportInsertPosition, findDeclareNsInsertPosition, } from "./namespace-diagnostics.js";
 import { checkUnused } from "./unused-diagnostics.js";
+import { checkUndeclaredVariables } from "./variable-diagnostics.js";
 import { checkContextItemUsage } from "./context-item-diagnostics.js";
-import { getRuntimeAnalyses } from "./runtimes.js";
+import { getRuntimeAnalyses, getRuntimePredeclaredNamespaces, withPredeclaredNs } from "./runtimes.js";
 const connection = createConnection(ProposedFeatures.all);
 const documents = new TextDocuments(TextDocument);
 const analysisCache = new Map();
+const lastValidAnalysisCache = new Map(); // last AST-path analysis per URI
 const typeErrorCache = new Map();
 // Glob analyses keyed by config directory, then by module namespace URI.
 // Populated lazily on the first request for a given config root.
@@ -26,11 +28,15 @@ const globAnalysesByConfigDir = new Map();
 function analyzeDocument(doc) {
     const { analysis } = analyzeWithAst(doc.getText(), doc.uri);
     analysisCache.set(doc.uri, analysis);
+    if (analysis.usedAstPath)
+        lastValidAnalysisCache.set(doc.uri, analysis);
     return analysis;
 }
 function analyzeDocumentFull(doc) {
     const { analysis, ast, parseError } = analyzeWithAst(doc.getText(), doc.uri);
     analysisCache.set(doc.uri, analysis);
+    if (analysis.usedAstPath)
+        lastValidAnalysisCache.set(doc.uri, analysis);
     return { analysis, parseDiagnostics: buildParseDiagnostics(parseError), hasAst: ast !== null, ast };
 }
 function buildParseDiagnostics(parseError) {
@@ -105,10 +111,12 @@ function getGlobAnalyses(currentUri) {
     globAnalysesByConfigDir.set(configDir, byNamespace);
     return { byNamespace, lib };
 }
-function resolveImports(currentUri, analysis) {
+function resolveContext(currentUri, rawAnalysis) {
     const result = new Map();
     result.set("builtin:fn", getBuiltins());
     const { byNamespace: globAnalyses, lib } = getGlobAnalyses(currentUri);
+    const predeclaredNs = getRuntimePredeclaredNamespaces(lib);
+    const analysis = withPredeclaredNs(rawAnalysis, predeclaredNs);
     const runtimeByNamespace = new Map();
     for (const runtimeAnalysis of getRuntimeAnalyses(lib)) {
         if (runtimeAnalysis.moduleNamespaceUri) {
@@ -116,7 +124,7 @@ function resolveImports(currentUri, analysis) {
             runtimeByNamespace.set(runtimeAnalysis.moduleNamespaceUri, existing ? mergeAnalyses(existing, runtimeAnalysis) : runtimeAnalysis);
         }
     }
-    for (const imp of analysis.imports) {
+    for (const imp of rawAnalysis.imports) {
         if (imp.atPath) {
             const uri = resolveImportUri(currentUri, imp.atPath);
             const imported = getImportedAnalysis(uri);
@@ -130,7 +138,15 @@ function resolveImports(currentUri, analysis) {
                 result.set(imp.namespaceUri, imported);
         }
     }
-    return result;
+    // Add pre-declared runtime analyses directly — available without explicit import
+    for (const nd of predeclaredNs) {
+        if (!result.has(nd.namespaceUri)) {
+            const runtimeAnalysis = runtimeByNamespace.get(nd.namespaceUri);
+            if (runtimeAnalysis)
+                result.set(nd.namespaceUri, runtimeAnalysis);
+        }
+    }
+    return { analysis, imported: result };
 }
 // ── LSP lifecycle ────────────────────────────────────────────────────────────
 let snippetSupport = false;
@@ -155,12 +171,12 @@ connection.onInitialize((params) => {
 });
 documents.onDidChangeContent((change) => {
     const doc = change.document;
-    const { analysis, parseDiagnostics: parseDiags, hasAst, ast } = analyzeDocumentFull(doc);
+    const { analysis: rawAnalysis, parseDiagnostics: parseDiags, hasAst, ast } = analyzeDocumentFull(doc);
+    const { analysis, imported: resolvedImported } = resolveContext(doc.uri, rawAnalysis);
     if (hasAst && ast !== null) {
-        const imported = resolveImports(doc.uri, analysis);
         typeErrorCache.set(doc.uri, [
-            ...checkTypes(ast, doc.getText(), analysis, imported),
-            ...checkFunctionCalls(ast, analysis, imported),
+            ...checkTypes(ast, doc.getText(), analysis, resolvedImported),
+            ...checkFunctionCalls(ast, analysis, resolvedImported),
         ]);
     }
     const typeDiags = (typeErrorCache.get(doc.uri) ?? []).map((td) => ({
@@ -209,34 +225,48 @@ documents.onDidChangeContent((change) => {
         code: cd.code,
         source: "xquery-lsp",
     }));
+    const undeclaredVarDiagRaw = hasAst && ast !== null ? checkUndeclaredVariables(ast, analysis, resolvedImported) : [];
+    const undeclaredVarDiags = undeclaredVarDiagRaw.map((d) => ({
+        severity: DiagnosticSeverity.Error,
+        range: {
+            start: doc.positionAt(d.offset),
+            end: doc.positionAt(d.offset + d.length),
+        },
+        message: d.message,
+        code: d.code,
+        source: "xquery-lsp",
+    }));
     connection.sendDiagnostics({
         uri: doc.uri,
-        diagnostics: [...parseDiags, ...typeDiags, ...nsDiags, ...unusedDiags, ...contextItemDiags],
+        diagnostics: [
+            ...parseDiags, ...typeDiags, ...nsDiags, ...unusedDiags, ...contextItemDiags,
+            ...undeclaredVarDiags,
+        ],
     });
 });
 connection.onCompletion((params) => {
     const doc = documents.get(params.textDocument.uri);
     if (!doc)
         return [];
-    const analysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
-    const imported = resolveImports(doc.uri, analysis);
+    const rawAnalysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
+    const { analysis, imported } = resolveContext(doc.uri, rawAnalysis);
     const offset = doc.offsetAt(params.position);
-    return getCompletions({ textBeforeCursor: doc.getText().slice(0, offset), cursorOffset: offset }, analysis, imported, snippetSupport);
+    return getCompletions({ textBeforeCursor: doc.getText().slice(0, offset), cursorOffset: offset }, analysis, imported, snippetSupport, lastValidAnalysisCache.get(doc.uri));
 });
 connection.onHover((params) => {
     const doc = documents.get(params.textDocument.uri);
     if (!doc)
         return null;
-    const analysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
-    const imported = resolveImports(doc.uri, analysis);
+    const rawAnalysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
+    const { analysis, imported } = resolveContext(doc.uri, rawAnalysis);
     return getHover(doc, doc.offsetAt(params.position), analysis, imported);
 });
 connection.onSignatureHelp((params) => {
     const doc = documents.get(params.textDocument.uri);
     if (!doc)
         return null;
-    const analysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
-    const imported = resolveImports(doc.uri, analysis);
+    const rawAnalysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
+    const { analysis, imported } = resolveContext(doc.uri, rawAnalysis);
     return getSignatureHelp(doc, doc.offsetAt(params.position), analysis, imported);
 });
 connection.onDocumentSymbol((params) => {
@@ -250,8 +280,8 @@ connection.onDefinition((params) => {
     const doc = documents.get(params.textDocument.uri);
     if (!doc)
         return null;
-    const analysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
-    const imported = resolveImports(doc.uri, analysis);
+    const rawAnalysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
+    const { analysis, imported } = resolveContext(doc.uri, rawAnalysis);
     return getDefinition(doc, doc.offsetAt(params.position), analysis, imported, (atPath) => resolveImportUri(doc.uri, atPath));
 });
 connection.onCodeAction((params) => {

package/dist/variable-diagnostics.d.ts

@@ -0,0 +1,19 @@
+import type { Node } from "xq-parser";
+import type { FileAnalysis } from "./types.ts";
+export interface UndeclaredVariableDiagnostic {
+    message: string;
+    code: "XPST0008";
+    offset: number;
+    length: number;
+}
+/**
+ * Walk the AST and report every variable reference that cannot be resolved
+ * to a declared variable: function parameter, let/for binding, module-level
+ * `declare variable`, or an imported module variable.
+ *
+ * Variables whose namespace prefix is undeclared are skipped — XQST0081
+ * already fires for those, and adding XPST0008 on top would be noisy.
+ * Variables inside catch clauses are also skipped since the implicit
+ * `$err:*` bindings are not represented in the AST.
+ */
+export declare function checkUndeclaredVariables(ast: Node, analysis: FileAnalysis, importedAnalyses: Map<string, FileAnalysis>): UndeclaredVariableDiagnostic[];

package/dist/variable-diagnostics.js

@@ -0,0 +1,164 @@
+import { qnameKey } from "./types.js";
+import { isTerminal, directChildOf, directChildrenOf } from "./analyzer.js";
+import { asFunctionDecl, asVarRef, asVarName, asBinding } from "./ast-nodes.js";
+// ── Scope stack ───────────────────────────────────────────────────────────────
+class ScopeStack {
+    frames = [];
+    push() { this.frames.push(new Set()); }
+    pop() { this.frames.pop(); }
+    add(key) { this.frames[this.frames.length - 1]?.add(key); }
+    has(key) { return this.frames.some((f) => f.has(key)); }
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function isKnown(qname, scope, moduleVarKeys) {
+    // Variables with an undeclared-prefix URI are already caught by XQST0081; skip here.
+    if (qname.namespaceUri.startsWith("urn:xq-lsp:undeclared:"))
+        return true;
+    return scope.has(qnameKey(qname)) || moduleVarKeys.has(qnameKey(qname));
+}
+function reportVarRef(node, qname, out) {
+    const name = qname.prefix ? `${qname.prefix}:${qname.localName}` : qname.localName;
+    out.push({
+        message: `Variable '$${name}' is not declared`,
+        code: "XPST0008",
+        offset: node.start ?? 0,
+        length: name.length + 1, // +1 for "$"
+    });
+}
+function addBinding(bindingNode, scope, analysis, moduleVarKeys, out) {
+    const b = asBinding(bindingNode, analysis);
+    if (!b)
+        return;
+    if (b.initExpr)
+        walk(b.initExpr, scope, analysis, moduleVarKeys, out);
+    scope.add(qnameKey(b.qname));
+    if (b.positionalVar)
+        scope.add(qnameKey(b.positionalVar.qname));
+}
+// ── Scope-aware AST walker ────────────────────────────────────────────────────
+function walk(node, scope, analysis, moduleVarKeys, out) {
+    if (isTerminal(node))
+        return;
+    const { children } = node;
+    switch (node.type) {
+        case "AnnotatedDecl": {
+            const fnDeclNode = directChildOf(node, "FunctionDecl");
+            const fn = fnDeclNode ? asFunctionDecl(fnDeclNode, analysis) : null;
+            if (fn) {
+                scope.push();
+                for (const p of fn.params)
+                    scope.add(qnameKey(p.qname));
+                if (fn.body)
+                    walk(fn.body, scope, analysis, moduleVarKeys, out);
+                scope.pop();
+                return;
+            }
+            // Module variable declaration: walk the initializer expression only
+            const varDecl = directChildOf(node, "VarDecl");
+            if (varDecl && !isTerminal(varDecl)) {
+                for (const child of varDecl.children)
+                    walk(child, scope, analysis, moduleVarKeys, out);
+            }
+            return;
+        }
+        case "FLWORExpr": {
+            scope.push();
+            for (const child of children) {
+                if (isTerminal(child))
+                    continue;
+                // Unwrap InitialClause/IntermediateClause wrappers (may be multiply nested)
+                let clause = child;
+                while (!isTerminal(clause) && (clause.type === "InitialClause" || clause.type === "IntermediateClause")) {
+                    const inner = clause.children.find((c) => !isTerminal(c));
+                    if (!inner)
+                        break;
+                    clause = inner;
+                }
+                switch (clause.type) {
+                    case "ForClause":
+                        for (const b of directChildrenOf(clause, "ForBinding"))
+                            addBinding(b, scope, analysis, moduleVarKeys, out);
+                        break;
+                    case "LetClause":
+                        for (const b of directChildrenOf(clause, "LetBinding"))
+                            addBinding(b, scope, analysis, moduleVarKeys, out);
+                        break;
+                    case "CountClause":
+                        addBinding(clause, scope, analysis, moduleVarKeys, out);
+                        break;
+                    case "GroupByClause": {
+                        const specList = directChildOf(clause, "GroupingSpecList");
+                        for (const spec of specList ? directChildrenOf(specList, "GroupingSpec") : [])
+                            addBinding(spec, scope, analysis, moduleVarKeys, out);
+                        break;
+                    }
+                    case "WindowClause": {
+                        const inner = directChildOf(clause, "TumblingWindowClause") ??
+                            directChildOf(clause, "SlidingWindowClause");
+                        if (inner)
+                            addBinding(inner, scope, analysis, moduleVarKeys, out);
+                        for (const c of clause.children)
+                            if (!isTerminal(c))
+                                walk(c, scope, analysis, moduleVarKeys, out);
+                        break;
+                    }
+                    default:
+                        walk(clause, scope, analysis, moduleVarKeys, out);
+                }
+            }
+            scope.pop();
+            return;
+        }
+        case "QuantifiedExpr": {
+            scope.push();
+            for (const child of children) {
+                if (isTerminal(child))
+                    continue;
+                if (child.type === "VarName") {
+                    const qname = asVarName(child, analysis);
+                    if (qname)
+                        scope.add(qnameKey(qname));
+                }
+                else {
+                    walk(child, scope, analysis, moduleVarKeys, out);
+                }
+            }
+            scope.pop();
+            return;
+        }
+        case "CatchClause":
+            // Skip: implicit $err:* variables inside catch clauses are not tracked in the AST.
+            return;
+        case "VarRef": {
+            const qname = asVarRef(node, analysis);
+            if (qname && !isKnown(qname, scope, moduleVarKeys))
+                reportVarRef(node, qname, out);
+            return;
+        }
+        default:
+            for (const child of children)
+                walk(child, scope, analysis, moduleVarKeys, out);
+    }
+}
+// ── Public entry point ────────────────────────────────────────────────────────
+/**
+ * Walk the AST and report every variable reference that cannot be resolved
+ * to a declared variable: function parameter, let/for binding, module-level
+ * `declare variable`, or an imported module variable.
+ *
+ * Variables whose namespace prefix is undeclared are skipped — XQST0081
+ * already fires for those, and adding XPST0008 on top would be noisy.
+ * Variables inside catch clauses are also skipped since the implicit
+ * `$err:*` bindings are not represented in the AST.
+ */
+export function checkUndeclaredVariables(ast, analysis, importedAnalyses) {
+    const moduleVarKeys = new Set();
+    for (const v of analysis.moduleVariables)
+        moduleVarKeys.add(qnameKey(v.qname));
+    for (const imported of importedAnalyses.values())
+        for (const v of imported.moduleVariables)
+            moduleVarKeys.add(qnameKey(v.qname));
+    const out = [];
+    walk(ast, new ScopeStack(), analysis, moduleVarKeys, out);
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "xq-lsp",
-	"version": "1.4.1",
+	"version": "1.5.0",
 	"description": "XQuery Language Server Protocol implementation",
 	"license": "MIT",
 	"author": "Martin Middel",
@@ -17,7 +17,7 @@
 		"build": "tsc",
 		"start": "node ./src/server.ts --stdio",
 		"test": "node --test",
-		"test:coverage": "mkdir -p coverage && node --experimental-test-coverage --test --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info --test-coverage-exclude='src/**/*.test.ts'",
+		"test:coverage": "mkdir -p coverage && node --experimental-test-coverage --test --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='editors/**'",
 		"prepublishOnly": "npm run build"
 	},
 	"dependencies": {
@@ -25,7 +25,7 @@
 		"slimdom": "^4.3.5",
 		"vscode-languageserver": "^9.0.1",
 		"vscode-languageserver-textdocument": "^1.0.12",
-		"xq-parser": "^0.4.0"
+		"xq-parser": "^0.5.1"
 	},
 	"devDependencies": {
 		"@types/node": "^25.6.0",

package/src/completion-core.ts

@@ -1,6 +1,6 @@
-import type { FileAnalysis, FunctionSymbol, VariableSymbol } from "./types.ts";
+import type { FileAnalysis, FunctionSymbol, VariableSymbol, ParamInfo } from "./types.ts";
 import { formatQName } from "./types.ts";
-import { resolvePrefix } from "./analyzer.ts";
+import { resolvePrefix, nodeStackAtOffset, findAll } from "./analyzer.ts";
 
 export interface CompletionContext {
 	/** Text from start of document up to (and including) the cursor position */
@@ -61,6 +61,34 @@ function buildVariableEntry(v: VariableSymbol, filter: string): CompletionEntry
 	return { label, kind: "variable", insertText: label, isSnippet: false };
 }
 
+function buildParamEntry(p: ParamInfo, filter: string): CompletionEntry | null {
+	if (filter && !p.name.toLowerCase().startsWith(filter.toLowerCase())) return null;
+	return {
+		label: `$${p.name}`,
+		kind: "variable",
+		detail: p.type ? `as ${p.type}` : undefined,
+		insertText: `$${p.name}`,
+		isSnippet: false,
+	};
+}
+
+/** Find the function symbol enclosing the cursor using the AST. */
+function findEnclosingFunction(
+	ast: NonNullable<FileAnalysis["ast"]>,
+	cursorOffset: number,
+	functions: FunctionSymbol[],
+): { fn: FunctionSymbol; bodyStart: number; bodyEnd: number } | null {
+	const stack = nodeStackAtOffset(ast, cursorOffset);
+	const bodyNode = stack.slice().reverse().find((n) => n.type === "FunctionBody");
+	if (!bodyNode || bodyNode.start === undefined || bodyNode.end == null) return null;
+	const annotatedNode = stack.find((n) => n.type === "AnnotatedDecl");
+	if (!annotatedNode || annotatedNode.start === undefined) return null;
+	const fn = functions.find((f) => f.sourceOffset === annotatedNode.start);
+	if (!fn) return null;
+	return { fn, bodyStart: bodyNode.start, bodyEnd: bodyNode.end };
+}
+
+
 function buildFunctionEntry(fn: FunctionSymbol, label: string, snippets: boolean): CompletionEntry {
 	return {
 		label,
@@ -77,22 +105,59 @@ export function getCompletions(
 	currentAnalysis: FileAnalysis,
 	importedAnalyses: Map<string, FileAnalysis>,
 	snippets = false,
+	lastValidAnalysis?: FileAnalysis,
 ): CompletionEntry[] {
 	const token = parseToken(ctx.textBeforeCursor);
 	const items: CompletionEntry[] = [];
 
 	if (token.kind === "variable") {
 		const filter = token.prefix;
+
+		// Module-level variables are always visible
 		for (const v of currentAnalysis.moduleVariables) {
 			const e = buildVariableEntry(v, filter);
 			if (e) items.push(e);
 		}
-		for (const v of currentAnalysis.localBindings) {
-			if (v.offset < ctx.cursorOffset) {
-				const e = buildVariableEntry(v, filter);
-				if (e) items.push(e);
+
+		// Prefer the current AST; fall back to the last successfully-parsed one for scope analysis
+		const scopeAst = currentAnalysis.ast ?? lastValidAnalysis?.ast;
+		if (scopeAst) {
+			const enclosing = findEnclosingFunction(scopeAst, ctx.cursorOffset, currentAnalysis.functions);
+			if (enclosing) {
+				// Inside a function body: params + local bindings within this body before cursor
+				for (const p of enclosing.fn.params) {
+					const e = buildParamEntry(p, filter);
+					if (e) items.push(e);
+				}
+				for (const v of currentAnalysis.localBindings) {
+					if (v.offset > enclosing.bodyStart && v.offset < ctx.cursorOffset && v.offset < enclosing.bodyEnd) {
+						const e = buildVariableEntry(v, filter);
+						if (e) items.push(e);
+					}
+				}
+			} else {
+				// In query body: exclude local bindings that live inside function bodies
+				const functionBodyRanges = findAll(scopeAst, "FunctionBody")
+					.filter((b) => b.start !== undefined && b.end != null)
+					.map((b) => ({ start: b.start as number, end: b.end as number }));
+				for (const v of currentAnalysis.localBindings) {
+					if (v.offset >= ctx.cursorOffset) continue;
+					if (functionBodyRanges.some((r) => v.offset >= r.start && v.offset <= r.end)) continue;
+					const e = buildVariableEntry(v, filter);
+					if (e) items.push(e);
+				}
+			}
+		} else {
+			// No AST ever available: simple offset-based filter, no function-param completions
+			for (const v of currentAnalysis.localBindings) {
+				if (v.offset < ctx.cursorOffset) {
+					const e = buildVariableEntry(v, filter);
+					if (e) items.push(e);
+				}
 			}
 		}
+
+		// Imported module-level variables are always visible
 		for (const analysis of importedAnalyses.values()) {
 			for (const v of analysis.moduleVariables) {
 				const e = buildVariableEntry(v, filter);

package/src/runtimes/existdb/predeclared-namespaces.json

@@ -0,0 +1,34 @@
+{
+  "util": "http://exist-db.org/xquery/util",
+  "xmldb": "http://exist-db.org/xquery/xmldb",
+  "system": "http://exist-db.org/xquery/system",
+  "request": "http://exist-db.org/xquery/request",
+  "response": "http://exist-db.org/xquery/response",
+  "session": "http://exist-db.org/xquery/session",
+  "process": "http://exist-db.org/xquery/process",
+  "sm": "http://exist-db.org/xquery/securitymanager",
+  "inspect": "http://exist-db.org/xquery/inspection",
+  "ft": "http://exist-db.org/xquery/lucene",
+  "ngram": "http://exist-db.org/xquery/ngram",
+  "range": "http://exist-db.org/xquery/range",
+  "sort": "http://exist-db.org/xquery/sort",
+  "file": "http://exist-db.org/xquery/file",
+  "compression": "http://exist-db.org/xquery/compression",
+  "cache": "http://exist-db.org/xquery/cache",
+  "transform": "http://exist-db.org/xquery/transform",
+  "scheduler": "http://exist-db.org/xquery/scheduler",
+  "validation": "http://exist-db.org/xquery/validation",
+  "image": "http://exist-db.org/xquery/image",
+  "repo": "http://exist-db.org/xquery/repo",
+  "mail": "http://exist-db.org/xquery/mail",
+  "xmldiff": "http://exist-db.org/xquery/xmldiff",
+  "contentextraction": "http://exist-db.org/xquery/contentextraction",
+  "counter": "http://exist-db.org/xquery/counter",
+  "exist": "http://exist.sourceforge.net/NS/exist",
+  "xsi": "http://www.w3.org/2001/XMLSchema-instance",
+  "xdt": "http://www.w3.org/2003/05/xpath-datatypes",
+  "err": "http://www.w3.org/2005/xqt-errors",
+  "exerr": "http://www.exist-db.org/xqt-errors/",
+  "java": "http://exist.sourceforge.net/NS/exist/java-binding",
+  "dbgp": "http://www.xdebug.org/"
+}

package/src/runtimes/existdb/util.xq

@@ -619,6 +619,38 @@ declare function util:is-module-registered() as xs:boolean external;
  :)
 declare function util:line-number() as xs:integer external;
 
+(:~
+ : Logs a message to the current logger (log4j). The $priority argument
+ : specifies the log level, e.g. 'DEBUG', 'INFO', 'WARN', 'ERROR'.
+ : @param $priority The log level priority string (e.g. 'INFO', 'WARN', 'ERROR')
+ : @param $message The message to log
+ :)
+declare function util:log($priority as xs:string, $message as item()*) as empty-sequence() external;
+
+(:~
+ : Logs a message to a named logger.
+ : @param $priority The log level: 'error', 'warn', 'debug', 'info', 'trace'
+ : @param $logger-name The name of the logger, e.g. 'my.app.log'
+ : @param $message The message to log
+ :)
+declare function util:log-app(
+	$priority as xs:string,
+	$logger-name as xs:string,
+	$message as item()*
+) as empty-sequence() external;
+
+(:~
+ : Logs the message to System.err.
+ : @param $message The message to log
+ :)
+declare function util:log-system-err($message as item()*) as empty-sequence() external;
+
+(:~
+ : Logs the message to System.out.
+ : @param $message The message to log
+ :)
+declare function util:log-system-out($message as item()*) as empty-sequence() external;
+
 (:~
  : Returns a sequence of function items for each function in the current
  : module.

package/src/runtimes.ts

@@ -2,10 +2,24 @@ import * as path from "path";
 import * as fs from "fs";
 import { fileURLToPath } from "url";
 import { analyze } from "./analyzer.ts";
-import type { FileAnalysis } from "./types.ts";
+import type { FileAnalysis, NamespaceDecl } from "./types.ts";
 
 const runtimesDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "runtimes");
 
+function toNamespaceDecls(raw: Record<string, string>): NamespaceDecl[] {
+	return Object.entries(raw).map(([prefix, namespaceUri]) => ({ prefix, namespaceUri }));
+}
+
+// Lazily loaded predeclared namespace list for the existdb runtime.
+let existdbPredeclared: NamespaceDecl[] | null = null;
+function loadExistdbPredeclared(): NamespaceDecl[] {
+	return (existdbPredeclared ??= toNamespaceDecls(
+		JSON.parse(
+			fs.readFileSync(path.join(runtimesDir, "existdb", "predeclared-namespaces.json"), "utf-8"),
+		) as Record<string, string>,
+	));
+}
+
 const RUNTIME_FILES: Record<string, string[]> = {
 	fonto: [path.join(runtimesDir, "fonto", "fonto.xq")],
 	existdb: [
@@ -44,6 +58,34 @@ const RUNTIME_FILES: Record<string, string[]> = {
 
 const runtimeAnalysisCache = new Map<string, FileAnalysis>();
 
+/**
+ * Returns all namespace declarations that are in scope without any explicit
+ * `import module namespace` or `declare namespace` statement. Includes the
+ * standard XQuery 3.1 predeclared namespaces (math, map, array) and any
+ * runtime-specific additions (e.g. eXist-db's util, xmldb, …).
+ */
+export function getRuntimePredeclaredNamespaces(runtimes: string[]): NamespaceDecl[] {
+	if (!runtimes.includes("existdb")) return [];
+	return loadExistdbPredeclared();
+}
+
+/**
+ * Return a copy of `analysis` with the given predeclared namespace declarations
+ * merged into `namespaceDecls`. Prefixes already visible via imports, the
+ * module's own prefix, or an existing `declare namespace` are skipped.
+ */
+export function withPredeclaredNs(analysis: FileAnalysis, predeclaredNs: NamespaceDecl[]): FileAnalysis {
+	if (predeclaredNs.length === 0) return analysis;
+	const known = new Set<string>([
+		...analysis.imports.map((i) => i.prefix),
+		...analysis.namespaceDecls.map((nd) => nd.prefix),
+		...(analysis.modulePrefix ? [analysis.modulePrefix] : []),
+	]);
+	const toAdd = predeclaredNs.filter((nd) => !known.has(nd.prefix));
+	if (toAdd.length === 0) return analysis;
+	return { ...analysis, namespaceDecls: [...analysis.namespaceDecls, ...toAdd] };
+}
+
 export function getRuntimeAnalyses(runtimes: string[]): FileAnalysis[] {
 	const results: FileAnalysis[] = [];
 	for (const runtime of runtimes) {

package/src/server.ts

@@ -28,13 +28,15 @@ import {
 } from "./namespace-diagnostics.ts";
 import type { NamespaceUsageKind } from "./namespace-diagnostics.ts";
 import { checkUnused } from "./unused-diagnostics.ts";
+import { checkUndeclaredVariables } from "./variable-diagnostics.ts";
 import { checkContextItemUsage } from "./context-item-diagnostics.ts";
-import { getRuntimeAnalyses } from "./runtimes.ts";
+import { getRuntimeAnalyses, getRuntimePredeclaredNamespaces, withPredeclaredNs } from "./runtimes.ts";
 
 const connection = createConnection(ProposedFeatures.all);
 const documents = new TextDocuments(TextDocument);
 
 const analysisCache = new Map<string, FileAnalysis>();
+const lastValidAnalysisCache = new Map<string, FileAnalysis>(); // last AST-path analysis per URI
 const typeErrorCache = new Map<string, TypeDiagnostic[]>();
 
 // Glob analyses keyed by config directory, then by module namespace URI.
@@ -44,6 +46,7 @@ const globAnalysesByConfigDir = new Map<string, Map<string, FileAnalysis>>();
 function analyzeDocument(doc: TextDocument): FileAnalysis {
 	const { analysis } = analyzeWithAst(doc.getText(), doc.uri);
 	analysisCache.set(doc.uri, analysis);
+	if (analysis.usedAstPath) lastValidAnalysisCache.set(doc.uri, analysis);
 	return analysis;
 }
 
@@ -55,6 +58,7 @@ function analyzeDocumentFull(doc: TextDocument): {
 } {
 	const { analysis, ast, parseError } = analyzeWithAst(doc.getText(), doc.uri);
 	analysisCache.set(doc.uri, analysis);
+	if (analysis.usedAstPath) lastValidAnalysisCache.set(doc.uri, analysis);
 	return { analysis, parseDiagnostics: buildParseDiagnostics(parseError), hasAst: ast !== null, ast };
 }
 
@@ -133,10 +137,16 @@ function getGlobAnalyses(currentUri: string): { byNamespace: Map<string, FileAna
 	return { byNamespace, lib };
 }
 
-function resolveImports(currentUri: string, analysis: FileAnalysis): Map<string, FileAnalysis> {
+function resolveContext(
+	currentUri: string,
+	rawAnalysis: FileAnalysis,
+): { analysis: FileAnalysis; imported: Map<string, FileAnalysis> } {
 	const result = new Map<string, FileAnalysis>();
 	result.set("builtin:fn", getBuiltins());
 	const { byNamespace: globAnalyses, lib } = getGlobAnalyses(currentUri);
+	const predeclaredNs = getRuntimePredeclaredNamespaces(lib);
+	const analysis = withPredeclaredNs(rawAnalysis, predeclaredNs);
+
 	const runtimeByNamespace = new Map<string, FileAnalysis>();
 	for (const runtimeAnalysis of getRuntimeAnalyses(lib)) {
 		if (runtimeAnalysis.moduleNamespaceUri) {
@@ -147,7 +157,7 @@ function resolveImports(currentUri: string, analysis: FileAnalysis): Map<string,
 			);
 		}
 	}
-	for (const imp of analysis.imports) {
+	for (const imp of rawAnalysis.imports) {
 		if (imp.atPath) {
 			const uri = resolveImportUri(currentUri, imp.atPath);
 			const imported = getImportedAnalysis(uri);
@@ -158,7 +168,14 @@ function resolveImports(currentUri: string, analysis: FileAnalysis): Map<string,
 			if (imported) result.set(imp.namespaceUri, imported);
 		}
 	}
-	return result;
+	// Add pre-declared runtime analyses directly — available without explicit import
+	for (const nd of predeclaredNs) {
+		if (!result.has(nd.namespaceUri)) {
+			const runtimeAnalysis = runtimeByNamespace.get(nd.namespaceUri);
+			if (runtimeAnalysis) result.set(nd.namespaceUri, runtimeAnalysis);
+		}
+	}
+	return { analysis, imported: result };
 }
 
 // ── LSP lifecycle ────────────────────────────────────────────────────────────
@@ -187,13 +204,13 @@ connection.onInitialize((params) => {
 
 documents.onDidChangeContent((change) => {
 	const doc = change.document;
-	const { analysis, parseDiagnostics: parseDiags, hasAst, ast } = analyzeDocumentFull(doc);
+	const { analysis: rawAnalysis, parseDiagnostics: parseDiags, hasAst, ast } = analyzeDocumentFull(doc);
+	const { analysis, imported: resolvedImported } = resolveContext(doc.uri, rawAnalysis);
 
 	if (hasAst && ast !== null) {
-		const imported = resolveImports(doc.uri, analysis);
 		typeErrorCache.set(doc.uri, [
-			...checkTypes(ast, doc.getText(), analysis, imported),
-			...checkFunctionCalls(ast, analysis, imported),
+			...checkTypes(ast, doc.getText(), analysis, resolvedImported),
+			...checkFunctionCalls(ast, analysis, resolvedImported),
 		]);
 	}
 
@@ -247,39 +264,56 @@ documents.onDidChangeContent((change) => {
 		source: "xquery-lsp",
 	}));
 
+	const undeclaredVarDiagRaw =
+		hasAst && ast !== null ? checkUndeclaredVariables(ast, analysis, resolvedImported) : [];
+	const undeclaredVarDiags = undeclaredVarDiagRaw.map((d) => ({
+		severity: DiagnosticSeverity.Error,
+		range: {
+			start: doc.positionAt(d.offset),
+			end: doc.positionAt(d.offset + d.length),
+		},
+		message: d.message,
+		code: d.code,
+		source: "xquery-lsp",
+	}));
+
 	connection.sendDiagnostics({
 		uri: doc.uri,
-		diagnostics: [...parseDiags, ...typeDiags, ...nsDiags, ...unusedDiags, ...contextItemDiags],
+		diagnostics: [
+			...parseDiags, ...typeDiags, ...nsDiags, ...unusedDiags, ...contextItemDiags,
+			...undeclaredVarDiags,
+		],
 	});
 });
 
 connection.onCompletion((params) => {
 	const doc = documents.get(params.textDocument.uri);
 	if (!doc) return [];
-	const analysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
-	const imported = resolveImports(doc.uri, analysis);
+	const rawAnalysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
+	const { analysis, imported } = resolveContext(doc.uri, rawAnalysis);
 	const offset = doc.offsetAt(params.position);
 	return getCompletions(
 		{ textBeforeCursor: doc.getText().slice(0, offset), cursorOffset: offset },
 		analysis,
 		imported,
 		snippetSupport,
+		lastValidAnalysisCache.get(doc.uri),
 	);
 });
 
 connection.onHover((params) => {
 	const doc = documents.get(params.textDocument.uri);
 	if (!doc) return null;
-	const analysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
-	const imported = resolveImports(doc.uri, analysis);
+	const rawAnalysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
+	const { analysis, imported } = resolveContext(doc.uri, rawAnalysis);
 	return getHover(doc, doc.offsetAt(params.position), analysis, imported);
 });
 
 connection.onSignatureHelp((params) => {
 	const doc = documents.get(params.textDocument.uri);
 	if (!doc) return null;
-	const analysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
-	const imported = resolveImports(doc.uri, analysis);
+	const rawAnalysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
+	const { analysis, imported } = resolveContext(doc.uri, rawAnalysis);
 	return getSignatureHelp(doc, doc.offsetAt(params.position), analysis, imported);
 });
 
@@ -293,8 +327,8 @@ connection.onDocumentSymbol((params) => {
 connection.onDefinition((params) => {
 	const doc = documents.get(params.textDocument.uri);
 	if (!doc) return null;
-	const analysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
-	const imported = resolveImports(doc.uri, analysis);
+	const rawAnalysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
+	const { analysis, imported } = resolveContext(doc.uri, rawAnalysis);
 	return getDefinition(doc, doc.offsetAt(params.position), analysis, imported, (atPath) =>
 		resolveImportUri(doc.uri, atPath),
 	);

package/src/variable-diagnostics.ts

@@ -0,0 +1,190 @@
+import type { Node, NonTerminal } from "xq-parser";
+import type { FileAnalysis, QName } from "./types.ts";
+import { qnameKey } from "./types.ts";
+import { isTerminal, directChildOf, directChildrenOf } from "./analyzer.ts";
+import { asFunctionDecl, asVarRef, asVarName, asBinding } from "./ast-nodes.ts";
+
+export interface UndeclaredVariableDiagnostic {
+	message: string;
+	code: "XPST0008";
+	offset: number;
+	length: number;
+}
+
+// ── Scope stack ───────────────────────────────────────────────────────────────
+
+class ScopeStack {
+	private frames: Array<Set<string>> = [];
+	push(): void { this.frames.push(new Set()); }
+	pop(): void { this.frames.pop(); }
+	add(key: string): void { this.frames[this.frames.length - 1]?.add(key); }
+	has(key: string): boolean { return this.frames.some((f) => f.has(key)); }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function isKnown(qname: QName, scope: ScopeStack, moduleVarKeys: Set<string>): boolean {
+	// Variables with an undeclared-prefix URI are already caught by XQST0081; skip here.
+	if (qname.namespaceUri.startsWith("urn:xq-lsp:undeclared:")) return true;
+	return scope.has(qnameKey(qname)) || moduleVarKeys.has(qnameKey(qname));
+}
+
+function reportVarRef(node: Node, qname: QName, out: UndeclaredVariableDiagnostic[]): void {
+	const name = qname.prefix ? `${qname.prefix}:${qname.localName}` : qname.localName;
+	out.push({
+		message: `Variable '$${name}' is not declared`,
+		code: "XPST0008",
+		offset: node.start ?? 0,
+		length: name.length + 1, // +1 for "$"
+	});
+}
+
+function addBinding(
+	bindingNode: Node,
+	scope: ScopeStack,
+	analysis: FileAnalysis,
+	moduleVarKeys: Set<string>,
+	out: UndeclaredVariableDiagnostic[],
+): void {
+	const b = asBinding(bindingNode, analysis);
+	if (!b) return;
+	if (b.initExpr) walk(b.initExpr, scope, analysis, moduleVarKeys, out);
+	scope.add(qnameKey(b.qname));
+	if (b.positionalVar) scope.add(qnameKey(b.positionalVar.qname));
+}
+
+// ── Scope-aware AST walker ────────────────────────────────────────────────────
+
+function walk(
+	node: Node,
+	scope: ScopeStack,
+	analysis: FileAnalysis,
+	moduleVarKeys: Set<string>,
+	out: UndeclaredVariableDiagnostic[],
+): void {
+	if (isTerminal(node)) return;
+	const { children } = node as NonTerminal;
+
+	switch (node.type) {
+		case "AnnotatedDecl": {
+			const fnDeclNode = directChildOf(node, "FunctionDecl");
+			const fn = fnDeclNode ? asFunctionDecl(fnDeclNode, analysis) : null;
+			if (fn) {
+				scope.push();
+				for (const p of fn.params) scope.add(qnameKey(p.qname));
+				if (fn.body) walk(fn.body, scope, analysis, moduleVarKeys, out);
+				scope.pop();
+				return;
+			}
+			// Module variable declaration: walk the initializer expression only
+			const varDecl = directChildOf(node, "VarDecl");
+			if (varDecl && !isTerminal(varDecl)) {
+				for (const child of (varDecl as NonTerminal).children)
+					walk(child, scope, analysis, moduleVarKeys, out);
+			}
+			return;
+		}
+
+		case "FLWORExpr": {
+			scope.push();
+			for (const child of children) {
+				if (isTerminal(child)) continue;
+				// Unwrap InitialClause/IntermediateClause wrappers (may be multiply nested)
+				let clause: Node = child;
+				while (!isTerminal(clause) && (clause.type === "InitialClause" || clause.type === "IntermediateClause")) {
+					const inner: Node | undefined = (clause as NonTerminal).children.find((c) => !isTerminal(c));
+					if (!inner) break;
+					clause = inner;
+				}
+				switch (clause.type) {
+					case "ForClause":
+						for (const b of directChildrenOf(clause, "ForBinding"))
+							addBinding(b, scope, analysis, moduleVarKeys, out);
+						break;
+					case "LetClause":
+						for (const b of directChildrenOf(clause, "LetBinding"))
+							addBinding(b, scope, analysis, moduleVarKeys, out);
+						break;
+					case "CountClause":
+						addBinding(clause, scope, analysis, moduleVarKeys, out);
+						break;
+					case "GroupByClause": {
+						const specList = directChildOf(clause, "GroupingSpecList");
+						for (const spec of specList ? directChildrenOf(specList, "GroupingSpec") : [])
+							addBinding(spec, scope, analysis, moduleVarKeys, out);
+						break;
+					}
+					case "WindowClause": {
+						const inner =
+							directChildOf(clause, "TumblingWindowClause") ??
+							directChildOf(clause, "SlidingWindowClause");
+						if (inner) addBinding(inner, scope, analysis, moduleVarKeys, out);
+						for (const c of (clause as NonTerminal).children)
+							if (!isTerminal(c)) walk(c, scope, analysis, moduleVarKeys, out);
+						break;
+					}
+					default:
+						walk(clause, scope, analysis, moduleVarKeys, out);
+				}
+			}
+			scope.pop();
+			return;
+		}
+
+		case "QuantifiedExpr": {
+			scope.push();
+			for (const child of children) {
+				if (isTerminal(child)) continue;
+				if (child.type === "VarName") {
+					const qname = asVarName(child, analysis);
+					if (qname) scope.add(qnameKey(qname));
+				} else {
+					walk(child, scope, analysis, moduleVarKeys, out);
+				}
+			}
+			scope.pop();
+			return;
+		}
+
+		case "CatchClause":
+			// Skip: implicit $err:* variables inside catch clauses are not tracked in the AST.
+			return;
+
+		case "VarRef": {
+			const qname = asVarRef(node, analysis);
+			if (qname && !isKnown(qname, scope, moduleVarKeys))
+				reportVarRef(node, qname, out);
+			return;
+		}
+
+		default:
+			for (const child of children) walk(child, scope, analysis, moduleVarKeys, out);
+	}
+}
+
+// ── Public entry point ────────────────────────────────────────────────────────
+
+/**
+ * Walk the AST and report every variable reference that cannot be resolved
+ * to a declared variable: function parameter, let/for binding, module-level
+ * `declare variable`, or an imported module variable.
+ *
+ * Variables whose namespace prefix is undeclared are skipped — XQST0081
+ * already fires for those, and adding XPST0008 on top would be noisy.
+ * Variables inside catch clauses are also skipped since the implicit
+ * `$err:*` bindings are not represented in the AST.
+ */
+export function checkUndeclaredVariables(
+	ast: Node,
+	analysis: FileAnalysis,
+	importedAnalyses: Map<string, FileAnalysis>,
+): UndeclaredVariableDiagnostic[] {
+	const moduleVarKeys = new Set<string>();
+	for (const v of analysis.moduleVariables) moduleVarKeys.add(qnameKey(v.qname));
+	for (const imported of importedAnalyses.values())
+		for (const v of imported.moduleVariables) moduleVarKeys.add(qnameKey(v.qname));
+
+	const out: UndeclaredVariableDiagnostic[] = [];
+	walk(ast, new ScopeStack(), analysis, moduleVarKeys, out);
+	return out;
+}