xq-lsp 1.0.0

package/dist/completion.js

@@ -0,0 +1,152 @@
+import { CompletionItem, CompletionItemKind, InsertTextFormat, MarkupKind } from "vscode-languageserver/node.js";
+import { resolvePrefix } from "./analyzer.js";
+function parseToken(textBefore) {
+    const match = textBefore.match(/\$([\w:\-]*)$|(?:([\w\-]+):)([\w\-]*)$|([\w\-]+)$/);
+    if (!match)
+        return { kind: "name", prefix: "" };
+    if (match[0].startsWith("$")) {
+        return { kind: "variable", prefix: match[1] ?? "" };
+    }
+    if (match[2] !== undefined) {
+        return { kind: "qualified-name", nsPrefix: match[2], prefix: match[3] ?? "" };
+    }
+    return { kind: "name", prefix: match[4] ?? "" };
+}
+function functionDoc(fn) {
+    const paramStr = fn.params.map((p) => `$${p.name}${p.type ? " as " + p.type : ""}`).join(", ");
+    const ret = fn.returnType ? ` as ${fn.returnType}` : "";
+    const sig = `\`\`\`xquery\ndeclare function ${fn.name}(${paramStr})${ret}\n\`\`\``;
+    if (!fn.doc)
+        return sig;
+    const parts = [sig];
+    if (fn.doc.description)
+        parts.push(fn.doc.description);
+    const paramDocs = fn.params.filter((p) => p.description);
+    if (paramDocs.length > 0) {
+        parts.push(paramDocs.map((p) => `- \`$${p.name}\` — ${p.description}`).join("\n"));
+    }
+    if (fn.doc.returns)
+        parts.push(`**Returns:** ${fn.doc.returns}`);
+    return parts.join("\n\n");
+}
+function localInsertText(fn, snippets) {
+    if (fn.params.length === 0)
+        return fn.localName + "()";
+    const args = snippets
+        ? fn.params.map((p, i) => `\${${i + 1}:\\$${p.name}}`).join(", ")
+        : fn.params.map((p) => `$${p.name}`).join(", ");
+    return `${fn.localName}(${args})`;
+}
+function buildVariableItem(v, filter) {
+    if (filter && !v.name.toLowerCase().startsWith(filter.toLowerCase()))
+        return null;
+    return {
+        label: `$${v.name}`,
+        kind: CompletionItemKind.Variable,
+        insertText: `$${v.name}`,
+        insertTextFormat: InsertTextFormat.PlainText,
+    };
+}
+export function getCompletions(ctx, currentAnalysis, importedAnalyses, snippets = false) {
+    const token = parseToken(ctx.textBeforeCursor);
+    const items = [];
+    // ── Variable completions ─────────────────────────────────────────────────
+    if (token.kind === "variable") {
+        for (const v of currentAnalysis.moduleVariables) {
+            const item = buildVariableItem(v, token.prefix);
+            if (item)
+                items.push(item);
+        }
+        for (const v of currentAnalysis.localBindings) {
+            if (v.offset < ctx.cursorOffset) {
+                const item = buildVariableItem(v, token.prefix);
+                if (item)
+                    items.push(item);
+            }
+        }
+        for (const analysis of importedAnalyses.values()) {
+            for (const v of analysis.moduleVariables) {
+                const item = buildVariableItem(v, token.prefix);
+                if (item)
+                    items.push(item);
+            }
+        }
+        return items;
+    }
+    // ── Qualified-name completions (user typed "ns:partial") ─────────────────
+    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.namespaceUri !== targetUri)
+                continue;
+            if (filter && !fn.localName.toLowerCase().includes(filter))
+                continue;
+            items.push({
+                label: fn.localName,
+                kind: CompletionItemKind.Function,
+                detail: `${fn.localName}#${fn.arity}`,
+                documentation: { kind: MarkupKind.Markdown, value: functionDoc(fn) },
+                insertText: localInsertText(fn, snippets),
+                insertTextFormat: snippets ? InsertTextFormat.Snippet : InsertTextFormat.PlainText,
+            });
+        }
+        return items;
+    }
+    // ── Plain-name completions ───────────────────────────────────────────────
+    const filter = token.prefix.toLowerCase();
+    const defaultUri = currentAnalysis.defaultFunctionNamespace;
+    // Functions declared in the current file (full qualified name)
+    for (const fn of currentAnalysis.functions) {
+        if (filter && !fn.name.toLowerCase().includes(filter))
+            continue;
+        items.push({
+            label: fn.name,
+            kind: CompletionItemKind.Function,
+            detail: `${fn.name}#${fn.arity}`,
+            documentation: { kind: MarkupKind.Markdown, value: functionDoc(fn) },
+            insertText: snippets
+                ? fn.params.length === 0
+                    ? fn.name + "()"
+                    : fn.name + "(" + fn.params.map((p, i) => `\${${i + 1}:\\$${p.name}}`).join(", ") + ")"
+                : fn.name + "(" + fn.params.map((p) => `$${p.name}`).join(", ") + ")",
+            insertTextFormat: snippets ? InsertTextFormat.Snippet : InsertTextFormat.PlainText,
+        });
+    }
+    // Imported functions: those in the default function namespace are offered
+    // without prefix (since they can be called unqualified); others with full name.
+    for (const analysis of importedAnalyses.values()) {
+        for (const fn of analysis.functions) {
+            if (fn.namespaceUri === defaultUri) {
+                if (filter && !fn.localName.toLowerCase().includes(filter))
+                    continue;
+                items.push({
+                    label: fn.localName,
+                    kind: CompletionItemKind.Function,
+                    detail: `${fn.localName}#${fn.arity}`,
+                    documentation: { kind: MarkupKind.Markdown, value: functionDoc(fn) },
+                    insertText: localInsertText(fn, snippets),
+                    insertTextFormat: snippets ? InsertTextFormat.Snippet : InsertTextFormat.PlainText,
+                });
+            }
+            else {
+                if (filter && !fn.name.toLowerCase().includes(filter))
+                    continue;
+                items.push({
+                    label: fn.name,
+                    kind: CompletionItemKind.Function,
+                    detail: `${fn.name}#${fn.arity}`,
+                    documentation: { kind: MarkupKind.Markdown, value: functionDoc(fn) },
+                    insertText: snippets
+                        ? fn.params.length === 0
+                            ? fn.name + "()"
+                            : fn.name + "(" + fn.params.map((p, i) => `\${${i + 1}:\\$${p.name}}`).join(", ") + ")"
+                        : fn.name + "(" + fn.params.map((p) => `$${p.name}`).join(", ") + ")",
+                    insertTextFormat: snippets ? InsertTextFormat.Snippet : InsertTextFormat.PlainText,
+                });
+            }
+        }
+    }
+    return items;
+}

