@danypops/lector 0.1.0

package/src/adapters/ripgrep-text-search.ts

@@ -0,0 +1,97 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { assertSafeSearchQuery } from "../domain/assert-safe-search-query.ts";
+import type { TextSearchMatch, TextSearchResult } from "../domain/text-search-result.ts";
+import type { TextSearchOptions, TextSearchPort } from "../ports/text-search-port.ts";
+import { SKIP_DIRECTORY_NAMES } from "./find-source-files.ts";
+
+// ripgrep only skips a directory automatically when a real .gitignore names it -- verified
+// empirically (a fixture with no .gitignore let a bare `rg` search node_modules freely).
+// Explicit globs make the same bound findSourceFiles already enforces hold here too, regardless
+// of whether the target repo's own .gitignore happens to list these directories.
+const EXCLUDE_GLOBS = Array.from(SKIP_DIRECTORY_NAMES, (name) => ["--glob", `!${name}/`]).flat();
+
+interface RipgrepMatchEvent {
+	readonly type: "match";
+	readonly data: {
+		readonly path: { readonly text: string };
+		readonly lines: { readonly text: string };
+		readonly line_number: number;
+		readonly submatches: readonly { readonly start: number; readonly end: number }[];
+	};
+}
+
+function isMatchEvent(value: unknown): value is RipgrepMatchEvent {
+	return typeof value === "object" && value !== null && (value as { type?: unknown }).type === "match";
+}
+
+/**
+ * TextSearchPort backed by real ripgrep (`rg --json`), streamed line-by-line via readline
+ * rather than buffered wholesale (execFile's default maxBuffer would either truncate or throw
+ * on a search producing megabytes of matches). The moment a bound is hit the child process is
+ * killed outright, not just stopped-reading-from -- a search over a huge monorepo must not keep
+ * scanning to completion just because this adapter already has enough matches.
+ *
+ * ripgrep already respects a real .gitignore and skips hidden/binary files by default, but a
+ * repo with no .gitignore listing node_modules gets searched into it freely -- explicit
+ * --glob exclusions (the same skip-list findSourceFiles uses) make that bound unconditional.
+ */
+export class RipgrepTextSearch implements TextSearchPort {
+	async search(rootPath: string, query: string, options: TextSearchOptions): Promise<TextSearchResult> {
+		assertSafeSearchQuery(query);
+		// `--` marks the end of flags -- defense in depth beyond assertSafeSearchQuery, the same
+		// two-layer approach local-git.ts already uses for git's diff ref.
+		const child = spawn("rg", ["--json", ...EXCLUDE_GLOBS, "--", query], { cwd: rootPath, stdio: ["ignore", "pipe", "pipe"] });
+
+		// Registered before draining stdout, not after: an 'exit' event fired while this adapter
+		// was still reading matches would otherwise be missed entirely, hanging the process-exit
+		// wait forever.
+		const exited = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve, reject) => {
+			child.once("exit", (code, signal) => resolve({ code, signal }));
+			child.once("error", reject);
+		});
+
+		const matches: TextSearchMatch[] = [];
+		let bytesUsed = 0;
+		let truncated = false;
+
+		const rl = createInterface({ input: child.stdout });
+		for await (const line of rl) {
+			let event: unknown;
+			try {
+				event = JSON.parse(line);
+			} catch {
+				continue;
+			}
+			if (!isMatchEvent(event)) continue;
+
+			const lineText = event.data.lines.text;
+			const submatch = event.data.submatches[0];
+			matches.push({
+				path: event.data.path.text.replace(/^\.\//, ""),
+				lineNumber: event.data.line_number,
+				line: lineText,
+				matchStart: submatch?.start ?? 0,
+				matchEnd: submatch?.end ?? 0,
+			});
+			bytesUsed += Buffer.byteLength(lineText, "utf8");
+
+			if (matches.length >= options.maxMatches || bytesUsed >= options.maxBytes) {
+				truncated = true;
+				child.kill();
+				break;
+			}
+		}
+		rl.close();
+
+		const { code } = await exited;
+		// rg's own exit codes: 0 = matches found, 1 = no matches, 2 = a real error (e.g. an
+		// invalid regex). A kill this adapter itself issued is expected and never an error,
+		// whatever exit code/signal it produced.
+		if (!truncated && code !== 0 && code !== 1) {
+			throw new Error(`rg exited with code ${code}`);
+		}
+
+		return { matches, truncated };
+	}
+}

