codesearch-mcp 0.2.2-alpha → 0.2.3-alpha

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

@@ -3,6 +3,7 @@ import type { IEmbedder } from '../interfaces/IEmbedder';
 import type { IAstParser } from '../interfaces/IAstParser';
 import type { IChunker } from '../interfaces/IChunker';
 import type { IDatabase } from '../interfaces/IDatabase';
+import type { DiscoveredProject } from '../interfaces/IProjectDiscovery';
 import type { ILogger } from '../interfaces/ILogger';
 import type { IndexMeta } from '../interfaces/IDatabase';
 export interface IndexStats {
@@ -39,6 +40,13 @@ export declare class IndexerService {
     scanAndIndex(dir: string, serviceName: string, force?: boolean, signal?: AbortSignal, preCollectedFiles?: string[], opts?: {
         rootTsConfigPath?: string;
     }): Promise<IndexStats>;
+    /**
+     * Scan several leaf projects in one call, each with its own `rootTsConfigPath`
+     * (a unit's children may belong to different monorepos). No pruning, no
+     * console output — callers (CLI or a future hook) own reporting. A rejecting
+     * `scanAndIndex` call stops the loop before the next target and propagates.
+     */
+    scanProjects(targets: DiscoveredProject[], force: boolean, signal: AbortSignal, filesPerProject: string[][]): Promise<IndexStats[]>;
     pruneProjects(keep: string[]): Promise<{
         removed: string[];
         failed: string[];

package/dist/src/services/IndexerService.js

@@ -254,12 +254,6 @@ class IndexerService {
             }
         }
         this.ast.clearCache(dir);
-        // The marker is written exactly when the scan reaches here without having
-        // been interrupted — never on the early-return abort path above, and never
-        // when anything in this method throws (the error propagates instead).
-        if (!signal?.aborted) {
-            await this.db.upsertSymbolIndexVersion(serviceName);
-        }
         stats.elapsedSec = Math.round((Date.now() - startTime) / 100) / 10;
         this.logger.debug('IndexerService: project indexed', {
             project: serviceName,
@@ -271,6 +265,22 @@ class IndexerService {
         });
         return stats;
     }
+    /**
+     * Scan several leaf projects in one call, each with its own `rootTsConfigPath`
+     * (a unit's children may belong to different monorepos). No pruning, no
+     * console output — callers (CLI or a future hook) own reporting. A rejecting
+     * `scanAndIndex` call stops the loop before the next target and propagates.
+     */
+    async scanProjects(targets, force, signal, filesPerProject) {
+        const allStats = [];
+        for (let i = 0; i < targets.length; i++) {
+            if (signal.aborted)
+                break;
+            const stats = await this.scanAndIndex(targets[i].path, targets[i].name, force, signal, filesPerProject[i], { rootTsConfigPath: targets[i].rootTsConfigPath ?? undefined });
+            allStats.push(stats);
+        }
+        return allStats;
+    }
     async pruneProjects(keep) {
         if (keep.length === 0)
             return { removed: [], failed: [] };
@@ -315,7 +325,7 @@ class IndexerService {
                 return { status: 'skipped', chunks: 0, pendingMtimeRefresh: relFilePath };
             }
             const tAst = Date.now();
-            const { edges: rawEdges, symbols: rawSymbols, members: rawMembers = [], calls: rawCalls, ownerRanges: rawOwnerRanges = [], } = analysis ?? { edges: [], symbols: [], calls: [] };
+            const { edges: rawEdges, symbols: rawSymbols, members: rawMembers = [], calls: rawCalls, ownerRanges: rawOwnerRanges = [], graphqlNames: rawGraphqlNames = [], } = analysis ?? { edges: [], symbols: [], calls: [] };
             // astMs is near-zero — actual AST time is spent upfront in analyzeProject()
             // Normalize edges to workspace-relative paths
             const edges = rawEdges
@@ -338,9 +348,12 @@ class IndexerService {
                 line: c.line,
                 col: c.col,
             }));
-            // symbols ∪ members → code_symbol rows: overload sets collapse to their
-            // representative row, then a final dedup by (container, name, kind, line).
-            const symbolRows = (0, symbol_rows_1.buildSymbolRows)(rawSymbols, rawMembers).map(s => ({ ...s, filePath: relFilePath }));
+            // symbols ∪ members ∪ graphqlNames → code_symbol rows: overload sets
+            // collapse to their representative row (graphqlNames bypass the
+            // collapse), then a final dedup by (container, name, kind, line).
+            const symbolRows = (0, symbol_rows_1.buildSymbolRows)(rawSymbols, rawMembers, rawGraphqlNames).map(s => ({ ...s, filePath: relFilePath }));
+            // Side-effect imports bind no name, so they stay out of the Dependencies: line.
+            const promptEdges = edges.filter(e => e.depType !== 'import-side-effect');
             const astMs = Date.now() - tAst;
             const chunks = await this.chunker.chunk(code, {
                 strategy: this.config.indexer.chunkStrategy,
@@ -357,7 +370,7 @@ class IndexerService {
             const embedBatchSize = this.config.embedding.batchSize;
             for (let i = 0; i < chunks.length; i += embedBatchSize) {
                 const batch = chunks.slice(i, i + embedBatchSize);
-                const prompts = batch.map(piece => (0, enriched_prompt_1.getEnrichedPrompt)(piece, relPath, serviceName, edges, rawSymbols));
+                const prompts = batch.map(piece => (0, enriched_prompt_1.getEnrichedPrompt)(piece, relPath, serviceName, promptEdges, rawSymbols));
                 const vectors = await this.embedder.embedBatch(prompts, 'document');
                 for (let j = 0; j < batch.length; j++) {
                     const piece = batch[j];

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

@@ -1,6 +1,13 @@
 import type { Config } from '../config';
 import type { ISearcher } from '../interfaces/ISearcher';
 import type { ILogger } from '../interfaces/ILogger';
+import type { IMcpToolHandler, ToolResponse } from '../interfaces/IMcpToolHandler';
+/**
+ * The dispatch logic behind `CallToolRequestSchema` — pulled out so it is testable
+ * without a live stdio transport. A rejecting handler becomes `Tool error: <message>`.
+ */
+export declare function dispatchTool(tools: Map<string, IMcpToolHandler>, name: string, args: Record<string, unknown>, logger: ILogger): Promise<ToolResponse>;
+export declare function buildInstructions(t: number): string;
 /**
  * McpServer — thin orchestration layer that delegates tool handling
  * to individual IMcpToolHandler implementations (Open/Closed Principle).

package/dist/src/services/McpServer.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.McpServer = void 0;
+exports.dispatchTool = dispatchTool;
+exports.buildInstructions = buildInstructions;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
@@ -48,6 +50,24 @@ function readPackageVersion() {
         return '0.0.0';
     }
 }
+/**
+ * The dispatch logic behind `CallToolRequestSchema` — pulled out so it is testable
+ * without a live stdio transport. A rejecting handler becomes `Tool error: <message>`.
+ */
+async function dispatchTool(tools, name, args, logger) {
+    const handler = tools.get(name);
+    if (!handler) {
+        return { isError: true, content: [{ type: 'text', text: `Unknown tool: ${name}` }] };
+    }
+    try {
+        return await handler.handle(args);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.error('McpServer: tool handler error', { tool: name, reason });
+        return { isError: true, content: [{ type: 'text', text: `Tool error: ${reason}` }] };
+    }
+}
 function buildInstructions(t) {
     return `
 You have access to a local code intelligence server. Use these tools to search codebases by meaning, navigate import graphs, look up symbol definitions, and read source files.
@@ -58,7 +78,7 @@ Pick one workflow based on what you need:
 
 | Type | Signals | Workflow |
 |---|---|---|
-| **Lookup** | "where is X defined", "find Y" | find_symbol (if name known) → search_codebase (if not found) |
+| **Lookup** | "where is X defined", "find Y" | find_symbol first when the exact name is known — exact and faster. Call search_codebase too, in parallel, when you also want surrounding context or the name might not match verbatim; fall back to it alone if find_symbol comes back empty. |
 | **Caller trace** | "who calls X", "find usages of Y", "what invokes Z" | find_symbol → get_callers |
 | **Conceptual** | "how does X work", "what is Y" | search_codebase → read_file_range |
 | **Flow audit** | "how does X connect to Y", "audit this flow", "trace the path" | search_codebase → **get_dependencies + get_dependents** → Grep |
@@ -68,26 +88,28 @@ Pick one workflow based on what you need:
 
 ## Tools
 
-- **list_projects** — call this first to see what projects are indexed and their exact names.
-- **search_codebase** — semantic search across indexed source files. Returns file path, line number, and a code chunk.
-- **read_file_range** — read a specific line range from any indexed file. Expects a **relative path** as returned by search_codebase.
+Every file or directory argument (\`file_path\`, \`callee_file\`, \`path\`) is workspace-relative, exactly as printed by search_codebase (e.g. \`my-app/src/index.ts\`; \`.\` is the workspace root) — copy paths between tools unchanged.
+
+- **list_projects** — call this first to see what projects are indexed, their exact names and their directories (\`path:\`).
+- **search_codebase** — semantic search across indexed source files. Returns file path, line number, and a code chunk. **Pass \`project\` whenever the target project is known or guessable from the question** — this workspace indexes many projects at once, and an unscoped query competes against all of them, which \`rerank\` cannot fix (reranking only reorders whatever the vector search already retrieved). Pass \`rerank: false\` for "what does X do" / "where is X" lookups described without an exact name — measurement shows reranking hurts these (-0.23 to -0.31 MRR@10). If you already know the exact symbol name, use \`find_symbol\` instead, not \`search_codebase\` — it is faster and exact, and the rerank setting does not matter there. Leave reranking at its default (omit \`rerank\`, or pass \`true\`) for conceptual/architectural queries, where it helps (+0.08 MRR@10).
+- **read_file_range** — read a specific line range from any file under the workspace, indexed or not.
 - **get_dependencies** — show what files a given file imports (direct or transitive). Use to understand what a file depends on.
 - **get_dependents** — show which files import a given file (reverse graph). Use before refactoring to find all callers.
 - **find_symbol** — find where a symbol is defined by exact name: top-level declarations, class/object-literal members (methods, get/set accessors, constructors, function properties), interface and type-literal method signatures, and namespace-level declarations. Accepts a bare name (\`assertUsersInOrg\`), a qualified name (\`RepairsService.assertUsersInOrg\`, \`NS.Parser.parse\`) to disambiguate same-named members, a quoted name for string-literal members (\`Router.'kebab-name'\`), or a computed name (\`Stack.[Symbol.iterator]\`). Faster than semantic search when you know the name.
 - **get_callers** — find all call sites of a function or method by exact name. Accepts a bare or qualified (\`Class.method\`) symbol, using the same suffix matching as \`find_symbol\`. Uses the call graph index — faster and more precise than grep. A call through an interface-typed receiver is recorded under the interface member (e.g. \`IEmbedder.embedBatch\`), not the implementing class. Use after find_symbol to trace where a symbol is actually called.
-- **list_files** — browse the directory tree of a project path. Use to understand project structure before reading files.
-- **read_file** — read a complete file by **absolute path** with line numbers. Truncates at max_lines with a hint to continue.
+- **list_files** — browse the directory tree of a directory. Use to understand project structure before reading files.
+- **read_file** — read a complete file with line numbers. Truncates at max_lines with a hint to continue.
 
 ## Recommended workflow
 
 ### Lookup / Conceptual
 1. Use \`list_projects\` to discover available projects before filtering by \`project\`.
-2. Use \`search_codebase\` to find relevant code by meaning. If your query uses an ambiguous term (e.g. "subscription" could mean pub/sub or billing), pass a lower \`threshold\` (e.g. \`0.40–0.45\`) to filter out weak matches.
+2. Use \`search_codebase\` to find relevant code by meaning. **Always pass \`project\` when the question names or implies one** — an unscoped search ranks candidates across every indexed project together, so an unrelated project's weak match can outrank the right project's real one. If your query uses an ambiguous term (e.g. "subscription" could mean pub/sub or billing), pass a lower \`threshold\` (e.g. \`0.40–0.45\`) to filter out weak matches.
 3. If a result looks **truncated or incomplete**, call \`read_file_range\` with the returned \`file_path\` and \`start_line\`.
 4. For exploratory searches where results span chunk boundaries, pass \`include_neighbors: true\`.
 5. To immediately see a file's imports and callers without extra tool calls, pass \`include_graph_context: true\` to \`search_codebase\`. Use this when doing a quick structural survey; switch to \`get_dependencies\`/\`get_dependents\` for full transitive graphs.
-6. Use \`find_symbol\` when you know the exact name — faster than semantic search. Use a qualified name (\`Class.method\`) to disambiguate same-named methods of different classes; a bare name searches every container. Hits marked \`(grep — not in index; may be stale or imprecise)\` come from a fallback text search, not the index — treat them as less reliable. After locating a symbol, use \`get_callers\` to find all call sites — faster and more precise than grep.
-7. Use \`list_files\` to explore project structure before diving into files. Use \`read_file\` to read a complete file by absolute path.
+6. Use \`find_symbol\` when you know the exact name — faster and exact, unlike semantic search. Use a qualified name (\`Class.method\`) to disambiguate same-named methods of different classes; a bare name searches every container. When you also want surrounding context (callers' intent, nearby helpers, how it's described elsewhere), call \`search_codebase\` in parallel rather than after — the two tools answer different questions and neither blocks the other. Hits marked \`(grep — not in index; may be stale or imprecise)\` come from a fallback text search, not the index — treat them as less reliable. After locating a symbol, use \`get_callers\` to find all call sites — faster and more precise than grep. For a NestJS GraphQL operation, resolve field or type, pass the matching \`graphql_query\`/\`graphql_mutation\`/\`graphql_subscription\`/\`graphql_field\`/\`graphql_type\` kind to look it up by the name the schema exposes, not the TypeScript declaration name.
+7. Use \`list_files\` to explore project structure before diving into files. Use \`read_file\` to read a complete file.
 
 ### Flow audit (mandatory steps — do not skip 3 and 4)
 1. Use \`list_projects\` to confirm project names.
@@ -97,8 +119,6 @@ Pick one workflow based on what you need:
 5. For each peripheral file found in steps 3–4: use \`read_file_range\` or \`find_symbol\` to inspect it.
 6. Only after steps 3–4 draw architectural conclusions — \`search_codebase\` alone misses peripheral files because they are semantically thin (configs, types, loaders contain no domain vocabulary).
 
-> **Note:** If \`get_dependencies\` / \`get_dependents\` return empty, the file likely uses path aliases (e.g. \`@core/\`, \`@/\`, \`@db/\`). Fall back to \`Grep\` on the symbol name across the project.
-
 ### Impact analysis
 1. \`get_dependents(target_file)\` — direct callers.
 2. \`get_dependents(target_file, transitive: true)\` — full reverse graph.
@@ -115,7 +135,7 @@ Pick one workflow based on what you need:
 
 ## Dependency graph
 
-\`get_dependencies\` and \`get_dependents\` require \`file_path\` (as returned by \`search_codebase\`) and \`project\` (from \`list_projects\`). Pass \`transitive: true\` for the full dependency chain. depType values: \`import\` | \`import-default\` | \`import-namespace\` | \`reexport\` | \`reexport-namespace\`. \`fromSymbol\` — the top-level class or function in the importing file that uses this import (null if ambiguous or not tracked).
+\`get_dependencies\` and \`get_dependents\` take \`file_path\` alone and list edges in every project. A path that names no file is an error, never an empty result. Pass \`transitive: true\` for the full dependency chain. depType values: \`import\` | \`import-default\` | \`import-namespace\` | \`import-side-effect\` | \`reexport\` | \`reexport-namespace\`. \`fromSymbol\` — the top-level class or function in the importing file that uses this import (null if ambiguous or not tracked).
 
 If \`get_dependents\` returns 0 results, add \`symbol\` (the exported name you care about) — this triggers a grep fallback that finds runtime usages in DI containers, string references, and dynamic lookups that the import graph misses.
 
@@ -161,27 +181,11 @@ class McpServer {
                         }],
                 };
             }
-            const handler = this.tools.get(req.params.name);
-            if (!handler) {
-                return {
-                    isError: true,
-                    content: [{ type: 'text', text: `Unknown tool: ${req.params.name}` }],
-                };
-            }
-            try {
-                const t0 = Date.now();
-                const result = await handler.handle((req.params.arguments ?? {}));
+            const t0 = Date.now();
+            const result = await dispatchTool(this.tools, req.params.name, (req.params.arguments ?? {}), this.logger);
+            if (!result.isError)
                 this.logger.debug('McpServer: tool handled', { tool: req.params.name, ms: Date.now() - t0 });
-                return result;
-            }
-            catch (err) {
-                const reason = err instanceof Error ? err.message : String(err);
-                this.logger.error('McpServer: tool handler error', { tool: req.params.name, reason });
-                return {
-                    isError: true,
-                    content: [{ type: 'text', text: `Tool error: ${reason}` }],
-                };
-            }
+            return result;
         });
         await server.connect(new stdio_js_1.StdioServerTransport());
         this.logger.info('McpServer: started', { version: this.version });
@@ -194,13 +198,13 @@ class McpServer {
         const handlers = [
             new tools_1.ListProjectsTool(this.searcher),
             new tools_1.SearchCodebaseTool(this.searcher, this.config.search.defaultLimit, this.config.search.maxLimit, this.config.search.similarityThreshold, this.logger),
-            new tools_1.ReadFileRangeTool(this.searcher),
-            new tools_1.GetDependenciesTool(this.searcher),
-            new tools_1.GetDependentsTool(this.searcher),
+            new tools_1.ReadFileRangeTool(this.searcher, this.logger),
+            new tools_1.GetDependenciesTool(this.searcher, this.logger),
+            new tools_1.GetDependentsTool(this.searcher, this.logger),
             new tools_1.FindSymbolTool(this.searcher),
-            new tools_1.GetCallersTool(this.searcher),
-            new tools_1.ListFilesTool(this.searcher),
-            new tools_1.ReadFileTool(this.searcher),
+            new tools_1.GetCallersTool(this.searcher, this.logger),
+            new tools_1.ListFilesTool(this.searcher, this.logger),
+            new tools_1.ReadFileTool(this.searcher, this.logger),
         ];
         const map = new Map();
         for (const h of handlers) {

package/dist/src/services/OpenAICompatibleEmbedder.js

@@ -51,7 +51,8 @@ class OpenAICompatibleEmbedder {
             const res = await this.doFetch(this.url, {
                 method: 'POST',
                 headers,
-                signal: AbortSignal.timeout(120_000),
+                // CPU inference of one batch of token-dense text (e.g. pseudo-localized strings) takes well over 2 min.
+                signal: AbortSignal.timeout(240_000),
                 body: JSON.stringify(body),
             });
             if (!res.ok) {

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

@@ -1,7 +1,8 @@
+import * as fs from 'fs';
 import type { Config } from '../config';
 import type { IEmbedder } from '../interfaces';
 import type { IDatabase } from '../interfaces';
-import { type ProjectMeta } from '../file-utils';
+import { type IndexingExclusion, type ProjectMeta } from '../file-utils';
 import type { ILogger } from '../interfaces';
 import type { IProjectDiscovery } from '../interfaces';
 export interface ChunkRow {
@@ -23,6 +24,58 @@ export interface GraphContext {
     imports: string[];
     usedBy: string[];
 }
+/** A tool path argument refused on its form alone, before any lookup. */
+export type PathRefusal = {
+    ok: false;
+    reason: 'invalid';
+    missing: boolean;
+} | {
+    ok: false;
+    reason: 'absolute';
+    relative: string;
+} | {
+    ok: false;
+    reason: 'outside_workspace';
+};
+export type ResolvedToolPath = {
+    ok: true;
+    relPath: string;
+    absPath: string;
+} | PathRefusal;
+export type NotIndexedExplanation = IndexingExclusion | {
+    kind: 'no_project';
+} | {
+    kind: 'project_not_indexed';
+    project: string;
+} | {
+    kind: 'unknown';
+};
+/** A well-formed path that leads to no readable data. */
+export type PathFailure = {
+    ok: false;
+    reason: 'outside_workspace';
+} | {
+    ok: false;
+    reason: 'unreadable';
+    code: string;
+} | {
+    ok: false;
+    reason: 'not_found';
+    candidates: string[];
+} | {
+    ok: false;
+    reason: 'deleted';
+} | {
+    ok: false;
+    reason: 'not_indexed';
+    explanation: NotIndexedExplanation;
+} | {
+    ok: false;
+    reason: 'not_a_file';
+} | {
+    ok: false;
+    reason: 'not_a_directory';
+};
 export type FileRangeResult = {
     ok: true;
     filePath: string;
@@ -30,10 +83,36 @@ export type FileRangeResult = {
     endLine: number;
     lines: string[];
     hasMore: boolean;
+} | PathFailure | {
+    ok: false;
+    reason: 'past_end';
+    lineCount: number;
+    startLine: number;
+} | {
+    ok: false;
+    reason: 'bad_range';
+    startLine: number;
+    endLine: number;
+};
+export type ListFilesResult = {
+    ok: true;
+    tree: string;
+} | PathFailure;
+export type GrepSymbolResult = {
+    ok: true;
+    matches: GrepMatch[];
+    truncated: boolean;
+    partial: boolean;
 } | {
     ok: false;
-    reason: 'not_indexed' | 'not_on_disk' | 'invalid_path';
 };
+/** Filesystem access of the path tools — injectable so error codes are testable without permissions. */
+export interface SearcherFs {
+    realpath(p: string): Promise<string>;
+    stat(p: string): Promise<fs.Stats>;
+    readdir(p: string): Promise<fs.Dirent[]>;
+    createReadStream(p: string): NodeJS.ReadableStream;
+}
 export interface DependencyRow {
     fromFile: string;
     fromSymbol: string | null;
@@ -50,12 +129,16 @@ export interface ProjectRow extends ProjectMeta {
     type?: 'app' | 'lib';
     /** Real filesystem root of the project (resolved via discovery). */
     path?: string;
+    /** `path` in workspace-relative form (`.` for the workspace root). */
+    relPath?: string;
+    /** Error code of `stat` on `path`, null when it exists. */
+    rootError?: string | null;
 }
 export interface GrepMatch {
     filePath: string;
     line: number;
 }
-export type SymbolKind = 'function' | 'class' | 'type' | 'interface' | 'variable' | 'method' | 'get_accessor' | 'set_accessor' | 'constructor' | 'function_property' | 'method_signature' | 'all';
+export type SymbolKind = 'function' | 'class' | 'type' | 'interface' | 'variable' | 'method' | 'get_accessor' | 'set_accessor' | 'constructor' | 'function_property' | 'method_signature' | 'graphql_query' | 'graphql_mutation' | 'graphql_subscription' | 'graphql_field' | 'graphql_type' | 'all';
 export interface CallerRow {
     fromFile: string;
     fromSymbol: string | null;
@@ -73,6 +156,8 @@ export interface SymbolHit {
     qualified: string;
     isStatic: boolean;
     source: 'index' | 'grep';
+    /** Qualified TypeScript name of the decorated declaration (GraphQL rows only); null otherwise. */
+    target: string | null;
 }
 export declare class SearcherService {
     private db;
@@ -80,7 +165,18 @@ export declare class SearcherService {
     private discovery;
     private config;
     private logger;
-    constructor(db: IDatabase, embedder: IEmbedder, discovery: IProjectDiscovery, config: Config, logger?: ILogger);
+    private readonly fs;
+    constructor(db: IDatabase, embedder: IEmbedder, discovery: IProjectDiscovery, config: Config, logger?: ILogger, fsDeps?: Partial<SearcherFs>);
+    /**
+     * 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`).
+     */
+    private targetColumnPresent;
+    /** Real path of `workspaceRoot`; cached only once resolved, so a transient failure is retried. */
+    private realRootCache?;
     /** Lazily-built, cached map of project name → real filesystem root. */
     private rootMap?;
     /** Cached, lazily-built map of leaf project name → real filesystem root (via discovery). */
@@ -92,6 +188,65 @@ export declare class SearcherService {
      * project since removed from disk, or a flat project not surfaced by discovery).
      */
     private resolveProjectRoot;
+    private toRel;
+    private toAbs;
+    private workspaceRoot;
+    private realWorkspaceRoot;
+    /**
+     * 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`.
+     */
+    resolveToolPath(input: string | null | undefined): Promise<ResolvedToolPath>;
+    /**
+     * 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.
+     */
+    private realLocation;
+    /**
+     * 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`.
+     */
+    checkRealLocation(relPath: string, absPath: string, kind: 'file' | 'dir'): Promise<{
+        ok: true;
+    } | Extract<PathFailure, {
+        reason: 'outside_workspace' | 'unreadable';
+    }>>;
+    private pathExists;
+    /** Whether any table of the index holds `relPath` (a canonical path, never `../…`). */
+    isIndexedPath(relPath: string): Promise<boolean>;
+    /** Whether the indexer read the file at `relPath`. */
+    isContentPath(relPath: string): Promise<boolean>;
+    private hasContentUnder;
+    /**
+     * 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.
+     */
+    findPathCandidates(relPath: string, kind: 'file' | 'dir'): Promise<string[]>;
+    /** `findPathCandidates`, with a failed lookup logged and answered by no candidates. */
+    private candidatesOrNone;
+    /**
+     * `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.
+     */
+    private substituteProjectName;
+    private findProjectRootByName;
+    /** Longest workspace-relative project root accepted by `match`; discovery is re-run once before giving up. */
+    private findProjectRoot;
+    /** Root directory (workspace-relative) of the project the text-search fallback for `relPath` runs in. */
+    fallbackRoot(relPath: string): string | 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.
+     */
+    checkGraphPath(relPath: string): Promise<PathFailure | null>;
+    private explainNotIndexed;
     /**
      * 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.
@@ -119,7 +274,7 @@ export declare class SearcherService {
     assertIndexMatches(): Promise<void>;
     private compareIndexed;
     listProjects(): Promise<ProjectRow[]>;
-    searchChunks(query: string, limit: number, project: string | null, threshold?: number): Promise<SearchResult[]>;
+    searchChunks(query: string, limit: number, project: string | null, threshold?: number, rerankOverride?: boolean): Promise<SearchResult[]>;
     /**
      * Emit one structured search-tuning line (via `logger.metric`, at `info`
      * regardless of `logging.level`). `candidates` are in cosine order, so a
@@ -131,34 +286,42 @@ export declare class SearcherService {
     private emitSearchMetrics;
     fetchNeighbors(results: SearchResult[]): Promise<NeighborResult[]>;
     fetchGraphContext(results: SearchResult[]): Promise<Map<string, GraphContext>>;
-    getDependencies(filePath: string, project: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
-    getDependents(filePath: string, project: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
+    getDependencies(filePath: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
+    getDependents(filePath: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
     getCallers(symbol: string, project: string, calleeFile?: string | null): Promise<CallerRow[]>;
     /**
-     * One-line warning when any project in `scope` (the given `project`, or
-     * every project with `code_chunk`/`code_symbol` rows) is outdated — shown
-     * first in `find_symbol`/`get_callers` output. Any failure to determine the
-     * scope or read markers only drops the notice (warn logged); the lookup
-     * itself is unaffected.
+     * 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.
      */
-    outdatedNotice(project: string | null): Promise<string | null>;
-    grepSymbol(symbol: string, project: string, excludeFile: string): Promise<{
-        matches: GrepMatch[];
-        truncated: boolean;
-    }>;
+    grepSymbol(symbol: string, rootDir: string, excludeFile: string): Promise<GrepSymbolResult>;
     findSymbol(name: string, project: string | null, kind: SymbolKind): Promise<{
         hits: SymbolHit[];
         truncated: boolean;
         grepFailed: boolean;
     }>;
+    /**
+     * 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.
+     */
+    private hasTargetColumn;
     private findSymbolFromIndex;
     private grepFindSymbol;
-    listFiles(relativePath: string, project: string, depth: number, pattern: string | null): {
-        tree: string;
-        error?: string;
-    };
-    readFileAbsolute(absPath: string, maxLines: number): Promise<FileRangeResult>;
-    readFileRange(filePath: string, startLine: number, endLine: number): Promise<FileRangeResult>;
+    listFiles(relPath: string, depth: number, pattern: string | null): Promise<ListFilesResult>;
+    /**
+     * The read tools' common front: workspace boundary, then existence and type.
+     * A missing file still in the index is `deleted`; otherwise `not_found`.
+     */
+    private openableFile;
+    /**
+     * 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.
+     */
+    private readLines;
+    readFile(relPath: string, maxLines: number): Promise<FileRangeResult>;
+    readFileRange(relPath: string, startLine: number, endLine: number): Promise<FileRangeResult>;
+    /** Throws when `absDir` itself cannot be read; an unreadable subdirectory is marked in place. */
     private walkDir;
     /**
      * ERE pattern for a grep-fallback kind, or null when that kind is never
@@ -171,8 +334,9 @@ export declare class SearcherService {
     private inferKind;
     /**
      * Async wrapper around grep to avoid blocking the event loop. `ok: false`
-     * means grep could not be spawned or exited with status ≥ 2 (distinguishable
-     * from a clean "no matches", which is `ok: true, output: null`).
+     * 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`.
      */
     private spawnGrep;
 }