package/dist/features.d.ts

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

package/dist/features.js

@@ -0,0 +1,214 @@
+import { SignatureInformation, ParameterInformation, SymbolKind, Location, MarkupKind, } from "vscode-languageserver/node.js";
+import * as fs from "fs";
+import { fileURLToPath } from "url";
+import { resolvePrefix } from "./analyzer.js";
+// ── Shared helpers ───────────────────────────────────────────────────────────
+/**
+ * Resolve a qualified-name word (e.g. "fn:true", "m:sin", "true") to a FunctionSymbol
+ * using proper namespace URI resolution against the current file's namespace context.
+ */
+function resolveFunction(word, currentAnalysis, fns) {
+    const colonIdx = word.indexOf(":");
+    const prefix = colonIdx >= 0 ? word.slice(0, colonIdx) : "";
+    const localName = colonIdx >= 0 ? word.slice(colonIdx + 1) : word;
+    const uri = resolvePrefix(prefix, currentAnalysis);
+    return fns.find((f) => f.namespaceUri === uri && f.localName === localName);
+}
+function wordAt(text, offset) {
+    let start = offset;
+    let end = offset;
+    while (start > 0 && /[\w:\-]/.test(text[start - 1]))
+        start--;
+    while (end < text.length && /[\w:\-]/.test(text[end]))
+        end++;
+    return { word: text.slice(start, end), start, end };
+}
+function functionSignature(fn) {
+    const params = fn.params.map((p) => `$${p.name}${p.type ? " as " + p.type : ""}`).join(", ");
+    const ret = fn.returnType ? ` as ${fn.returnType}` : "";
+    return `declare function ${fn.name}(${params})${ret}`;
+}
+function allFunctions(current, imported) {
+    const fns = [...current.functions];
+    for (const a of imported.values())
+        fns.push(...a.functions);
+    return fns;
+}
+function positionInText(text, offset) {
+    const before = text.slice(0, offset);
+    const lines = before.split("\n");
+    return { line: lines.length - 1, character: lines[lines.length - 1].length };
+}
+function rangeFromOffset(doc, start, end) {
+    return { start: doc.positionAt(start), end: doc.positionAt(end) };
+}
+// ── Hover ────────────────────────────────────────────────────────────────────
+export function getHover(doc, offset, current, imported) {
+    const text = doc.getText();
+    const { word, start, end } = wordAt(text, offset);
+    if (!word)
+        return null;
+    // Check if hovering over a $ variable
+    const hasDollar = start > 0 && text[start - 1] === "$";
+    if (hasDollar) {
+        const varName = word;
+        const allVars = [
+            ...current.moduleVariables,
+            ...current.localBindings,
+            ...[...imported.values()].flatMap((a) => a.moduleVariables),
+        ];
+        const v = allVars.find((v) => v.name === varName);
+        if (v) {
+            return {
+                contents: { kind: MarkupKind.Markdown, value: `\`$${v.name}\`` },
+                range: rangeFromOffset(doc, start - 1, end),
+            };
+        }
+        return null;
+    }
+    // Check if hovering over a function name
+    const fn = resolveFunction(word, current, allFunctions(current, imported));
+    if (fn) {
+        return {
+            contents: {
+                kind: MarkupKind.Markdown,
+                value: "```xquery\n" + functionSignature(fn) + "\n```",
+            },
+            range: rangeFromOffset(doc, start, end),
+        };
+    }
+    return null;
+}
+// ── Signature help ───────────────────────────────────────────────────────────
+/**
+ * Scan left from cursor to find the function call we're inside.
+ * Returns { name, activeParam } or null.
+ */
+function findEnclosingCall(text, offset) {
+    let depth = 0;
+    let commas = 0;
+    for (let i = offset - 1; i >= 0; i--) {
+        const ch = text[i];
+        if (ch === ")") {
+            depth++;
+            continue;
+        }
+        if (ch === "(") {
+            if (depth > 0) {
+                depth--;
+                continue;
+            }
+            // Found the opening paren of our call — scan left for the function name
+            let nameEnd = i;
+            while (nameEnd > 0 && /\s/.test(text[nameEnd - 1]))
+                nameEnd--;
+            const { word, start } = wordAt(text, nameEnd - 1);
+            if (!word)
+                return null;
+            return { name: word, activeParam: commas };
+        }
+        if (ch === "," && depth === 0)
+            commas++;
+        // Stop at statement boundaries
+        if ((ch === ";" || ch === "{") && depth === 0)
+            return null;
+    }
+    return null;
+}
+export function getSignatureHelp(doc, offset, current, imported) {
+    const text = doc.getText();
+    const call = findEnclosingCall(text, offset);
+    if (!call)
+        return null;
+    const fn = resolveFunction(call.name, current, allFunctions(current, imported));
+    if (!fn)
+        return null;
+    const sig = {
+        label: functionSignature(fn),
+        parameters: fn.params.map((p) => {
+            const label = `$${p.name}${p.type ? " as " + p.type : ""}`;
+            return ParameterInformation.create(label);
+        }),
+    };
+    return {
+        signatures: [sig],
+        activeSignature: 0,
+        activeParameter: Math.min(call.activeParam, fn.params.length - 1),
+    };
+}
+// ── Document symbols ─────────────────────────────────────────────────────────
+export function getDocumentSymbols(doc, current) {
+    const symbols = [];
+    for (const fn of current.functions) {
+        const pos = doc.positionAt(fn.sourceOffset ?? 0);
+        const range = { start: pos, end: pos };
+        symbols.push({
+            name: fn.name,
+            kind: SymbolKind.Function,
+            range,
+            selectionRange: range,
+            detail: `#${fn.arity}`,
+        });
+    }
+    for (const v of current.moduleVariables) {
+        const pos = doc.positionAt(v.offset);
+        const range = { start: pos, end: pos };
+        symbols.push({
+            name: `$${v.name}`,
+            kind: SymbolKind.Variable,
+            range,
+            selectionRange: range,
+        });
+    }
+    return symbols;
+}
+// ── Go to definition ─────────────────────────────────────────────────────────
+export function getDefinition(doc, offset, current, imported, resolveUri) {
+    const text = doc.getText();
+    const { word, start } = wordAt(text, offset);
+    if (!word)
+        return null;
+    const hasDollar = start > 0 && text[start - 1] === "$";
+    if (hasDollar) {
+        // Variable definition — search current file only
+        const allVars = [...current.moduleVariables, ...current.localBindings];
+        const v = allVars.find((v) => v.name === word);
+        if (!v)
+            return null;
+        const pos = doc.positionAt(v.offset);
+        return Location.create(doc.uri, { start: pos, end: pos });
+    }
+    // Function definition — resolve by namespace URI, search current file then all imports
+    const colonIdx = word.indexOf(":");
+    const wordPrefix = colonIdx >= 0 ? word.slice(0, colonIdx) : "";
+    const wordLocalName = colonIdx >= 0 ? word.slice(colonIdx + 1) : word;
+    const targetUri = resolvePrefix(wordPrefix, current);
+    const localFn = current.functions.find((f) => f.namespaceUri === targetUri && f.localName === wordLocalName);
+    if (localFn) {
+        const pos = doc.positionAt(localFn.sourceOffset ?? 0);
+        return Location.create(doc.uri, { start: pos, end: pos });
+    }
+    // Search imported files: find which atPath contains the function, then navigate there
+    for (const imp of current.imports) {
+        const analysis = imported.get(imp.atPath);
+        if (!analysis)
+            continue;
+        const fn = analysis.functions.find((f) => f.namespaceUri === targetUri && f.localName === wordLocalName);
+        if (!fn)
+            continue;
+        const uri = resolveUri(imp.atPath);
+        let pos = { line: 0, character: 0 };
+        if (fn.sourceOffset !== undefined) {
+            try {
+                const filePath = fileURLToPath(uri);
+                const srcText = fs.readFileSync(filePath, "utf-8");
+                pos = positionInText(srcText, fn.sourceOffset);
+            }
+            catch {
+                /* file not readable, use line 0 */
+            }
+        }
+        return Location.create(uri, { start: pos, end: pos });
+    }
+    return null;
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+import { createConnection, TextDocuments, ProposedFeatures, TextDocumentSyncKind, DiagnosticSeverity, } from 'vscode-languageserver/node.js';
+import { TextDocument } from 'vscode-languageserver-textdocument';
+import * as path from 'path';
+import * as fs from 'fs';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { XQuery31Full } from 'xq-parser';
+import { analyze } from "./analyzer.js";
+import { getBuiltins } from "./builtins.js";
+import { getCompletions } from "./completion.js";
+import { getHover, getSignatureHelp, getDocumentSymbols, getDefinition } from "./features.js";
+const connection = createConnection(ProposedFeatures.all);
+const documents = new TextDocuments(TextDocument);
+const analysisCache = new Map();
+function analyzeDocument(doc) {
+    const analysis = analyze(doc.getText(), doc.uri);
+    analysisCache.set(doc.uri, analysis);
+    return analysis;
+}
+function uriToPath(uri) {
+    try {
+        return fileURLToPath(uri);
+    }
+    catch {
+        return uri.replace(/^file:\/\//, '');
+    }
+}
+function resolveImportUri(currentUri, atPath) {
+    const currentPath = uriToPath(currentUri);
+    const dir = path.dirname(currentPath);
+    const resolved = path.resolve(dir, atPath);
+    return pathToFileURL(resolved).toString();
+}
+function getImportedAnalysis(importUri) {
+    if (analysisCache.has(importUri))
+        return analysisCache.get(importUri);
+    try {
+        const text = fs.readFileSync(uriToPath(importUri), 'utf-8');
+        const analysis = analyze(text, importUri);
+        analysisCache.set(importUri, analysis);
+        return analysis;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveImports(currentUri, analysis) {
+    const result = new Map();
+    result.set('builtin:fn', getBuiltins());
+    for (const imp of analysis.imports) {
+        const uri = resolveImportUri(currentUri, imp.atPath);
+        const imported = getImportedAnalysis(uri);
+        if (imported)
+            result.set(imp.atPath, imported);
+    }
+    return result;
+}
+function parseDiagnostics(text, uri) {
+    try {
+        XQuery31Full(text);
+        return [];
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        // "at line N, column M:" in the parser's error messages
+        const loc = msg.match(/at line (\d+), column (\d+)/);
+        const line = loc ? parseInt(loc[1]) - 1 : 0;
+        const col = loc ? parseInt(loc[2]) - 1 : 0;
+        return [{
+                severity: DiagnosticSeverity.Error,
+                range: { start: { line, character: col }, end: { line, character: col + 1 } },
+                message: msg.split('\n')[0],
+                source: 'xquery-lsp',
+            }];
+    }
+}
+// ── LSP lifecycle ────────────────────────────────────────────────────────────
+let snippetSupport = false;
+connection.onInitialize((params) => {
+    snippetSupport =
+        params.capabilities.textDocument?.completion?.completionItem?.snippetSupport ?? false;
+    return {
+        capabilities: {
+            textDocumentSync: TextDocumentSyncKind.Incremental,
+            completionProvider: {
+                triggerCharacters: ['$', ':'],
+                resolveProvider: false,
+            },
+            hoverProvider: true,
+            signatureHelpProvider: {
+                triggerCharacters: ['(', ','],
+            },
+            documentSymbolProvider: true,
+            definitionProvider: true,
+        },
+    };
+});
+documents.onDidChangeContent(change => {
+    const doc = change.document;
+    analyzeDocument(doc);
+    const diagnostics = parseDiagnostics(doc.getText(), doc.uri);
+    connection.sendDiagnostics({ uri: doc.uri, diagnostics });
+});
+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 offset = doc.offsetAt(params.position);
+    return getCompletions({ textBeforeCursor: doc.getText().slice(0, offset), cursorOffset: offset }, analysis, imported, snippetSupport);
+});
+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);
+    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);
+    return getSignatureHelp(doc, doc.offsetAt(params.position), analysis, imported);
+});
+connection.onDocumentSymbol(params => {
+    const doc = documents.get(params.textDocument.uri);
+    if (!doc)
+        return [];
+    const analysis = analysisCache.get(doc.uri) ?? analyzeDocument(doc);
+    return getDocumentSymbols(doc, analysis);
+});
+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);
+    return getDefinition(doc, doc.offsetAt(params.position), analysis, imported, atPath => resolveImportUri(doc.uri, atPath));
+});
+documents.listen(connection);
+connection.listen();