package/src/adapters/source-manifest.ts

@@ -0,0 +1,44 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+import { findSourceFiles } from "./find-source-files.ts";
+
+export interface SourceManifest {
+	readonly fingerprint: string;
+	readonly absoluteFiles: readonly string[];
+}
+
+export class SourceManifestLimitExceeded extends Error {
+	constructor(readonly maxBytes: number) {
+		super(`source manifest exceeds the ${maxBytes}-byte hashing bound`);
+		this.name = "SourceManifestLimitExceeded";
+	}
+}
+
+/** Hashes the same bounded, sorted source-file set population will consume. */
+export async function deriveSourceManifest(rootPath: string, extensions: readonly string[], maxFiles: number, maxBytes: number): Promise<SourceManifest> {
+	if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new RangeError("maxBytes must be a positive safe integer");
+	const relativeFiles = findSourceFiles(rootPath, (extension) => extensions.includes(extension), maxFiles);
+	const hash = createHash("sha256");
+	const absoluteFiles: string[] = [];
+	let bytesHashed = 0;
+	for (const relativePath of relativeFiles) {
+		const absolutePath = join(rootPath, relativePath);
+		const expectedSize = (await stat(absolutePath)).size;
+		if (bytesHashed + expectedSize > maxBytes) throw new SourceManifestLimitExceeded(maxBytes);
+		hash.update(String(Buffer.byteLength(relativePath)));
+		hash.update(":");
+		hash.update(relativePath);
+		hash.update(":");
+		hash.update(String(expectedSize));
+		hash.update(":");
+		for await (const chunk of createReadStream(absolutePath)) {
+			bytesHashed += chunk.byteLength;
+			if (bytesHashed > maxBytes) throw new SourceManifestLimitExceeded(maxBytes);
+			hash.update(chunk);
+		}
+		absoluteFiles.push(absolutePath);
+	}
+	return { fingerprint: hash.digest("hex"), absoluteFiles };
+}

package/src/adapters/sqlite-content-cache.ts

@@ -0,0 +1,67 @@
+import type { Database } from "bun:sqlite";
+import { type Migration, openSqliteWithPragmas } from "@danypops/daemon-kit/storage";
+import type { ContentHash } from "../domain/content-hash.ts";
+import type { ContentCacheEntry, ContentCachePort, ContentSymbol } from "../ports/content-cache-port.ts";
+
+const MIGRATIONS: Migration[] = [
+	{
+		version: 1,
+		up: (db) => {
+			db.exec("CREATE TABLE content_cache (hash TEXT PRIMARY KEY, raw_content TEXT, symbols_json TEXT)");
+		},
+	},
+];
+
+interface ContentCacheRow {
+	raw_content: string | null;
+	symbols_json: string | null;
+}
+
+/**
+ * SQLite-backed ContentCachePort (via daemon-kit's migration-runner
+ * bootstrap -- same pragmas/versioning as every other @danypops daemon,
+ * not a bespoke SQLite setup). One row per ContentHash; a put for one lens
+ * only ever updates that lens's column (SQLite upsert with a targeted SET
+ * clause), never clobbering a lens already recorded for the same hash --
+ * this is what makes the single-row-per-hash design actually deliver "one
+ * shared store," not two columns that happen to live in the same table but
+ * still get overwritten independently.
+ *
+ * This is Lector's first genuinely durable state: unlike everything else
+ * built so far (in-memory registries, live LSP/tree-sitter queries), a
+ * cache entry written here is still present after the daemon restarts,
+ * pointed at the same database file (test: content-cache-port-conformance
+ * runs this exact "survives reopen" case against both adapters).
+ */
+export class SqliteContentCache implements ContentCachePort {
+	private readonly db: Database;
+
+	constructor(path: string) {
+		this.db = openSqliteWithPragmas(path, { migrations: MIGRATIONS });
+	}
+
+	async get(hash: ContentHash): Promise<ContentCacheEntry | undefined> {
+		const row = this.db.query("SELECT raw_content, symbols_json FROM content_cache WHERE hash = ?").get(hash) as ContentCacheRow | null;
+		if (!row) return undefined;
+		const entry: { rawContent?: string; symbols?: readonly ContentSymbol[] } = {};
+		if (row.raw_content !== null) entry.rawContent = row.raw_content;
+		if (row.symbols_json !== null) entry.symbols = JSON.parse(row.symbols_json) as ContentSymbol[];
+		return entry;
+	}
+
+	async putRawContent(hash: ContentHash, content: string): Promise<void> {
+		this.db
+			.query("INSERT INTO content_cache (hash, raw_content) VALUES (?, ?) ON CONFLICT(hash) DO UPDATE SET raw_content = excluded.raw_content")
+			.run(hash, content);
+	}
+
+	async putSymbols(hash: ContentHash, symbols: readonly ContentSymbol[]): Promise<void> {
+		this.db
+			.query("INSERT INTO content_cache (hash, symbols_json) VALUES (?, ?) ON CONFLICT(hash) DO UPDATE SET symbols_json = excluded.symbols_json")
+			.run(hash, JSON.stringify(symbols));
+	}
+
+	close(): void {
+		this.db.close();
+	}
+}

