xq-lsp 1.7.0 → 1.8.1

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## [1.8.1](https://github.com/DrRataplan/xq-lsp/compare/lsp-v1.8.0...lsp-v1.8.1) (2026-07-29)
+
+
+### Bug Fixes
+
+* stop retaining full ASTs for every glob-matched file to prevent OOM ([b44460f](https://github.com/DrRataplan/xq-lsp/commit/b44460f1de449b48903ebddff4f56b7524b99234))
+
+## [1.8.0](https://github.com/DrRataplan/xq-lsp/compare/lsp-v1.7.0...lsp-v1.8.0) (2026-07-28)
+
+
+### Features
+
+* add AST debug panel to demo and standalone dump-ast script ([dd42db4](https://github.com/DrRataplan/xq-lsp/commit/dd42db4866af25cd25732c3464089447e6a537ce))
+* add call hierarchy support ([27cbe5d](https://github.com/DrRataplan/xq-lsp/commit/27cbe5d8c01e376f6e6dba3bc8903913ef4e0181))
+* add code lens for reference counts ([b69300a](https://github.com/DrRataplan/xq-lsp/commit/b69300a3c036198d05eb24dacd7ecf000eed1d6e))
+* add document links for module imports ([154bb04](https://github.com/DrRataplan/xq-lsp/commit/154bb0448758d49b26839ecff882381a4adaeb20)), closes [#118](https://github.com/DrRataplan/xq-lsp/issues/118)
+* add inlay hints for parameter names and inferred types ([ee90295](https://github.com/DrRataplan/xq-lsp/commit/ee9029594df7a4faef6af7e34291aa77ae1a50a7))
+* add refactor code actions ([34a9315](https://github.com/DrRataplan/xq-lsp/commit/34a93155f953f11d40579b38454b7614cba8e92c)), closes [#121](https://github.com/DrRataplan/xq-lsp/issues/121)
+* add workspace symbol search ([fdeb48e](https://github.com/DrRataplan/xq-lsp/commit/fdeb48e2ab56478480847c8b3bb7b4dd7da09008))
+* predeclare eXist-db install-script variables and surface variable doc comments ([67a8075](https://github.com/DrRataplan/xq-lsp/commit/67a807500cb723c0e8d6e8b229b06ccaf3e0fa04))
+* show inlay hints in the demo playground ([169814d](https://github.com/DrRataplan/xq-lsp/commit/169814da37a47d141062946c255fd1ecb46a008f))
+
+
+### Bug Fixes
+
+* add hint diagnostic for whitespace inside Q{uri} literals ([5f8d5d6](https://github.com/DrRataplan/xq-lsp/commit/5f8d5d6b4a517cf997b73a8c39d6d22621cfcf82))
+* **ci:** pack xq-lsp before installing vscode extension deps ([527d824](https://github.com/DrRataplan/xq-lsp/commit/527d82486a26ea7742ad74d58c0ab18330a61405))
+* **ci:** stop validating packed xq-lsp tarball against stale lockfile ([2369252](https://github.com/DrRataplan/xq-lsp/commit/23692529a2cf9d759665dee80c6e9c7aa1ac0968))
+* correct qt4tests exclusion typo in .npmignore ([20080f1](https://github.com/DrRataplan/xq-lsp/commit/20080f1c242640bc9184a30949fe949b016398a4))
+* declare vscode-languageserver-textdocument as a demo dependency ([013b04f](https://github.com/DrRataplan/xq-lsp/commit/013b04f9fd4da712bf56cb4afe731eed0f4b26f4))
+* don't hover function signatures on lookalike element/attribute names ([1d87635](https://github.com/DrRataplan/xq-lsp/commit/1d87635e6c98b1bb1eb3af5e49b0ec6ae175e128))
+* exclude version-exclusive spec dependencies from QT4 3.1 filter ([ad9bbe5](https://github.com/DrRataplan/xq-lsp/commit/ad9bbe5290ccb16f055da9df454d471f9ed5bec2))
+* exclude XP-only spec dependencies from QT4 3.1 filter ([e5514b1](https://github.com/DrRataplan/xq-lsp/commit/e5514b1f6019ee694b7bb0fa6603a853e46cb55c))
+* honor lib config for runtime function diagnostics in the playground demo ([cc29fd2](https://github.com/DrRataplan/xq-lsp/commit/cc29fd2f6edaccc655f9332e41db3ba9e3ab018a))
+* infer arithmetic types and stop misinferring literal path exprs as nodes ([825a9ab](https://github.com/DrRataplan/xq-lsp/commit/825a9ab1b004c262c4d7cb0f585df67bc441b6f6))
+* infer inlay hint types for for-bindings over range/typed sequences ([1a6d202](https://github.com/DrRataplan/xq-lsp/commit/1a6d202349e7d79372d79d5dd199e636de8926dc))
+* predeclare xsi namespace prefix unconditionally ([ac6f47d](https://github.com/DrRataplan/xq-lsp/commit/ac6f47d59176cde7c2e0649cb4854d02c71811a4))
+* resolve vscode-languageserver from src/inlay-hints.ts in the demo build ([db43ee1](https://github.com/DrRataplan/xq-lsp/commit/db43ee184a7005fb76e93a87dfcf6dd716acef33))
+* resolve XPST0008 false positives from typeswitch scoping and EQName whitespace ([df0f89c](https://github.com/DrRataplan/xq-lsp/commit/df0f89c45fbe6ee2330e9311dc639f59bd4370a9))
+
 ## [1.7.0](https://github.com/DrRataplan/xq-lsp/compare/lsp-v1.6.0...lsp-v1.7.0) (2026-07-15)
 
 

package/demo/index.html

@@ -30,8 +30,24 @@
 				font-size: 15px;
 				font-weight: 600;
 			}
-			#share-btn {
+			#ast-toggle {
 				margin-left: auto;
+				background: transparent;
+				color: #cdd6f4;
+				border: 1px solid #45475a;
+				padding: 4px 12px;
+				border-radius: 4px;
+				cursor: pointer;
+				font-size: 13px;
+				font-weight: 600;
+			}
+			#ast-toggle:hover {
+				border-color: #89b4fa;
+			}
+			#ast-toggle.active {
+				background: #45475a;
+			}
+			#share-btn {
 				background: #89b4fa;
 				color: #1e1e2e;
 				border: none;
@@ -44,11 +60,48 @@
 			#share-btn:hover {
 				background: #74c7ec;
 			}
+			#main {
+				flex: 1;
+				display: flex;
+				overflow: hidden;
+				min-height: 0;
+			}
 			#editor {
 				flex: 1;
 				overflow: hidden;
 				min-height: 0;
 			}
+			#ast-panel {
+				display: none;
+				width: 420px;
+				flex-shrink: 0;
+				flex-direction: column;
+				background: #181825;
+				border-left: 1px solid #45475a;
+				overflow: hidden;
+			}
+			#ast-panel.visible {
+				display: flex;
+			}
+			#ast-label {
+				padding: 3px 12px;
+				font-size: 11px;
+				color: #585b70;
+				font-family: monospace;
+				border-bottom: 1px solid #313244;
+				letter-spacing: 0.02em;
+				flex-shrink: 0;
+			}
+			#ast-output {
+				flex: 1;
+				margin: 0;
+				padding: 8px 12px;
+				overflow: auto;
+				font-family: monospace;
+				font-size: 11px;
+				color: #cdd6f4;
+				white-space: pre;
+			}
 			.cm-editor {
 				height: 100%;
 			}
@@ -88,6 +141,15 @@
 				color: #89b4fa;
 				font-weight: bold;
 			}
+			.xq-inlay-hint {
+				font-family: monospace;
+				font-size: 11px;
+				color: #9399b2;
+				background: #313244;
+				border-radius: 3px;
+				padding: 0 4px;
+				margin: 0 2px;
+			}
 			#config-panel {
 				flex-shrink: 0;
 				background: #181825;
@@ -135,9 +197,16 @@
 		<header>
 			<img src="./favicon.svg" alt="" width="20" height="20" />
 			<h1>xq-lsp playground</h1>
+			<button id="ast-toggle">Show AST</button>
 			<button id="share-btn">Copy link</button>
 		</header>
-		<div id="editor"></div>
+		<div id="main">
+			<div id="editor"></div>
+			<div id="ast-panel">
+				<div id="ast-label">ast (xq-parser)</div>
+				<pre id="ast-output"></pre>
+			</div>
+		</div>
 		<div id="config-panel">
 			<div id="config-label">lsp-config.xq</div>
 			<textarea

package/demo/main.ts

@@ -1,11 +1,13 @@
 import { EditorView, basicSetup } from "codemirror";
-import { hoverTooltip, showTooltip } from "@codemirror/view";
-import { StateField } from "@codemirror/state";
+import { hoverTooltip, showTooltip, Decoration, WidgetType, type DecorationSet } from "@codemirror/view";
+import { StateField, StateEffect } from "@codemirror/state";
 import { StreamLanguage } from "@codemirror/language";
 import { xQuery } from "@codemirror/legacy-modes/mode/xquery";
 import { linter, lintGutter, forceLinting, type Diagnostic } from "@codemirror/lint";
 import { autocompletion, type CompletionContext as CMCompletionContext } from "@codemirror/autocomplete";
 import { analyzeWithAst, analyze, XMLNS_FN } from "../src/analyzer.ts";
+import { getInlayHints } from "../src/inlay-hints.ts";
+import { TextDocument } from "vscode-languageserver-textdocument";
 import builtinsFn from "../builtins/builtins-fn.xq?raw";
 import builtinsMath from "../builtins/builtins-math.xq?raw";
 import builtinsMap from "../builtins/builtins-map.xq?raw";
@@ -13,10 +15,45 @@ import builtinsArray from "../builtins/builtins-array.xq?raw";
 import { findUndeclaredPrefixUsages } from "../src/namespace-diagnostics.ts";
 import { runDiagnostics, runHints } from "../src/diagnostics.ts";
 import { type FileAnalysis } from "../src/types.ts";
+import type { Node } from "xq-parser";
 import { resolveFunctionAtOffset, resolveSignatureAtOffset, functionSignature } from "../src/hover-core.ts";
 import { getCompletions } from "../src/completion-core.ts";
+import { getRuntimePredeclaredNamespaces, withPredeclaredNs } from "../src/predeclared-namespaces.ts";
 import fontoxpath from "fontoxpath";
 
+// Raw XQuery source for every runtime module file (src/runtimes/<lib>/*.xq), grouped
+// by lib name below. Loaded eagerly via ?raw so this stays a plain string bundled
+// into the browser build — src/runtimes.ts itself uses Node's fs and can't be
+// imported here (see the computeRelativePath fix for the same class of issue).
+const runtimeSources = import.meta.glob("../src/runtimes/*/*.xq", {
+	query: "?raw",
+	import: "default",
+	eager: true,
+}) as Record<string, string>;
+
+const runtimeFilesByLib = new Map<string, string[]>();
+for (const [filePath, source] of Object.entries(runtimeSources)) {
+	const match = filePath.match(/\/runtimes\/([^/]+)\//);
+	if (!match) continue;
+	const list = runtimeFilesByLib.get(match[1]) ?? [];
+	list.push(source);
+	runtimeFilesByLib.set(match[1], list);
+}
+
+const runtimeAnalysisCache = new Map<string, FileAnalysis[]>();
+function getRuntimeAnalyses(libs: string[]): FileAnalysis[] {
+	const results: FileAnalysis[] = [];
+	for (const lib of libs) {
+		let cached = runtimeAnalysisCache.get(lib);
+		if (!cached) {
+			cached = (runtimeFilesByLib.get(lib) ?? []).map((src, i) => analyze(src, `builtin:${lib}:${i}`));
+			runtimeAnalysisCache.set(lib, cached);
+		}
+		results.push(...cached);
+	}
+	return results;
+}
+
 const DEFAULT_CODE = `(: xq-lsp playground — errors are annotated inline :)
 for $x in (1, 2, 3)
 return $x * 2
@@ -79,16 +116,40 @@ function getBuiltins() {
 	return _builtins;
 }
 
-function getImported(analysis: FileAnalysis): Map<string, FileAnalysis> {
-	return new Map([["builtin:fn", getBuiltins()]]);
+function getImported(analysis: FileAnalysis, libs: string[]): Map<string, FileAnalysis> {
+	const imported = new Map<string, FileAnalysis>([["builtin:fn", getBuiltins()]]);
+
+	const runtimeByNamespace = new Map<string, FileAnalysis>();
+	for (const runtimeAnalysis of getRuntimeAnalyses(libs)) {
+		if (runtimeAnalysis.moduleNamespaceUri)
+			runtimeByNamespace.set(runtimeAnalysis.moduleNamespaceUri, runtimeAnalysis);
+	}
+
+	for (const imp of analysis.imports) {
+		const runtimeAnalysis = runtimeByNamespace.get(imp.namespaceUri);
+		if (runtimeAnalysis) imported.set(imp.namespaceUri, runtimeAnalysis);
+	}
+
+	// Runtime modules that are pre-declared (e.g. existdb's util/xmldb) are available
+	// without an explicit import.
+	for (const nd of getRuntimePredeclaredNamespaces(libs)) {
+		if (!imported.has(nd.namespaceUri)) {
+			const runtimeAnalysis = runtimeByNamespace.get(nd.namespaceUri);
+			if (runtimeAnalysis) imported.set(nd.namespaceUri, runtimeAnalysis);
+		}
+	}
+
+	return imported;
 }
 
 // ── Hover ────────────────────────────────────────────────────────────────────
 
 const xqueryHover = hoverTooltip((view, pos) => {
 	const text = view.state.doc.toString();
-	const { analysis } = analyzeWithAst(text, "playground.xq");
-	const result = resolveFunctionAtOffset(text, pos, analysis, getImported(analysis));
+	const libs = getConfigLibs();
+	const { analysis: rawAnalysis } = analyzeWithAst(text, "playground.xq");
+	const analysis = withPredeclaredNs(rawAnalysis, getRuntimePredeclaredNamespaces(libs));
+	const result = resolveFunctionAtOffset(text, pos, analysis, getImported(analysis, libs));
 	if (!result) return null;
 
 	return {
@@ -118,11 +179,13 @@ function xqueryCompletions(ctx: CMCompletionContext) {
 	if (!word && !ctx.explicit) return null;
 
 	const text = ctx.state.doc.toString();
-	const { analysis } = analyzeWithAst(text, "playground.xq");
+	const libs = getConfigLibs();
+	const { analysis: rawAnalysis } = analyzeWithAst(text, "playground.xq");
+	const analysis = withPredeclaredNs(rawAnalysis, getRuntimePredeclaredNamespaces(libs));
 	const entries = getCompletions(
 		{ textBeforeCursor: text.slice(0, ctx.pos), cursorOffset: ctx.pos },
 		analysis,
-		getImported(analysis),
+		getImported(analysis, libs),
 	);
 	if (!entries.length) return null;
 
@@ -151,8 +214,10 @@ const signatureField = StateField.define({
 		showTooltip.computeN([f], (state) => {
 			const text = state.doc.toString();
 			const pos = state.selection.main.head;
-			const { analysis } = analyzeWithAst(text, "playground.xq");
-			const sig = resolveSignatureAtOffset(text, pos, analysis, new Map([["builtin:fn", getBuiltins()]]));
+			const libs = getConfigLibs();
+			const { analysis: rawAnalysis } = analyzeWithAst(text, "playground.xq");
+			const analysis = withPredeclaredNs(rawAnalysis, getRuntimePredeclaredNamespaces(libs));
+			const sig = resolveSignatureAtOffset(text, pos, analysis, getImported(analysis, libs));
 			if (!sig) return [];
 			const name = sig.fn.qname.prefix
 				? `${sig.fn.qname.prefix}:${sig.fn.qname.localName}`
@@ -183,6 +248,78 @@ const signatureField = StateField.define({
 		}),
 });
 
+// ── Inlay hints ───────────────────────────────────────────────────────────────
+
+class InlayHintWidget extends WidgetType {
+	constructor(private label: string) {
+		super();
+	}
+	eq(other: InlayHintWidget) {
+		return other.label === this.label;
+	}
+	toDOM() {
+		const span = document.createElement("span");
+		span.className = "xq-inlay-hint";
+		span.textContent = this.label;
+		return span;
+	}
+}
+
+const refreshInlayHints = StateEffect.define<null>();
+
+function computeInlayDecorations(text: string): DecorationSet {
+	const { analysis: rawAnalysis, ast } = analyzeWithAst(text, "playground.xq");
+	if (!ast) return Decoration.none;
+	const libs = getConfigLibs();
+	const analysis = withPredeclaredNs(rawAnalysis, getRuntimePredeclaredNamespaces(libs));
+	const doc = TextDocument.create("playground.xq", "xquery", 0, text);
+	const range = { start: doc.positionAt(0), end: doc.positionAt(text.length) };
+	const hints = getInlayHints(doc, ast, analysis, getImported(analysis, libs), range);
+
+	const widgets = hints.map((h) =>
+		Decoration.widget({ widget: new InlayHintWidget(h.label as string), side: 1 }).range(doc.offsetAt(h.position)),
+	);
+	widgets.sort((a, b) => a.from - b.from);
+	return Decoration.set(widgets);
+}
+
+const inlayHintsField = StateField.define<DecorationSet>({
+	create(state) {
+		return computeInlayDecorations(state.doc.toString());
+	},
+	update(decos, tr) {
+		if (!tr.docChanged && !tr.effects.some((e) => e.is(refreshInlayHints))) return decos.map(tr.changes);
+		return computeInlayDecorations(tr.state.doc.toString());
+	},
+	provide: (f) => EditorView.decorations.from(f),
+});
+
+// ── AST panel ─────────────────────────────────────────────────────────────────
+// Dumps the raw xq-parser tree for the current doc, for debugging analyzer/
+// diagnostic logic against a specific parse shape. Runnable outside the
+// browser too — see `node scripts/dump-ast.ts` (documented in CLAUDE.md).
+
+const astPanel = document.getElementById("ast-panel")!;
+const astOutput = document.getElementById("ast-output")!;
+const astToggle = document.getElementById("ast-toggle")!;
+
+function setAstVisible(visible: boolean) {
+	astPanel.classList.toggle("visible", visible);
+	astToggle.classList.toggle("active", visible);
+	astToggle.textContent = visible ? "Hide AST" : "Show AST";
+	const url = new URL(location.href);
+	if (visible) url.searchParams.set("ast", "1");
+	else url.searchParams.delete("ast");
+	history.replaceState(null, "", url);
+}
+
+function renderAst(ast: Node | null, parseError: Error | null) {
+	astOutput.textContent = parseError ? `Parse error: ${parseError.message}` : JSON.stringify(ast, null, 2);
+}
+
+astToggle.addEventListener("click", () => setAstVisible(!astPanel.classList.contains("visible")));
+setAstVisible(new URLSearchParams(location.search).get("ast") === "1");
+
 // ── Config panel ─────────────────────────────────────────────────────────────
 
 const configEl = document.getElementById("config-editor") as HTMLTextAreaElement;
@@ -205,9 +342,23 @@ function getConfigPrefixes(): Record<string, string> {
 	}
 }
 
+function getConfigLibs(): string[] {
+	const text = configEl.value.trim();
+	if (!text) return [];
+	try {
+		return fontoxpath.evaluateXPathToStrings(`(${text})?lib`, null, null, {});
+	} catch {
+		return [];
+	}
+}
+
 const xqueryLinter = linter((view): Diagnostic[] => {
 	const code = view.state.doc.toString();
-	const { analysis, ast, parseError } = analyzeWithAst(code, "playground.xq");
+	const libs = getConfigLibs();
+	const { analysis: rawAnalysis, ast, parseError } = analyzeWithAst(code, "playground.xq");
+	const analysis = withPredeclaredNs(rawAnalysis, getRuntimePredeclaredNamespaces(libs));
+	renderAst(ast, parseError);
+
 	const configPrefixes = getConfigPrefixes();
 	const diagnostics: Diagnostic[] = [];
 
@@ -234,7 +385,7 @@ const xqueryLinter = linter((view): Diagnostic[] => {
 	}
 
 	if (ast) {
-		const imported = getImported(analysis);
+		const imported = getImported(analysis, libs);
 		for (const d of runDiagnostics(ast, code, analysis, imported)) {
 			diagnostics.push({ from: d.offset, to: d.offset + d.length, severity: "error", message: d.message });
 		}
@@ -258,6 +409,7 @@ const view = new EditorView({
 		xqueryHover,
 		autocompletion({ override: [xqueryCompletions] }),
 		signatureField,
+		inlayHintsField,
 		EditorView.updateListener.of((update) => {
 			if (!update.docChanged) return;
 			const url = new URL(location.href);
@@ -289,6 +441,7 @@ function applyConfig() {
 	}
 	history.replaceState(null, "", url);
 	forceLinting(view);
+	view.dispatch({ effects: refreshInlayHints.of(null) });
 }
 
 applyConfig();

package/demo/package-lock.json

@@ -12,6 +12,8 @@
 				"@codemirror/lint": "^6.8.4",
 				"codemirror": "^6.0.1",
 				"fontoxpath": "^3.34.0",
+				"vscode-languageserver": "^9.0.1",
+				"vscode-languageserver-textdocument": "^1.0.12",
 				"xq-parser": "^0.4.0"
 			},
 			"devDependencies": {
@@ -1270,6 +1272,49 @@
 				}
 			}
 		},
+		"node_modules/vscode-jsonrpc": {
+			"version": "8.2.0",
+			"resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-8.2.0.tgz",
+			"integrity": "sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=14.0.0"
+			}
+		},
+		"node_modules/vscode-languageserver": {
+			"version": "9.0.1",
+			"resolved": "https://registry.npmjs.org/vscode-languageserver/-/vscode-languageserver-9.0.1.tgz",
+			"integrity": "sha512-woByF3PDpkHFUreUa7Hos7+pUWdeWMXRd26+ZX2A8cFx6v/JPTtd4/uN0/jB6XQHYaOlHbio03NTHCqrgG5n7g==",
+			"license": "MIT",
+			"dependencies": {
+				"vscode-languageserver-protocol": "3.17.5"
+			},
+			"bin": {
+				"installServerIntoExtension": "bin/installServerIntoExtension"
+			}
+		},
+		"node_modules/vscode-languageserver-protocol": {
+			"version": "3.17.5",
+			"resolved": "https://registry.npmjs.org/vscode-languageserver-protocol/-/vscode-languageserver-protocol-3.17.5.tgz",
+			"integrity": "sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg==",
+			"license": "MIT",
+			"dependencies": {
+				"vscode-jsonrpc": "8.2.0",
+				"vscode-languageserver-types": "3.17.5"
+			}
+		},
+		"node_modules/vscode-languageserver-textdocument": {
+			"version": "1.0.12",
+			"resolved": "https://registry.npmjs.org/vscode-languageserver-textdocument/-/vscode-languageserver-textdocument-1.0.12.tgz",
+			"integrity": "sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==",
+			"license": "MIT"
+		},
+		"node_modules/vscode-languageserver-types": {
+			"version": "3.17.5",
+			"resolved": "https://registry.npmjs.org/vscode-languageserver-types/-/vscode-languageserver-types-3.17.5.tgz",
+			"integrity": "sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg==",
+			"license": "MIT"
+		},
 		"node_modules/w3c-keyname": {
 			"version": "2.2.8",
 			"resolved": "https://registry.npmjs.org/w3c-keyname/-/w3c-keyname-2.2.8.tgz",

package/demo/package.json

@@ -12,6 +12,8 @@
 		"@codemirror/lint": "^6.8.4",
 		"codemirror": "^6.0.1",
 		"fontoxpath": "^3.34.0",
+		"vscode-languageserver": "^9.0.1",
+		"vscode-languageserver-textdocument": "^1.0.12",
 		"xq-parser": "^0.4.0"
 	},
 	"devDependencies": {

package/demo/vite.config.ts

@@ -10,6 +10,9 @@ export default defineConfig({
 			// xq-parser is imported by ../src/analyzer.ts; Rollup resolves it
 			// from src/'s ancestor chain and misses demo/node_modules.
 			"xq-parser": resolve(__dirname, "node_modules/xq-parser"),
+			// vscode-languageserver/node.js is imported by ../src/inlay-hints.ts for
+			// the InlayHintKind enum; same ancestor-chain resolution gap as xq-parser.
+			"vscode-languageserver/node.js": resolve(__dirname, "node_modules/vscode-languageserver/node.js"),
 		},
 	},
 });

package/dist/analyzer.d.ts

@@ -3,6 +3,7 @@ import type { FileAnalysis } from "./types.ts";
 export declare const XMLNS_FN = "http://www.w3.org/2005/xpath-functions";
 export declare const XMLNS_LOCAL = "http://www.w3.org/2005/xquery-local-functions";
 export declare const XMLNS_XS = "http://www.w3.org/2001/XMLSchema";
+export declare const XMLNS_XSI = "http://www.w3.org/2001/XMLSchema-instance";
 export declare const XMLNS_MATH = "http://www.w3.org/2005/xpath-functions/math";
 export declare const XMLNS_MAP = "http://www.w3.org/2005/xpath-functions/map";
 export declare const XMLNS_ARRAY = "http://www.w3.org/2005/xpath-functions/array";

package/dist/analyzer.js

@@ -3,13 +3,20 @@ import { XQuery31Full } from "xq-parser";
 export const XMLNS_FN = "http://www.w3.org/2005/xpath-functions";
 export const XMLNS_LOCAL = "http://www.w3.org/2005/xquery-local-functions";
 export const XMLNS_XS = "http://www.w3.org/2001/XMLSchema";
+export const XMLNS_XSI = "http://www.w3.org/2001/XMLSchema-instance";
 export const XMLNS_MATH = "http://www.w3.org/2005/xpath-functions/math";
 export const XMLNS_MAP = "http://www.w3.org/2005/xpath-functions/map";
 export const XMLNS_ARRAY = "http://www.w3.org/2005/xpath-functions/array";
+// fn, local, xs, xsi, and xml are the five namespaces the XQuery 3.1 spec
+// (§2.1.1 Static Context) mandates as pre-declared in every processor's static
+// context, independent of any runtime/library configuration. math/map/array
+// aren't spec-mandated but are universally available in practice (they back
+// the 3.1 map/array/math core function libraries), so they're predeclared here too.
 const BUILTIN_PREFIXES = {
     fn: XMLNS_FN,
     local: XMLNS_LOCAL,
     xs: XMLNS_XS,
+    xsi: XMLNS_XSI,
     math: XMLNS_MATH,
     map: XMLNS_MAP,
     array: XMLNS_ARRAY,
@@ -173,6 +180,15 @@ function buildPrefixMap(moduleNs, imports, namespaceDecls) {
 function resolveNamespaceUri(prefix, prefixMap) {
     return prefixMap.get(prefix) ?? `urn:xq-lsp:undeclared:${prefix}`;
 }
+/**
+ * Per the BracedURILiteral grammar, whitespace inside `Q{...}` is insignificant:
+ * leading/trailing whitespace is trimmed and internal runs are collapsed to a
+ * single space, so `Q{ urn:foo bar }` and `Q{urn:foo   bar}` name the same URI.
+ * This does not decode percent-escapes — `Q{foo%20bar}` stays distinct from `Q{foo bar}`.
+ */
+function normalizeBracedUri(uri) {
+    return uri.trim().replace(/\s+/g, " ");
+}
 /**
  * Split a raw EQName terminal into its components, handling both the
  * conventional `prefix:local` form and the `Q{uri}local` URIQualifiedName form.
@@ -182,7 +198,7 @@ export function parseEQName(raw) {
     if (raw.startsWith("Q{")) {
         const close = raw.indexOf("}");
         if (close >= 0)
-            return { prefix: "", localName: raw.slice(close + 1), uri: raw.slice(2, close) };
+            return { prefix: "", localName: raw.slice(close + 1), uri: normalizeBracedUri(raw.slice(2, close)) };
     }
     const ci = raw.indexOf(":");
     return ci >= 0 ? { prefix: raw.slice(0, ci), localName: raw.slice(ci + 1) } : { prefix: "", localName: raw };
@@ -249,18 +265,25 @@ function extractFunctions(ast, sourceUri, comments, text, prefixMap, defaultFnNs
     }
     return results;
 }
-function extractModuleVariables(ast, sourceUri, prefixMap) {
+function extractModuleVariables(ast, sourceUri, prefixMap, comments, text) {
     const results = [];
-    for (const varDecl of findAll(ast, "VarDecl")) {
+    // Use AnnotatedDecl (starts at 'declare') so the comment lookup clears the 'declare' keyword,
+    // matching how extractFunctions locates its doc comment.
+    for (const annotated of findAll(ast, "AnnotatedDecl")) {
+        const varDecl = directChildOf(annotated, "VarDecl");
+        if (!varDecl)
+            continue;
         const varName = directChildOf(varDecl, "VarName");
         const name = varName ? firstTerminalValue(varName) : null;
         if (!name)
             continue;
+        const doc = findPrecedingDoc(comments, text, annotated.start);
         results.push({
             qname: makeVarQName(name, prefixMap),
             offset: varDecl.start,
             isModuleLevel: true,
             sourceUri,
+            doc: doc?.description || undefined,
         });
     }
     return results;
@@ -323,7 +346,7 @@ function analyzeAst(ast, comments, text, sourceUri) {
     const prefixMap = buildPrefixMap(moduleNs, imports, namespaceDecls);
     return {
         functions: extractFunctions(ast, sourceUri, comments, text, prefixMap, defaultFunctionNamespace),
-        moduleVariables: extractModuleVariables(ast, sourceUri, prefixMap),
+        moduleVariables: extractModuleVariables(ast, sourceUri, prefixMap, comments, text),
         localBindings: extractLocalBindings(ast, sourceUri, prefixMap),
         imports,
         namespaceDecls,
@@ -393,11 +416,13 @@ function analyzeRegex(text, sourceUri) {
     }
     RE_VAR_DECL.lastIndex = 0;
     while ((m = RE_VAR_DECL.exec(text)) !== null) {
+        const doc = findPrecedingDocInText(text, m.index);
         moduleVariables.push({
             qname: makeVarQName(m[1], prefixMap),
             offset: m.index,
             isModuleLevel: true,
             sourceUri,
+            doc: doc?.description || undefined,
         });
     }
     RE_LET.lastIndex = 0;

package/dist/ast-nodes.d.ts

@@ -3,6 +3,7 @@ import type { QName, FileAnalysis } from "./types.ts";
 export interface FunctionCallShape {
     qname: QName;
     args: Node[];
+    eqnameNode: Node;
 }
 export declare function asFunctionCall(node: Node, analysis: FileAnalysis): FunctionCallShape | null;
 export interface NamedFunctionRefShape {

package/dist/ast-nodes.js

@@ -51,7 +51,7 @@ export function asFunctionCall(node, analysis) {
     const namespaceUri = uri ?? resolvePrefix(prefix, analysis);
     const argList = directChildOf(node, "ArgumentList");
     const args = argList ? directChildrenOf(argList, "Argument") : [];
-    return { qname: { prefix, localName, namespaceUri }, args };
+    return { qname: { prefix, localName, namespaceUri }, args, eqnameNode: fnEqname };
 }
 export function asNamedFunctionRef(node, analysis) {
     if (node.type !== "NamedFunctionRef")

package/dist/braced-uri-diagnostics.d.ts

@@ -0,0 +1,13 @@
+import type { Node } from "xq-parser";
+export interface BracedUriDiagnostic {
+    message: string;
+    code: "xq-lsp:braced-uri-whitespace";
+    offset: number;
+    length: number;
+}
+/**
+ * Flag whitespace inside a `Q{uri}local` URIQualifiedName. The grammar treats it
+ * as insignificant (trimmed and collapsed to single spaces), so two literals that
+ * look different can name the same URI, and vice versa — easy to typo unnoticed.
+ */
+export declare function checkBracedUriWhitespace(ast: Node): BracedUriDiagnostic[];

package/dist/braced-uri-diagnostics.js

@@ -0,0 +1,27 @@
+import { findAll, firstTerminalValue } from "./analyzer.js";
+/**
+ * Flag whitespace inside a `Q{uri}local` URIQualifiedName. The grammar treats it
+ * as insignificant (trimmed and collapsed to single spaces), so two literals that
+ * look different can name the same URI, and vice versa — easy to typo unnoticed.
+ */
+export function checkBracedUriWhitespace(ast) {
+    const out = [];
+    for (const node of findAll(ast, "URIQualifiedName")) {
+        const raw = firstTerminalValue(node);
+        if (!raw)
+            continue;
+        const close = raw.indexOf("}");
+        if (close < 2)
+            continue;
+        const uri = raw.slice(2, close);
+        if (!/\s/.test(uri))
+            continue;
+        out.push({
+            message: "Whitespace inside 'Q{...}' is insignificant (trimmed/collapsed by the grammar) and easy to misread — remove it to avoid ambiguity.",
+            code: "xq-lsp:braced-uri-whitespace",
+            offset: (node.start ?? 0) + 2,
+            length: close - 2,
+        });
+    }
+    return out;
+}