@danypops/lector 0.1.8 → 0.1.9

package/README.md

@@ -64,5 +64,7 @@ Three independent `SymbolIndexPort` implementations use one result DTO with expl
 - **TypeScript compiler** extracts bounded structural declarations from cold, malformed, or partially configured projects. It does not claim cross-file identity.
 - **tree-sitter** extracts bounded structural declarations and caches them by content hash. It does not claim type or language-server identity.
 
-Symbol results report `fidelity`, `backend`, `authority`, `freshness`, `limitations`, and `truncated`. Language-server messages, pending requests, opened files, file bytes, settling, parser files, parser nodes, parser bytes, and returned symbols are bounded.
+File-position operations dispatch by extension and seed a cold server with the requested file. Workspace symbol search and graph population detect every enabled language, merge results deterministically, and retain per-symbol and per-backend provenance; one failed backend produces an explicit partial result instead of hiding successful languages. Bash remains explicit-file-only until its vulnerable upstream dependency chain is removed; generic YAML is explicit-file-only because lockfiles and data files do not establish a workspace language.
+
+Symbol results report `fidelity`, `backend`, `authority`, `freshness`, `limitations`, `truncated`, and composite `sources`/`completeness` when applicable. Language-server messages, pending requests, opened files, file bytes, settling, parser files, parser nodes, parser bytes, language indexes, and returned symbols are bounded.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/lector",
-	"version": "0.1.8",
+	"version": "0.1.9",
 	"description": "Platform-neutral filesystem & code-intelligence capability: core, service, and driven adapters",
 	"license": "MIT",
 	"type": "module",

package/src/adapters/lsp/discover-seed-file.ts

@@ -6,6 +6,7 @@ import { refineTypescriptSeedFile } from "./typescript-project-files.ts";
 const SKIP_DIRECTORY_NAMES = new Set(["node_modules", "dist", "build", "out", "coverage"]);
 const MAX_SCAN_DEPTH = 4;
 const MAX_ENTRIES_SCANNED = 2_000;