package/src/adapters/sqlite-search-cache.ts

@@ -0,0 +1,60 @@
+import type { Database } from "bun:sqlite";
+import { type Migration, openSqliteWithPragmas } from "@danypops/daemon-kit/storage";
+import { deriveSearchCacheKey, type SearchCacheKey } from "../domain/search-cache-key.ts";
+import type { TextSearchResult } from "../domain/text-search-result.ts";
+import type { SearchCachePort } from "../ports/search-cache-port.ts";
+
+const MIGRATIONS: Migration[] = [
+	{
+		version: 1,
+		up: (db) => {
+			db.exec("CREATE TABLE search_cache (key TEXT PRIMARY KEY, result_json TEXT NOT NULL, expires_at INTEGER NOT NULL)");
+		},
+	},
+];
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+
+interface SearchCacheRow {
+	result_json: string;
+	expires_at: number;
+}
+
+export interface SqliteSearchCacheOptions {
+	readonly ttlMs?: number;
+}
+
+/**
+ * SQLite-backed SearchCachePort -- survives a daemon restart, unlike InMemorySearchCache.
+ * TTL is enforced by storing an explicit expires_at and filtering on read; there is no
+ * background sweep of expired rows (this is a cache, not a durability guarantee -- a stale row
+ * sitting unread on disk costs nothing until something actually asks for that exact key again).
+ */
+export class SqliteSearchCache implements SearchCachePort {
+	private readonly db: Database;
+	private readonly ttlMs: number;
+
+	constructor(path: string, options: SqliteSearchCacheOptions = {}) {
+		this.db = openSqliteWithPragmas(path, { migrations: MIGRATIONS });
+		this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+	}
+
+	async get(key: SearchCacheKey): Promise<TextSearchResult | undefined> {
+		const row = this.db.query("SELECT result_json, expires_at FROM search_cache WHERE key = ?").get(deriveSearchCacheKey(key)) as SearchCacheRow | null;
+		if (!row) return undefined;
+		if (row.expires_at <= Date.now()) return undefined;
+		return JSON.parse(row.result_json) as TextSearchResult;
+	}
+
+	async set(key: SearchCacheKey, result: TextSearchResult): Promise<void> {
+		this.db
+			.query(
+				"INSERT INTO search_cache (key, result_json, expires_at) VALUES (?, ?, ?) ON CONFLICT(key) DO UPDATE SET result_json = excluded.result_json, expires_at = excluded.expires_at",
+			)
+			.run(deriveSearchCacheKey(key), JSON.stringify(result), Date.now() + this.ttlMs);
+	}
+
+	close(): void {
+		this.db.close();
+	}
+}

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

