xq-lsp 1.8.2 → 1.8.3-next.430

package/dist/types.d.ts

@@ -26,6 +26,7 @@ export interface FunctionSymbol {
     doc?: DocComment;
     sourceUri: string;
     sourceOffset?: number;
+    visibility?: "public" | "private";
 }
 export interface VariableSymbol {
     qname: QName;
@@ -33,6 +34,7 @@ export interface VariableSymbol {
     isModuleLevel: boolean;
     sourceUri: string;
     doc?: string;
+    type?: string;
 }
 export interface ImportInfo {
     prefix: string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "xq-lsp",
-	"version": "1.8.2",
+	"version": "1.8.3-next.430",
 	"description": "XQuery Language Server Protocol implementation",
 	"license": "MIT",
 	"author": "Martin Middel",

package/src/analyzer.ts

@@ -26,7 +26,7 @@ export const XMLNS_ARRAY = "http://www.w3.org/2005/xpath-functions/array";
 // context, independent of any runtime/library configuration. math/map/array
 // aren't spec-mandated but are universally available in practice (they back
 // the 3.1 map/array/math core function libraries), so they're predeclared here too.
-const BUILTIN_PREFIXES: Record<string, string> = {
+export const BUILTIN_PREFIXES: Record<string, string> = {
 	fn: XMLNS_FN,
 	local: XMLNS_LOCAL,
 	xs: XMLNS_XS,
@@ -176,7 +176,10 @@ function findPrecedingDoc(comments: Terminal[], text: string, offset: number): D
 // ── Namespace helpers ────────────────────────────────────────────────────────
 
 function extractModuleNamespace(text: string): { prefix: string; uri: string } | undefined {
-	const m = text.match(/module\s+namespace\s+([\w\-]+)\s*=\s*["']([^"']*)["']/);
+	// The negative lookbehind excludes `import module namespace ...` — a module
+	// import, not this file's own `module namespace` declaration — which would
+	// otherwise match the same pattern and be mistaken for it.
+	const m = text.match(/(?<!import\s+)\bmodule\s+namespace\s+([\w\-]+)\s*=\s*["']([^"']*)["']/);
 	return m ? { prefix: m[1], uri: m[2] } : undefined;
 }
 
@@ -201,6 +204,25 @@ function resolveNamespaceUri(prefix: string, prefixMap: Map<string, string>): st
 	return prefixMap.get(prefix) ?? `urn:xq-lsp:undeclared:${prefix}`;
 }
 
+const PREDEFINED_ENTITIES: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+
+/**
+ * A BracedURILiteral's content may contain PredefinedEntityRef (&amp; &lt; &gt;
+ * &quot; &apos;) and CharRef (&#DDDD; / &#xHHHH;) escapes, same as string content —
+ * e.g. `Q{http:&#x2F;&#x2F;example.com}` names the URI "http://example.com". The
+ * parser's terminal value is the raw, un-decoded source slice, so this decoding
+ * has to happen here rather than being assumed already done.
+ */
+function decodeCharRefs(text: string): string {
+	return text.replace(/&(#x[0-9a-fA-F]+|#[0-9]+|[a-zA-Z]+);/g, (match, ref: string) => {
+		if (ref[0] === "#") {
+			const codePoint = ref[1] === "x" ? parseInt(ref.slice(2), 16) : parseInt(ref.slice(1), 10);
+			return Number.isNaN(codePoint) ? match : String.fromCodePoint(codePoint);
+		}
+		return PREDEFINED_ENTITIES[ref] ?? match;
+	});
+}
+
 /**
  * Per the BracedURILiteral grammar, whitespace inside `Q{...}` is insignificant:
  * leading/trailing whitespace is trimmed and internal runs are collapsed to a
@@ -208,7 +230,7 @@ function resolveNamespaceUri(prefix: string, prefixMap: Map<string, string>): st
  * This does not decode percent-escapes — `Q{foo%20bar}` stays distinct from `Q{foo bar}`.
  */
 function normalizeBracedUri(uri: string): string {
-	return uri.trim().replace(/\s+/g, " ");
+	return decodeCharRefs(uri).trim().replace(/\s+/g, " ");
 }
 
 /**
@@ -244,6 +266,19 @@ export function sequenceTypeText(text: string, node: Node): string | undefined {
 	return text.slice(node.start, node.end ?? undefined).trim() || undefined;
 }
 
+// A %public/%private annotation on an AnnotatedDecl controls whether the
+// declaration is visible to modules that import it (XQuery 3.0+). Returns
+// undefined when neither annotation is present; callers treat that as public,
+// same as FunctionSymbol.visibility's own default.
+function extractVisibility(annotated: Node): "public" | "private" | undefined {
+	for (const ann of directChildrenOf(annotated, "Annotation")) {
+		const eqname = directChildOf(ann, "EQName");
+		const raw = eqname ? firstTerminalValue(eqname) : null;
+		if (raw === "private" || raw === "public") return raw;
+	}
+	return undefined;
+}
+
 function extractFunctions(
 	ast: Node,
 	sourceUri: string,
@@ -296,6 +331,7 @@ function extractFunctions(
 			doc,
 			sourceUri,
 			sourceOffset: annotated.start,
+			visibility: extractVisibility(annotated),
 		});
 	}
 	return results;
@@ -318,12 +354,15 @@ function extractModuleVariables(
 		const name = varName ? firstTerminalValue(varName) : null;
 		if (!name) continue;
 		const doc = findPrecedingDoc(comments, text, annotated.start);
+		const typeDecl = directChildOf(varDecl, "TypeDeclaration");
+		const seqType = typeDecl ? directChildOf(typeDecl, "SequenceType") : undefined;
 		results.push({
 			qname: makeVarQName(name, prefixMap),
 			offset: varDecl.start,
 			isModuleLevel: true,
 			sourceUri,
 			doc: doc?.description || undefined,
+			type: seqType ? sequenceTypeText(text, seqType) : undefined,
 		});
 	}
 	return results;
@@ -466,12 +505,15 @@ function analyzeRegex(text: string, sourceUri: string): FileAnalysis {
 	RE_VAR_DECL.lastIndex = 0;
 	while ((m = RE_VAR_DECL.exec(text)) !== null) {
 		const doc = findPrecedingDocInText(text, m.index);
+		// `declare variable $x as T := …` / `… as T external` — T runs up to `:=` or `external`.
+		const typeMatch = /^\s+as\s+([^;]{1,200}?)\s*(?::=|\bexternal\b)/.exec(text.slice(m.index + m[0].length));
 		moduleVariables.push({
 			qname: makeVarQName(m[1], prefixMap),
 			offset: m.index,
 			isModuleLevel: true,
 			sourceUri,
 			doc: doc?.description || undefined,
+			type: typeMatch?.[1],
 		});
 	}
 

package/src/ast-nodes.ts

@@ -145,6 +145,63 @@ export function asFunctionDecl(node: Node, analysis: FileAnalysis): FunctionDecl
 	return { nameNode, qname: { prefix, localName, namespaceUri }, params, body: directChildOf(node, "FunctionBody") ?? null };
 }
 
+// ── Prolog declarations ───────────────────────────────────────────────────────
+
+/** The version string of `xquery version "x"` (quotes stripped) and its literal node; null when only an encoding is given. */
+export function asVersionDecl(node: Node): { version: string; versionNode: Node } | null {
+	if (node.type !== "VersionDecl" || !directChildOf(node, "'version'")) return null;
+	const versionNode = directChildOf(node, "StringLiteral");
+	const raw = versionNode ? firstTerminalValue(versionNode) : null;
+	if (!versionNode || !raw) return null;
+	// String literals may contain character references, e.g. '1.0'
+	const version = raw
+		.slice(1, -1)
+		.replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCodePoint(parseInt(hex, 16)))
+		.replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(parseInt(dec, 10)));
+	return { version, versionNode };
+}
+
+/** Resolved QName and name node of a `declare option` OptionDecl. */
+export function asOptionDecl(node: Node, analysis: FileAnalysis): { qname: QName; nameNode: Node } | null {
+	if (node.type !== "OptionDecl") return null;
+	const nameNode = directChildOf(node, "EQName");
+	const qname = nameNode ? qnameFromRawTerminal(nameNode, analysis) : null;
+	return nameNode && qname ? { qname, nameNode } : null;
+}
+
+/** Prefix bound by a `declare namespace p = "uri"` NamespaceDecl. */
+export function asNamespaceDecl(node: Node): { prefix: string } | null {
+	if (node.type !== "NamespaceDecl") return null;
+	const prefixNode = directChildOf(node, "NCName");
+	const prefix = prefixNode ? firstTerminalValue(prefixNode) : null;
+	return prefix === null ? null : { prefix };
+}
+
+/** Which default namespace a `declare default element|function namespace` DefaultNamespaceDecl sets. */
+export function asDefaultNamespaceDecl(node: Node): { kind: "element" | "function" } | null {
+	if (node.type !== "DefaultNamespaceDecl") return null;
+	if (directChildOf(node, "'element'")) return { kind: "element" };
+	if (directChildOf(node, "'function'")) return { kind: "function" };
+	return null;
+}
+
+export interface DecimalFormatDeclShape {
+	/** Expanded name of the format; "" for the default decimal format. */
+	key: string;
+	properties: Array<{ nameNode: Node; name: string }>;
+}
+
+export function asDecimalFormatDecl(node: Node, analysis: FileAnalysis): DecimalFormatDeclShape | null {
+	if (node.type !== "DecimalFormatDecl") return null;
+	const eqname = directChildOf(node, "EQName");
+	const qname = eqname ? qnameFromRawTerminal(eqname, analysis) : null;
+	const properties = directChildrenOf(node, "DFPropertyName").flatMap((nameNode) => {
+		const name = firstTerminalValue(nameNode);
+		return name ? [{ nameNode, name }] : [];
+	});
+	return { key: qname ? `${qname.namespaceUri}#${qname.localName}` : "", properties };
+}
+
 // ── InlineFunctionExpr ────────────────────────────────────────────────────────
 
 export interface InlineFunctionExprShape {
@@ -426,3 +483,31 @@ export function argExpr(node: Node): Node | null {
 	if (node.type !== "Argument") return null;
 	return directChildOf(node, "ExprSingle") ?? null;
 }
+
+// ── Arithmetic expressions ────────────────────────────────────────────────────
+
+export interface ArithmeticExprShape {
+	/** Operand expressions in source order (always at least two). */
+	operands: Node[];
+	/**
+	 * Operators in source order; `operators[i]` sits between `operands[i]` and `operands[i + 1]`.
+	 * Invariant: `operators.length === operands.length - 1`, so `operands[i + 1]` is always
+	 * defined for every index into `operators`.
+	 */
+	operators: string[];
+}
+
+// The grammar produces a flat, left-associative chain `operand (op operand)*`. Every expression
+// passes through these node types, so a chain with a single operand is not arithmetic → null.
+export function asArithmeticExpr(node: Node): ArithmeticExprShape | null {
+	if (node.type !== "AdditiveExpr" && node.type !== "MultiplicativeExpr") return null;
+	if (isTerminal(node)) return null;
+	const operands: Node[] = [];
+	const operators: string[] = [];
+	for (const c of (node as import("xq-parser").NonTerminal).children) {
+		if (isTerminal(c)) operators.push(c.value);
+		else operands.push(c);
+	}
+	// Enforces the invariant documented on ArithmeticExprShape; a malformed chain is not arithmetic.
+	return operands.length > 1 && operators.length === operands.length - 1 ? { operands, operators } : null;
+}

package/src/diagnostics.ts

@@ -12,6 +12,7 @@ import { findUndeclaredPrefixUsages } from "./namespace-diagnostics.ts";
 import { checkContextItemUsage } from "./context-item-diagnostics.ts";
 import { checkUndeclaredVariables } from "./variable-diagnostics.ts";
 import { checkDuplicateFunctions } from "./duplicate-function-diagnostics.ts";
+import { checkDuplicatePrologDecls } from "./prolog-diagnostics.ts";
 import { checkModuleImportTargets } from "./module-import-diagnostics.ts";
 import { checkUnused } from "./unused-diagnostics.ts";
 import { checkBracedUriWhitespace } from "./braced-uri-diagnostics.ts";
@@ -35,6 +36,7 @@ export function runDiagnostics(
 		...checkContextItemUsage(ast),
 		...checkUndeclaredVariables(ast, analysis, imports),
 		...checkDuplicateFunctions(ast, analysis, imports),
+		...checkDuplicatePrologDecls(ast, analysis),
 		...checkModuleImportTargets(analysis, imports),
 	];
 }

package/src/functioncall-diagnostics.ts

@@ -1,13 +1,85 @@
 import type { Node, NonTerminal } from "xq-parser";
 import type { TypeDiagnostic, FileAnalysis, FunctionSymbol, QName } from "./types.ts";
 import { formatQName } from "./types.ts";
-import { findAll, isTerminal, directChildrenOf, firstTerminalValue, parseEQName, resolvePrefix } from "./analyzer.ts";
+import {
+	findAll,
+	isTerminal,
+	directChildrenOf,
+	firstTerminalValue,
+	parseEQName,
+	resolvePrefix,
+	XMLNS_LOCAL,
+	XMLNS_FN,
+	XMLNS_XS,
+	XMLNS_MATH,
+	XMLNS_MAP,
+	XMLNS_ARRAY,
+} from "./analyzer.ts";
 import { asFunctionCall, asNamedFunctionRef } from "./ast-nodes.ts";
 
-function allFunctionsFlat(analysis: FileAnalysis, importedAnalyses: Map<string, FileAnalysis>): FunctionSymbol[] {
+// Namespaces that are always in scope without an explicit import: the
+// spec-mandated predeclared ones, plus whatever this file declares of its own
+// (local: functions, its own module namespace, and its default function
+// namespace) — we have complete, closed-world knowledge of all of these.
+function alwaysAccessibleNamespaceUris(analysis: FileAnalysis): Set<string> {
+	const uris = new Set([XMLNS_LOCAL, XMLNS_FN, XMLNS_XS, XMLNS_MATH, XMLNS_MAP, XMLNS_ARRAY, analysis.defaultFunctionNamespace]);
+	if (analysis.moduleNamespaceUri) uris.add(analysis.moduleNamespaceUri);
+	return uris;
+}
+
+/**
+ * Gather every function symbol this file can legally call, plus the set of
+ * imported namespace URIs we couldn't resolve to any analysis (unresolvable
+ * "at" path, or an unresolvable bare import — genuinely unknown, so calls
+ * into them are left unchecked to avoid false positives).
+ *
+ * A namespace not covered by any of the above (not declared, not imported,
+ * not predeclared) has zero accessible functions by construction: nothing in
+ * this module's static scope could have brought a function from it into
+ * view, regardless of what happens to be sitting in `importedAnalyses` (the
+ * QT4 harness, for instance, loads catalog modules that were never actually
+ * imported by the query under test, specifically to verify this isn't enough
+ * to make their functions callable).
+ */
+function accessibleFunctions(
+	analysis: FileAnalysis,
+	importedAnalyses: Map<string, FileAnalysis>,
+): { fns: FunctionSymbol[]; unresolvedImportUris: Set<string> } {
 	const fns = [...analysis.functions];
-	for (const a of importedAnalyses.values()) fns.push(...a.functions);
-	return fns;
+	const alwaysOpen = alwaysAccessibleNamespaceUris(analysis);
+	const importedNamespaceUris = new Set(analysis.imports.map((i) => i.namespaceUri));
+	// Runtime-predeclared namespaces (e.g. eXist-db's util:, xmldb:) are merged into
+	// namespaceDecls with offset -1 — see withPredeclaredNs — marking them as
+	// implicitly available without a written import. The QT4 harness uses the same
+	// offset -1 convention for <environment><namespace> bindings, which name a
+	// namespace without providing (or requiring) any declaration of what's in it.
+	const predeclaredUris = new Set(analysis.namespaceDecls.filter((nd) => nd.offset === -1).map((nd) => nd.namespaceUri));
+	// Namespaces we might have real knowledge of — but only once we find a matching
+	// entry in importedAnalyses below. Until then, stay silent about them rather
+	// than treating "no analysis available" as "no such function". Namespaces
+	// already in alwaysOpen are excluded: they're already guaranteed accessible
+	// (e.g. builtins arrive under a "builtin:" map key, not one matching their own
+	// namespace URI), so redundantly re-declaring one — as the QT4 harness's
+	// <environment><namespace prefix="map" uri=".../map"/> does — must not make it
+	// look unresolved.
+	const candidateUris = new Set([...importedNamespaceUris, ...predeclaredUris].filter((u) => !alwaysOpen.has(u)));
+	const resolvedUris = new Set<string>();
+
+	for (const [key, a] of importedAnalyses) {
+		if (key.startsWith("builtin:") || alwaysOpen.has(key)) {
+			fns.push(...a.functions);
+			continue;
+		}
+		if (candidateUris.has(key)) {
+			// A %private function/variable is only visible within its own declaring
+			// module — filter it out for anything reached through an import.
+			fns.push(...a.functions.filter((f) => f.visibility !== "private"));
+			resolvedUris.add(key);
+		}
+	}
+
+	const unresolvedImportUris = new Set([...candidateUris].filter((u) => !resolvedUris.has(u)));
+	return { fns, unresolvedImportUris };
 }
 
 function arityDescription(overloads: FunctionSymbol[]): string {
@@ -20,15 +92,20 @@ function checkArity(
 	arity: number,
 	nodeStart: number,
 	allFns: FunctionSymbol[],
-	knownNamespaceUris: Set<string>,
+	unresolvedImportUris: Set<string>,
 	errors: TypeDiagnostic[],
 ): void {
 	const { namespaceUri, localName } = qname;
+	// A prefix that resolves to nothing at all is a separate diagnostic's
+	// concern (findUndeclaredPrefixUsages) — don't pile on here.
+	if (namespaceUri.startsWith("urn:xq-lsp:undeclared:")) return;
+	// An import we couldn't resolve to any analysis: genuinely unknown, stay silent.
+	if (unresolvedImportUris.has(namespaceUri)) return;
+
 	const overloads = allFns.filter((f) => f.qname.namespaceUri === namespaceUri && f.qname.localName === localName);
 	const name = formatQName(qname);
 
 	if (overloads.length === 0) {
-		if (!knownNamespaceUris.has(namespaceUri)) return;
 		errors.push({ message: `${name} is not declared`, code: "XPST0017", offset: nodeStart, length: name.length });
 		return;
 	}
@@ -48,10 +125,13 @@ function checkArity(
  * Walk all FunctionCall, NamedFunctionRef, and ArrowExpr nodes in the AST
  * and report XPST0017 for any call where the argument count does not match
  * any known overload, or where the function name is not declared in a
- * namespace we have analysis for.
+ * namespace this file can call into.
  *
- * If the function's namespace is entirely unknown (no analysis loaded for it),
- * the call is silently skipped — it could be a runtime-only library.
+ * A namespace is only skipped (left unchecked) when it's the target of an
+ * import we couldn't resolve to any analysis, or when the prefix itself is
+ * undeclared (that's findUndeclaredPrefixUsages's concern) — see
+ * accessibleFunctions and checkArity. Every other namespace is closed-world:
+ * not finding a matching declaration there means one doesn't exist.
  */
 export function checkFunctionCalls(
 	ast: Node,
@@ -59,16 +139,14 @@ export function checkFunctionCalls(
 	importedAnalyses: Map<string, FileAnalysis>,
 ): TypeDiagnostic[] {
 	const errors: TypeDiagnostic[] = [];
-	const allFns = allFunctionsFlat(analysis, importedAnalyses);
-	// Namespaces we have at least one function declaration for.
-	const knownNamespaceUris = new Set(allFns.map((f) => f.qname.namespaceUri));
+	const { fns: allFns, unresolvedImportUris } = accessibleFunctions(analysis, importedAnalyses);
 
 	// ── FunctionCall ─────────────────────────────────────────────────────────────
 
 	for (const callNode of findAll(ast, "FunctionCall")) {
 		const call = asFunctionCall(callNode, analysis);
 		if (!call) continue;
-		checkArity(call.qname, call.args.length, callNode.start, allFns, knownNamespaceUris, errors);
+		checkArity(call.qname, call.args.length, callNode.start, allFns, unresolvedImportUris, errors);
 	}
 
 	// ── NamedFunctionRef ─────────────────────────────────────────────────────────
@@ -76,7 +154,7 @@ export function checkFunctionCalls(
 	for (const refNode of findAll(ast, "NamedFunctionRef")) {
 		const ref = asNamedFunctionRef(refNode, analysis);
 		if (!ref) continue;
-		checkArity(ref.qname, ref.arity, refNode.start, allFns, knownNamespaceUris, errors);
+		checkArity(ref.qname, ref.arity, refNode.start, allFns, unresolvedImportUris, errors);
 	}
 
 	// ── ArrowExpr ────────────────────────────────────────────────────────────────
@@ -102,7 +180,7 @@ export function checkFunctionCalls(
 			const namespaceUri = uri ?? resolvePrefix(prefix, analysis);
 			const explicitArgs = directChildrenOf(argList, "Argument").length;
 
-			checkArity({ prefix, localName, namespaceUri }, 1 + explicitArgs, arrowNode.start, allFns, knownNamespaceUris, errors);
+			checkArity({ prefix, localName, namespaceUri }, 1 + explicitArgs, arrowNode.start, allFns, unresolvedImportUris, errors);
 		}
 	}
 

package/src/inlay-hints.ts

@@ -1,12 +1,17 @@
 import { InlayHintKind } from "vscode-languageserver/node.js";
 import type { InlayHint, Range } from "vscode-languageserver/node.js";
 import type { TextDocument } from "vscode-languageserver-textdocument";
-import type { Node, NonTerminal } from "xq-parser";
+import type { Node } from "xq-parser";
 import type { FileAnalysis, FunctionSymbol, XQueryType } from "./types.ts";
-import { qnameKey } from "./types.ts";
-import { findAll, isTerminal, directChildOf } from "./analyzer.ts";
-import { asFunctionCall, asBinding, asTypedBinding } from "./ast-nodes.ts";
-import { parseType, inferExprType, formatType } from "./typechecker.ts";
+import { findAll } from "./analyzer.ts";
+import { asFunctionCall } from "./ast-nodes.ts";
+import {
+	externalVariableTypes,
+	formatType,
+	resolveFunction,
+	walkModuleScopes,
+	withInferredReturnTypes,
+} from "./typechecker.ts";
 
 function allFunctionsFlat(analysis: FileAnalysis, importedAnalyses: Map<string, FileAnalysis>): FunctionSymbol[] {
 	const fns = [...analysis.functions];
@@ -14,28 +19,10 @@ function allFunctionsFlat(analysis: FileAnalysis, importedAnalyses: Map<string,
 	return fns;
 }
 
-function resolveCallee(
-	call: { qname: { namespaceUri: string; localName: string } },
-	argCount: number,
-	allFns: FunctionSymbol[],
-): FunctionSymbol | undefined {
-	const overloads = allFns.filter(
-		(f) => f.qname.namespaceUri === call.qname.namespaceUri && f.qname.localName === call.qname.localName,
-	);
-	return overloads.find((f) => (f.variadic ? argCount >= f.arity : f.arity === argCount));
-}
-
 function inRange(offset: number, range: { start: number; end: number }): boolean {
 	return offset >= range.start && offset <= range.end;
 }
 
-// Narrows a sequence's type to its item type (occurrence ""), for `for` bindings
-// where the bound variable holds one item per iteration, not the whole sequence.
-function itemTypeOf(t: XQueryType): XQueryType {
-	if (t.kind === "unknown" || t.kind === "empty") return t;
-	return t.occurrence === "" ? t : { ...t, occurrence: "" };
-}
-
 // ── Parameter name hints ─────────────────────────────────────────────────────
 
 function collectParameterHints(
@@ -49,7 +36,7 @@ function collectParameterHints(
 	for (const callNode of findAll(ast, "FunctionCall")) {
 		const call = asFunctionCall(callNode, analysis);
 		if (!call || call.args.length === 0) continue;
-		const fn = resolveCallee(call, call.args.length, allFns);
+		const fn = resolveFunction(call.qname, call.args.length, allFns);
 		if (!fn) continue;
 
 		for (let i = 0; i < call.args.length && i < fn.params.length; i++) {
@@ -65,78 +52,40 @@ function collectParameterHints(
 	}
 }
 
-// ── Inferred type hints on untyped let/for bindings ──────────────────────────
+// ── Inferred type hints on untyped bindings ──────────────────────────────────
 
-function collectParams(paramList: Node | undefined, text: string, analysis: FileAnalysis, scope: Map<string, XQueryType>): void {
-	if (!paramList) return;
-	for (const param of findAll(paramList, "Param")) {
-		const binding = asTypedBinding(param, text, analysis);
-		if (binding?.typeStr) scope.set(qnameKey(binding.qname), parseType(binding.typeStr));
-	}
-}
-
-function buildModuleVarTypes(ast: Node, text: string, analysis: FileAnalysis): Map<string, XQueryType> {
-	const types = new Map<string, XQueryType>();
-	for (const node of findAll(ast, "VarDecl")) {
-		const binding = asTypedBinding(node, text, analysis);
-		if (binding?.typeStr) types.set(qnameKey(binding.qname), parseType(binding.typeStr));
-	}
-	return types;
-}
-
-// Walks the tree tracking in-scope variable types, mirroring typechecker.ts's scope walk,
-// but also records the inferred type of untyped let/for bindings so later bindings see it.
-function walkForTypeHints(
-	node: Node,
-	scopeTypes: Map<string, XQueryType>,
-	moduleTypes: Map<string, XQueryType>,
-	text: string,
+// Shows the inferred type after the name of every binding without a declared type:
+// let/for/group-by variables and module-level `declare variable`s. The scope walk is the
+// same one the type checker uses, so hints reflect exactly what diagnostics see.
+function collectTypeHints(
+	ast: Node,
 	analysis: FileAnalysis,
 	allFns: FunctionSymbol[],
 	range: { start: number; end: number },
 	hints: InlayHint[],
 	doc: TextDocument,
+	outerScope: Map<string, XQueryType>,
 ): void {
-	if (isTerminal(node)) return;
-	const nt = node as NonTerminal;
-
-	if (node.type === "InlineFunctionExpr") {
-		const innerScope = new Map(moduleTypes);
-		collectParams(directChildOf(node, "ParamList"), text, analysis, innerScope);
-		const body = directChildOf(node, "FunctionBody");
-		if (body) walkForTypeHints(body, innerScope, moduleTypes, text, analysis, allFns, range, hints, doc);
-		return;
-	}
-
-	if (node.type === "LetBinding" || node.type === "ForBinding") {
-		const typed = asTypedBinding(node, text, analysis);
-		const binding = asBinding(node, analysis);
-		if (typed && binding) {
-			if (typed.typeStr) {
-				scopeTypes.set(qnameKey(typed.qname), parseType(typed.typeStr));
-			} else if (binding.initExpr) {
-				const inferredSeq = inferExprType(binding.initExpr, scopeTypes, analysis, allFns);
-				// A `for` binding iterates the sequence one item at a time, so $x's type
-				// is the *item* type (occurrence narrowed to singular) — not the type of
-				// the whole iterated sequence, which is what inferExprType returns.
-				const inferred = node.type === "ForBinding" ? itemTypeOf(inferredSeq) : inferredSeq;
-				scopeTypes.set(qnameKey(typed.qname), inferred);
-				const nameEnd = binding.nameNode.end ?? binding.nameNode.start;
-				if (inferred.kind !== "unknown" && inRange(nameEnd, range)) {
-					hints.push({
-						position: doc.positionAt(nameEnd),
-						label: `: ${formatType(inferred)}`,
-						kind: InlayHintKind.Type,
-						paddingLeft: true,
-					});
-				}
-			}
-		}
-	}
-
-	for (const child of nt.children) {
-		walkForTypeHints(child, scopeTypes, moduleTypes, text, analysis, allFns, range, hints, doc);
-	}
+	const seen = new Set<number>();
+	walkModuleScopes(
+		ast,
+		analysis,
+		allFns,
+		{
+			onBinding: (nameNode, type) => {
+				const nameEnd = nameNode.end ?? nameNode.start;
+				if (type.kind === "unknown" || !inRange(nameEnd, range) || seen.has(nameEnd)) return;
+				seen.add(nameEnd);
+				hints.push({
+					position: doc.positionAt(nameEnd),
+					label: `: ${formatType(type)}`,
+					kind: InlayHintKind.Type,
+					paddingLeft: true,
+				});
+			},
+		},
+		outerScope,
+	);
 }
 
 // ── Entry point ───────────────────────────────────────────────────────────────
@@ -148,15 +97,15 @@ export function getInlayHints(
 	imported: Map<string, FileAnalysis>,
 	range: Range,
 ): InlayHint[] {
-	const text = doc.getText();
 	const offsetRange = { start: doc.offsetAt(range.start), end: doc.offsetAt(range.end) };
-	const allFns = allFunctionsFlat(analysis, imported);
+	const declaredFns = allFunctionsFlat(analysis, imported);
+	const outerScope = externalVariableTypes(analysis, imported.values(), declaredFns);
+	const allFns = withInferredReturnTypes(ast, analysis, declaredFns, outerScope);
 	const hints: InlayHint[] = [];
 
 	collectParameterHints(ast, analysis, allFns, offsetRange, hints, doc);
 
-	const moduleTypes = buildModuleVarTypes(ast, text, analysis);
-	walkForTypeHints(ast, new Map(moduleTypes), moduleTypes, text, analysis, allFns, offsetRange, hints, doc);
+	collectTypeHints(ast, analysis, allFns, offsetRange, hints, doc, outerScope);
 
 	return hints;
 }

package/src/module-siblings.ts

@@ -0,0 +1,17 @@
+import type { FileAnalysis } from "./types.ts";
+
+/**
+ * The declarations that *other* files contribute to a module namespace. XQuery lets one module be
+ * implemented by several module files sharing a target namespace, and some runtimes (e.g. Fonto)
+ * merge them, so a file can call a function declared in a sibling without importing it.
+ *
+ * `merged` is the glob index entry for the namespace, which may include the current file's own
+ * on-disk declarations. Those are dropped so they aren't reported as duplicates of the (possibly
+ * edited) in-memory versions, nor resolved to stale positions. Returns null when nothing is left.
+ */
+export function siblingModuleAnalysis(merged: FileAnalysis, currentUri: string): FileAnalysis | null {
+	const functions = merged.functions.filter((f) => f.sourceUri !== currentUri);
+	const moduleVariables = merged.moduleVariables.filter((v) => v.sourceUri !== currentUri);
+	if (functions.length === 0 && moduleVariables.length === 0) return null;
+	return { ...merged, functions, moduleVariables };
+}

package/src/predeclared-namespaces.ts

@@ -133,6 +133,7 @@ export function getRuntimePredeclaredVariables(runtimes: string[], sourceUri: st
 		isModuleLevel: true,
 		sourceUri,
 		doc,
+		type: "xs:string", // all three are file system / collection paths
 	}));
 }