xq-lsp 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # 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)
+
+
+### Bug Fixes
+
+* change the bin to the dist version ([e77944d](https://github.com/DrRataplan/xq-lsp/commit/e77944de7da857ac6ca9d3148b4a41abec175de4))
+* do not package testing snapshots to npm ([9638734](https://github.com/DrRataplan/xq-lsp/commit/963873401f3e4d74a9338c387bcfc3c3564f4f0d))
+* union multiple imports of modules ([1d77b65](https://github.com/DrRataplan/xq-lsp/commit/1d77b65b48933abfe20c6f0e9abd113c318f16b4))
+
 ## [1.4.0](https://github.com/DrRataplan/xq-lsp/compare/lsp-v1.3.0...lsp-v1.4.0) (2026-05-28)
 
 

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) {
@@ -77,6 +83,13 @@ function getImportedAnalysis(importUri) {
         return null;
     }
 }
+function mergeAnalyses(a, b) {
+    return {
+        ...a,
+        functions: [...a.functions, ...b.functions],
+        moduleVariables: [...a.moduleVariables, ...b.moduleVariables],
+    };
+}
 function getGlobAnalyses(currentUri) {
     const found = findConfig(currentUri);
     if (!found)
@@ -90,23 +103,28 @@ function getGlobAnalyses(currentUri) {
     for (const filePath of expandGlobs(config.globs, configDir)) {
         const fileUri = pathToFileURL(filePath).toString();
         const imported = getImportedAnalysis(fileUri);
-        if (imported?.moduleNamespaceUri)
-            byNamespace.set(imported.moduleNamespaceUri, imported);
+        if (!imported?.moduleNamespaceUri)
+            continue;
+        const existing = byNamespace.get(imported.moduleNamespaceUri);
+        byNamespace.set(imported.moduleNamespaceUri, existing ? mergeAnalyses(existing, imported) : imported);
     }
     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) {
-            runtimeByNamespace.set(runtimeAnalysis.moduleNamespaceUri, runtimeAnalysis);
+            const existing = runtimeByNamespace.get(runtimeAnalysis.moduleNamespaceUri);
+            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);
@@ -120,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;
@@ -145,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) => ({
@@ -199,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) => {
@@ -240,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;
+}