xq-lsp 1.0.0

package/builtins/builtins-map.xq

@@ -0,0 +1,86 @@
+module namespace map="http://www.w3.org/2005/xpath-functions/map";
+
+(:~
+ : Returns a map that combines the entries of a sequence of maps.
+ : @param $maps The maps to merge
+ : @return A map containing all entries
+ :)
+declare function map:merge($maps as map(*)*) as map(*) external;
+(:~
+ : Merges maps with options controlling duplicate key handling.
+ : @param $maps The maps to merge
+ : @param $options Options map (e.g. map{"duplicates": "use-first"})
+ : @return A map containing all entries
+ :)
+declare function map:merge($maps as map(*)*, $options as map(*)) as map(*) external;
+
+(:~
+ : Returns the number of entries in a map.
+ : @param $map The map
+ : @return The number of key-value pairs
+ :)
+declare function map:size($map as map(*)) as xs:integer external;
+
+(:~
+ : Returns the keys of a map as a sequence of atomic values.
+ : @param $map The map
+ : @return Sequence of keys
+ :)
+declare function map:keys($map as map(*)) as xs:anyAtomicType* external;
+
+(:~
+ : Tests whether a map contains a given key.
+ : @param $map The map
+ : @param $key The key to look for
+ : @return true if the map contains the key
+ :)
+declare function map:contains($map as map(*), $key as xs:anyAtomicType) as xs:boolean external;
+
+(:~
+ : Returns the value associated with a key in a map.
+ : @param $map The map
+ : @param $key The key
+ : @return The associated value, or empty sequence if the key is absent
+ :)
+declare function map:get($map as map(*), $key as xs:anyAtomicType) as item()* external;
+
+(:~
+ : Searches a nested data structure for all values with a given key.
+ : @param $input The structure to search
+ : @param $key The key to find
+ : @return An array of all matching values
+ :)
+declare function map:find($input as item()*, $key as xs:anyAtomicType) as array(*) external;
+
+(:~
+ : Returns a new map with an added or replaced entry.
+ : @param $map The source map
+ : @param $key The key
+ : @param $value The value
+ : @return A new map with the entry added or replaced
+ :)
+declare function map:put($map as map(*), $key as xs:anyAtomicType, $value as item()*) as map(*) external;
+
+(:~
+ : Creates a single-entry map.
+ : @param $key The key
+ : @param $value The value
+ : @return A map with one entry
+ :)
+declare function map:entry($key as xs:anyAtomicType, $value as item()*) as map(*) external;
+
+(:~
+ : Returns a new map with one or more entries removed.
+ : @param $map The source map
+ : @param $keys Keys to remove
+ : @return A new map without the specified entries
+ :)
+declare function map:remove($map as map(*), $keys as xs:anyAtomicType*) as map(*) external;
+
+(:~
+ : Applies a function to each entry in a map, returning a sequence of results.
+ : @param $map The map
+ : @param $action Function taking (key, value) and returning items
+ : @return Concatenated results
+ :)
+declare function map:for-each($map as map(*), $action as function(xs:anyAtomicType, item()*) as item()*) as item()* external;

package/builtins/builtins-math.xq

