xq-lsp 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## [1.7.0](https://github.com/DrRataplan/xq-lsp/compare/lsp-v1.6.0...lsp-v1.7.0) (2026-07-15)
+
+
+### Features
+
+* add document highlight support (textDocument/documentHighlight) ([6d90ad7](https://github.com/DrRataplan/xq-lsp/commit/6d90ad7b63e50b10b68705e819320035318a56da))
+* add find-references support via cross-file glob scan ([f0b0085](https://github.com/DrRataplan/xq-lsp/commit/f0b00852265c68ec95b96d86781eef41cb9dd940))
+* add rename support (textDocument/rename, prepareRename) ([d0cb55d](https://github.com/DrRataplan/xq-lsp/commit/d0cb55dbcba1d5b8520f7a2080818cdc420e06e6))
+* add XQST0034 diagnostic for double-declared functions ([6d44620](https://github.com/DrRataplan/xq-lsp/commit/6d44620e5b41e7de2c0a548086abec0b45ae22ff))
+* add XQST0059 diagnostic for module import namespace mismatches ([d8111fc](https://github.com/DrRataplan/xq-lsp/commit/d8111fcbf034d23306a53cfe28bd7c3dd43ce3a7))
+* auto-import and auto-declare-namespace via completion additionalTextEdits ([e1a9a93](https://github.com/DrRataplan/xq-lsp/commit/e1a9a935dea941bf35a3dc580ee77f7e88dd22c1))
+
+
+### Bug Fixes
+
+* don't blanket-skip XQUpdate-tagged QT4 tests ([f2e45f1](https://github.com/DrRataplan/xq-lsp/commit/f2e45f18022873cb3bb5105eb727b484bedfd518))
+* don't count literal fn:error() code calls as expected static errors ([0bead1b](https://github.com/DrRataplan/xq-lsp/commit/0bead1b8044c52daa2d7f2a11a24f8512d6ee2a9))
+* fall back to glob-resolved namespace when import location hint fails ([6ce03db](https://github.com/DrRataplan/xq-lsp/commit/6ce03db6d9c5deb1fa501617c29b6005f2540102))
+* go-to-definition for function params and imported variables ([415cfdd](https://github.com/DrRataplan/xq-lsp/commit/415cfdd4717b71af66041a7727641f18d091175d))
+* go-to-definition for inline function params and dashed variable names ([a4e7279](https://github.com/DrRataplan/xq-lsp/commit/a4e7279d4b27357bb27e7b67f2ed0551650ef66e))
+* handle InlineFunctionExpr scope in variable and unused-variable walkers ([de19b18](https://github.com/DrRataplan/xq-lsp/commit/de19b186fd367dc1450de1554205e8c07d0e40fd))
+* insert auto-import after last existing import, skip multi-line docblocks ([12227a9](https://github.com/DrRataplan/xq-lsp/commit/12227a916dcdafeb2ba5ddef21e82b4e2f6acbca))
+* load external <test file> queries and skip unsupported QT4 features ([4cbdc58](https://github.com/DrRataplan/xq-lsp/commit/4cbdc589b9af65f9043e3c0de6b5ffe950f3c7fe))
+* make computeRelativePath browser-safe and build the demo in CI ([033a057](https://github.com/DrRataplan/xq-lsp/commit/033a057849cbc492f8e243cf8f4e908200673033))
+* model QT4 environment-bound variables to cut XPST0008 false positives ([5dcb404](https://github.com/DrRataplan/xq-lsp/commit/5dcb4040bd79c0b7dc8edac5086b2289b1582b9e))
+* rewrite imported variable prefix to the importing module's prefix in completions ([f7c5ccc](https://github.com/DrRataplan/xq-lsp/commit/f7c5ccc337af75bae0c2d881210ba3373c90bb71))
+* scope inline function params, window vars, and copy bindings for XPST0008 ([7391a94](https://github.com/DrRataplan/xq-lsp/commit/7391a94c2607a028b6636ad6fcdadb29ba1356e5))
+
+## [1.6.0](https://github.com/DrRataplan/xq-lsp/compare/lsp-v1.5.0...lsp-v1.6.0) (2026-07-09)
+
+
+### Features
+
+* add diagnostics for unused imports and namespace declarations ([0ded7ba](https://github.com/DrRataplan/xq-lsp/commit/0ded7ba26b98bc308ca59cf7061f8ade197a4d13))
+* **claude-code:** add xq-lsp plugin for Claude Code ([aa96a4d](https://github.com/DrRataplan/xq-lsp/commit/aa96a4d5fdd9192e33be862608674d71e020017f))
+* **vscode:** add XQuery 4.0 syntax highlighting grammar ([f2ee489](https://github.com/DrRataplan/xq-lsp/commit/f2ee489ff1ec3ab67f9142d6c039c559d28d5e67))
+
+
+### Bug Fixes
+
+* add the $exist:* variables to the exist runtime ([4798582](https://github.com/DrRataplan/xq-lsp/commit/4798582c28f036c959432dbcca56edc81f7cca93))
+* copy runtime files to dist and inline existdb predeclared namespaces ([e98b6d6](https://github.com/DrRataplan/xq-lsp/commit/e98b6d672ba504bba5dda30980b7a58cbdfcf847))
+* **vscode:** recognize .xquery file extension ([7afc049](https://github.com/DrRataplan/xq-lsp/commit/7afc04913c1b02419c1965c489c32d09df1834b6))
+
 ## [1.5.0](https://github.com/DrRataplan/xq-lsp/compare/lsp-v1.4.1...lsp-v1.5.0) (2026-06-18)
 
 

package/README.md

@@ -1,9 +1,12 @@
+<img src="./logo.svg" alt="xq-lsp" width="48" height="48">
+
 # xq-lsp
 
 Language Server Protocol implementation for XQuery, providing autocompletion, hover documentation, signature help, go-to-definition, and diagnostics.
 
 ## Features
 
+- **Syntax highlighting** — keywords, types, variables, operators, comments, and XQuery 4.0 tokens (VS Code extension)
 - **Completion** — functions declared in the current file, imported modules, and variables in scope
 - **Hover** — function signatures on hover
 - **Signature help** — active parameter hints inside function calls
@@ -234,4 +237,23 @@ npx vsce package
 code --install-extension xquery-lsp-vscode-*.vsix
 ```
 
-The extension registers `.xq`, `.xql`, `.xqm`, and `.xqy` files as XQuery and starts `xq-lsp` automatically when you open one.
+The extension registers `.xq`, `.xql`, `.xqm`, `.xqy`, and `.xquery` files as XQuery, provides syntax highlighting via a bundled TextMate grammar, and starts `xq-lsp` automatically when you open one.
+
+## Claude Code
+
+A plugin lives in [`editors/claude-code/`](./editors/claude-code/) that registers `xq-lsp` as a native LSP server for Claude Code, giving diagnostics, go-to-definition, find-references, and hover for XQuery files.
+
+Make sure the `xq-lsp` binary is on `PATH`:
+
+```sh
+npm install -g xq-lsp
+```
+
+Then, from within Claude Code:
+
+```
+/plugin marketplace add DrRataplan/xq-lsp
+/plugin install xquery-lsp@xq-lsp
+```
+
+See [`editors/claude-code/README.md`](./editors/claude-code/README.md) for local-development setup and details on what the plugin configures.

package/demo/favicon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="7" fill="#1e1b4b"/>
+  <path d="M5 9 L11 16 L5 23" stroke="#a78bfa" stroke-width="3" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M27 9 L21 16 L27 23" stroke="#a78bfa" stroke-width="3" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="16" cy="16" r="2.5" fill="#a78bfa"/>
+</svg>

package/demo/index.html

@@ -4,6 +4,7 @@
 		<meta charset="utf-8" />
 		<meta name="viewport" content="width=device-width, initial-scale=1" />
 		<title>xq-lsp playground</title>
+		<link rel="icon" type="image/svg+xml" href="./favicon.svg" />
 		<style>
 			* {
 				box-sizing: border-box;
@@ -132,6 +133,7 @@
 	</head>
 	<body>
 		<header>
+			<img src="./favicon.svg" alt="" width="20" height="20" />
 			<h1>xq-lsp playground</h1>
 			<button id="share-btn">Copy link</button>
 		</header>

package/demo/main.ts

@@ -11,10 +11,7 @@ import builtinsMath from "../builtins/builtins-math.xq?raw";
 import builtinsMap from "../builtins/builtins-map.xq?raw";
 import builtinsArray from "../builtins/builtins-array.xq?raw";
 import { findUndeclaredPrefixUsages } from "../src/namespace-diagnostics.ts";
-import { checkTypes } from "../src/typechecker.ts";
-import { checkFunctionCalls } from "../src/functioncall-diagnostics.ts";
-import { checkUnused } from "../src/unused-diagnostics.ts";
-import { checkContextItemUsage } from "../src/context-item-diagnostics.ts";
+import { runDiagnostics, runHints } from "../src/diagnostics.ts";
 import { type FileAnalysis } from "../src/types.ts";
 import { resolveFunctionAtOffset, resolveSignatureAtOffset, functionSignature } from "../src/hover-core.ts";
 import { getCompletions } from "../src/completion-core.ts";
@@ -238,18 +235,12 @@ const xqueryLinter = linter((view): Diagnostic[] => {
 
 	if (ast) {
 		const imported = getImported(analysis);
-		for (const d of checkTypes(ast, code, analysis, new Map())) {
-			diagnostics.push({ from: d.offset, to: d.offset + d.length, severity: "warning", message: d.message });
-		}
-		for (const d of checkFunctionCalls(ast, analysis, imported)) {
+		for (const d of runDiagnostics(ast, code, analysis, imported)) {
 			diagnostics.push({ from: d.offset, to: d.offset + d.length, severity: "error", message: d.message });
 		}
-		for (const d of checkUnused(ast, analysis)) {
+		for (const d of runHints(ast, analysis)) {
 			diagnostics.push({ from: d.offset, to: d.offset + d.length, severity: "hint", message: d.message });
 		}
-		for (const d of checkContextItemUsage(ast)) {
-			diagnostics.push({ from: d.offset, to: d.offset + d.length, severity: "error", message: d.message });
-		}
 	}
 
 	return diagnostics;

package/dist/analyzer.js

@@ -229,6 +229,7 @@ function extractFunctions(ast, sourceUri, comments, text, prefixMap, defaultFnNs
                     name: paramName,
                     type: paramType,
                     description: doc?.params[paramName],
+                    sourceOffset: param.start,
                 });
             }
         }
@@ -291,7 +292,7 @@ function extractNamespaceDecls(ast) {
         const namespaceUri = uriNode ? stripQuotes(firstTerminalValue(uriNode) ?? "") : null;
         if (!namespaceUri)
             continue;
-        results.push({ prefix, namespaceUri });
+        results.push({ prefix, namespaceUri, offset: ncname.start ?? nd.start ?? 0 });
     }
     return results;
 }
@@ -307,7 +308,7 @@ function extractImports(ast) {
             continue;
         const namespaceUri = stripQuotes(firstTerminalValue(uris[0]) ?? "");
         const atPath = uris.length >= 2 ? stripQuotes(firstTerminalValue(uris[1]) ?? "") : undefined;
-        results.push({ prefix, namespaceUri, atPath });
+        results.push({ prefix, namespaceUri, atPath, offset: ncname.start ?? mi.start ?? 0 });
     }
     return results;
 }
@@ -338,8 +339,8 @@ const RE_FUNC = /declare\s+(?:%[\w:\-]+(?:\([^)]*\))?\s+)*function\s+([\w:\-]+)\
 const RE_VAR_DECL = /declare\s+(?:%[\w:\-]+(?:\([^)]*\))?\s+)*variable\s+\$([\w:\-]+)/g;
 const RE_LET = /\blet\s+\$([\w:\-]+)\s*:=/g;
 const RE_FOR = /\bfor\s+\$([\w:\-]+)\s+in\b/g;
-const RE_IMPORT = /import\s+module\s+namespace\s+([\w\-]+)\s*=\s*["']([^"']*)["'](?:\s+at\s+["']([^"']*)["'])?/g;
-const RE_NS_DECL = /declare\s+namespace\s+([\w\-]+)\s*=\s*["']([^"']*)["']/g;
+const RE_IMPORT = /import\s+module\s+namespace\s+([\w\-]+)\s*=\s*["']([^"']*)["'](?:\s+at\s+["']([^"']*)["'])?/gd;
+const RE_NS_DECL = /declare\s+namespace\s+([\w\-]+)\s*=\s*["']([^"']*)["']/gd;
 function analyzeRegex(text, sourceUri) {
     const moduleVariables = [];
     const localBindings = [];
@@ -350,7 +351,8 @@ function analyzeRegex(text, sourceUri) {
     const imports = [];
     RE_IMPORT.lastIndex = 0;
     while ((m = RE_IMPORT.exec(text)) !== null) {
-        const imp = { prefix: m[1], namespaceUri: m[2] };
+        const indices = m.indices;
+        const imp = { prefix: m[1], namespaceUri: m[2], offset: indices[1][0] };
         if (m[3])
             imp.atPath = m[3];
         imports.push(imp);
@@ -358,7 +360,8 @@ function analyzeRegex(text, sourceUri) {
     const namespaceDecls = [];
     RE_NS_DECL.lastIndex = 0;
     while ((m = RE_NS_DECL.exec(text)) !== null) {
-        namespaceDecls.push({ prefix: m[1], namespaceUri: m[2] });
+        const indices = m.indices;
+        namespaceDecls.push({ prefix: m[1], namespaceUri: m[2], offset: indices[1][0] });
     }
     const prefixMap = buildPrefixMap(moduleNs, imports, namespaceDecls);
     const functions = [];

package/dist/ast-nodes.d.ts

@@ -27,6 +27,35 @@ export interface FunctionDeclShape {
 }
 /** Inner shape of a FunctionDecl node: name, resolved params, and function body. */
 export declare function asFunctionDecl(node: Node, analysis: FileAnalysis): FunctionDeclShape | null;
+export interface InlineFunctionExprShape {
+    params: Array<{
+        nameNode: Node;
+        qname: QName;
+    }>;
+    body: Node | null;
+}
+export declare function asInlineFunctionExpr(node: Node, analysis: FileAnalysis): InlineFunctionExprShape | null;
+export interface WindowVarsShape {
+    currentItem?: QName;
+    positionalVar?: {
+        nameNode: Node;
+        qname: QName;
+    };
+    previousItem?: QName;
+    nextItem?: QName;
+}
+/** Resolves the `$current at $pos previous $prev next $next` bindings of a WindowVars node. */
+export declare function asWindowVars(node: Node, analysis: FileAnalysis): WindowVarsShape | null;
+export interface CopyBindingShape {
+    qname: QName;
+    initExpr: Node;
+}
+export interface TransformExprShape {
+    copyBindings: CopyBindingShape[];
+    modifyExpr: Node | null;
+    returnExpr: Node | null;
+}
+export declare function asTransformExpr(node: Node, analysis: FileAnalysis): TransformExprShape | null;
 /** QName, name node, arity, and annotation local-names for an AnnotatedDecl containing a FunctionDecl, or null. */
 export declare function asFunctionDeclaration(node: Node, analysis: FileAnalysis): {
     qname: QName;

package/dist/ast-nodes.js

@@ -18,6 +18,26 @@ function resolveQName(raw, analysis, defaultNs) {
     const namespaceUri = uri ?? resolvePrefix(prefix, analysis);
     return { prefix, localName, namespaceUri };
 }
+/** Resolves a variable QName from a node whose first descendant terminal is the bare name (no "$"). */
+function qnameFromRawTerminal(node, analysis) {
+    const rawName = firstTerminalValue(node);
+    if (!rawName)
+        return null;
+    const { prefix, localName, uri } = parseEQName(rawName);
+    return { prefix, localName, namespaceUri: uri ?? (prefix ? resolvePrefix(prefix, analysis) : "") };
+}
+function extractParamsFromParamList(paramList, analysis) {
+    const paramNodes = paramList ? directChildrenOf(paramList, "Param") : [];
+    return paramNodes.flatMap((p) => {
+        const pNameNode = directChildOf(p, "EQName");
+        if (!pNameNode)
+            return [];
+        const qname = qnameFromRawTerminal(pNameNode, analysis);
+        if (!qname)
+            return [];
+        return [{ nameNode: pNameNode, qname }];
+    });
+}
 export function asFunctionCall(node, analysis) {
     if (node.type !== "FunctionCall")
         return null;
@@ -90,18 +110,51 @@ export function asFunctionDecl(node, analysis) {
         return null;
     const { prefix, localName, uri } = parseEQName(rawName);
     const namespaceUri = uri ?? resolvePrefix(prefix, analysis);
-    const paramList = directChildOf(node, "ParamList");
-    const paramNodes = paramList ? directChildrenOf(paramList, "Param") : [];
-    const params = paramNodes.flatMap((p) => {
-        const pNameNode = directChildOf(p, "EQName");
-        const pName = pNameNode ? firstTerminalValue(pNameNode) : null;
-        if (!pName || !pNameNode)
+    const params = extractParamsFromParamList(directChildOf(node, "ParamList"), analysis);
+    return { nameNode, qname: { prefix, localName, namespaceUri }, params, body: directChildOf(node, "FunctionBody") ?? null };
+}
+export function asInlineFunctionExpr(node, analysis) {
+    if (node.type !== "InlineFunctionExpr")
+        return null;
+    const params = extractParamsFromParamList(directChildOf(node, "ParamList"), analysis);
+    return { params, body: directChildOf(node, "FunctionBody") ?? null };
+}
+/** Resolves the `$current at $pos previous $prev next $next` bindings of a WindowVars node. */
+export function asWindowVars(node, analysis) {
+    if (node.type !== "WindowVars")
+        return null;
+    const result = {};
+    const currentItemNode = directChildOf(node, "CurrentItem");
+    if (currentItemNode)
+        result.currentItem = qnameFromRawTerminal(currentItemNode, analysis) ?? undefined;
+    const posVarNode = directChildOf(node, "PositionalVar");
+    if (posVarNode)
+        result.positionalVar = asPositionalVar(posVarNode, analysis) ?? undefined;
+    const prevNode = directChildOf(node, "PreviousItem");
+    if (prevNode)
+        result.previousItem = qnameFromRawTerminal(prevNode, analysis) ?? undefined;
+    const nextNode = directChildOf(node, "NextItem");
+    if (nextNode)
+        result.nextItem = qnameFromRawTerminal(nextNode, analysis) ?? undefined;
+    return result;
+}
+export function asTransformExpr(node, analysis) {
+    if (node.type !== "XQUF_TransformExpr")
+        return null;
+    const bindingList = directChildOf(node, "XQUF_CopyBindingList");
+    const bindingNodes = bindingList ? directChildrenOf(bindingList, "XQUF_CopyBinding") : [];
+    const copyBindings = bindingNodes.flatMap((b) => {
+        const nameNode = directChildOf(b, "VarName");
+        const initExpr = directChildOf(b, "ExprSingle");
+        if (!nameNode || !initExpr)
             return [];
-        const { prefix: pPrefix, localName: pLocalName, uri: pUri } = parseEQName(pName);
-        const pNsUri = pUri ?? (pPrefix ? resolvePrefix(pPrefix, analysis) : "");
-        return [{ nameNode: pNameNode, qname: { prefix: pPrefix, localName: pLocalName, namespaceUri: pNsUri } }];
+        const qname = qnameFromRawTerminal(nameNode, analysis);
+        if (!qname)
+            return [];
+        return [{ qname, initExpr }];
     });
-    return { nameNode, qname: { prefix, localName, namespaceUri }, params, body: directChildOf(node, "FunctionBody") ?? null };
+    const [modifyExpr, returnExpr] = directChildrenOf(node, "ExprSingle");
+    return { copyBindings, modifyExpr: modifyExpr ?? null, returnExpr: returnExpr ?? null };
 }
 // ── AnnotatedDecl wrappers ────────────────────────────────────────────────────
 /** QName, name node, arity, and annotation local-names for an AnnotatedDecl containing a FunctionDecl, or null. */

package/dist/completion-core.d.ts

@@ -5,13 +5,26 @@ export interface CompletionContext {
     /** Character offset of the cursor in the document */
     cursorOffset: number;
 }
+/** Carries enough information for the LSP adapter to build the additionalTextEdit. */
+export interface AdditionalEdit {
+    kind: "import-module" | "declare-namespace";
+    prefix: string;
+    namespaceUri: string;
+    /** Source URI of the module file, used to compute the relative `at` path. */
+    sourceUri?: string;
+}
 export interface CompletionEntry {
     label: string;
-    kind: "function" | "variable";
+    kind: "function" | "variable" | "namespace";
     detail?: string;
     documentation?: string;
     insertText: string;
     isSnippet: boolean;
+    additionalEdit?: AdditionalEdit;
 }
 export declare function functionDoc(fn: FunctionSymbol): string;
-export declare function getCompletions(ctx: CompletionContext, currentAnalysis: FileAnalysis, importedAnalyses: Map<string, FileAnalysis>, snippets?: boolean, lastValidAnalysis?: FileAnalysis): CompletionEntry[];
+export declare function getCompletions(ctx: CompletionContext, currentAnalysis: FileAnalysis, importedAnalyses: Map<string, FileAnalysis>, snippets?: boolean, lastValidAnalysis?: FileAnalysis, 
+/** Modules available in the workspace but not yet imported in the current file. Keyed by namespace URI. */
+availableAnalyses?: Map<string, FileAnalysis>, 
+/** Known namespace prefix → URI mappings (from config / glob scans) for pure XML namespaces. */
+knownNamespaces?: Map<string, string>): CompletionEntry[];

package/dist/completion-core.js

@@ -76,7 +76,15 @@ function buildFunctionEntry(fn, label, snippets) {
         isSnippet: snippets && fn.params.length > 0,
     };
 }
-export function getCompletions(ctx, currentAnalysis, importedAnalyses, snippets = false, lastValidAnalysis) {
+/** Return the source URI for a module's analysis (taken from the first known symbol). */
+function moduleSourceUri(analysis) {
+    return analysis.functions[0]?.sourceUri ?? analysis.moduleVariables[0]?.sourceUri;
+}
+export function getCompletions(ctx, currentAnalysis, importedAnalyses, snippets = false, lastValidAnalysis, 
+/** Modules available in the workspace but not yet imported in the current file. Keyed by namespace URI. */
+availableAnalyses, 
+/** Known namespace prefix → URI mappings (from config / glob scans) for pure XML namespaces. */
+knownNamespaces) {
     const token = parseToken(ctx.textBeforeCursor);
     const items = [];
     if (token.kind === "variable") {
@@ -132,29 +140,94 @@ export function getCompletions(ctx, currentAnalysis, importedAnalyses, snippets
                 }
             }
         }
-        // Imported module-level variables are always visible
+        // Imported module-level variables — rewrite prefix to the one used in the current module
         for (const analysis of importedAnalyses.values()) {
             for (const v of analysis.moduleVariables) {
-                const e = buildVariableEntry(v, filter);
+                const localPrefix = currentAnalysis.imports.find((i) => i.namespaceUri === v.qname.namespaceUri)?.prefix;
+                const displayVar = localPrefix !== undefined && localPrefix !== v.qname.prefix
+                    ? { ...v, qname: { ...v.qname, prefix: localPrefix } }
+                    : v;
+                const e = buildVariableEntry(displayVar, filter);
                 if (e)
                     items.push(e);
             }
         }
+        // Variables from modules available in the workspace but not yet imported
+        if (availableAnalyses) {
+            const colonIdx = filter.indexOf(":");
+            if (colonIdx >= 0) {
+                const nsPrefix = filter.slice(0, colonIdx);
+                const localFilter = filter.slice(colonIdx + 1).toLowerCase();
+                const nsUri = resolvePrefix(nsPrefix, currentAnalysis);
+                if (nsUri.startsWith("urn:xq-lsp:undeclared:")) {
+                    for (const [moduleNsUri, analysis] of availableAnalyses) {
+                        if (analysis.modulePrefix !== nsPrefix)
+                            continue;
+                        const sourceUri = moduleSourceUri(analysis);
+                        for (const v of analysis.moduleVariables) {
+                            if (localFilter && !v.qname.localName.toLowerCase().startsWith(localFilter))
+                                continue;
+                            const displayQName = { ...v.qname, prefix: nsPrefix };
+                            items.push({
+                                label: `$${formatQName(displayQName)}`,
+                                kind: "variable",
+                                insertText: `$${formatQName(displayQName)}`,
+                                isSnippet: false,
+                                additionalEdit: { kind: "import-module", prefix: nsPrefix, namespaceUri: moduleNsUri, sourceUri },
+                            });
+                        }
+                    }
+                }
+            }
+        }
         return items;
     }
     if (token.kind === "qualified-name" && token.nsPrefix) {
         const targetUri = resolvePrefix(token.nsPrefix, currentAnalysis);
         const filter = token.prefix.toLowerCase();
-        const allFns = [
-            ...currentAnalysis.functions,
-            ...[...importedAnalyses.values()].flatMap((a) => a.functions),
-        ];
-        for (const fn of allFns) {
-            if (fn.qname.namespaceUri !== targetUri)
-                continue;
-            if (filter && !fn.qname.localName.toLowerCase().includes(filter))
-                continue;
-            items.push(buildFunctionEntry(fn, fn.qname.localName, snippets));
+        if (!targetUri.startsWith("urn:xq-lsp:undeclared:")) {
+            // Prefix is declared — show functions from current + imported analyses (no additionalEdit needed)
+            const allFns = [
+                ...currentAnalysis.functions,
+                ...[...importedAnalyses.values()].flatMap((a) => a.functions),
+            ];
+            for (const fn of allFns) {
+                if (fn.qname.namespaceUri !== targetUri)
+                    continue;
+                if (filter && !fn.qname.localName.toLowerCase().includes(filter))
+                    continue;
+                items.push(buildFunctionEntry(fn, fn.qname.localName, snippets));
+            }
+            return items;
+        }
+        // Prefix is undeclared — look for matching modules in the workspace
+        let foundModule = false;
+        if (availableAnalyses) {
+            for (const [moduleNsUri, analysis] of availableAnalyses) {
+                if (analysis.modulePrefix !== token.nsPrefix)
+                    continue;
+                foundModule = true;
+                const sourceUri = moduleSourceUri(analysis);
+                for (const fn of analysis.functions) {
+                    if (filter && !fn.qname.localName.toLowerCase().includes(filter))
+                        continue;
+                    items.push({
+                        ...buildFunctionEntry(fn, fn.qname.localName, snippets),
+                        additionalEdit: { kind: "import-module", prefix: token.nsPrefix, namespaceUri: moduleNsUri, sourceUri },
+                    });
+                }
+            }
+        }
+        // Pure XML namespace (no module functions): offer a declare-namespace item if prefix is known
+        if (!foundModule && knownNamespaces?.has(token.nsPrefix)) {
+            const nsUri = knownNamespaces.get(token.nsPrefix);
+            items.push({
+                label: `declare namespace ${token.nsPrefix} = "${nsUri}"`,
+                kind: "namespace",
+                insertText: token.prefix,
+                isSnippet: false,
+                additionalEdit: { kind: "declare-namespace", prefix: token.nsPrefix, namespaceUri: nsUri },
+            });
         }
         return items;
     }

package/dist/completion.d.ts

@@ -1,4 +1,10 @@
 import { CompletionItem } from "vscode-languageserver/node.js";
-import { getCompletions as getCoreCompletions } from "./completion-core.ts";
+import type { FileAnalysis } from "./types.ts";
+import type { CompletionContext } from "./completion-core.ts";
 export type { CompletionContext } from "./completion-core.ts";
-export declare function getCompletions(...args: Parameters<typeof getCoreCompletions>): CompletionItem[];
+export interface EditContext {
+    docText: string;
+    docUri: string;
+    generateLocationHints: boolean;
+}
+export declare function getCompletions(ctx: CompletionContext, currentAnalysis: FileAnalysis, importedAnalyses: Map<string, FileAnalysis>, snippets?: boolean, lastValidAnalysis?: FileAnalysis, availableAnalyses?: Map<string, FileAnalysis>, knownNamespaces?: Map<string, string>, editContext?: EditContext): CompletionItem[];

package/dist/completion.js

@@ -1,12 +1,39 @@
 import { CompletionItem, CompletionItemKind, InsertTextFormat, MarkupKind } from "vscode-languageserver/node.js";
 import { getCompletions as getCoreCompletions } from "./completion-core.js";
-export function getCompletions(...args) {
-    return getCoreCompletions(...args).map((e) => ({
-        label: e.label,
-        kind: e.kind === "function" ? CompletionItemKind.Function : CompletionItemKind.Variable,
-        detail: e.detail,
-        documentation: e.documentation ? { kind: MarkupKind.Markdown, value: e.documentation } : undefined,
-        insertText: e.insertText,
-        insertTextFormat: e.isSnippet ? InsertTextFormat.Snippet : InsertTextFormat.PlainText,
-    }));
+import { findImportInsertPosition, findDeclareNsInsertPosition, computeRelativePath } from "./namespace-diagnostics.js";
+export function getCompletions(ctx, currentAnalysis, importedAnalyses, snippets, lastValidAnalysis, availableAnalyses, knownNamespaces, editContext) {
+    return getCoreCompletions(ctx, currentAnalysis, importedAnalyses, snippets, lastValidAnalysis, availableAnalyses, knownNamespaces).map((e) => {
+        const item = {
+            label: e.label,
+            kind: e.kind === "function"
+                ? CompletionItemKind.Function
+                : e.kind === "namespace"
+                    ? CompletionItemKind.Module
+                    : CompletionItemKind.Variable,
+            detail: e.detail,
+            documentation: e.documentation ? { kind: MarkupKind.Markdown, value: e.documentation } : undefined,
+            insertText: e.insertText,
+            insertTextFormat: e.isSnippet ? InsertTextFormat.Snippet : InsertTextFormat.PlainText,
+        };
+        if (e.additionalEdit && editContext) {
+            const { docText, docUri, generateLocationHints } = editContext;
+            const insertPos = e.additionalEdit.kind === "import-module"
+                ? findImportInsertPosition(docText)
+                : findDeclareNsInsertPosition(docText);
+            let newText;
+            if (e.additionalEdit.kind === "import-module") {
+                const atPath = generateLocationHints && e.additionalEdit.sourceUri
+                    ? computeRelativePath(docUri, e.additionalEdit.sourceUri)
+                    : undefined;
+                newText = atPath
+                    ? `import module namespace ${e.additionalEdit.prefix} = "${e.additionalEdit.namespaceUri}" at "${atPath}";\n`
+                    : `import module namespace ${e.additionalEdit.prefix} = "${e.additionalEdit.namespaceUri}";\n`;
+            }
+            else {
+                newText = `declare namespace ${e.additionalEdit.prefix} = "${e.additionalEdit.namespaceUri}";\n`;
+            }
+            item.additionalTextEdits = [{ range: { start: insertPos, end: insertPos }, newText }];
+        }
+        return item;
+    });
 }

package/dist/definition.d.ts

@@ -1,4 +1,4 @@
 import { Location } from "vscode-languageserver/node.js";
 import type { TextDocument } from "vscode-languageserver-textdocument";
 import type { FileAnalysis } from "./types.ts";
-export declare function getDefinition(doc: TextDocument, offset: number, current: FileAnalysis, imported: Map<string, FileAnalysis>, resolveUri: (atPath: string) => string): Location | null;
+export declare function getDefinition(doc: TextDocument, offset: number, current: FileAnalysis, imported: Map<string, FileAnalysis>): Location | null;