@@ -0,0 +1,154 @@
+import type { Database } from "bun:sqlite";
+import { type Migration, openSqliteWithPragmas } from "@danypops/daemon-kit/storage";
+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";
+
+const MIGRATIONS: Migration[] = [
+	{
+		version: 1,
+		up: (db) => {
+			db.exec(
+				"CREATE TABLE symbol_nodes (id TEXT PRIMARY KEY, name TEXT NOT NULL, kind TEXT NOT NULL, path TEXT NOT NULL, line INTEGER NOT NULL, character INTEGER NOT NULL)",
+			);
+			db.exec("CREATE TABLE symbol_edges (from_id TEXT NOT NULL, to_id TEXT NOT NULL, kind TEXT NOT NULL, PRIMARY KEY (from_id, to_id, kind))");
+			db.exec("CREATE INDEX symbol_edges_to_idx ON symbol_edges (to_id, kind)");
+		},
+	},
+	{
+		version: 2,
+		up: (db) => {
+			db.exec(
+				"CREATE TABLE symbol_graph_generation (singleton INTEGER PRIMARY KEY CHECK (singleton = 1), source_fingerprint TEXT NOT NULL, max_files INTEGER NOT NULL, max_symbols_per_file INTEGER NOT NULL, completed_at INTEGER NOT NULL, files_processed INTEGER NOT NULL, symbols_processed INTEGER NOT NULL, nodes_added INTEGER NOT NULL, edges_added INTEGER NOT NULL)",
+			);
+		},
+	},
+];
+
+interface NodeRow {
+	name: string;
+	kind: string;
+	path: string;
+	line: number;
+	character: number;
+}
+
+interface GenerationRow {
+	source_fingerprint: string;
+	max_files: number;
+	max_symbols_per_file: number;
+	completed_at: number;
+	files_processed: number;
+	symbols_processed: number;
+	nodes_added: number;
+	edges_added: number;
+}
+
+/**
+ * SQLite-backed SymbolGraphPort; survives a daemon restart pointed at the
+ * same database file. reachableFrom uses `WITH RECURSIVE` rather than an
+ * application-level loop issuing one query per hop -- one round trip
+ * regardless of maxDepth.
+ */
+export class SqliteSymbolGraph implements SymbolGraphPort {
+	private readonly db: Database;
+
+	constructor(path: string) {
+		this.db = openSqliteWithPragmas(path, { migrations: MIGRATIONS });
+	}
+
+	async addNode(node: SymbolNode): Promise<void> {
+		this.db
+			.query(
+				"INSERT INTO symbol_nodes (id, name, kind, path, line, character) VALUES (?, ?, ?, ?, ?, ?) " +
+					"ON CONFLICT(id) DO UPDATE SET name = excluded.name, kind = excluded.kind, path = excluded.path, line = excluded.line, character = excluded.character",
+			)
+			.run(node.id, node.name, node.kind, node.location.path, node.location.line, node.location.character);
+	}
+
+	async getNode(id: SymbolNodeId): Promise<SymbolNode | undefined> {
+		const row = this.db.query("SELECT name, kind, path, line, character FROM symbol_nodes WHERE id = ?").get(id) as NodeRow | null;
+		if (!row) return undefined;
+		return { id, name: row.name, kind: row.kind, location: { path: row.path, line: row.line, character: row.character } };
+	}
+
+	async addEdge(from: SymbolNodeId, to: SymbolNodeId, kind: SymbolEdgeKind): Promise<void> {
+		this.db.query("INSERT OR IGNORE INTO symbol_edges (from_id, to_id, kind) VALUES (?, ?, ?)").run(from, to, kind);
+	}
+
+	async edgesFrom(id: SymbolNodeId, kind?: SymbolEdgeKind): Promise<readonly SymbolNodeId[]> {
+		const rows = kind
+			? (this.db.query("SELECT to_id FROM symbol_edges WHERE from_id = ? AND kind = ?").all(id, kind) as { to_id: string }[])
+			: (this.db.query("SELECT to_id FROM symbol_edges WHERE from_id = ?").all(id) as { to_id: string }[]);
+		return rows.map((row) => row.to_id);
+	}
+
+	async edgesTo(id: SymbolNodeId, kind?: SymbolEdgeKind): Promise<readonly SymbolNodeId[]> {
+		const rows = kind
+			? (this.db.query("SELECT from_id FROM symbol_edges WHERE to_id = ? AND kind = ?").all(id, kind) as { from_id: string }[])
+			: (this.db.query("SELECT from_id FROM symbol_edges WHERE to_id = ?").all(id) as { from_id: string }[]);
+		return rows.map((row) => row.from_id);
+	}
+
+	async reachableFrom(id: SymbolNodeId, options: { maxDepth: number; kind?: SymbolEdgeKind }): Promise<readonly SymbolNodeId[]> {
+		if (options.maxDepth < 1) return [];
+		const kindClause = options.kind ? "AND e.kind = $kind" : "";
+		const sql = `
+			WITH RECURSIVE reachable(id, depth) AS (
+				SELECT to_id, 1 FROM symbol_edges e WHERE e.from_id = $id ${kindClause}
+				UNION
+				SELECT e.to_id, r.depth + 1
+				FROM symbol_edges e
+				JOIN reachable r ON e.from_id = r.id
+				WHERE r.depth < $maxDepth ${kindClause}
+			)
+			SELECT DISTINCT id FROM reachable
+		`;
+		const params: Record<string, string | number> = { $id: id, $maxDepth: options.maxDepth };
+		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);
+	}
+
+	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",
+			)
+			.get() as GenerationRow | null;
+		if (!row) return undefined;
+		return {
+			sourceFingerprint: row.source_fingerprint,
+			maxFiles: row.max_files,
+			maxSymbolsPerFile: row.max_symbols_per_file,
+			completedAt: row.completed_at,
+			result: {
+				filesProcessed: row.files_processed,
+				symbolsProcessed: row.symbols_processed,
+				nodesAdded: row.nodes_added,
+				edgesAdded: row.edges_added,
+			},
+		};
+	}
+
+	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",
+			)
+			.run(
+				generation.sourceFingerprint,
+				generation.maxFiles,
+				generation.maxSymbolsPerFile,
+				generation.completedAt,
+				generation.result.filesProcessed,
+				generation.result.symbolsProcessed,
+				generation.result.nodesAdded,
+				generation.result.edgesAdded,
+			);
+	}
+
+	async close(): Promise<void> {
+		this.db.close();
+	}
+}