package/dist/types.d.ts

@@ -0,0 +1,42 @@
+export interface ParamInfo {
+    name: string;
+    type?: string;
+    description?: string;
+}
+export interface DocComment {
+    description: string;
+    params: Record<string, string>;
+    returns?: string;
+}
+export interface FunctionSymbol {
+    name: string;
+    prefix: string;
+    localName: string;
+    namespaceUri: string;
+    arity: number;
+    params: ParamInfo[];
+    returnType?: string;
+    doc?: DocComment;
+    sourceUri: string;
+    sourceOffset?: number;
+}
+export interface VariableSymbol {
+    name: string;
+    offset: number;
+    isModuleLevel: boolean;
+    sourceUri: string;
+}
+export interface ImportInfo {
+    prefix: string;
+    namespaceUri: string;
+    atPath: string;
+}
+export interface FileAnalysis {
+    functions: FunctionSymbol[];
+    moduleVariables: VariableSymbol[];
+    localBindings: VariableSymbol[];
+    imports: ImportInfo[];
+    defaultFunctionNamespace: string;
+    moduleNamespaceUri?: string;
+    modulePrefix?: string;
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "xq-lsp",
+  "version": "1.0.0",
+  "description": "XQuery Language Server Protocol implementation",
+  "license": "MIT",
+  "author": "Martin Middel",
+  "type": "module",
+  "main": "dist/server.js",
+  "repository": "https://github.com/DrRataplan/xq-lsp.git",
+  "bin": {
+    "xq-lsp": "./src/server.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node ./src/server.ts --stdio",
+    "test": "node --test src/test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "vscode-languageserver": "^9.0.1",
+    "vscode-languageserver-textdocument": "^1.0.12",
+    "xq-parser": "^0.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "prettier": "^3.8.3",
+    "typescript": "^6.0.3"
+  }
+}