xq-lsp 1.0.0

package/src/features.ts

@@ -0,0 +1,260 @@
+import {
+	SignatureInformation,
+	ParameterInformation,
+	SymbolKind,
+	Location,
+	MarkupKind,
+} from "vscode-languageserver/node.js";
+import type { Hover, SignatureHelp, DocumentSymbol, Range, Position } from "vscode-languageserver/node.js";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import * as fs from "fs";
+import { fileURLToPath } from "url";
+import type { FileAnalysis, FunctionSymbol } from "./types.ts";
+import { resolvePrefix } from "./analyzer.ts";
+
+// ── 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: string,
+	currentAnalysis: FileAnalysis,
+	fns: FunctionSymbol[],
+): FunctionSymbol | undefined {
+	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: string, offset: number): { word: string; start: number; end: number } {
+	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: FunctionSymbol): string {
+	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: FileAnalysis, imported: Map<string, FileAnalysis>): FunctionSymbol[] {
+	const fns = [...current.functions];
+	for (const a of imported.values()) fns.push(...a.functions);
+	return fns;
+}
+
+function positionInText(text: string, offset: number): Position {
+	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: TextDocument, start: number, end: number): Range {
+	return { start: doc.positionAt(start), end: doc.positionAt(end) };
+}
+
+// ── Hover ────────────────────────────────────────────────────────────────────
+
+export function getHover(
+	doc: TextDocument,
+	offset: number,
+	current: FileAnalysis,
+	imported: Map<string, FileAnalysis>,
+): Hover | null {
+	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: string, offset: number): { name: string; activeParam: number } | null {
+	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: TextDocument,
+	offset: number,
+	current: FileAnalysis,
+	imported: Map<string, FileAnalysis>,
+): SignatureHelp | null {
+	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: SignatureInformation = {
+		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: TextDocument, current: FileAnalysis): DocumentSymbol[] {
+	const symbols: DocumentSymbol[] = [];
+
+	for (const fn of current.functions) {
+		const pos = doc.positionAt(fn.sourceOffset ?? 0);
+		const range: 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: 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: TextDocument,
+	offset: number,
+	current: FileAnalysis,
+	imported: Map<string, FileAnalysis>,
+	resolveUri: (atPath: string) => string,
+): Location | null {
+	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: Position = { 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/src/server.ts

@@ -0,0 +1,165 @@
+#!/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.ts';
+import { getBuiltins } from './builtins.ts';
+import { getCompletions } from './completion.ts';
+import { getHover, getSignatureHelp, getDocumentSymbols, getDefinition } from './features.ts';
+import type { FileAnalysis } from './types.ts';
+
+const connection = createConnection(ProposedFeatures.all);
+const documents = new TextDocuments(TextDocument);
+
+const analysisCache = new Map<string, FileAnalysis>();
+
+function analyzeDocument(doc: TextDocument): FileAnalysis {
+  const analysis = analyze(doc.getText(), doc.uri);
+  analysisCache.set(doc.uri, analysis);
+  return analysis;
+}
+
+function uriToPath(uri: string): string {
+  try {
+    return fileURLToPath(uri);
+  } catch {
+    return uri.replace(/^file:\/\//, '');
+  }
+}
+
+function resolveImportUri(currentUri: string, atPath: string): string {
+  const currentPath = uriToPath(currentUri);
+  const dir = path.dirname(currentPath);
+  const resolved = path.resolve(dir, atPath);
+  return pathToFileURL(resolved).toString();
+}
+
+function getImportedAnalysis(importUri: string): FileAnalysis | null {
+  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: string, analysis: FileAnalysis): Map<string, FileAnalysis> {
+  const result = new Map<string, FileAnalysis>();
+  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: string, uri: string) {
+  try {
+    XQuery31Full(text);
+    return [];
+  } catch (e: unknown) {
+    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/src/types.ts

@@ -0,0 +1,47 @@
+export interface ParamInfo {
+	name: string;
+	type?: string;
+	description?: string;
+}
+
+export interface DocComment {
+	description: string;
+	params: Record<string, string>; // param name (without $) → description
+	returns?: string;
+}
+
+export interface FunctionSymbol {
+	name: string; // full qualified name as declared, e.g. "local:add"
+	prefix: string; // namespace prefix as declared, e.g. "local"
+	localName: string; // local part, e.g. "add"
+	namespaceUri: string; // resolved namespace URI, e.g. "http://www.w3.org/2005/xquery-local-functions"
+	arity: number;
+	params: ParamInfo[];
+	returnType?: string;
+	doc?: DocComment;
+	sourceUri: string;
+	sourceOffset?: number; // char offset of the declare keyword
+}
+
+export interface VariableSymbol {
+	name: string; // without $, e.g. "sum" or "local:count"
+	offset: number; // char offset in source where it's defined
+	isModuleLevel: boolean;
+	sourceUri: string;
+}
+
+export interface ImportInfo {
+	prefix: string;
+	namespaceUri: string;
+	atPath: string; // as written in source, e.g. "./other.xq"
+}
+
+export interface FileAnalysis {
+	functions: FunctionSymbol[];
+	moduleVariables: VariableSymbol[]; // declare variable
+	localBindings: VariableSymbol[]; // let/for bindings
+	imports: ImportInfo[];
+	defaultFunctionNamespace: string; // from 'declare default function namespace', else XMLNS_FN
+	moduleNamespaceUri?: string; // from 'module namespace prefix="uri"'
+	modulePrefix?: string; // from 'module namespace prefix="uri"'
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+	"compilerOptions": {
+		"target": "esnext",
+		"module": "preserve",
+		"moduleResolution": "bundler",
+		"strict": true,
+		"erasableSyntaxOnly": true,
+		"verbatimModuleSyntax": true,
+		"outDir": "dist",
+		"rootDir": "src",
+		"rewriteRelativeImportExtensions": true,
+		"declaration": true,
+		"skipLibCheck": true,
+		"types": ["node"]
+	},
+	"paths": {
+		"vscode-languageserver/node.js": ["./node_modules/vscode-languageserver/node.d.ts"]
+	},
+	"include": [
+		"./src/*"
+	]
+}