codesearch-mcp 0.2.3-alpha → 0.3.0-alpha

package/dist/src/services/SearcherService.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SearcherService = void 0;
+exports.rerankDocument = rerankDocument;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const readline = __importStar(require("readline"));
@@ -43,12 +44,14 @@ const MonorepoAwareDiscoveryService_1 = require("./MonorepoAwareDiscoveryService
 const legacy_ollama_index_1 = require("./legacy-ollama-index");
 const symbol_name_1 = require("../symbol-name");
 const dependency_traversal_1 = require("../dependency-traversal");
+const result_shaping_1 = require("../search/result-shaping");
+const hnsw_settings_1 = require("../hnsw-settings");
 const SILENT_LOGGER = {
     debug() { },
     info() { },
     warn() { },
     error() { },
-    metric() { },
+    withContext(_, fn) { return fn(); },
 };
 const NODE_FS = {
     realpath: p => fs.promises.realpath(p),
@@ -66,7 +69,6 @@ const GREP_EXCLUDE_DIRS = [...file_utils_1.IGNORE_DIRS].map(d => `--exclude-dir=
 const FIND_SYMBOL_LIMIT = 50;
 const FIND_SYMBOL_RAW_LIMIT = FIND_SYMBOL_LIMIT * 10;
 const PATH_CANDIDATE_LIMIT = 3;
-/** Every path column of the index; `content` marks those whose file the indexer read. */
 const INDEX_PATH_COLUMNS = [
     { table: 'code_chunk', column: '"filePath"', content: true },
     { table: 'code_symbol', column: '"filePath"', content: true },
@@ -79,7 +81,6 @@ const OUTSIDE_WORKSPACE_VALUE = (col) => `(${col} = '..' OR ${col} LIKE '../%')`
 function stripTrailingSlash(p) {
     return p.length > 1 && p.endsWith('/') ? p.slice(0, -1) : p;
 }
-/** Segment-boundary containment: `/ws-other` is not within `/ws`; `.` contains every relative path. */
 function isWithin(p, root) {
     if (root === '.')
         return true;
@@ -90,6 +91,13 @@ function isWithin(p, root) {
 function errorCode(err) {
     return err?.code ?? 'EIO';
 }
+function rerankDocument(row) {
+    const symbol = row.ownerPath ? ` | Symbol: ${oneLine(row.ownerPath)}` : '';
+    return `File: ${oneLine(row.filePath)}${symbol}\n${row.content}`;
+}
+function oneLine(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
 class SearcherService {
     db;
     embedder;
@@ -105,38 +113,47 @@ class SearcherService {
         this.logger = logger;
         this.fs = { ...NODE_FS, ...fsDeps };
     }
-    /**
-     * Whether `code_symbol.target` exists — `true` once a check finds it (never
-     * re-checked again in this process), `false` until then (re-checked on
-     * every lookup, so a `rag-index` run that adds the column takes effect
-     * without restarting `rag-mcp`). See "find_symbol works before the target
-     * column exists" (`graphql-symbols`).
-     */
     targetColumnPresent = false;
-    /** Real path of `workspaceRoot`; cached only once resolved, so a transient failure is retried. */
     realRootCache;
-    /** Lazily-built, cached map of project name → real filesystem root. */
     rootMap;
-    /** Cached, lazily-built map of leaf project name → real filesystem root (via discovery). */
+    pgvectorVersionRead;
+    degradedScanWarned = false;
+    async iterativeScanEnabled() {
+        const read = this.pgvectorVersionRead ??= this.db.pgvectorVersion().then(v => {
+            if (v === null)
+                throw new Error('vector extension not found in pg_extension');
+            return v;
+        });
+        let version;
+        try {
+            version = await read;
+        }
+        catch (err) {
+            if (this.pgvectorVersionRead === read)
+                this.pgvectorVersionRead = undefined;
+            this.warnDegradedScan('unknown', err);
+            return false;
+        }
+        if ((0, hnsw_settings_1.supportsIterativeScan)(version))
+            return true;
+        this.warnDegradedScan(version);
+        return false;
+    }
+    warnDegradedScan(version, err) {
+        if (this.degradedScanWarned)
+            return;
+        this.degradedScanWarned = true;
+        this.logger.warn(`SearcherService: pgvector ${version} lacks hnsw.iterative_scan — filtered searches on large projects may return fewer candidates than requested; upgrade to pgvector ≥ 0.8`, err ? { err } : undefined);
+    }
     projectRootMap() {
         if (!this.rootMap) {
             this.rootMap = new Map((0, MonorepoAwareDiscoveryService_1.toLeafProjects)(this.discovery.discover(this.config.workspaceRoot)).map(p => [p.name, p.path]));
         }
         return this.rootMap;
     }
-    /**
-     * Resolve a project name to its real filesystem root. Uses discovery (leaf
-     * projects) so nested-monorepo names like `repo/app` map to their true path;
-     * falls back to `join(workspaceRoot, name)` when the name is unknown (e.g. a
-     * project since removed from disk, or a flat project not surfaced by discovery).
-     */
     resolveProjectRoot(name) {
         let root = this.projectRootMap().get(name);
         if (root === undefined) {
-            // Cache miss — the project may have been added/renamed on disk since the
-            // map was built (mcp/web servers are long-lived). Rebuild once and retry
-            // before the flat fallback, which is wrong for nested-monorepo names
-            // (`repo/app` lives at `repo/apps/app`, not `repo/app`).
             this.rootMap = undefined;
             root = this.projectRootMap().get(name);
         }
@@ -163,12 +180,6 @@ class SearcherService {
             return null;
         }
     }
-    /**
-     * Lexical validation of a tool path argument: refusals for an empty value,
-     * `\`, an absolute path and a `..` escape; otherwise the canonical
-     * workspace-relative form. The only filesystem access is the cached real path
-     * of `workspaceRoot`.
-     */
     async resolveToolPath(input) {
         if (input == null || input === '')
             return { ok: false, reason: 'invalid', missing: true };
@@ -190,11 +201,6 @@ class SearcherService {
             return { ok: false, reason: 'outside_workspace' };
         return { ok: true, relPath, absPath: this.toAbs(relPath) };
     }
-    /**
-     * Whether the real location of `absPath` — of the target, else of its nearest
-     * existing ancestor plus the remaining segments — lies under the real
-     * workspace root.
-     */
     async realLocation(absPath) {
         const root = (await this.realWorkspaceRoot()) ?? this.workspaceRoot();
         let existing = absPath;
@@ -215,11 +221,6 @@ class SearcherService {
             }
         }
     }
-    /**
-     * Workspace boundary of the disk tools. A real location outside the workspace
-     * is allowed only for content the indexer already read (a symlinked share):
-     * the file itself for `file`, any file below it for `dir`.
-     */
     async checkRealLocation(relPath, absPath, kind) {
         const loc = await this.realLocation(absPath);
         if (!loc.ok)
@@ -234,11 +235,9 @@ class SearcherService {
         const [{ exists }] = await this.db.query(`SELECT EXISTS (${branches.join(' UNION ALL ')}) AS exists`, [param]);
         return exists;
     }
-    /** Whether any table of the index holds `relPath` (a canonical path, never `../…`). */
     isIndexedPath(relPath) {
         return this.pathExists(INDEX_PATH_COLUMNS, '$col = $1', relPath);
     }
-    /** Whether the indexer read the file at `relPath`. */
     isContentPath(relPath) {
         return this.pathExists(INDEX_PATH_COLUMNS.filter(c => c.content), '$col = $1', relPath);
     }
@@ -246,11 +245,6 @@ class SearcherService {
         const prefix = relPath === '.' ? '' : (0, symbol_name_1.escapeLike)(relPath) + '/';
         return this.pathExists(INDEX_PATH_COLUMNS.filter(c => c.content), `$col LIKE $1 ESCAPE '\\'`, prefix + '%');
     }
-    /**
-     * Up to three index paths ending in `/<relPath>` (`file`) or directories
-     * ending in `/<relPath>` that hold one (`dir`), in byte order. For `dir`, the
-     * root of a project named `relPath` comes first.
-     */
     async findPathCandidates(relPath, kind) {
         const union = INDEX_PATH_COLUMNS.map(c => `SELECT ${c.column} AS p FROM ${c.table}`).join(' UNION ALL ');
         const notOutside = `NOT ${OUTSIDE_WORKSPACE_VALUE('p')}`;
@@ -273,21 +267,15 @@ class SearcherService {
         const rest = rows.map(r => r.p).filter(p => !first.includes(p));
         return [...first, ...rest].slice(0, PATH_CANDIDATE_LIMIT);
     }
-    /** `findPathCandidates`, with a failed lookup logged and answered by no candidates. */
     async candidatesOrNone(relPath, kind) {
         try {
             return await this.findPathCandidates(relPath, kind);
         }
         catch (err) {
-            this.logger.error('SearcherService: path candidate lookup failed', { relPath, reason: err.message });
+            this.logger.error('SearcherService: path candidate lookup failed', { relPath, err });
             return [];
         }
     }
-    /**
-     * `relPath` with a leading project name replaced by that project's root
-     * (`repo/app/src/x.ts` → `repo/apps/app/src/x.ts`), or null when no name
-     * prefixes it, the root equals the name, or the result names nothing.
-     */
     async substituteProjectName(relPath) {
         let named = [];
         for (let attempt = 0; attempt < 2 && named.length === 0; attempt++) {
@@ -320,7 +308,6 @@ class SearcherService {
         }
         return root === undefined ? null : this.toRel(root);
     }
-    /** Longest workspace-relative project root accepted by `match`; discovery is re-run once before giving up. */
     findProjectRoot(match) {
         for (let attempt = 0; attempt < 2; attempt++) {
             if (attempt === 1)
@@ -334,15 +321,9 @@ class SearcherService {
         }
         return null;
     }
-    /** Root directory (workspace-relative) of the project the text-search fallback for `relPath` runs in. */
     fallbackRoot(relPath) {
         return this.findProjectRoot(r => isWithin(relPath, r))?.rel ?? null;
     }
-    /**
-     * Why a graph tool has no data for `relPath`, or null when the path is in the
-     * index path set. Touches the disk only for an unknown path, and answers a
-     * real location outside the workspace as `not_found` without looking at it.
-     */
     async checkGraphPath(relPath) {
         if (await this.isIndexedPath(relPath))
             return null;
@@ -381,17 +362,8 @@ class SearcherService {
        ) AS exists`, [owner.name]);
         return exists ? { kind: 'unknown' } : { kind: 'project_not_indexed', project: owner.name };
     }
-    /**
-     * Project-level dependency edges aggregated from `code_dependency`: an edge
-     * `A → B` means some file in project A imports a file owned by project B.
-     * Used by the graph to draw links between a monorepo's sub-projects. Only
-     * edges whose target file belongs to an indexed project are returned (targets
-     * outside any indexed project — e.g. unindexed libs — are skipped).
-     */
     async getProjectEdges() {
         const rows = await this.db.query(`SELECT DISTINCT project, "toFile" FROM code_dependency`);
-        // Reverse map: workspace-relative project root → name, longest first so the
-        // most specific owner wins (e.g. repo/apps/account before repo).
         const byRelPath = [...this.projectRootMap().entries()]
             .map(([name, abs]) => ({ name, rel: path.relative(this.config.workspaceRoot, abs) }))
             .sort((a, b) => b.rel.length - a.rel.length);
@@ -416,29 +388,15 @@ class SearcherService {
         }
         return edges;
     }
-    // Query translation was removed (legacy). The query is embedded as-is; the
-    // method is kept so the tool layer needs no change and `translated` is always
-    // false.
     async prepareQuery(raw) {
         return { query: raw, translated: false };
     }
-    /**
-     * Refuse when the configured embedding model disagrees with the one that built
-     * the index — embedding a query into a foreign vector space returns noise. A
-     * missing `index_meta` row with an empty (or altogether absent) `code_chunk`
-     * does not block — but a *populated* `code_chunk` with no `index_meta` row is a
-     * pre-`index_meta` install, treated as the legacy `ollama`/`bge-m3` index (same
-     * interpretation as the `rag-index` legacy-Ollama guard), read-only — this check
-     * never writes `index_meta`.
-     */
     async assertIndexMatches() {
         const meta = await this.db.readIndexMeta();
         if (meta) {
             this.compareIndexed(meta.provider, meta.model, meta.dimensions);
             return;
         }
-        // No row — a missing code_chunk table counts as empty; any other DB error
-        // while counting propagates rather than being read as "not indexed".
         if (await (0, legacy_ollama_index_1.hasIndexedChunks)(this.db)) {
             this.compareIndexed(legacy_ollama_index_1.LEGACY_OLLAMA_IDENTITY.provider, legacy_ollama_index_1.LEGACY_OLLAMA_IDENTITY.model, null);
         }
@@ -449,14 +407,6 @@ class SearcherService {
             throw new Error(`Index was built with ${indexedProvider}/${indexedModel} but the config selects ${provider}/${model}. ` +
                 `Run \`rag-index --reindex\` to rebuild the index for the new model.`);
         }
-        // Same model but a changed dimension (e.g. a Matryoshka `embedding.dimensions`
-        // override) would embed the query at a width the column can't hold — pgvector
-        // would throw an opaque "different vector dimensions" error mid-query. Catch
-        // it here with the friendly hint. `embedder.dimensions` is 0 when the width is
-        // only knowable by probing, in which case we skip (can't compare cheaply).
-        // `indexedDimensions` is null for the legacy-inferred identity, whose provider
-        // can never match a configured provider (ollama is no longer selectable), so
-        // this branch is unreached in that case.
         const dim = this.embedder.dimensions;
         if (indexedDimensions != null && dim > 0 && dim !== indexedDimensions) {
             throw new Error(`Index was built at ${indexedDimensions} dimensions but ${provider}/${model} now resolves to ${dim}. ` +
@@ -484,22 +434,20 @@ class SearcherService {
             };
         }));
     }