package/src/adapters/tiered-search-cache.ts

@@ -0,0 +1,29 @@
+import type { SearchCacheKey } from "../domain/search-cache-key.ts";
+import type { TextSearchResult } from "../domain/text-search-result.ts";
+import type { SearchCachePort } from "../ports/search-cache-port.ts";
+
+/**
+ * Composes a fast (in-memory) and a durable (disk-backed) SearchCachePort into one: a read
+ * checks fast first, falls through to durable on a miss and warms fast with what it finds; a
+ * write goes to both. This is what actually delivers the "in-memory tier plus a disk-backed
+ * tier" design -- a single SearchCachePort implementation can only be one or the other.
+ */
+export class TieredSearchCache implements SearchCachePort {
+	constructor(
+		private readonly fast: SearchCachePort,
+		private readonly durable: SearchCachePort,
+	) {}
+
+	async get(key: SearchCacheKey): Promise<TextSearchResult | undefined> {
+		const fastHit = await this.fast.get(key);
+		if (fastHit) return fastHit;
+
+		const durableHit = await this.durable.get(key);
+		if (durableHit) await this.fast.set(key, durableHit);
+		return durableHit;
+	}
+
+	async set(key: SearchCacheKey, result: TextSearchResult): Promise<void> {
+		await Promise.all([this.fast.set(key, result), this.durable.set(key, result)]);
+	}
+}

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