@@ -0,0 +1,100 @@
+module namespace math="http://www.w3.org/2005/xpath-functions/math";
+
+(:~
+ : Returns the mathematical constant π (approximately 3.14159265358979).
+ : @return π as xs:double
+ :)
+declare function math:pi() as xs:double external;
+
+(:~
+ : Returns e raised to the power of a number (eˣ).
+ : @param $x The exponent
+ : @return e^x
+ :)
+declare function math:exp($x as xs:double?) as xs:double? external;
+
+(:~
+ : Returns 10 raised to the power of a number.
+ : @param $x The exponent
+ : @return 10^x
+ :)
+declare function math:exp10($x as xs:double?) as xs:double? external;
+
+(:~
+ : Returns the natural logarithm of a number.
+ : @param $x The value (must be positive)
+ : @return ln(x)
+ :)
+declare function math:log($x as xs:double?) as xs:double? external;
+
+(:~
+ : Returns the base-10 logarithm of a number.
+ : @param $x The value (must be positive)
+ : @return log₁₀(x)
+ :)
+declare function math:log10($x as xs:double?) as xs:double? external;
+
+(:~
+ : Returns a number raised to the power of another.
+ : @param $x The base
+ : @param $y The exponent
+ : @return x^y
+ :)
+declare function math:pow($x as xs:double?, $y as xs:numeric) as xs:double? external;
+
+(:~
+ : Returns the square root of a number.
+ : @param $x The value (must be non-negative)
+ : @return √x
+ :)
+declare function math:sqrt($x as xs:double?) as xs:double? external;
+
+(:~
+ : Returns the sine of an angle given in radians.
+ : @param $x The angle in radians
+ : @return sin(x)
+ :)
+declare function math:sin($x as xs:double?) as xs:double? external;
+
+(:~
+ : Returns the cosine of an angle given in radians.
+ : @param $x The angle in radians
+ : @return cos(x)
+ :)
+declare function math:cos($x as xs:double?) as xs:double? external;
+
+(:~
+ : Returns the tangent of an angle given in radians.
+ : @param $x The angle in radians
+ : @return tan(x)
+ :)
+declare function math:tan($x as xs:double?) as xs:double? external;
+
+(:~
+ : Returns the arc sine of a value, in radians.
+ : @param $x The value (between -1 and 1)
+ : @return asin(x) in radians
+ :)
+declare function math:asin($x as xs:double?) as xs:double? external;
+
+(:~
+ : Returns the arc cosine of a value, in radians.
+ : @param $x The value (between -1 and 1)
+ : @return acos(x) in radians
+ :)
+declare function math:acos($x as xs:double?) as xs:double? external;
+
+(:~
+ : Returns the arc tangent of a value, in radians.
+ : @param $x The value
+ : @return atan(x) in radians
+ :)
+declare function math:atan($x as xs:double?) as xs:double? external;
+
+(:~
+ : Returns the angle in radians from the positive x-axis to the point (x, y).
+ : @param $y The y coordinate
+ : @param $x The x coordinate
+ : @return The angle in radians (between -π and π)
+ :)
+declare function math:atan2($y as xs:double, $x as xs:double) as xs:double external;

package/dist/analyzer.d.ts

@@ -0,0 +1,14 @@
+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_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";
+/**
+ * Resolve a namespace prefix to its URI given the namespace context of a file.
+ * Unprefixed calls (prefix="") resolve to the file's default function namespace.
+ * Unknown prefixes fall back to a stable synthetic URI so within-file matches still work.
+ */
+export declare function resolvePrefix(prefix: string, analysis: FileAnalysis): string;
+export declare function analyze(text: string, sourceUri: string): FileAnalysis;

package/dist/analyzer.js

