@danypops/lector 0.1.7 → 0.1.8

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

@@ -1,5 +1,6 @@
 import type { Database } from "bun:sqlite";
 import { type Migration, openSqliteWithPragmas } from "@danypops/daemon-kit/storage";
+import type { IntelligenceProvenance } from "../domain/intelligence-provenance.ts";
 import type { SymbolGraphGeneration } from "../domain/symbol-graph-generation.ts";
 import type { SymbolNodeId } from "../domain/symbol-node-id.ts";
 import type { SymbolEdgeKind, SymbolGraphPort, SymbolNode } from "../ports/symbol-graph-port.ts";
@@ -23,6 +24,10 @@ const MIGRATIONS: Migration[] = [
 			);
 		},
 	},
+	{
+		version: 3,
+		up: (db) => db.exec("ALTER TABLE symbol_graph_generation ADD COLUMN provenance_json TEXT"),
+	},
 ];
 
 interface NodeRow {
@@ -42,6 +47,42 @@ interface GenerationRow {
 	symbols_processed: number;
 	nodes_added: number;
 	edges_added: number;
+	provenance_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;
+	}
+	if (!isRecord(value)) return undefined;
+	const candidate = value;
+	if (
+		(candidate.fidelity !== "semantic" && candidate.fidelity !== "structural") ||
+		typeof candidate.backend !== "string" ||
+		typeof candidate.languageId !== "string" ||
+		(candidate.authority !== "language-server" && candidate.authority !== "parser" && candidate.authority !== "compiler") ||
+		(candidate.freshness !== "live-process" && candidate.freshness !== "content-hash" && candidate.freshness !== "filesystem-snapshot") ||
+		!Array.isArray(candidate.limitations) ||
+		!candidate.limitations.every((item) => typeof item === "string")
+	) {
+		return undefined;
+	}
+	return {
+		fidelity: candidate.fidelity,
+		backend: candidate.backend,
+		languageId: candidate.languageId,
+		authority: candidate.authority,
+		freshness: candidate.freshness,
+		limitations: candidate.limitations,
+	};
 }
 
 /**
@@ -105,7 +146,7 @@ export class SqliteSymbolGraph implements SymbolGraphPort {
 			SELECT DISTINCT id FROM reachable
 		`;
 		const params: Record<string, string | number> = { $id: id, $maxDepth: options.maxDepth };
-		if (options.kind) params["$kind"] = options.kind;
+		if (options.kind) params.$kind = options.kind;
 		const rows = this.db.query(sql).all(params) as { id: string }[];
 		return rows.map((row) => row.id).filter((reachedId) => reachedId !== id);
 	}
@@ -113,15 +154,17 @@ 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 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 FROM symbol_graph_generation WHERE singleton = 1",
 			)
 			.get() as GenerationRow | null;
 		if (!row) return undefined;
+		const provenance = parseProvenance(row.provenance_json);
 		return {
 			sourceFingerprint: row.source_fingerprint,
 			maxFiles: row.max_files,
 			maxSymbolsPerFile: row.max_symbols_per_file,
 			completedAt: row.completed_at,
+			...(provenance ? { provenance } : {}),
 			result: {
 				filesProcessed: row.files_processed,
 				symbolsProcessed: row.symbols_processed,
@@ -134,7 +177,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) 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",
+				"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",
 			)
 			.run(
 				generation.sourceFingerprint,
@@ -145,6 +188,7 @@ export class SqliteSymbolGraph implements SymbolGraphPort {
 				generation.result.symbolsProcessed,
 				generation.result.nodesAdded,
 				generation.result.edgesAdded,
+				generation.provenance ? JSON.stringify(generation.provenance) : null,
 			);
 	}
 

package/src/adapters/tree-sitter/typescript-tree-sitter-symbol-index.ts

@@ -1,15 +1,32 @@
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { extname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import Parser from "web-tree-sitter";
 import { contentHashOf } from "../../domain/content-hash.ts";
-import type { WorkspaceSymbol } from "../../domain/workspace-symbol.ts";
+import type { IntelligenceProvenance, SymbolSearchBounds } from "../../domain/intelligence-provenance.ts";
+import type { SymbolSearchResult, WorkspaceSymbol } from "../../domain/workspace-symbol.ts";
 import type { ContentCachePort, ContentSymbol } from "../../ports/content-cache-port.ts";
 import type { SymbolIndexPort } from "../../ports/symbol-index-port.ts";
 import { findSourceFiles } from "../find-source-files.ts";
 import { InMemoryContentCache } from "../in-memory-content-cache.ts";
 
-const MAX_FILES_SCANNED = 5_000;
+const DEFAULT_MAX_FILES = 5_000;
+const DEFAULT_MAX_FILE_BYTES = 2 * 1024 * 1024;
+const DEFAULT_MAX_TOTAL_BYTES = 50 * 1024 * 1024;
+const DEFAULT_MAX_RESULTS = 1_000;
+
+export interface TreeSitterSymbolIndexOptions {
+	readonly maxFiles?: number;
+	readonly maxFileBytes?: number;
+	readonly maxTotalBytes?: number;
+	readonly maxResults?: number;
+}
+
+function positiveLimit(value: number | undefined, fallback: number, field: string): number {
+	const result = value ?? fallback;
+	if (!Number.isSafeInteger(result) || result < 1) throw new TypeError(`${field} must be a positive safe integer`);
+	return result;
+}
 
 interface DeclarationKind {
 	readonly nodeType: string;
@@ -86,13 +103,29 @@ function toWorkspaceSymbols(symbols: readonly ContentSymbol[], relativePath: str
  * read to compute it.
  */
 export class TreeSitterSymbolIndex implements SymbolIndexPort {
+	readonly provenance: IntelligenceProvenance = {
+		fidelity: "structural",
+		backend: "tree-sitter-typescript-javascript",
+		languageId: "typescript-javascript",
+		authority: "parser",
+		freshness: "content-hash",
+		limitations: ["no cross-file identity", "no type information", "syntax recovery may include malformed declarations"],
+	};
 	private readonly rootPath: string;
 	private readonly contentCache: ContentCachePort;
+	private readonly maxFiles: number;
+	private readonly maxFileBytes: number;
+	private readonly maxTotalBytes: number;
+	private readonly maxResults: number;
 	private readonly parsersByWasmPath = new Map<string, Parser>();
 
-	constructor(rootPath: string, contentCache: ContentCachePort = new InMemoryContentCache()) {
+	constructor(rootPath: string, contentCache: ContentCachePort = new InMemoryContentCache(), options: TreeSitterSymbolIndexOptions = {}) {
 		this.rootPath = rootPath;
 		this.contentCache = contentCache;
+		this.maxFiles = positiveLimit(options.maxFiles, DEFAULT_MAX_FILES, "maxFiles");
+		this.maxFileBytes = positiveLimit(options.maxFileBytes, DEFAULT_MAX_FILE_BYTES, "maxFileBytes");
+		this.maxTotalBytes = positiveLimit(options.maxTotalBytes, DEFAULT_MAX_TOTAL_BYTES, "maxTotalBytes");
+		this.maxResults = positiveLimit(options.maxResults, DEFAULT_MAX_RESULTS, "maxResults");
 	}
 
 	private async parserFor(wasmPath: string): Promise<Parser> {
@@ -106,7 +139,7 @@ export class TreeSitterSymbolIndex implements SymbolIndexPort {
 		return parser;
 	}
 
-	private async contentSymbolsFor(relativePath: string, wasmPath: string, content: string): Promise<ContentSymbol[]> {
+	private async contentSymbolsFor(wasmPath: string, content: string): Promise<ContentSymbol[]> {
 		const hash = contentHashOf(content);
 
 		// Reading the file already required reading its content -- warm the fs lens for this
@@ -125,28 +158,45 @@ export class TreeSitterSymbolIndex implements SymbolIndexPort {
 		return symbols;
 	}
 
-	async findSymbols(query: string): Promise<WorkspaceSymbol[]> {
+	async findSymbols(query: string, bounds: SymbolSearchBounds = { maxResults: this.maxResults }): Promise<SymbolSearchResult> {
+		const maxResults = Math.min(positiveLimit(bounds.maxResults, this.maxResults, "maxResults"), this.maxResults);
 		const lowerQuery = query.toLowerCase();
 		const results: WorkspaceSymbol[] = [];
+		const files = findSourceFiles(this.rootPath, (extension) => wasmPathFor(extension) !== undefined, this.maxFiles);
+		let totalBytes = 0;
+		let truncated = files.length === this.maxFiles;
 
-		for (const relativePath of findSourceFiles(this.rootPath, (extension) => wasmPathFor(extension) !== undefined, MAX_FILES_SCANNED)) {
+		for (const relativePath of files) {
 			const wasmPath = wasmPathFor(extname(relativePath));
 			if (!wasmPath) continue;
 
 			let content: string;
 			try {
-				content = readFileSync(join(this.rootPath, relativePath), "utf-8");
+				const absolutePath = join(this.rootPath, relativePath);
+				const size = statSync(absolutePath).size;
+				if (size > this.maxFileBytes || totalBytes + size > this.maxTotalBytes) {
+					truncated = true;
+					continue;
+				}
+				totalBytes += size;
+				content = readFileSync(absolutePath, "utf-8");
 			} catch {
 				continue;
 			}
 
-			const contentSymbols = await this.contentSymbolsFor(relativePath, wasmPath, content);
+			const contentSymbols = await this.contentSymbolsFor(wasmPath, content);
 			for (const symbol of toWorkspaceSymbols(contentSymbols, relativePath)) {
-				if (symbol.name.toLowerCase().includes(lowerQuery)) results.push(symbol);
+				if (!symbol.name.toLowerCase().includes(lowerQuery)) continue;
+				if (results.length === maxResults) {
+					truncated = true;
+					break;
+				}
+				results.push(symbol);
 			}
+			if (results.length === maxResults) break;
 		}
 
-		return results;
+		return { symbols: results, truncated, provenance: this.provenance };
 	}
 
 	async close(): Promise<void> {

package/src/adapters/typescript-compiler-symbol-index.ts

@@ -0,0 +1,129 @@
+import { readFileSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+import ts from "typescript";
+import type { IntelligenceProvenance, SymbolSearchBounds } from "../domain/intelligence-provenance.ts";
+import type { SymbolSearchResult, WorkspaceSymbol } from "../domain/workspace-symbol.ts";
+import type { SymbolIndexPort } from "../ports/symbol-index-port.ts";
+import { findSourceFiles } from "./find-source-files.ts";
+
+const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
+
+export interface TypeScriptCompilerSymbolIndexOptions {
+	readonly maxFiles?: number;
+	readonly maxFileBytes?: number;
+	readonly maxTotalBytes?: number;
+	readonly maxResults?: number;
+	readonly maxNodesPerFile?: number;
+}
+
+function positiveLimit(value: number | undefined, fallback: number, field: string): number {
+	const result = value ?? fallback;
+	if (!Number.isSafeInteger(result) || result < 1) throw new TypeError(`${field} must be a positive safe integer`);
+	return result;
+}
+
+function scriptKind(path: string): ts.ScriptKind {
+	switch (extname(path)) {
+		case ".tsx":
+			return ts.ScriptKind.TSX;
+		case ".jsx":
+			return ts.ScriptKind.JSX;
+		case ".js":
+		case ".mjs":
+		case ".cjs":
+			return ts.ScriptKind.JS;
+		default:
+			return ts.ScriptKind.TS;
+	}
+}
+
+function declaration(node: ts.Node): { name: ts.Node; kind: string } | undefined {
+	if (ts.isFunctionDeclaration(node) && node.name) return { name: node.name, kind: "function" };
+	if (ts.isClassDeclaration(node) && node.name) return { name: node.name, kind: "class" };
+	if (ts.isInterfaceDeclaration(node)) return { name: node.name, kind: "interface" };
+	if (ts.isTypeAliasDeclaration(node)) return { name: node.name, kind: "type-alias" };
+	if (ts.isEnumDeclaration(node)) return { name: node.name, kind: "enum" };
+	if (ts.isMethodDeclaration(node)) return { name: node.name, kind: "method" };
+	if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) return { name: node.name, kind: "variable" };
+	return undefined;
+}
+
+export class TypeScriptCompilerSymbolIndex implements SymbolIndexPort {
+	readonly provenance: IntelligenceProvenance = {
+		fidelity: "structural",
+		backend: "typescript-compiler",
+		languageId: "typescript-javascript",
+		authority: "compiler",
+		freshness: "filesystem-snapshot",
+		limitations: ["syntax declarations only", "no cross-file identity", "no language-server project state"],
+	};
+	private readonly maxFiles: number;
+	private readonly maxFileBytes: number;
+	private readonly maxTotalBytes: number;
+	private readonly maxResults: number;
+	private readonly maxNodesPerFile: number;
+
+	constructor(
+		private readonly rootPath: string,
+		options: TypeScriptCompilerSymbolIndexOptions = {},
+	) {
+		this.maxFiles = positiveLimit(options.maxFiles, 5_000, "maxFiles");
+		this.maxFileBytes = positiveLimit(options.maxFileBytes, 2 * 1024 * 1024, "maxFileBytes");
+		this.maxTotalBytes = positiveLimit(options.maxTotalBytes, 50 * 1024 * 1024, "maxTotalBytes");
+		this.maxResults = positiveLimit(options.maxResults, 1_000, "maxResults");
+		this.maxNodesPerFile = positiveLimit(options.maxNodesPerFile, 100_000, "maxNodesPerFile");
+	}
+
+	findSymbols(query: string, bounds: SymbolSearchBounds = { maxResults: this.maxResults }): Promise<SymbolSearchResult> {
+		const maxResults = Math.min(positiveLimit(bounds.maxResults, this.maxResults, "maxResults"), this.maxResults);
+		const files = findSourceFiles(this.rootPath, (extension) => SOURCE_EXTENSIONS.has(extension), this.maxFiles);
+		const symbols: WorkspaceSymbol[] = [];
+		const lowerQuery = query.toLowerCase();
+		let totalBytes = 0;
+		let truncated = files.length === this.maxFiles;
+
+		for (const relativePath of files) {
+			const absolutePath = join(this.rootPath, relativePath);
+			let sourceText: string;
+			try {
+				const size = statSync(absolutePath).size;
+				if (size > this.maxFileBytes || totalBytes + size > this.maxTotalBytes) {
+					truncated = true;
+					continue;
+				}
+				totalBytes += size;
+				sourceText = readFileSync(absolutePath, "utf-8");
+			} catch {
+				continue;
+			}
+
+			const sourceFile = ts.createSourceFile(relativePath, sourceText, ts.ScriptTarget.Latest, true, scriptKind(relativePath));
+			let visited = 0;
+			const visit = (node: ts.Node): void => {
+				if (visited++ >= this.maxNodesPerFile || symbols.length >= maxResults) {
+					truncated = true;
+					return;
+				}
+				const found = declaration(node);
+				if (found) {
+					const name = found.name.getText(sourceFile);
+					if (name.toLowerCase().includes(lowerQuery)) {
+						const position = sourceFile.getLineAndCharacterOfPosition(found.name.getStart(sourceFile));
+						symbols.push({ name, kind: found.kind, location: { path: relativePath, line: position.line + 1, character: position.character + 1 } });
+					}
+				}
+				if (visited < this.maxNodesPerFile && symbols.length < maxResults) ts.forEachChild(node, visit);
+				else if (node.getChildCount(sourceFile) > 0) truncated = true;
+			};
+			visit(sourceFile);
+			if (symbols.length >= maxResults) {
+				truncated = true;
+				break;
+			}
+		}
+
+		return Promise.resolve({ symbols, truncated, provenance: this.provenance });
+	}
+
+	async close(): Promise<void> {}
+}

package/src/cli.ts

@@ -2,7 +2,7 @@
 import { execFileSync } from "node:child_process";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { InMemoryWorkspace } from "./adapters/in-memory-workspace.ts";
 import { LocalFilesystemWorkspace } from "./adapters/local-filesystem-workspace.ts";
@@ -11,6 +11,7 @@ import { LECTOR_PATH_NAMES } from "./constants.ts";
 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 { WorkspacePort } from "./ports/workspace-port.ts";
 import type { WorkspaceId } from "./service.ts";
 
@@ -51,6 +52,8 @@ const USAGE = `Usage:
   lector workspace git-diff <workspace-id> [--ref <ref>] --max-bytes <n> [--json]
   lector workspace repo-fetch <owner>/<repo>[@ref] [--host <host>] [--json]
     shallow-clones an external repo into a disk-bounded cache and registers it read-only
+  lector package source <project-dir> <package-name> [--version <exact-version>] [--registry <url>] [--json]
+    resolves an installed npm package to verified exact repository source and registers it read-only
   lector workspace search-text <workspace-id> <query> --max-matches <n> --max-bytes <n> [--json]
   lector search symbols <query> [--workspace <id>]... [--timeout-ms <n>] [--json]
   lector search text <query> --max-matches <n> --max-bytes <n> [--workspace <id>]... [--timeout-ms <n>] [--json]
@@ -131,11 +134,13 @@ async function runWorkspaceSymbols(workspaceId: string | undefined, query: strin
 	if (!workspaceId || !query) fail(USAGE);
 	const seedFile = flagValue(flags, "--seed-file"); // omit to auto-discover one
 	const client = await connectLectorClient();
-	const { symbols } = await client.call("workspace.findSymbols", { workspaceId, query, seedFile });
+	const result = await client.call("workspace.findSymbols", { workspaceId, query, seedFile });
 	if (hasFlag(flags, "--json")) {
-		console.log(JSON.stringify(symbols));
+		console.log(JSON.stringify(result));
 		return;
 	}
+	const { symbols, provenance, truncated } = result;
+	console.log(`${provenance.fidelity} via ${provenance.backend}${truncated ? " (truncated)" : ""}`);
 	if (symbols.length === 0) {
 		console.log(`no symbols matched "${query}"`);
 		return;
@@ -154,16 +159,22 @@ function parsePosition(line: string | undefined, character: string | undefined):
 	return { line: parsedLine, character: parsedCharacter };
 }
 
+function formatIntelligenceSource(provenance: { fidelity: string; backend: string }): string {
+	return `${provenance.fidelity} via ${provenance.backend}`;
+}
+
 async function runWorkspaceDefinition(workspaceId: string | undefined, path: string | undefined, rest: string[]): Promise<void> {
 	if (!workspaceId || !path) fail(USAGE);
 	const [lineArg, characterArg, ...flags] = rest;
 	const { line, character } = parsePosition(lineArg, characterArg);
 	const client = await connectLectorClient();
-	const { locations } = await client.call("workspace.goToDefinition", { workspaceId, path, line, character });
+	const result = await client.call("workspace.goToDefinition", { workspaceId, path, line, character });
 	if (hasFlag(flags, "--json")) {
-		console.log(JSON.stringify(locations));
+		console.log(JSON.stringify(result));
 		return;
 	}
+	const { locations, provenance } = result;
+	console.log(formatIntelligenceSource(provenance));
 	if (locations.length === 0) {
 		console.log("no definition found");
 		return;
@@ -176,11 +187,13 @@ async function runWorkspaceImplementation(workspaceId: string | undefined, path:
 	const [lineArg, characterArg, ...flags] = rest;
 	const { line, character } = parsePosition(lineArg, characterArg);
 	const client = await connectLectorClient();
-	const { locations } = await client.call("workspace.goToImplementation", { workspaceId, path, line, character });
+	const result = await client.call("workspace.goToImplementation", { workspaceId, path, line, character });
 	if (hasFlag(flags, "--json")) {
-		console.log(JSON.stringify(locations));
+		console.log(JSON.stringify(result));
 		return;
 	}
+	const { locations, provenance } = result;
+	console.log(formatIntelligenceSource(provenance));
 	if (locations.length === 0) {
 		console.log("no implementation found");
 		return;
@@ -194,11 +207,13 @@ async function runWorkspaceReferences(workspaceId: string | undefined, path: str
 	const { line, character } = parsePosition(lineArg, characterArg);
 	const includeDeclaration = hasFlag(flags, "--include-declaration");
 	const client = await connectLectorClient();
-	const { locations } = await client.call("workspace.findReferences", { workspaceId, path, line, character, includeDeclaration });
+	const result = await client.call("workspace.findReferences", { workspaceId, path, line, character, includeDeclaration });
 	if (hasFlag(flags, "--json")) {
-		console.log(JSON.stringify(locations));
+		console.log(JSON.stringify(result));
 		return;
 	}
+	const { locations, provenance } = result;
+	console.log(formatIntelligenceSource(provenance));
 	if (locations.length === 0) {
 		console.log("no references found");
 		return;
@@ -211,22 +226,25 @@ async function runWorkspaceHover(workspaceId: string | undefined, path: string |
 	const [lineArg, characterArg, ...flags] = rest;
 	const { line, character } = parsePosition(lineArg, characterArg);
 	const client = await connectLectorClient();
-	const { hover } = await client.call("workspace.hover", { workspaceId, path, line, character });
+	const result = await client.call("workspace.hover", { workspaceId, path, line, character });
 	if (hasFlag(flags, "--json")) {
-		console.log(JSON.stringify(hover ?? null));
+		console.log(JSON.stringify(result));
 		return;
 	}
-	console.log(hover ? hover.contents : "no hover information available");
+	console.log(formatIntelligenceSource(result.provenance));
+	console.log(result.hover ? result.hover.contents : "no hover information available");
 }
 
 async function runWorkspaceDocumentSymbols(workspaceId: string | undefined, path: string | undefined, flags: string[]): Promise<void> {
 	if (!workspaceId || !path) fail(USAGE);
 	const client = await connectLectorClient();
-	const { symbols } = await client.call("workspace.documentSymbols", { workspaceId, path });
+	const result = await client.call("workspace.documentSymbols", { workspaceId, path });
 	if (hasFlag(flags, "--json")) {
-		console.log(JSON.stringify(symbols));
+		console.log(JSON.stringify(result));
 		return;
 	}
+	const { symbols, provenance } = result;
+	console.log(formatIntelligenceSource(provenance));
 	if (symbols.length === 0) {
 		console.log("no symbols found");
 		return;
@@ -241,11 +259,13 @@ async function runWorkspaceDocumentSymbols(workspaceId: string | undefined, path
 async function runWorkspaceDiagnostics(workspaceId: string | undefined, path: string | undefined, flags: string[]): Promise<void> {
 	if (!workspaceId || !path) fail(USAGE);
 	const client = await connectLectorClient();
-	const { diagnostics } = await client.call("workspace.diagnostics", { workspaceId, path });
+	const result = await client.call("workspace.diagnostics", { workspaceId, path });
 	if (hasFlag(flags, "--json")) {
-		console.log(JSON.stringify(diagnostics));
+		console.log(JSON.stringify(result));
 		return;
 	}
+	const { diagnostics, provenance } = result;
+	console.log(formatIntelligenceSource(provenance));
 	if (diagnostics.length === 0) {
 		console.log("no diagnostics");
 		return;
@@ -273,11 +293,13 @@ async function runWorkspaceCallHierarchy(
 	const client = await connectLectorClient();
 
 	if (subcommand === "prepare") {
-		const { items } = await client.call("workspace.prepareCallHierarchy", { workspaceId, path, line, character });
+		const result = await client.call("workspace.prepareCallHierarchy", { workspaceId, path, line, character });
 		if (hasFlag(flags, "--json")) {
-			console.log(JSON.stringify(items));
+			console.log(JSON.stringify(result));
 			return;
 		}
+		const { items, provenance } = result;
+		console.log(formatIntelligenceSource(provenance));
 		if (items.length === 0) {
 			console.log("no call-hierarchy root at this position");
 			return;
@@ -286,11 +308,13 @@ async function runWorkspaceCallHierarchy(
 		return;
 	}
 	if (subcommand === "incoming") {
-		const { calls } = await client.call("workspace.incomingCalls", { workspaceId, path, line, character });
+		const result = await client.call("workspace.incomingCalls", { workspaceId, path, line, character });
 		if (hasFlag(flags, "--json")) {
-			console.log(JSON.stringify(calls));
+			console.log(JSON.stringify(result));
 			return;
 		}
+		const { calls, provenance } = result;
+		console.log(formatIntelligenceSource(provenance));
 		if (calls.length === 0) {
 			console.log("no incoming calls found");
 			return;
@@ -299,11 +323,13 @@ async function runWorkspaceCallHierarchy(
 		return;
 	}
 	if (subcommand === "outgoing") {
-		const { calls } = await client.call("workspace.outgoingCalls", { workspaceId, path, line, character });
+		const result = await client.call("workspace.outgoingCalls", { workspaceId, path, line, character });
 		if (hasFlag(flags, "--json")) {
-			console.log(JSON.stringify(calls));
+			console.log(JSON.stringify(result));
 			return;
 		}
+		const { calls, provenance } = result;
+		console.log(formatIntelligenceSource(provenance));
 		if (calls.length === 0) {
 			console.log("no outgoing calls found");
 			return;
@@ -454,6 +480,38 @@ async function runWorkspaceRepoFetch(spec: string | undefined, flags: string[]):
 	if (result.refFallbackOccurred) console.log(`note: requested ref not found, fell back to the default branch (resolved: ${result.resolvedRef})`);
 }
 
+function formatPackageSourceResult(result: PackageSourceOperationResult): string {
+	const { outcome } = result;
+	if (outcome.status === "verified") {
+		return `${result.workspaceId ?? "unregistered"} ${outcome.coordinate.name}@${outcome.coordinate.resolvedVersion} -- ${outcome.workspace.cachePath}\n${outcome.repository.url ?? "local source"}@${outcome.repository.resolvedRef ?? "local"} ${outcome.repository.commit ?? outcome.verification.integrity}`;
+	}
+	if (outcome.status === "ambiguous") {
+		return `ambiguous [${outcome.code}] -- ${outcome.candidates.map((candidate) => `${candidate.version} (${candidate.source})`).join(", ")}${outcome.truncated ? ", …" : ""}`;
+	}
+	if (outcome.status === "unauthenticated") return `unauthenticated [${outcome.code}] -- configure ${outcome.requiredCredentialNames.join(", ")}`;
+	if (outcome.status === "oversized") return `oversized [${outcome.code}] -- ${outcome.resource} exceeded ${outcome.limit}`;
+	if (outcome.status === "mismatched") return `mismatched [${outcome.code}] -- expected ${outcome.expected}, got ${outcome.actual}`;
+	return `unavailable [${outcome.code}]`;
+}
+
+async function runPackageSource(projectDir: string | undefined, packageName: string | undefined, flags: string[]): Promise<void> {
+	if (!projectDir || !packageName) fail(USAGE);
+	const client = await connectLectorClient();
+	const result = await client.call("package.resolveSource", {
+		request: {
+			projectRoot: resolve(projectDir),
+			coordinate: {
+				ecosystem: "npm",
+				registry: flagValue(flags, "--registry") ?? null,
+				name: packageName,
+				requestedVersion: flagValue(flags, "--version") ?? null,
+			},
+		},
+		bounds: DEFAULT_PACKAGE_SOURCE_BOUNDS,
+	});
+	console.log(hasFlag(flags, "--json") ? JSON.stringify(result) : formatPackageSourceResult(result));
+}
+
 async function runWorkspaceSearchText(workspaceId: string | undefined, query: string | undefined, flags: string[]): Promise<void> {
 	if (!workspaceId || !query) fail(USAGE);
 	const maxMatches = requiredIntFlag(flags, "--max-matches");
@@ -655,7 +713,7 @@ WantedBy=default.target
 }
 
 function unitPath(): string {
-	const configHome = process.env["XDG_CONFIG_HOME"] ?? join(homedir(), ".config");
+	const configHome = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
 	return join(configHome, "systemd", "user", LECTOR_PATH_NAMES.systemdUnitName);
 }
 
@@ -713,6 +771,12 @@ async function main(): Promise<void> {
 		fail(USAGE);
 	}
 
+	if (command === "package") {
+		const [action, projectDir, packageName, ...packageFlags] = rest;
+		if (action === "source") return runPackageSource(projectDir, packageName, packageFlags);
+		fail(USAGE);
+	}
+
 	if (command === "workspace") {
 		const [action, ...actionArgs] = rest;
 		if (action === "register") {

package/src/daemon.ts

@@ -9,6 +9,7 @@ import { SqliteSearchCache } from "./adapters/sqlite-search-cache.ts";
 import { SqliteSymbolGraph } from "./adapters/sqlite-symbol-graph.ts";
 import { TieredSearchCache } from "./adapters/tiered-search-cache.ts";
 import { resolveLectorPaths } from "./constants.ts";
+import type { PackageSourceResolverPort } from "./ports/package-source-resolver-port.ts";
 import type { RepoFetcherPort } from "./ports/repo-fetcher-port.ts";
 import type { WorkspacePort } from "./ports/workspace-port.ts";
 import { createLectorService, type LectorService, type OperationName, type WorkspaceId } from "./service.ts";
@@ -84,6 +85,8 @@ export interface LectorDaemonOptions {
 	symbolIndexReapIntervalMs?: number;
 	/** Override the repo.fetch backend (tests inject a GitRepoFetcher pointed at a local fixture repo, avoiding live network). Defaults to a real GitRepoFetcher under this daemon's own data directory. */
 	createRepoFetcher?: () => RepoFetcherPort;
+	/** Override package source resolution while retaining the authenticated daemon/client seam. */
+	createPackageSourceResolver?: () => PackageSourceResolverPort;
 }
 
 function prepare(options: LectorDaemonOptions): {
@@ -110,6 +113,7 @@ function prepare(options: LectorDaemonOptions): {
 		allowDynamicOnly: options.allowDynamicOnly,
 		createSymbolGraph: (workspaceId) => new SqliteSymbolGraph(join(symbolGraphDirectory, `${workspaceId}.db`)),
 		createRepoFetcher: options.createRepoFetcher ?? (() => new GitRepoFetcher(reposDirectory)),
+		createPackageSourceResolver: options.createPackageSourceResolver,
 		// The real production shape the SearchCachePort design was for: an in-memory tier for
 		// speed plus a disk-backed tier so repeated searches survive a daemon restart -- a single
 		// SearchCachePort adapter can only be one or the other, service.ts's own safe default is

package/src/domain/find-workspace-symbols.ts

@@ -1,7 +1,8 @@
 import type { SymbolIndexPort } from "../ports/symbol-index-port.ts";
-import type { WorkspaceSymbol } from "./workspace-symbol.ts";
+import type { SymbolSearchBounds } from "./intelligence-provenance.ts";
+import type { SymbolSearchResult } from "./workspace-symbol.ts";
 
 /** Find workspace symbols matching a fuzzy query string. */
-export async function findWorkspaceSymbols(index: SymbolIndexPort, query: string): Promise<WorkspaceSymbol[]> {
-	return index.findSymbols(query);
+export async function findWorkspaceSymbols(index: SymbolIndexPort, query: string, bounds?: SymbolSearchBounds): Promise<SymbolSearchResult> {
+	return index.findSymbols(query, bounds);
 }