-    async searchChunks(query, limit, project, threshold, rerankOverride) {
+    async searchChunks(query, limit, project, threshold, rerankOverride, perFile = result_shaping_1.DEFAULT_PER_FILE) {
+        const { stages } = await this.searchChunksWithStages(query, limit, project, threshold, rerankOverride, perFile);
+        return stages.reranked ?? stages.vector;
+    }
+    async searchChunksWithStages(query, limit, project, threshold, rerankOverride, perFile = result_shaping_1.DEFAULT_PER_FILE) {
         const t0 = Date.now();
         await this.assertIndexMatches();
         const effectiveThreshold = threshold ?? this.config.search.similarityThreshold;
         const reranking = rerankOverride === false ? false : !!this.embedder.rerank;
-        // Candidate floor: decouple the pool size from `limit` so a small `limit`
-        // (e.g. the default 5) still gives the reranker a large-enough menu. Without
-        // a reranker the extra candidates are never reordered, so keep `limit`.
+        const perFileActive = perFile < limit;
         const fetchLimit = reranking
             ? Math.min(Math.max(limit * this.config.reranker.overfetch, this.config.reranker.candidateFloor), 200)
-            : limit;
-        // With metrics on, fetch one extra row to detect a saturated pool (more
-        // under-threshold candidates existed than the window took). The extra row is
-        // dropped before reranking so it never affects results.
-        const metricsOn = this.config.logging.searchMetrics;
-        const dbLimit = metricsOn ? fetchLimit + 1 : fetchLimit;
+            : perFileActive ? Math.min(limit * 3, 200) : limit;
+        const dbLimit = fetchLimit + 1;
         this.logger.debug('SearcherService: searchChunks', {
             query: query.slice(0, 120), limit, fetchLimit, project, threshold: effectiveThreshold,
         });
@@ -512,8 +460,14 @@ class SearcherService {
             params.push(project);
             projectFilter = `AND "serviceName" = $${params.length}`;
         }
+        const iterative = await this.iterativeScanEnabled();
+        const settings = (0, hnsw_settings_1.hnswSettings)(dbLimit, iterative);
+        const indexParams = {
+            efSearch: settings['hnsw.ef_search'],
+            iterativeScan: iterative ? hnsw_settings_1.ITERATIVE_SCAN_MODE : 'off',
+        };
         const tDb0 = Date.now();
-        const fetched = await this.db.query(`SELECT "serviceName", "filePath", "startLine", content, "ownerPath",
+        const fetched = await this.db.queryWithLocalSettings(settings, `SELECT "serviceName", "filePath", "startLine", content, "ownerPath",
               ROUND((embedding <=> $1)::numeric, 4)::float8 AS score
        FROM code_chunk
        WHERE embedding <=> $1 < $2
@@ -521,9 +475,8 @@ class SearcherService {
        ORDER BY embedding <=> $1
        LIMIT $3`, params);
         const dbMs = Date.now() - tDb0;
-        // Saturated iff the extra probe row came back — more candidates were under
-        // the threshold than `fetchLimit`. Trim the probe row before reranking.
-        const poolSaturated = metricsOn && fetched.length > fetchLimit;
+        fetched.sort((a, b) => a.score - b.score);
+        const poolSaturated = fetched.length > fetchLimit;
         const candidates = fetched.slice(0, fetchLimit);
         this.logger.debug('SearcherService: searchChunks candidates', {
             count: candidates.length,
@@ -531,45 +484,45 @@ class SearcherService {
             files: candidates.map(r => r.filePath),
             ms: Date.now() - t0,
         });
-        let results;
+        const vector = (0, result_shaping_1.limitPerFile)(candidates, limit, perFile);
+        let reranked;
+        let rerankFailed = false;
         let rerankMs = 0;
-        if (!reranking || candidates.length === 0) {
-            results = candidates.slice(0, limit);
+        if (reranking && candidates.length === 0) {
+            reranked = [];
         }
-        else {
+        else if (reranking) {
             const tRerank0 = Date.now();
             try {
-                const indices = await this.embedder.rerank(query, candidates.map(r => r.content), limit);
+                const topN = perFileActive ? candidates.length : limit;
+                const indices = await this.embedder.rerank(query, candidates.map(rerankDocument), topN);
                 rerankMs = Date.now() - tRerank0;
                 this.logger.debug('SearcherService: searchChunks rerank done', { indices, ms: Date.now() - t0 });
-                // Cap at `limit`: some rerank servers ignore `top_n` and echo back every
-                // candidate, so slicing here keeps the result count within the request.
-                results = indices.filter(i => i >= 0 && i < candidates.length).slice(0, limit).map(i => candidates[i]);
+                const order = indices.filter(i => i >= 0 && i < candidates.length).map(i => candidates[i]);
+                reranked = (0, result_shaping_1.limitPerFile)(order, limit, perFile);
             }
             catch (err) {
                 rerankMs = Date.now() - tRerank0;
                 this.logger.warn('SearcherService: rerank failed, falling back to vector order', {
-                    reason: err instanceof Error ? err.message : String(err),
+                    err,
                     ms: Date.now() - t0,
                 });
-                results = candidates.slice(0, limit);
+                reranked = vector;
+                rerankFailed = true;
             }
         }
-        if (metricsOn) {
-            this.emitSearchMetrics(query, {
-                fetchLimit, candidates, results, poolSaturated, embedMs, dbMs, rerankMs, totalMs: Date.now() - t0,
-            });
-        }
-        return results;
+        this.emitSearchMetrics(query, {
+            fetchLimit, candidates, results: reranked ?? vector, poolSaturated, indexParams,
+            embedMs, dbMs, rerankMs, totalMs: Date.now() - t0,
+        });
+        return {
+            pool: candidates,
+            stages: reranked ? { vector, reranked } : { vector },
+            rerankFailed,
+            fetchLimit,
+            indexParams,
+        };
     }
-    /**
-     * Emit one structured search-tuning line (via `logger.metric`, at `info`
-     * regardless of `logging.level`). `candidates` are in cosine order, so a
-     * candidate's array index is its cosine rank — `maxCosineRankSurvived` is the
-     * deepest cosine position that survived reranking into the returned set. Read
-     * it alongside `poolSaturated` to tune `candidateFloor`/`overfetch`/threshold
-     * per hardware. Never logs chunk content, embeddings, or credentials.
-     */
     emitSearchMetrics(query, m) {
         const { candidates, results } = m;
         const contentIndex = new Map(candidates.map((c, i) => [c, i]));
@@ -578,7 +531,7 @@ class SearcherService {
         for (const r of results)
             fileCounts.set(r.filePath, (fileCounts.get(r.filePath) ?? 0) + 1);
         const topFileCount = results.length ? Math.max(...fileCounts.values()) : 0;
-        this.logger.metric('search metrics', {
+        this.logger.info('search metrics', {
             query: query.slice(0, 120),
             fetchLimit: m.fetchLimit,
             candidatesReturned: candidates.length,
@@ -589,6 +542,8 @@ class SearcherService {
             topFileShare: results.length ? +(topFileCount / results.length).toFixed(3) : 0,
             bestResultScore: results.length ? Math.min(...results.map(r => r.score)) : null,
             worstResultScore: results.length ? Math.max(...results.map(r => r.score)) : null,
+            efSearch: m.indexParams.efSearch,
+            iterativeScan: m.indexParams.iterativeScan,
             embedMs: m.embedMs,
             rerankMs: m.rerankMs,
             dbMs: m.dbMs,
@@ -635,7 +590,6 @@ class SearcherService {
         this.logger.debug('SearcherService: fetchGraphContext', { files: files.length });
         if (files.length === 0)
             return new Map();
-        // Use proportional limit: 50 imports + 50 usedBy per file
         const proportionalLimit = Math.max(2000, files.length * 100);
         const values = files.map((_, i) => `($${i + 1}::text)`).join(', ');
         const rows = await this.db.query(`SELECT r.fp AS "filePath", 'import' AS direction, d."toFile" AS related
@@ -679,11 +633,12 @@ class SearcherService {
             params.push(symbol);
             symbolFilter = `AND "toSymbol" = $${params.length}`;
         }
-        const direct = await this.db.query(`SELECT DISTINCT "fromFile", "fromSymbol", "toFile", "toSymbol", "depType"
+        const direct = await this.db.query(`SELECT "fromFile", "fromSymbol", "toFile", "toSymbol", "depType", min("id"::text) AS "id"
        FROM code_dependency
        WHERE "fromFile" = $1 AND NOT ${OUTSIDE_WORKSPACE_VALUE('"toFile"')}
        ${symbolFilter}
-       ORDER BY "toFile"`, params);
+       GROUP BY "fromFile", "fromSymbol", "toFile", "toSymbol", "depType"
+       ORDER BY "toFile", min("id"::text)`, params);
         if (!transitive) {
             this.logger.debug('SearcherService: getDependencies result', { direct: direct.length, ms: Date.now() - t0 });
             return direct;
@@ -709,11 +664,12 @@ class SearcherService {
             params.push(symbol);
             symbolFilter = `AND "toSymbol" = $${params.length}`;
         }
-        const direct = await this.db.query(`SELECT DISTINCT "fromFile", "fromSymbol", "toFile", "toSymbol", "depType"
+        const direct = await this.db.query(`SELECT "fromFile", "fromSymbol", "toFile", "toSymbol", "depType", min("id"::text) AS "id"
        FROM code_dependency
        WHERE "toFile" = $1 AND NOT ${OUTSIDE_WORKSPACE_VALUE('"fromFile"')}
        ${symbolFilter}
-       ORDER BY "fromFile"`, params);
+       GROUP BY "fromFile", "fromSymbol", "toFile", "toSymbol", "depType"
+       ORDER BY "fromFile", min("id"::text)`, params);
         if (!transitive) {
             this.logger.debug('SearcherService: getDependents result', { direct: direct.length, ms: Date.now() - t0 });
             return direct;
@@ -763,11 +719,6 @@ class SearcherService {
         this.logger.debug('SearcherService: getCallers result', { count: rows.length, ms: Date.now() - t0 });
         return rows;
     }
-    /**
-     * Whole-word text search for `symbol` under `rootDir` (workspace-relative).
-     * grep exiting ≥ 2 after printing matches is a partial result; without
-     * matches, or when grep cannot be spawned, the search failed.
-     */
     async grepSymbol(symbol, rootDir, excludeFile) {
         const t0 = Date.now();
         this.logger.debug('SearcherService: grepSymbol', { symbol, rootDir, excludeFile });
@@ -795,19 +746,12 @@ class SearcherService {
         this.logger.debug('SearcherService: grepSymbol result', { matches: Math.min(all.length, GREP_MAX_RESULTS), truncated, partial: !result.ok, ms: Date.now() - t0 });
         return { ok: true, matches: all.slice(0, GREP_MAX_RESULTS), truncated, partial: !result.ok };
     }
-    // Sync wrapper: validates name (throws synchronously), then returns Promise.
-    // Every kind, including 'method', is looked up in the index first.
     findSymbol(name, project, kind) {
         const parsed = (0, symbol_name_1.parseFindSymbolName)(name);
         if (!parsed)
             throw new Error('Invalid symbol name');
         return this.findSymbolFromIndex(parsed, project, kind);
     }
-    /**
-     * Whether `code_symbol.target` exists. A present result is cached for the
-     * process; an absent one is re-checked on every call. Propagates on a
-     * failing check, same as any other failed index query.
-     */
     async hasTargetColumn() {
         if (this.targetColumnPresent)
             return true;
@@ -870,7 +814,6 @@ class SearcherService {
             this.logger.debug('SearcherService: findSymbol result', { source: 'index', hits: hits.length, truncated, ms: Date.now() - t0 });
             if (hits.length > 0)
                 return { hits, truncated, grepFailed: false };
-            // GraphQL kinds never grep — an empty result just means no row yet (stale index).
             if (isGraphqlKind)
                 return { hits: [], truncated: false, grepFailed: false };
             if (parsed.form === 'quoted' || parsed.form === 'computed')
@@ -878,8 +821,7 @@ class SearcherService {
             return this.grepFindSymbol(parsed, project, kind);
         }
         catch (err) {
-            this.logger.warn('SearcherService: symbol index unavailable', { reason: err.message, ms: Date.now() - t0 });
-            // GraphQL kinds never grep — a failing index query propagates as an error response instead.
+            this.logger.warn('SearcherService: symbol index unavailable', { err, ms: Date.now() - t0 });
             if (isGraphqlKind)
                 throw err;
             if (parsed.form === 'quoted' || parsed.form === 'computed')
@@ -889,7 +831,7 @@ class SearcherService {
     }
     async grepFindSymbol(parsed, project, kind) {
         const t0 = Date.now();
-        const grepName = parsed.name; // qualified names are grepped by their last segment, no container filter
+        const grepName = parsed.name;
         this.logger.debug('SearcherService: findSymbol', { grepName, project, kind, source: 'grep' });
         const pattern = this.buildFindSymbolPattern(grepName, kind);
         if (pattern === null)
@@ -971,10 +913,6 @@ class SearcherService {
         }
         return { ok: true, tree: lines.join('\n') };
     }
-    /**
-     * The read tools' common front: workspace boundary, then existence and type.
-     * A missing file still in the index is `deleted`; otherwise `not_found`.
-     */
     async openableFile(relPath, absPath) {
         const loc = await this.checkRealLocation(relPath, absPath, 'file');
         if (!loc.ok)
@@ -990,13 +928,8 @@ class SearcherService {
                 return { ok: false, reason: 'deleted' };
             return { ok: false, reason: 'not_found', candidates: await this.candidatesOrNone(relPath, 'file') };
         }
-        // Checked before opening: a FIFO or device would block the reader.
         return stat.isFile() ? null : { ok: false, reason: 'not_a_file' };
     }
-    /**
-     * Streams the file's lines (as `readline` yields them) to `onLine` until it
-     * returns false. An open or read error discards everything read so far.
-     */
     async readLines(absPath, onLine) {
         const stream = this.fs.createReadStream(absPath);
         const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
@@ -1069,7 +1002,6 @@ class SearcherService {
         this.logger.debug('SearcherService: readFileRange result', { linesRead: lines.length, hasMore, ms: Date.now() - t0 });
         return { ok: true, filePath: relPath, startLine, endLine: Math.min(endLine, lastRead), lines, hasMore };
     }
-    /** Throws when `absDir` itself cannot be read; an unreadable subdirectory is marked in place. */
     async walkDir(absDir, currentDepth, maxDepth, pattern, lines) {
         const entries = await this.fs.readdir(absDir);
         entries.sort((a, b) => {
@@ -1101,11 +1033,6 @@ class SearcherService {
             }
         }
     }
-    /**
-     * ERE pattern for a grep-fallback kind, or null when that kind is never
-     * grepped (`function_property`/`method_signature` are index-only; a bare
-     * `constructor` search only makes sense when the name itself is `constructor`).
-     */
     buildFindSymbolPattern(name, kind) {
         if (kind === 'function_property' || kind === 'method_signature')
             return null;
@@ -1113,7 +1040,7 @@ class SearcherService {
             return null;
         if (kind === 'constructor')
             return name === 'constructor' ? `(^|[[:space:]])constructor[[:space:]]*\\(` : null;
-        const esc = name.replace(/\$/g, '\\$'); // ERE end-of-line metachar
+        const esc = name.replace(/\$/g, '\\$');
         const MODIFIER = '(public|private|protected|static|abstract|async|override)';
         const BOUNDARY = '(^|[^[:alnum:]_$])';
         const patterns = {
@@ -1130,7 +1057,6 @@ class SearcherService {
             return Object.values(patterns).join('|');
         return patterns[kind];
     }
-    /** 1-based index of the first whole-word occurrence of `name` in `line`, or -1. */
     static wholeWordIndex(line, name) {
         const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
         const re = new RegExp(`(?<![\\w$#])${escaped}(?![\\w$#])`);
@@ -1160,12 +1086,6 @@ class SearcherService {
             return 'method';
         return 'variable';
     }
-    /**
-     * Async wrapper around grep to avoid blocking the event loop. `ok: false`
-     * means grep could not be spawned (`output: null`) or exited with status ≥ 2,
-     * keeping whatever it printed — distinguishable from a clean "no matches",
-     * which is `ok: true, output: null`.
-     */
     spawnGrep(args) {
         return new Promise((resolve) => {
             const proc = (0, child_process_1.spawn)('grep', args, { stdio: ['ignore', 'pipe', 'pipe'] });
@@ -1180,12 +1100,11 @@ class SearcherService {
             });
             proc.stderr.on('data', () => { });
             proc.on('error', (err) => {
-                this.logger.error('SearcherService: grep spawn failed', { reason: err.message });
+                this.logger.error('SearcherService: grep spawn failed', { err });
                 resolve({ ok: false, output: null });
             });
             proc.on('close', (code) => {
                 const output = chunks.length === 0 ? null : Buffer.concat(chunks).toString('utf-8');
-                // grep returns 1 for "no matches" — not an error; 2+ is a real failure
                 if (code !== null && code >= 2) {
                     this.logger.warn('SearcherService: grep exited with code', { code });
                     resolve({ ok: false, output });

package/dist/src/services/VoyageEmbedder.d.ts

@@ -2,12 +2,6 @@ import type { Config } from '../config';
 import type { IEmbedder, InputType } from '../interfaces/IEmbedder';
 import type { ILogger } from '../interfaces/ILogger';
 import type { EmbedderDeps } from './OpenAICompatibleEmbedder';
-/**
- * Voyage AI embedder. Voyage's schema differs from OpenAI's: `input` is an array
- * of strings, `input_type` (`query` | `document`) is required for best quality,
- * and the optional `output_dimension` requests Matryoshka truncation. Response
- * is `{ data: [{ embedding, index }] }`.
- */
 export declare class VoyageEmbedder implements IEmbedder {
     private config;
     private logger;

package/dist/src/services/VoyageEmbedder.js

@@ -6,12 +6,6 @@ const config_1 = require("../config");
 const reranker_1 = require("./reranker");
 const http_retry_1 = require("./http-retry");
 const constants_1 = require("../constants");
-/**
- * Voyage AI embedder. Voyage's schema differs from OpenAI's: `input` is an array
- * of strings, `input_type` (`query` | `document`) is required for best quality,
- * and the optional `output_dimension` requests Matryoshka truncation. Response
- * is `{ data: [{ embedding, index }] }`.
- */
 class VoyageEmbedder {
     config;
     logger;