+const MAX_WORKSPACE_DESCRIPTORS = 32;
 
 /** Raised when no matching source file could be found to warm a language server with. */
 export class NoSeedFileFound extends Error {
@@ -110,21 +111,28 @@ export function resolveSeedFile(rootPath: string, descriptor: LanguageServerDesc
 	return descriptor.languageId === "typescript" ? refineTypescriptSeedFile(rootPath, candidate) : candidate;
 }
 
-/**
- * For workspace.findSymbols called with no seedFile -- no anchor file to pick a language from.
- * Tries each descriptor's own discoverSeedFile in declared order; first real match wins.
- */
-export function discoverWorkspaceDescriptor(
+/** Detects every auto-enabled language in descriptor order; each language keeps the same bounded seed scan. */
+export function discoverWorkspaceDescriptors(
 	rootPath: string,
 	descriptors: readonly LanguageServerDescriptor[],
-): { descriptor: LanguageServerDescriptor; seedFile: string } | undefined {
+): readonly { descriptor: LanguageServerDescriptor; seedFile: string }[] {
+	if (descriptors.length > MAX_WORKSPACE_DESCRIPTORS) throw new TypeError(`workspace descriptor count exceeds ${MAX_WORKSPACE_DESCRIPTORS}`);
+	const discovered: { descriptor: LanguageServerDescriptor; seedFile: string }[] = [];
 	for (const descriptor of descriptors) {
+		if (descriptor.workspaceDiscovery === "explicit-only") continue;
 		try {
-			const seedFile = resolveSeedFile(rootPath, descriptor);
-			return { descriptor, seedFile };
+			discovered.push({ descriptor, seedFile: resolveSeedFile(rootPath, descriptor) });
 		} catch (error) {
 			if (!(error instanceof NoSeedFileFound)) throw error;
 		}
 	}
-	return undefined;
+	return discovered;
+}
+
+/** Compatibility helper for callers that still need one deterministic primary language. */
+export function discoverWorkspaceDescriptor(
+	rootPath: string,
+	descriptors: readonly LanguageServerDescriptor[],
+): { descriptor: LanguageServerDescriptor; seedFile: string } | undefined {
+	return discoverWorkspaceDescriptors(rootPath, descriptors)[0];
 }

package/src/adapters/lsp/lsp-symbol-index.ts

@@ -1,5 +1,5 @@
 import { readFileSync, realpathSync } from "node:fs";
-import { extname, join } from "node:path";
+import { extname, isAbsolute, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import type { CallHierarchyEntry, IncomingCall, OutgoingCall } from "../../domain/call-hierarchy.ts";
 import type { CodeRange } from "../../domain/code-range.ts";
@@ -27,6 +27,16 @@ export interface LspSymbolIndexOptions {
 	readonly maxFallbackSeedFiles?: number;
 }
 
+export class LanguageFileOutsideWorkspace extends Error {
+	constructor(
+		readonly path: string,
+		readonly root: string,
+	) {
+		super(`language file "${path}" resolves outside workspace root "${root}"`);
+		this.name = "LanguageFileOutsideWorkspace";
+	}
+}
+
 export class LanguageFileLimitExceeded extends Error {
 	constructor(
 		readonly limit: "open-files" | "file-bytes" | "refresh-bytes",
@@ -270,6 +280,7 @@ function normalizeDocumentSymbol(path: string, item: LspDocumentSymbol | LspSymb
 export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	readonly provenance: IntelligenceProvenance;
 	private readonly cwd: string;
+	private readonly canonicalCwd: string;
 	private readonly descriptor: LanguageServerDescriptor;
 	private readonly explicitSeedFile: string | undefined;
 	private fallbackSeedFile: string | undefined;
@@ -284,7 +295,8 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	private initializing: Promise<LanguageServerProcess> | undefined;
 
 	constructor(cwd: string, descriptor: LanguageServerDescriptor, seedFile?: string, options: LspSymbolIndexOptions = {}) {
-		this.cwd = cwd;
+		this.cwd = resolve(cwd);
+		this.canonicalCwd = realpathSync(this.cwd);
 		this.descriptor = descriptor;
 		this.explicitSeedFile = seedFile;
 		this.maxOpenFiles = positiveLimit(options.maxOpenFiles, DEFAULT_MAX_OPEN_FILES, "maxOpenFiles");
@@ -309,7 +321,18 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 		return this.process?.pid;
 	}
 
-	private async ensureInitialized(): Promise<LanguageServerProcess> {
+	private resolveTargetPath(path: string): string {
+		const absolute = resolve(this.cwd, path);
+		const canonical = realpathSync(absolute);
+		const relativeToRoot = relative(this.canonicalCwd, canonical);
+		if (relativeToRoot === ".." || relativeToRoot.startsWith(`..${sep}`) || isAbsolute(relativeToRoot)) {
+			throw new LanguageFileOutsideWorkspace(path, this.cwd);
+		}
+		return absolute;
+	}
+
+	private async ensureInitialized(initialPath?: string): Promise<LanguageServerProcess> {
+		const initialTargetPath = initialPath ? this.resolveTargetPath(initialPath) : undefined;
 		if (this.process) return this.process;
 		if (!this.initializing) {
 			let spawned: LanguageServerProcess | undefined;
@@ -350,8 +373,11 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 				});
 				proc.notify("initialized", {});
 
-				const seedFile = this.fallbackSeedFile ?? this.explicitSeedFile ?? resolveSeedFile(this.cwd, this.descriptor);
-				await this.ensureFileOpen(proc, join(this.cwd, seedFile));
+				const configuredSeedFile = this.fallbackSeedFile ?? this.explicitSeedFile;
+				const seedPath = configuredSeedFile
+					? resolve(this.cwd, configuredSeedFile)
+					: (initialTargetPath ?? resolve(this.cwd, resolveSeedFile(this.cwd, this.descriptor)));
+				await this.ensureFileOpen(proc, seedPath);
 
 				this.process = proc;
 				return proc;
@@ -374,6 +400,7 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 
 	/** Opens a file or sends a monotonic full-document change when its disk content changed since the prior query. */
 	private async ensureFileOpen(proc: LanguageServerProcess, path: string): Promise<void> {
+		path = this.resolveTargetPath(path);
 		const content = this.readBoundedFile(path);
 		const opened = this.openedFiles.get(path);
 		if (opened?.content === content) return;
@@ -459,7 +486,7 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	}
 
 	async goToDefinition(at: WorkspaceLocation): Promise<WorkspaceLocation[]> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(at.path);
 		await this.ensureFileOpen(proc, at.path);
 		const result = await proc.request<LspLocation | LspLocation[] | LspLocationLink[] | null>("textDocument/definition", {
 			textDocument: { uri: pathToFileURL(at.path).href },
@@ -469,7 +496,7 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	}
 
 	async goToImplementation(at: WorkspaceLocation): Promise<WorkspaceLocation[]> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(at.path);
 		await this.ensureFileOpen(proc, at.path);
 		const result = await proc.request<LspLocation | LspLocation[] | LspLocationLink[] | null>("textDocument/implementation", {
 			textDocument: { uri: pathToFileURL(at.path).href },
@@ -479,7 +506,7 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	}
 
 	async findReferences(at: WorkspaceLocation, includeDeclaration: boolean): Promise<WorkspaceLocation[]> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(at.path);
 		await this.ensureFileOpen(proc, at.path);
 		const results =
 			(await proc.request<LspLocation[] | null>("textDocument/references", {
@@ -491,7 +518,7 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	}
 
 	async hover(at: WorkspaceLocation): Promise<Hover | undefined> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(at.path);
 		await this.ensureFileOpen(proc, at.path);
 		const result = await proc.request<LspHover | null>("textDocument/hover", {
 			textDocument: { uri: pathToFileURL(at.path).href },
@@ -502,7 +529,7 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	}
 
 	async documentSymbols(path: string): Promise<DocumentSymbolEntry[]> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(path);
 		await this.ensureFileOpen(proc, path);
 		const results =
 			(await proc.request<(LspDocumentSymbol | LspSymbolInformation)[] | null>("textDocument/documentSymbol", {
@@ -512,7 +539,7 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	}
 
 	async diagnostics(path: string): Promise<Diagnostic[]> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(path);
 		await this.ensureFileOpen(proc, path);
 		if (!this.latestDiagnostics.has(path)) await this.waitForDiagnosticsNotification(path, 5000);
 		return this.latestDiagnostics.get(path) ?? [];
@@ -529,13 +556,13 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	}
 
 	async prepareCallHierarchy(at: WorkspaceLocation): Promise<CallHierarchyEntry[]> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(at.path);
 		const items = await this.prepareCallHierarchyRaw(proc, at);
 		return items.map((item) => normalizeCallHierarchyItem(item));
 	}
 
 	async incomingCalls(at: WorkspaceLocation): Promise<IncomingCall[]> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(at.path);
 		const root = (await this.prepareCallHierarchyRaw(proc, at))[0];
 		if (!root) return [];
 		const results = (await proc.request<LspCallHierarchyIncomingCall[] | null>("callHierarchy/incomingCalls", { item: root })) ?? [];
@@ -546,7 +573,7 @@ export class LspSymbolIndex implements SymbolIndexPort, CodeIntelligencePort {
 	}
 
 	async outgoingCalls(at: WorkspaceLocation): Promise<OutgoingCall[]> {
-		const proc = await this.ensureInitialized();
+		const proc = await this.ensureInitialized(at.path);
 		const root = (await this.prepareCallHierarchyRaw(proc, at))[0];
 		if (!root) return [];
 		const results = (await proc.request<LspCallHierarchyOutgoingCall[] | null>("callHierarchy/outgoingCalls", { item: root })) ?? [];

package/src/adapters/polyglot-code-intelligence-index.ts

@@ -0,0 +1,135 @@
+import { extname } from "node:path";
+import type { CallHierarchyEntry, IncomingCall, OutgoingCall } from "../domain/call-hierarchy.ts";
+import type { Diagnostic } from "../domain/diagnostic.ts";
+import type { DocumentSymbolEntry } from "../domain/document-symbol.ts";
+import type { Hover } from "../domain/hover.ts";
+import type { IntelligenceProvenance, IntelligenceSourceOutcome, SymbolSearchBounds } from "../domain/intelligence-provenance.ts";
+import type { LanguageServerDescriptor } from "../domain/language-server-descriptor.ts";
+import type { SymbolSearchResult, WorkspaceLocation, WorkspaceSymbol } from "../domain/workspace-symbol.ts";
+import type { CodeIntelligencePort } from "../ports/code-intelligence-port.ts";
+import type { SymbolIndexPort } from "../ports/symbol-index-port.ts";
+
+const MAX_SOURCE_ERROR_LENGTH = 500;
+const MAX_LANGUAGE_INDEXES = 16;
+const DEFAULT_MAX_RESULTS = 1_000;
+
+export interface PolyglotIndexEntry {
+	readonly descriptor: LanguageServerDescriptor;
+	readonly index: SymbolIndexPort;
+}
+
+function boundedError(error: unknown): { code: string; message: string } {
+	const code = error instanceof Error && error.name ? error.name : "CodeIntelligenceError";
+	const message = (error instanceof Error ? error.message : String(error)).slice(0, MAX_SOURCE_ERROR_LENGTH);
+	return { code, message };
+}
+
+function supportsCodeIntelligence(index: SymbolIndexPort): index is SymbolIndexPort & CodeIntelligencePort {
+	return "goToDefinition" in index && typeof index.goToDefinition === "function";
+}
+
+function compareSymbols(left: WorkspaceSymbol, right: WorkspaceSymbol): number {
+	return (
+		left.location.path.localeCompare(right.location.path) ||
+		left.location.line - right.location.line ||
+		left.location.character - right.location.character ||
+		left.name.localeCompare(right.name) ||
+		left.kind.localeCompare(right.kind)
+	);
+}
+
+export class PolyglotCodeIntelligenceIndex implements SymbolIndexPort, CodeIntelligencePort {
+	readonly provenance: IntelligenceProvenance = {
+		fidelity: "semantic",
+		backend: "polyglot-language-servers",
+		languageId: "polyglot",
+		authority: "language-server",
+		freshness: "live-process",
+		limitations: [],
+	};
+
+	constructor(private readonly entries: readonly PolyglotIndexEntry[]) {
+		if (entries.length === 0 || entries.length > MAX_LANGUAGE_INDEXES) {
+			throw new TypeError(`polyglot index requires between 1 and ${MAX_LANGUAGE_INDEXES} language indexes`);
+		}
+	}
+
+	private indexForPath(path: string): SymbolIndexPort & CodeIntelligencePort {
+		const extension = extname(path);
+		const entry = this.entries.find((candidate) => candidate.descriptor.extensions.includes(extension));
+		if (!entry) throw new Error(`no language index available for extension "${extension}"`);
+		if (!supportsCodeIntelligence(entry.index)) throw new Error(`code intelligence unavailable for ${entry.descriptor.languageId}`);
+		return entry.index;
+	}
+
+	async findSymbols(query: string, bounds: SymbolSearchBounds = { maxResults: DEFAULT_MAX_RESULTS }): Promise<SymbolSearchResult> {
+		if (!Number.isSafeInteger(bounds.maxResults) || bounds.maxResults < 1) throw new TypeError("maxResults must be a positive safe integer");
+		const settled = await Promise.allSettled(this.entries.map(({ index }) => index.findSymbols(query, bounds)));
+		const symbols: WorkspaceSymbol[] = [];
+		const sources: IntelligenceSourceOutcome[] = [];
+		let sourceTruncated = false;
+
+		for (const [position, outcome] of settled.entries()) {
+			const entry = this.entries[position];
+			if (!entry) continue;
+			if (outcome.status === "rejected") {
+				sources.push({ provenance: entry.index.provenance, status: "failed", symbolCount: 0, error: boundedError(outcome.reason) });
+				continue;
+			}
+			sources.push({
+				provenance: outcome.value.provenance,
+				status: "ready",
+				symbolCount: outcome.value.symbols.length,
+				truncated: outcome.value.truncated,
+			});
+			sourceTruncated ||= outcome.value.truncated;
+			for (const symbol of outcome.value.symbols) symbols.push({ ...symbol, provenance: outcome.value.provenance });
+		}
+
+		symbols.sort(compareSymbols);
+		const truncated = sourceTruncated || symbols.length > bounds.maxResults;
+		return {
+			symbols: symbols.slice(0, bounds.maxResults),
+			truncated,
+			provenance: this.provenance,
+			completeness: sources.every((source) => source.status === "ready") ? "complete" : "partial",
+			sources,
+		};
+	}
+
+	goToDefinition(at: WorkspaceLocation) {
+		return this.indexForPath(at.path).goToDefinition(at);
+	}
+
+	goToImplementation(at: WorkspaceLocation) {
+		return this.indexForPath(at.path).goToImplementation(at);
+	}
+
+	findReferences(at: WorkspaceLocation, includeDeclaration: boolean) {
+		return this.indexForPath(at.path).findReferences(at, includeDeclaration);
+	}
+
+	hover(at: WorkspaceLocation): Promise<Hover | undefined> {
+		return this.indexForPath(at.path).hover(at);
+	}
+
+	documentSymbols(path: string): Promise<DocumentSymbolEntry[]> {
+		return this.indexForPath(path).documentSymbols(path);
+	}
+
+	diagnostics(path: string): Promise<Diagnostic[]> {
+		return this.indexForPath(path).diagnostics(path);
+	}
+
+	prepareCallHierarchy(at: WorkspaceLocation): Promise<CallHierarchyEntry[]> {
+		return this.indexForPath(at.path).prepareCallHierarchy(at);
+	}
+
+	incomingCalls(at: WorkspaceLocation): Promise<IncomingCall[]> {
+		return this.indexForPath(at.path).incomingCalls(at);
+	}
+
+	outgoingCalls(at: WorkspaceLocation): Promise<OutgoingCall[]> {
+		return this.indexForPath(at.path).outgoingCalls(at);
+	}
+}

package/src/adapters/sqlite-symbol-graph.ts

@@ -28,6 +28,10 @@ const MIGRATIONS: Migration[] = [
 		version: 3,
 		up: (db) => db.exec("ALTER TABLE symbol_graph_generation ADD COLUMN provenance_json TEXT"),
 	},
+	{
+		version: 4,
+		up: (db) => db.exec("ALTER TABLE symbol_graph_generation ADD COLUMN sources_json TEXT"),
+	},
 ];
 
 interface NodeRow {
@@ -48,20 +52,14 @@ interface GenerationRow {
 	nodes_added: number;
 	edges_added: number;
 	provenance_json: string | null;
+	sources_json: string | null;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }
 
-function parseProvenance(json: string | null): IntelligenceProvenance | undefined {
-	if (!json) return undefined;
-	let value: unknown;
-	try {
-		value = JSON.parse(json);
-	} catch {
-		return undefined;
-	}
+function asProvenance(value: unknown): IntelligenceProvenance | undefined {
 	if (!isRecord(value)) return undefined;
 	const candidate = value;
 	if (
@@ -85,6 +83,26 @@ function parseProvenance(json: string | null): IntelligenceProvenance | undefine
 	};
 }
 
+function parseJson(json: string | null): unknown {
+	if (!json) return undefined;
+	try {
+		return JSON.parse(json);
+	} catch {
+		return undefined;
+	}
+}
+
+function parseProvenance(json: string | null): IntelligenceProvenance | undefined {
+	return asProvenance(parseJson(json));
+}
+
+function parseSources(json: string | null): readonly IntelligenceProvenance[] | undefined {
+	const value = parseJson(json);
+	if (!Array.isArray(value)) return undefined;
+	const sources = value.map(asProvenance);
+	return sources.every((source) => source !== undefined) ? sources : undefined;
+}
+
 /**
  * SQLite-backed SymbolGraphPort; survives a daemon restart pointed at the
  * same database file. reachableFrom uses `WITH RECURSIVE` rather than an
@@ -154,17 +172,19 @@ export class SqliteSymbolGraph implements SymbolGraphPort {
 	async getGeneration(): Promise<SymbolGraphGeneration | undefined> {
 		const row = this.db
 			.query(
-				"SELECT source_fingerprint, max_files, max_symbols_per_file, completed_at, files_processed, symbols_processed, nodes_added, edges_added, provenance_json FROM symbol_graph_generation WHERE singleton = 1",
+				"SELECT source_fingerprint, max_files, max_symbols_per_file, completed_at, files_processed, symbols_processed, nodes_added, edges_added, provenance_json, sources_json FROM symbol_graph_generation WHERE singleton = 1",
 			)
 			.get() as GenerationRow | null;
 		if (!row) return undefined;
 		const provenance = parseProvenance(row.provenance_json);
+		const sources = parseSources(row.sources_json);
 		return {
 			sourceFingerprint: row.source_fingerprint,
 			maxFiles: row.max_files,
 			maxSymbolsPerFile: row.max_symbols_per_file,
 			completedAt: row.completed_at,
 			...(provenance ? { provenance } : {}),
+			...(sources ? { sources } : {}),
 			result: {
 				filesProcessed: row.files_processed,
 				symbolsProcessed: row.symbols_processed,
@@ -177,7 +197,7 @@ export class SqliteSymbolGraph implements SymbolGraphPort {
 	async setGeneration(generation: SymbolGraphGeneration): Promise<void> {
 		this.db
 			.query(
-				"INSERT INTO symbol_graph_generation (singleton, source_fingerprint, max_files, max_symbols_per_file, completed_at, files_processed, symbols_processed, nodes_added, edges_added, provenance_json) VALUES (1, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(singleton) DO UPDATE SET source_fingerprint = excluded.source_fingerprint, max_files = excluded.max_files, max_symbols_per_file = excluded.max_symbols_per_file, completed_at = excluded.completed_at, files_processed = excluded.files_processed, symbols_processed = excluded.symbols_processed, nodes_added = excluded.nodes_added, edges_added = excluded.edges_added, provenance_json = excluded.provenance_json",
+				"INSERT INTO symbol_graph_generation (singleton, source_fingerprint, max_files, max_symbols_per_file, completed_at, files_processed, symbols_processed, nodes_added, edges_added, provenance_json, sources_json) VALUES (1, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(singleton) DO UPDATE SET source_fingerprint = excluded.source_fingerprint, max_files = excluded.max_files, max_symbols_per_file = excluded.max_symbols_per_file, completed_at = excluded.completed_at, files_processed = excluded.files_processed, symbols_processed = excluded.symbols_processed, nodes_added = excluded.nodes_added, edges_added = excluded.edges_added, provenance_json = excluded.provenance_json, sources_json = excluded.sources_json",
 			)
 			.run(
 				generation.sourceFingerprint,
@@ -189,6 +209,7 @@ export class SqliteSymbolGraph implements SymbolGraphPort {
 				generation.result.nodesAdded,
 				generation.result.edgesAdded,
 				generation.provenance ? JSON.stringify(generation.provenance) : null,
+				generation.sources ? JSON.stringify(generation.sources) : null,
 			);
 	}
 

package/src/cli.ts

@@ -12,6 +12,7 @@ import { serveMain } from "./daemon.ts";
 import type { JobSnapshot } from "./domain/bounded-job-executor.ts";
 import type { ContentHash } from "./domain/content-hash.ts";
 import { DEFAULT_PACKAGE_SOURCE_BOUNDS, type PackageSourceOperationResult } from "./domain/package-source.ts";
+import type { SymbolSearchResult } from "./domain/workspace-symbol.ts";
 import type { WorkspacePort } from "./ports/workspace-port.ts";
 import type { WorkspaceId } from "./service.ts";
 
@@ -130,6 +131,14 @@ async function runWorkspaceRegister(dir: string | undefined, flags: string[]): P
 	console.log(hasFlag(flags, "--json") ? JSON.stringify(result) : `${result.workspaceId} (${result.created ? "created" : "already registered"})`);
 }
 
+function formatSymbolSources(result: SymbolSearchResult): readonly string[] {
+	return (result.sources ?? []).map((source) => {
+		const identity = `${source.provenance.languageId}: ${source.status} via ${source.provenance.backend}`;
+		if (source.status === "failed") return source.error ? `${identity} [${source.error.code}] ${source.error.message}` : identity;
+		return `${identity} (${source.symbolCount} symbol${source.symbolCount === 1 ? "" : "s"}${source.truncated ? ", truncated" : ""})`;
+	});
+}
+
 async function runWorkspaceSymbols(workspaceId: string | undefined, query: string | undefined, flags: string[]): Promise<void> {
 	if (!workspaceId || !query) fail(USAGE);
 	const seedFile = flagValue(flags, "--seed-file"); // omit to auto-discover one
@@ -141,6 +150,7 @@ async function runWorkspaceSymbols(workspaceId: string | undefined, query: strin
 	}
 	const { symbols, provenance, truncated } = result;
 	console.log(`${provenance.fidelity} via ${provenance.backend}${truncated ? " (truncated)" : ""}`);
+	for (const source of formatSymbolSources(result)) console.log(source);
 	if (symbols.length === 0) {
 		console.log(`no symbols matched "${query}"`);
 		return;

package/src/domain/intelligence-provenance.ts

@@ -9,6 +9,14 @@ export interface IntelligenceProvenance {
 	readonly limitations: readonly string[];
 }
 
+export interface IntelligenceSourceOutcome {
+	readonly provenance: IntelligenceProvenance;
+	readonly status: "ready" | "failed";
+	readonly symbolCount: number;
+	readonly truncated?: boolean;
+	readonly error?: { readonly code: string; readonly message: string };
+}
+
 export interface SymbolSearchBounds {
 	readonly maxResults: number;
 }

package/src/domain/language-server-descriptor.ts

@@ -23,6 +23,8 @@ export interface LanguageServerDescriptor {
 	readonly rootMarkers: readonly string[];
 	/** Tried before the bounded directory scan when picking a file to warm the server with (e.g. a language's usual entry-point names). */
 	readonly commonSeedCandidates: readonly string[];
+	/** Excludes unsafe or unusually expensive servers from automatic workspace-wide fan-out while preserving explicit file operations. */
+	readonly workspaceDiscovery?: "enabled" | "explicit-only";
 	/** Extra textDocument/workspace capabilities this specific server gates real features behind (e.g. typescript-language-server withholds diagnostics/callHierarchy unless declared). */
 	readonly extraCapabilities?: Record<string, unknown>;
 	/** Milliseconds to wait after opening a file before trusting the server's answers -- no server signals "project loaded". Default 1000ms; rust-analyzer needs more (see RUST_DESCRIPTOR). */
@@ -101,6 +103,7 @@ export const BASH_DESCRIPTOR: LanguageServerDescriptor = {
 	languageId: "shellscript",
 	backendId: "bash-language-server",
 	extensions: [".sh", ".bash"],
+	workspaceDiscovery: "explicit-only",
 	launch: { kind: "npm-module", entryModule: "bash-language-server/out/cli.js" },
 	args: ["start"],
 	rootMarkers: [],
@@ -111,6 +114,7 @@ export const YAML_DESCRIPTOR: LanguageServerDescriptor = {
 	languageId: "yaml",
 	backendId: "yaml-language-server",
 	extensions: [".yaml", ".yml"],
+	workspaceDiscovery: "explicit-only",
 	launch: { kind: "npm-module", entryModule: "yaml-language-server/bin/yaml-language-server" },
 	args: ["--stdio"],
 	rootMarkers: [],

package/src/domain/symbol-graph-generation.ts

@@ -8,6 +8,8 @@ export interface SymbolGraphGeneration {
 	readonly completedAt: number;
 	/** Absent only for generations persisted before provenance was recorded. */
 	readonly provenance?: IntelligenceProvenance;
+	/** Per-language authorities included when provenance is polyglot. */
+	readonly sources?: readonly IntelligenceProvenance[];
 	readonly result: PopulateSymbolGraphResult;
 }
 

package/src/domain/workspace-symbol.ts

@@ -1,4 +1,4 @@
-import type { IntelligenceProvenance } from "./intelligence-provenance.ts";
+import type { IntelligenceProvenance, IntelligenceSourceOutcome } from "./intelligence-provenance.ts";
 
 /** A location within a workspace file: 1-indexed line and character, matching how humans and CLIs present positions. */
 export interface WorkspaceLocation {
@@ -13,10 +13,15 @@ export interface WorkspaceSymbol {
 	readonly kind: string;
 	readonly location: WorkspaceLocation;
 	readonly containerName?: string;
+	/** Present when a workspace-wide composite query needs to preserve which backend produced this symbol. */
+	readonly provenance?: IntelligenceProvenance;
 }
 
 export interface SymbolSearchResult {
 	readonly symbols: readonly WorkspaceSymbol[];
 	readonly truncated: boolean;
 	readonly provenance: IntelligenceProvenance;
+	/** Present for composite workspace queries; omitted for one-language adapters. */
+	readonly completeness?: "complete" | "partial";
+	readonly sources?: readonly IntelligenceSourceOutcome[];
 }

package/src/index.ts

@@ -12,7 +12,7 @@ export {
 	LanguageServerProcessExited,
 	LanguageServerRequestTimedOut,
 } from "./adapters/lsp/language-server-process.ts";
-export { LanguageFileLimitExceeded, LspSymbolIndex, type LspSymbolIndexOptions } from "./adapters/lsp/lsp-symbol-index.ts";
+export { LanguageFileLimitExceeded, LanguageFileOutsideWorkspace, LspSymbolIndex, type LspSymbolIndexOptions } from "./adapters/lsp/lsp-symbol-index.ts";
 export { InvalidInstalledPackageVersionRequest, NpmLockfileVersionResolver } from "./adapters/npm-lockfile-version-resolver.ts";
 export { NpmPackageSourceResolver, type NpmPackageSourceResolverOptions } from "./adapters/npm-package-source-resolver.ts";
 export {
@@ -26,6 +26,7 @@ export {
 	NpmRegistryResponseLimitExceeded,
 	NpmVersionNotFound,
 } from "./adapters/npm-registry-client.ts";
+export { PolyglotCodeIntelligenceIndex, type PolyglotIndexEntry } from "./adapters/polyglot-code-intelligence-index.ts";
 export { ReadOnlyWorkspace, WorkspaceIsReadOnly } from "./adapters/read-only-workspace.ts";
 export { RipgrepTextSearch } from "./adapters/ripgrep-text-search.ts";
 export { deriveSourceManifest, type SourceManifest, SourceManifestLimitExceeded } from "./adapters/source-manifest.ts";
@@ -92,7 +93,13 @@ export type {
 	ResolvedInstalledPackageVersion,
 	UnavailableInstalledPackageVersion,
 } from "./domain/installed-package-version.ts";
-export type { IntelligenceFidelity, IntelligenceProvenance, ProvenancedResult, SymbolSearchBounds } from "./domain/intelligence-provenance.ts";
+export type {
+	IntelligenceFidelity,
+	IntelligenceProvenance,
+	IntelligenceSourceOutcome,
+	ProvenancedResult,
+	SymbolSearchBounds,
+} from "./domain/intelligence-provenance.ts";
 export {
 	descriptorForExtension,
 	LANGUAGE_SERVER_DESCRIPTORS,

package/src/service.ts

@@ -6,11 +6,12 @@ import { InMemorySearchCache } from "./adapters/in-memory-search-cache.ts";
 import { InMemorySymbolGraph } from "./adapters/in-memory-symbol-graph.ts";
 import { LocalFilesystemWorkspace } from "./adapters/local-filesystem-workspace.ts";
 import { LocalGit } from "./adapters/local-git.ts";
-import { discoverWorkspaceDescriptor } from "./adapters/lsp/discover-seed-file.ts";
+import { discoverWorkspaceDescriptor, discoverWorkspaceDescriptors } from "./adapters/lsp/discover-seed-file.ts";
 import { LspSymbolIndex } from "./adapters/lsp/lsp-symbol-index.ts";
 import { NpmLockfileVersionResolver } from "./adapters/npm-lockfile-version-resolver.ts";
 import { NpmPackageSourceResolver } from "./adapters/npm-package-source-resolver.ts";
 import { NpmRegistryClient } from "./adapters/npm-registry-client.ts";
+import { PolyglotCodeIntelligenceIndex } from "./adapters/polyglot-code-intelligence-index.ts";
 import { ReadOnlyWorkspace } from "./adapters/read-only-workspace.ts";
 import { RipgrepTextSearch } from "./adapters/ripgrep-text-search.ts";
 import { deriveSourceManifest } from "./adapters/source-manifest.ts";
@@ -408,7 +409,7 @@ function resolveWorkspace(registry: MutableRegistry, workspaceId: WorkspaceId):
 
 /** True when a warm SymbolIndexPort is also a real CodeIntelligencePort (currently: any LspSymbolIndex, never TreeSitterSymbolIndex). */
 function supportsCodeIntelligence(index: SymbolIndexPort): index is SymbolIndexPort & CodeIntelligencePort {
-	return typeof (index as Partial<CodeIntelligencePort>).goToDefinition === "function";
+	return "goToDefinition" in index && typeof index.goToDefinition === "function";
 }
 
 type OperationHandlers = {
@@ -677,6 +678,18 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 		return { descriptor: discovered.descriptor, seedFile: discovered.seedFile };
 	}
 
+	function ensureLanguageIndex(workspaceId: WorkspaceId, rootPath: string, descriptor: LanguageServerDescriptor, seedFile?: string): ClosableSymbolIndex {
+		const key = symbolIndexKey(workspaceId, descriptor.languageId);
+		let entryIndex = symbolIndexes.get(key);
+		if (!entryIndex) {
+			entryIndex = { index: createSymbolIndex(rootPath, descriptor, seedFile), workspaceId, lastUsedAt: Date.now() };
+			symbolIndexes.set(key, entryIndex);
+		} else {
+			entryIndex.lastUsedAt = Date.now();
+		}
+		return entryIndex.index;
+	}
+
 	async function ensureWarmIndex(input: {
 		workspaceId: WorkspaceId;
 		path?: string;
@@ -685,18 +698,45 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 		const entry = registry.get(input.workspaceId);
 		if (!entry) throw new UnknownWorkspace(input.workspaceId);
 		if (!entry.rootPath) throw new SymbolQueryUnavailable(input.workspaceId);
-		const rootPath = entry.rootPath;
+		const { descriptor, seedFile } = resolveDescriptor(entry.rootPath, input);
+		return { index: ensureLanguageIndex(input.workspaceId, entry.rootPath, descriptor, seedFile), descriptor };
+	}
 
-		const { descriptor, seedFile } = resolveDescriptor(rootPath, input);
-		const key = symbolIndexKey(input.workspaceId, descriptor.languageId);
-		let entryIndex = symbolIndexes.get(key);
-		if (!entryIndex) {
-			entryIndex = { index: createSymbolIndex(rootPath, descriptor, seedFile), workspaceId: input.workspaceId, lastUsedAt: Date.now() };
-			symbolIndexes.set(key, entryIndex);
+	function ensureWorkspaceIndex(
+		workspaceId: WorkspaceId,
+		preferredSeedFile?: string,
+	): {
+		index: SymbolIndexPort;
+		descriptors: readonly LanguageServerDescriptor[];
+		sources: readonly IntelligenceProvenance[];
+	} {
+		const entry = registry.get(workspaceId);
+		if (!entry) throw new UnknownWorkspace(workspaceId);
+		if (!entry.rootPath) throw new SymbolQueryUnavailable(workspaceId);
+		const rootPath = entry.rootPath;
+		const preferredDescriptor = preferredSeedFile ? descriptorForPath(preferredSeedFile) : undefined;
+		if (preferredSeedFile && !preferredDescriptor) throw new UnsupportedLanguage(preferredSeedFile);
+		const discovered = [...discoverWorkspaceDescriptors(rootPath, LANGUAGE_SERVER_DESCRIPTORS)];
+		if (preferredDescriptor && preferredSeedFile && !discovered.some(({ descriptor }) => descriptor.languageId === preferredDescriptor.languageId)) {
+			discovered.push({ descriptor: preferredDescriptor, seedFile: preferredSeedFile });
+		}
+		if (discovered.length === 0) throw new UnsupportedLanguage(rootPath);
+		const indexes = discovered.map(({ descriptor, seedFile }) => ({
+			descriptor,
+			index: ensureLanguageIndex(workspaceId, rootPath, descriptor, preferredDescriptor?.languageId === descriptor.languageId ? preferredSeedFile : seedFile),
+		}));
+		const first = indexes[0];
+		let index: SymbolIndexPort;
+		if (indexes.length === 1 && first) {
+			index = first.index;
 		} else {
-			entryIndex.lastUsedAt = Date.now();
+			index = new PolyglotCodeIntelligenceIndex(indexes);
 		}
-		return { index: entryIndex.index, descriptor };
+		return { index, descriptors: discovered.map(({ descriptor }) => descriptor), sources: indexes.map(({ index: source }) => source.provenance) };
+	}
+
+	function workspaceSourceExtensions(descriptors: readonly LanguageServerDescriptor[]): readonly string[] {
+		return Array.from(new Set(descriptors.flatMap((descriptor) => descriptor.extensions)));
 	}
 
 	/** Never spawns -- a caller deciding whether to enrich a result with LSP-backed info must not pay a cold-start cost just to check. With a path, checks that file's own language; without one, whether anything is warm for the workspace at all. */
@@ -723,7 +763,7 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 		if (!Number.isSafeInteger(maxResults) || maxResults < 1 || maxResults > MAX_SYMBOL_RESULTS) {
 			throw new TypeError(`maxResults must be a positive safe integer no greater than ${MAX_SYMBOL_RESULTS}`);
 		}
-		const { index } = await ensureWarmIndex(input);
+		const { index } = ensureWorkspaceIndex(input.workspaceId, input.seedFile);
 		return findWorkspaceSymbols(index, input.query, { maxResults });
 	}
 
@@ -819,21 +859,24 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 		_registry: MutableRegistry,
 		input: OperationInputs["workspace.populateSymbolGraph"],
 	): Promise<OperationOutputs["workspace.populateSymbolGraph"]> {
-		const { index, descriptor } = await requireCodeIntelligence(input);
+		const workspaceIndex = ensureWorkspaceIndex(input.workspaceId);
+		if (!supportsCodeIntelligence(workspaceIndex.index)) throw new CodeIntelligenceUnavailable(input.workspaceId);
 		const entry = registry.get(input.workspaceId);
 		if (!entry?.rootPath) throw new SymbolQueryUnavailable(input.workspaceId);
 		const rootPath = entry.rootPath;
-		const before = await deriveSourceManifest(rootPath, descriptor.extensions, input.maxFiles, MAX_SOURCE_MANIFEST_BYTES);
+		const extensions = workspaceSourceExtensions(workspaceIndex.descriptors);
+		const before = await deriveSourceManifest(rootPath, extensions, input.maxFiles, MAX_SOURCE_MANIFEST_BYTES);
 		const graph = ensureSymbolGraph(input.workspaceId);
-		const result = await populateSymbolGraphQuery(index, graph, before.absoluteFiles, input.maxSymbolsPerFile);
-		const after = await deriveSourceManifest(rootPath, descriptor.extensions, input.maxFiles, MAX_SOURCE_MANIFEST_BYTES);
+		const result = await populateSymbolGraphQuery(workspaceIndex.index, graph, before.absoluteFiles, input.maxSymbolsPerFile);
+		const after = await deriveSourceManifest(rootPath, extensions, input.maxFiles, MAX_SOURCE_MANIFEST_BYTES);
 		if (after.fingerprint !== before.fingerprint) throw new WorkspaceChangedDuringPopulation(input.workspaceId);
 		await graph.setGeneration({
 			sourceFingerprint: after.fingerprint,
 			maxFiles: input.maxFiles,
 			maxSymbolsPerFile: input.maxSymbolsPerFile,
 			completedAt: Date.now(),
-			provenance: index.provenance,
+			provenance: workspaceIndex.index.provenance,
+			sources: workspaceIndex.sources,
 			result,
 		});
 		return result;
@@ -858,10 +901,12 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 		if (generation.maxFiles !== input.maxFiles || generation.maxSymbolsPerFile !== input.maxSymbolsPerFile) {
 			return { status: "not-cached", reason: "bounds-changed" };
 		}
-		const { descriptor } = resolveDescriptor(entry.rootPath, {});
+		const discovered = discoverWorkspaceDescriptors(entry.rootPath, LANGUAGE_SERVER_DESCRIPTORS);
+		if (discovered.length === 0) return { status: "not-cached", reason: "source-changed" };
+		const extensions = workspaceSourceExtensions(discovered.map(({ descriptor }) => descriptor));
 		let currentFingerprint: string;
 		try {
-			currentFingerprint = (await deriveSourceManifest(entry.rootPath, descriptor.extensions, input.maxFiles, MAX_SOURCE_MANIFEST_BYTES)).fingerprint;
+			currentFingerprint = (await deriveSourceManifest(entry.rootPath, extensions, input.maxFiles, MAX_SOURCE_MANIFEST_BYTES)).fingerprint;
 		} catch {
 			return { status: "not-cached", reason: "source-changed" };
 		}