@@ -0,0 +1,155 @@
+import { readFileSync } 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 { 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;
+
+interface DeclarationKind {
+	readonly nodeType: string;
+	readonly kind: string;
+}
+
+/** Top-level and class-member declaration shapes in tree-sitter's TypeScript/JavaScript grammars. */
+const DECLARATION_KINDS: readonly DeclarationKind[] = [
+	{ nodeType: "function_declaration", kind: "function" },
+	{ nodeType: "class_declaration", kind: "class" },
+	{ nodeType: "interface_declaration", kind: "interface" },
+	{ nodeType: "type_alias_declaration", kind: "type-alias" },
+	{ nodeType: "enum_declaration", kind: "enum" },
+	{ nodeType: "method_definition", kind: "method" },
+];
+
+let parserInitialization: Promise<void> | undefined;
+function ensureParserInitialized(): Promise<void> {
+	if (!parserInitialization) parserInitialization = Parser.init();
+	return parserInitialization;
+}
+
+function wasmPathFor(extension: string): string | undefined {
+	const specifier =
+		extension === ".ts"
+			? "tree-sitter-wasms/out/tree-sitter-typescript.wasm"
+			: extension === ".tsx"
+				? "tree-sitter-wasms/out/tree-sitter-tsx.wasm"
+				: extension === ".js" || extension === ".jsx" || extension === ".mjs" || extension === ".cjs"
+					? "tree-sitter-wasms/out/tree-sitter-javascript.wasm"
+					: undefined;
+	return specifier ? fileURLToPath(import.meta.resolve(specifier)) : undefined;
+}
+
+/** Content-derived only -- no path, so the extraction result is valid caching material regardless of which file currently holds this content. */
+function extractContentSymbols(root: Parser.SyntaxNode): ContentSymbol[] {
+	const results: ContentSymbol[] = [];
+	for (const spec of DECLARATION_KINDS) {
+		for (const node of root.descendantsOfType(spec.nodeType)) {
+			const nameNode = node.childForFieldName("name");
+			if (!nameNode) continue;
+			results.push({ name: nameNode.text, kind: spec.kind, line: node.startPosition.row + 1, character: node.startPosition.column + 1 });
+		}
+	}
+	return results;
+}
+
+function toWorkspaceSymbols(symbols: readonly ContentSymbol[], relativePath: string): WorkspaceSymbol[] {
+	return symbols.map((symbol) => ({
+		name: symbol.name,
+		kind: symbol.kind,
+		location: { path: relativePath, line: symbol.line, character: symbol.character },
+		...(symbol.containerName !== undefined ? { containerName: symbol.containerName } : {}),
+	}));
+}
+
+/**
+ * SymbolIndexPort backed by tree-sitter, via web-tree-sitter's WASM runtime
+ * (the native `tree-sitter` binding needs node-gyp, unavailable here).
+ *
+ * No subprocess or warm server: every call parses whatever files currently
+ * exist under the workspace root, so results are always current, at the
+ * cost of re-parsing on every query -- mitigated by the ContentHash-keyed
+ * cache below.
+ *
+ * `web-tree-sitter` is pinned to 0.20.8, matching the WASM ABI
+ * `tree-sitter-wasms`' prebuilt grammars were compiled against; 0.26.x
+ * fails to load them.
+ *
+ * Per-file results are cached, keyed by ContentHash, via an injected
+ * ContentCachePort (default in-memory; pass SqliteContentCache for
+ * durability). A cache hit skips parsing entirely, and also warms the
+ * cache's rawContent lens for that hash, since the content was already
+ * read to compute it.
+ */
+export class TreeSitterSymbolIndex implements SymbolIndexPort {
+	private readonly rootPath: string;
+	private readonly contentCache: ContentCachePort;
+	private readonly parsersByWasmPath = new Map<string, Parser>();
+
+	constructor(rootPath: string, contentCache: ContentCachePort = new InMemoryContentCache()) {
+		this.rootPath = rootPath;
+		this.contentCache = contentCache;
+	}
+
+	private async parserFor(wasmPath: string): Promise<Parser> {
+		const cached = this.parsersByWasmPath.get(wasmPath);
+		if (cached) return cached;
+		await ensureParserInitialized();
+		const language = await Parser.Language.load(wasmPath);
+		const parser = new Parser();
+		parser.setLanguage(language);
+		this.parsersByWasmPath.set(wasmPath, parser);
+		return parser;
+	}
+
+	private async contentSymbolsFor(relativePath: string, wasmPath: string, content: string): Promise<ContentSymbol[]> {
+		const hash = contentHashOf(content);
+
+		// Reading the file already required reading its content -- warm the fs lens for this
+		// hash regardless of whether the symbols lens below is a hit or a miss. Awaited, not
+		// fire-and-forget: a caller reading this hash's rawContent right after findSymbols
+		// resolves must see it, not race an in-flight write.
+		await this.contentCache.putRawContent(hash, content);
+
+		const cached = await this.contentCache.get(hash);
+		if (cached?.symbols) return [...cached.symbols];
+
+		const parser = await this.parserFor(wasmPath);
+		const tree = parser.parse(content);
+		const symbols = tree ? extractContentSymbols(tree.rootNode) : [];
+		await this.contentCache.putSymbols(hash, symbols);
+		return symbols;
+	}
+
+	async findSymbols(query: string): Promise<WorkspaceSymbol[]> {
+		const lowerQuery = query.toLowerCase();
+		const results: WorkspaceSymbol[] = [];
+
+		for (const relativePath of findSourceFiles(this.rootPath, (extension) => wasmPathFor(extension) !== undefined, MAX_FILES_SCANNED)) {
+			const wasmPath = wasmPathFor(extname(relativePath));
+			if (!wasmPath) continue;
+
+			let content: string;
+			try {
+				content = readFileSync(join(this.rootPath, relativePath), "utf-8");
+			} catch {
+				continue;
+			}
+
+			const contentSymbols = await this.contentSymbolsFor(relativePath, wasmPath, content);
+			for (const symbol of toWorkspaceSymbols(contentSymbols, relativePath)) {
+				if (symbol.name.toLowerCase().includes(lowerQuery)) results.push(symbol);
+			}
+		}
+
+		return results;
+	}
+
+	async close(): Promise<void> {
+		// In-process, synchronous parsing -- no subprocess or handle to release.
+	}
+}