@@ -0,0 +1,363 @@
+import { XQuery31Full } from "xq-parser";
+// ── Well-known namespace URIs ────────────────────────────────────────────────
+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_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";
+const BUILTIN_PREFIXES = {
+    fn: XMLNS_FN,
+    local: XMLNS_LOCAL,
+    xs: XMLNS_XS,
+    math: XMLNS_MATH,
+    map: XMLNS_MAP,
+    array: XMLNS_ARRAY,
+};
+/**
+ * Resolve a namespace prefix to its URI given the namespace context of a file.
+ * Unprefixed calls (prefix="") resolve to the file's default function namespace.
+ * Unknown prefixes fall back to a stable synthetic URI so within-file matches still work.
+ */
+export function resolvePrefix(prefix, analysis) {
+    if (!prefix)
+        return analysis.defaultFunctionNamespace;
+    const imp = analysis.imports.find((i) => i.prefix === prefix);
+    if (imp)
+        return imp.namespaceUri;
+    if (prefix === analysis.modulePrefix && analysis.moduleNamespaceUri)
+        return analysis.moduleNamespaceUri;
+    return BUILTIN_PREFIXES[prefix] ?? `urn:xq-lsp:undeclared:${prefix}`;
+}
+// ── AST helpers ─────────────────────────────────────────────────────────────
+function isTerminal(node) {
+    return node.isTerminal;
+}
+function asNonTerminal(node) {
+    return node;
+}
+function firstTerminalValue(node) {
+    if (isTerminal(node))
+        return node.value;
+    for (const child of asNonTerminal(node).children) {
+        const v = firstTerminalValue(child);
+        if (v !== null)
+            return v;
+    }
+    return null;
+}
+function findAll(node, type, out = []) {
+    if (node.type === type)
+        out.push(node);
+    if (!isTerminal(node)) {
+        for (const child of asNonTerminal(node).children) {
+            findAll(child, type, out);
+        }
+    }
+    return out;
+}
+function directChildOf(node, type) {
+    if (isTerminal(node))
+        return undefined;
+    return asNonTerminal(node).children.find((c) => c.type === type);
+}
+function directChildrenOf(node, type) {
+    if (isTerminal(node))
+        return [];
+    return asNonTerminal(node).children.filter((c) => c.type === type);
+}
+// ── Doc comment parsing ──────────────────────────────────────────────────────
+function parseDocComment(raw) {
+    // Strip (: / (:~ opening and :) closing, then strip leading " : " per line
+    const inner = raw
+        .replace(/^\(:~?/, "")
+        .replace(/:\)$/, "")
+        .split("\n")
+        .map((l) => l.replace(/^\s*:?\s?/, ""))
+        .join("\n")
+        .trim();
+    const params = {};
+    let returns;
+    const descLines = [];
+    let inDescription = true;
+    for (const line of inner.split("\n")) {
+        const paramMatch = line.match(/^@param\s+\$?([\w:\-]+)\s*(.*)/);
+        const returnMatch = line.match(/^@returns?\s+(.*)/);
+        if (paramMatch) {
+            inDescription = false;
+            params[paramMatch[1]] = paramMatch[2].trim();
+        }
+        else if (returnMatch) {
+            inDescription = false;
+            returns = returnMatch[1].trim();
+        }
+        else if (inDescription) {
+            descLines.push(line);
+        }
+    }
+    return { description: descLines.join("\n").trim(), params, returns };
+}
+/** Find a doc comment immediately preceding `offset` in raw text (regex fallback path). */
+function findPrecedingDocInText(text, offset) {
+    const before = text.slice(0, offset);
+    const match = before.match(/\(:~?[\s\S]*?:\)\s*$/);
+    if (!match)
+        return undefined;
+    return parseDocComment(match[0]);
+}
+/** Find the xqDoc comment immediately preceding `offset` (only whitespace between). */
+function findPrecedingDoc(comments, text, offset) {
+    // Walk backwards through comments sorted by end position
+    const before = comments.filter((c) => c.end <= offset).sort((a, b) => b.end - a.end);
+    for (const c of before) {
+        const between = text.slice(c.end, offset);
+        if (!/^\s*$/.test(between))
+            break; // something other than whitespace — stop
+        if (c.value.startsWith("(:~") || c.value.startsWith("(:")) {
+            return parseDocComment(c.value);
+        }
+    }
+    return undefined;
+}
+// ── Namespace helpers ────────────────────────────────────────────────────────
+function extractModuleNamespace(text) {
+    const m = text.match(/module\s+namespace\s+([\w\-]+)\s*=\s*["']([^"']*)["']/);
+    return m ? { prefix: m[1], uri: m[2] } : undefined;
+}
+function extractDefaultFunctionNamespace(text) {
+    const m = text.match(/declare\s+default\s+function\s+namespace\s+["']([^"']*)["']/);
+    return m ? m[1] : undefined;
+}
+function buildPrefixMap(moduleNs, imports) {
+    const map = new Map(Object.entries(BUILTIN_PREFIXES));
+    if (moduleNs)
+        map.set(moduleNs.prefix, moduleNs.uri);
+    for (const imp of imports)
+        map.set(imp.prefix, imp.namespaceUri);
+    return map;
+}
+function resolveNamespaceUri(prefix, prefixMap) {
+    return prefixMap.get(prefix) ?? `urn:xq-lsp:undeclared:${prefix}`;
+}
+// ── Extract from valid AST ───────────────────────────────────────────────────
+function sequenceTypeText(text, node) {
+    if (node.start === undefined || node.end === null)
+        return undefined;
+    return text.slice(node.start, node.end ?? undefined).trim() || undefined;
+}
+function extractFunctions(ast, sourceUri, comments, text, prefixMap) {
+    const results = [];
+    // Use AnnotatedDecl (starts at 'declare') so the comment lookup clears the 'declare' keyword
+    for (const annotated of findAll(ast, "AnnotatedDecl")) {
+        const decl = directChildOf(annotated, "FunctionDecl");
+        if (!decl)
+            continue;
+        const eqname = directChildOf(decl, "EQName");
+        const name = eqname ? firstTerminalValue(eqname) : null;
+        if (!name)
+            continue;
+        const colonIdx = name.indexOf(":");
+        const prefix = colonIdx >= 0 ? name.slice(0, colonIdx) : "";
+        const localName = colonIdx >= 0 ? name.slice(colonIdx + 1) : name;
+        const doc = findPrecedingDoc(comments, text, annotated.start);
+        const params = [];
+        const paramList = directChildOf(decl, "ParamList");
+        if (paramList) {
+            for (const param of findAll(paramList, "Param")) {
+                const paramEqname = directChildOf(param, "EQName");
+                const paramName = paramEqname ? firstTerminalValue(paramEqname) : null;
+                if (!paramName)
+                    continue;
+                const typeDecl = directChildOf(param, "TypeDeclaration");
+                const seqTypeNode = typeDecl && directChildOf(typeDecl, "SequenceType");
+                const paramType = seqTypeNode ? sequenceTypeText(text, seqTypeNode) : undefined;
+                params.push({
+                    name: paramName,
+                    type: paramType,
+                    description: doc?.params[paramName],
+                });
+            }
+        }
+        // Return type: 'as' followed by SequenceType (direct child of FunctionDecl)
+        const seqType = directChildOf(decl, "SequenceType");
+        const returnType = seqType ? sequenceTypeText(text, seqType) : undefined;
+        results.push({
+            name,
+            prefix,
+            localName,
+            namespaceUri: resolveNamespaceUri(prefix, prefixMap),
+            arity: params.length,
+            params,
+            returnType,
+            doc,
+            sourceUri,
+            sourceOffset: annotated.start,
+        });
+    }
+    return results;
+}
+function extractModuleVariables(ast, sourceUri) {
+    const results = [];
+    for (const varDecl of findAll(ast, "VarDecl")) {
+        const varName = directChildOf(varDecl, "VarName");
+        const name = varName ? firstTerminalValue(varName) : null;
+        if (!name)
+            continue;
+        results.push({
+            name,
+            offset: varDecl.start,
+            isModuleLevel: true,
+            sourceUri,
+        });
+    }
+    return results;
+}
+function extractLocalBindings(ast, sourceUri) {
+    const results = [];
+    for (const binding of [...findAll(ast, "LetBinding"), ...findAll(ast, "ForBinding")]) {
+        const varName = directChildOf(binding, "VarName");
+        const name = varName ? firstTerminalValue(varName) : null;
+        if (!name)
+            continue;
+        results.push({
+            name,
+            offset: binding.start,
+            isModuleLevel: false,
+            sourceUri,
+        });
+    }
+    return results;
+}
+function extractImports(ast) {
+    const results = [];
+    for (const mi of findAll(ast, "ModuleImport")) {
+        const ncname = directChildOf(mi, "NCName");
+        const prefix = ncname ? firstTerminalValue(ncname) : null;
+        if (!prefix)
+            continue;
+        const uris = directChildrenOf(mi, "URILiteral");
+        if (uris.length < 2)
+            continue;
+        const namespaceUri = stripQuotes(firstTerminalValue(uris[0]) ?? "");
+        const atPath = stripQuotes(firstTerminalValue(uris[1]) ?? "");
+        results.push({ prefix, namespaceUri, atPath });
+    }
+    return results;
+}
+function stripQuotes(s) {
+    return s.replace(/^["']|["']$/g, "");
+}
+function analyzeAst(ast, comments, text, sourceUri) {
+    const imports = extractImports(ast);
+    const moduleNs = extractModuleNamespace(text);
+    const defaultFunctionNamespace = extractDefaultFunctionNamespace(text) ?? XMLNS_FN;
+    const prefixMap = buildPrefixMap(moduleNs, imports);
+    return {
+        functions: extractFunctions(ast, sourceUri, comments, text, prefixMap),
+        moduleVariables: extractModuleVariables(ast, sourceUri),
+        localBindings: extractLocalBindings(ast, sourceUri),
+        imports,
+        defaultFunctionNamespace,
+        moduleNamespaceUri: moduleNs?.uri,
+        modulePrefix: moduleNs?.prefix,
+    };
+}
+// ── Regex fallback for syntactically invalid / partial XQuery ────────────────
+const RE_FUNC = /declare\s+(?:%[\w:\-]+(?:\([^)]*\))?\s+)*function\s+([\w:\-]+)\s*\(([^)]*)\)/g;
+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;
+function analyzeRegex(text, sourceUri) {
+    const moduleVariables = [];
+    const localBindings = [];
+    const moduleNs = extractModuleNamespace(text);
+    const defaultFunctionNamespace = extractDefaultFunctionNamespace(text) ?? XMLNS_FN;
+    let m;
+    // Collect imports first so we can build the prefix map before resolving functions.
+    const imports = [];
+    RE_IMPORT.lastIndex = 0;
+    while ((m = RE_IMPORT.exec(text)) !== null) {
+        imports.push({ prefix: m[1], namespaceUri: m[2], atPath: m[3] });
+    }
+    const prefixMap = buildPrefixMap(moduleNs, imports);
+    const functions = [];
+    RE_FUNC.lastIndex = 0;
+    while ((m = RE_FUNC.exec(text)) !== null) {
+        const name = m[1];
+        const colonIdx = name.indexOf(":");
+        const prefix = colonIdx >= 0 ? name.slice(0, colonIdx) : "";
+        const localName = colonIdx >= 0 ? name.slice(colonIdx + 1) : name;
+        const doc = findPrecedingDocInText(text, m.index);
+        const rawParams = m[2].trim();
+        const params = rawParams
+            ? rawParams.split(",").map((p) => {
+                const varMatch = p.match(/\$([\w:\-]+)/);
+                const typeMatch = p.match(/as\s+([\w:\-]+(?:\(.*?\))?)/);
+                const paramName = varMatch ? varMatch[1] : p.trim();
+                return {
+                    name: paramName,
+                    type: typeMatch ? typeMatch[1] : undefined,
+                    description: doc?.params[paramName],
+                };
+            })
+            : [];
+        functions.push({
+            name,
+            prefix,
+            localName,
+            namespaceUri: resolveNamespaceUri(prefix, prefixMap),
+            arity: params.length,
+            params,
+            doc,
+            sourceUri,
+            sourceOffset: m.index,
+        });
+    }
+    RE_VAR_DECL.lastIndex = 0;
+    while ((m = RE_VAR_DECL.exec(text)) !== null) {
+        moduleVariables.push({
+            name: m[1],
+            offset: m.index,
+            isModuleLevel: true,
+            sourceUri,
+        });
+    }
+    RE_LET.lastIndex = 0;
+    while ((m = RE_LET.exec(text)) !== null) {
+        localBindings.push({
+            name: m[1],
+            offset: m.index,
+            isModuleLevel: false,
+            sourceUri,
+        });
+    }
+    RE_FOR.lastIndex = 0;
+    while ((m = RE_FOR.exec(text)) !== null) {
+        localBindings.push({
+            name: m[1],
+            offset: m.index,
+            isModuleLevel: false,
+            sourceUri,
+        });
+    }
+    return {
+        functions,
+        moduleVariables,
+        localBindings,
+        imports,
+        defaultFunctionNamespace,
+        moduleNamespaceUri: moduleNs?.uri,
+        modulePrefix: moduleNs?.prefix,
+    };
+}
+// Testing
+export function analyze(text, sourceUri) {
+    try {
+        const { ast, comments } = XQuery31Full(text);
+        return analyzeAst(ast, comments, text, sourceUri);
+    }
+    catch {
+        return analyzeRegex(text, sourceUri);
+    }
+}

