xq-lsp 1.0.0

package/src/analyzer.ts

@@ -0,0 +1,402 @@
+import { XQuery31Full } from "xq-parser";
+import type { Node, NonTerminal, Terminal } from "xq-parser";
+import type { FileAnalysis, FunctionSymbol, VariableSymbol, ImportInfo, ParamInfo, DocComment } from "./types.ts";
+
+// ── 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: Record<string, string> = {
+	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: string, analysis: FileAnalysis): string {
+	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: Node): node is Terminal {
+	return node.isTerminal;
+}
+
+function asNonTerminal(node: Node): NonTerminal {
+	return node as NonTerminal;
+}
+
+function firstTerminalValue(node: Node): string | null {
+	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: Node, type: string, out: Node[] = []): Node[] {
+	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: Node, type: string): Node | undefined {
+	if (isTerminal(node)) return undefined;
+	return asNonTerminal(node).children.find((c) => c.type === type);
+}
+
+function directChildrenOf(node: Node, type: string): Node[] {
+	if (isTerminal(node)) return [];
+	return asNonTerminal(node).children.filter((c) => c.type === type);
+}
+
+// ── Doc comment parsing ──────────────────────────────────────────────────────
+
+function parseDocComment(raw: string): DocComment {
+	// 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: Record<string, string> = {};
+	let returns: string | undefined;
+	const descLines: string[] = [];
+	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: string, offset: number): DocComment | undefined {
+	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: Terminal[], text: string, offset: number): DocComment | undefined {
+	// 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: string): { prefix: string; uri: string } | undefined {
+	const m = text.match(/module\s+namespace\s+([\w\-]+)\s*=\s*["']([^"']*)["']/);
+	return m ? { prefix: m[1], uri: m[2] } : undefined;
+}
+
+function extractDefaultFunctionNamespace(text: string): string | undefined {
+	const m = text.match(/declare\s+default\s+function\s+namespace\s+["']([^"']*)["']/);
+	return m ? m[1] : undefined;
+}
+
+function buildPrefixMap(
+	moduleNs: { prefix: string; uri: string } | undefined,
+	imports: ImportInfo[],
+): Map<string, string> {
+	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: string, prefixMap: Map<string, string>): string {
+	return prefixMap.get(prefix) ?? `urn:xq-lsp:undeclared:${prefix}`;
+}
+
+// ── Extract from valid AST ───────────────────────────────────────────────────
+
+function sequenceTypeText(text: string, node: Node): string | undefined {
+	if (node.start === undefined || node.end === null) return undefined;
+	return text.slice(node.start, node.end ?? undefined).trim() || undefined;
+}
+
+function extractFunctions(
+	ast: Node,
+	sourceUri: string,
+	comments: Terminal[],
+	text: string,
+	prefixMap: Map<string, string>,
+): FunctionSymbol[] {
+	const results: FunctionSymbol[] = [];
+	// 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: ParamInfo[] = [];
+		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: Node, sourceUri: string): VariableSymbol[] {
+	const results: VariableSymbol[] = [];
+	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: Node, sourceUri: string): VariableSymbol[] {
+	const results: VariableSymbol[] = [];
+	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: Node): ImportInfo[] {
+	const results: ImportInfo[] = [];
+	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: string): string {
+	return s.replace(/^["']|["']$/g, "");
+}
+
+function analyzeAst(ast: Node, comments: Terminal[], text: string, sourceUri: string): FileAnalysis {
+	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: string, sourceUri: string): FileAnalysis {
+	const moduleVariables: VariableSymbol[] = [];
+	const localBindings: VariableSymbol[] = [];
+	const moduleNs = extractModuleNamespace(text);
+	const defaultFunctionNamespace = extractDefaultFunctionNamespace(text) ?? XMLNS_FN;
+
+	let m: RegExpExecArray | null;
+
+	// Collect imports first so we can build the prefix map before resolving functions.
+	const imports: ImportInfo[] = [];
+	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: FunctionSymbol[] = [];
+	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: ParamInfo[] = 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: string, sourceUri: string): FileAnalysis {
+	try {
+		const { ast, comments } = XQuery31Full(text);
+		return analyzeAst(ast, comments, text, sourceUri);
+	} catch {
+		return analyzeRegex(text, sourceUri);
+	}
+}

package/src/builtins.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { join, dirname } from "path";
+import { analyze, XMLNS_FN } from "./analyzer.ts";
+import type { FileAnalysis } from "./types.ts";
+
+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: FileAnalysis | null = null;
+
+export function getBuiltins(): FileAnalysis {
+	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/src/completion.ts

@@ -0,0 +1,179 @@
+import { CompletionItem, CompletionItemKind, InsertTextFormat, MarkupKind } from "vscode-languageserver/node.js";
+import type { FileAnalysis, FunctionSymbol, VariableSymbol } from "./types.ts";
+import { resolvePrefix } from "./analyzer.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;
+}
+
+interface TokenInfo {
+	kind: "variable" | "qualified-name" | "name";
+	/** Prefix typed so far — used to filter completions */
+	prefix: string;
+	/** For qualified names, the namespace prefix before the colon */
+	nsPrefix?: string;
+}
+
+function parseToken(textBefore: string): TokenInfo {
+	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: FunctionSymbol): string {
+	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: string[] = [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: FunctionSymbol, snippets: boolean): string {
+	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: VariableSymbol, filter: string): CompletionItem | null {
+	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: CompletionContext,
+	currentAnalysis: FileAnalysis,
+	importedAnalyses: Map<string, FileAnalysis>,
+	snippets = false,
+): CompletionItem[] {
+	const token = parseToken(ctx.textBeforeCursor);
+	const items: CompletionItem[] = [];
+
+	// ── 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;
+}