package/dist/builtins.d.ts

@@ -0,0 +1,2 @@
+import type { FileAnalysis } from "./types.ts";
+export declare function getBuiltins(): FileAnalysis;

package/dist/builtins.js

@@ -0,0 +1,28 @@
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { join, dirname } from "path";
+import { analyze, XMLNS_FN } from "./analyzer.js";
+const baseDir = dirname(fileURLToPath(import.meta.url));
+const BUILTIN_FILES = [
+    "builtins/builtins-fn.xq",
+    "builtins/builtins-math.xq",
+    "builtins/builtins-map.xq",
+    "builtins/builtins-array.xq",
+];
+let _builtins = null;
+export function getBuiltins() {
+    if (!_builtins) {
+        const analyses = BUILTIN_FILES.map((f) => {
+            const text = readFileSync(join(baseDir, "..", f), "utf-8");
+            return analyze(text, `builtin:${f}`);
+        });
+        _builtins = {
+            functions: analyses.flatMap((a) => a.functions),
+            moduleVariables: [],
+            localBindings: [],
+            imports: [],
+            defaultFunctionNamespace: XMLNS_FN,
+        };
+    }
+    return _builtins;
+}

package/dist/completion.d.ts

@@ -0,0 +1,9 @@
+import { CompletionItem } from "vscode-languageserver/node.js";
+import type { FileAnalysis } from "./types.ts";
+export interface CompletionContext {
+    /** Text from start of document up to (and including) the cursor position */
+    textBeforeCursor: string;
+    /** Character offset of the cursor in the document */
+    cursorOffset: number;
+}
+export declare function getCompletions(ctx: CompletionContext, currentAnalysis: FileAnalysis, importedAnalyses: Map<string, FileAnalysis>, snippets?: boolean): CompletionItem[];