codesearch-mcp 0.2.0-alpha → 0.2.1-alpha

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

@@ -6,6 +6,7 @@ import * as schema from '../db/schema';
 type Schema = typeof schema;
 export type DrizzleDb = NodePgDatabase<Schema>;
 export type DrizzleTx = NodePgTransaction<Schema, ExtractTablesWithRelations<Schema>>;
+export declare const CURRENT_SYMBOL_INDEX_VERSION = 2;
 export declare class DatabaseService implements IDatabase {
     private config;
     private pool;
@@ -31,8 +32,20 @@ export declare class DatabaseService implements IDatabase {
     deleteFiles(project: string, filePaths: string[]): Promise<void>;
     listIndexedProjects(): Promise<string[]>;
     deleteProject(name: string): Promise<void>;
+    listProjectsWithIndexRows(): Promise<string[]>;
+    /**
+     * Among `projectNames` (or every project with rows when null), those with at
+     * least one row in `code_chunk`/`code_symbol` and a `symbol_index_version`
+     * below `CURRENT_SYMBOL_INDEX_VERSION` (a missing row counts as version 1).
+     * A missing `symbol_index_version` table (un-migrated DB, `rag-mcp`/`rag-web`
+     * bootstrapped with `initDb`) counts as "no marker rows" — every project with
+     * rows is then outdated. Any other database error propagates.
+     */
+    listOutdatedProjects(projectNames: string[] | null): Promise<string[]>;
+    upsertSymbolIndexVersion(project: string): Promise<void>;
     /** Guard against SQL injection — the dimension is interpolated into DDL. */
     private assertDim;
+    private assertMinPostgresVersion;
     private ensureDatabaseExists;
 }
 export {};

package/dist/src/services/DatabaseService.js

@@ -33,12 +33,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DatabaseService = void 0;
+exports.DatabaseService = exports.CURRENT_SYMBOL_INDEX_VERSION = void 0;
 const node_postgres_1 = require("drizzle-orm/node-postgres");
 const pg_1 = require("pg");
 const drizzle_orm_1 = require("drizzle-orm");
 const schema = __importStar(require("../db/schema"));
 const db_1 = require("../db");
+const MIN_PG_VERSION_NUM = 150000;
+exports.CURRENT_SYMBOL_INDEX_VERSION = 2;
 class DatabaseService {
     config;
     pool;
@@ -68,6 +70,12 @@ class DatabaseService {
     async initDbWithSchema() {
         await this.ensureDatabaseExists();
         await this.initDb();
+        // Read as the very first statement on the application database, before any
+        // CREATE TABLE / CREATE INDEX / ALTER TABLE / DROP — `NULLS NOT DISTINCT`
+        // (used below) requires PostgreSQL 15+, and the DROP/CREATE pair must never
+        // run against an older server (it would fail after the DROP and leave
+        // code_symbol without a unique index).
+        await this.assertMinPostgresVersion();
         // code_chunk table — created at the legacy default width (1024) so search
         // tools always have a table. IndexerService recreates it at the resolved
         // width before indexing when the active model's dimension differs.
@@ -130,7 +138,23 @@ class DatabaseService {
         }
         await this.query(`CREATE INDEX IF NOT EXISTS idx_symbol_name   ON code_symbol (name, project)`);
         await this.query(`CREATE INDEX IF NOT EXISTS idx_symbol_file   ON code_symbol (project, "filePath")`);
-        await this.query(`CREATE UNIQUE INDEX IF NOT EXISTS idx_symbol_unique ON code_symbol (project, "filePath", name, kind)`);
+        await this.query(`ALTER TABLE code_symbol ADD COLUMN IF NOT EXISTS container TEXT`);
+        await this.query(`ALTER TABLE code_symbol ADD COLUMN IF NOT EXISTS "isStatic" BOOLEAN NOT NULL DEFAULT false`);
+        // DDL is transactional in PostgreSQL — either both statements apply or
+        // neither does, so a failure here never leaves code_symbol without a
+        // unique index (the old idx_symbol_unique is dropped only once the new
+        // one is confirmed to exist).
+        await this.transaction(async (tx) => {
+            await tx.execute('DROP INDEX IF EXISTS idx_symbol_unique');
+            await tx.execute('CREATE UNIQUE INDEX IF NOT EXISTS idx_symbol_unique_v2 ' +
+                'ON code_symbol (project, "filePath", container, name, kind, line) NULLS NOT DISTINCT');
+        });
+        await this.query(`
+      CREATE TABLE IF NOT EXISTS symbol_index_version (
+        project TEXT PRIMARY KEY,
+        version INT NOT NULL
+      )
+    `);
         // code_call table
         await this.query(`
       CREATE TABLE IF NOT EXISTS code_call (
@@ -244,6 +268,50 @@ class DatabaseService {
             await tx.delete(db_1.codeDependency).where((0, drizzle_orm_1.eq)(db_1.codeDependency.project, name));
         });
     }
+    async listProjectsWithIndexRows() {
+        const rows = await this.query(`SELECT DISTINCT name FROM (
+         SELECT "serviceName" AS name FROM code_chunk
+         UNION
+         SELECT project AS name FROM code_symbol
+       ) t`);
+        return rows.map(r => r.name);
+    }
+    /**
+     * Among `projectNames` (or every project with rows when null), those with at
+     * least one row in `code_chunk`/`code_symbol` and a `symbol_index_version`
+     * below `CURRENT_SYMBOL_INDEX_VERSION` (a missing row counts as version 1).
+     * A missing `symbol_index_version` table (un-migrated DB, `rag-mcp`/`rag-web`
+     * bootstrapped with `initDb`) counts as "no marker rows" — every project with
+     * rows is then outdated. Any other database error propagates.
+     */
+    async listOutdatedProjects(projectNames) {
+        const rowsUnion = `
+      SELECT "serviceName" AS name FROM code_chunk
+      UNION
+      SELECT project AS name FROM code_symbol
+    `;
+        const filterSql = projectNames ? 'AND t.name = ANY($1)' : '';
+        const params = projectNames ? [projectNames] : [];
+        try {
+            const rows = await this.query(`SELECT DISTINCT t.name FROM (${rowsUnion}) t
+         WHERE NOT EXISTS (
+           SELECT 1 FROM symbol_index_version v
+           WHERE v.project = t.name AND v.version >= ${exports.CURRENT_SYMBOL_INDEX_VERSION}
+         )
+         ${filterSql}`, params);
+            return rows.map(r => r.name);
+        }
+        catch (err) {
+            if (!/relation "symbol_index_version" does not exist/i.test(err.message))
+                throw err;
+            const rows = await this.query(`SELECT DISTINCT t.name FROM (${rowsUnion}) t ${projectNames ? 'WHERE t.name = ANY($1)' : ''}`, params);
+            return rows.map(r => r.name);
+        }
+    }
+    async upsertSymbolIndexVersion(project) {
+        await this.query(`INSERT INTO symbol_index_version (project, version) VALUES ($1, $2)
+       ON CONFLICT (project) DO UPDATE SET version = EXCLUDED.version`, [project, exports.CURRENT_SYMBOL_INDEX_VERSION]);
+    }
     /** Guard against SQL injection — the dimension is interpolated into DDL. */
     assertDim(dimensions) {
         if (!Number.isInteger(dimensions) || dimensions <= 0 || dimensions > 2000) {
@@ -251,6 +319,20 @@ class DatabaseService {
         }
         return dimensions;
     }
+    async assertMinPostgresVersion() {
+        let versionNum;
+        try {
+            const rows = await this.query(`SELECT current_setting('server_version_num') AS v`);
+            versionNum = Number(rows[0]?.v);
+        }
+        catch (err) {
+            throw new Error(`Failed to read PostgreSQL server_version_num (requires PostgreSQL 15+): ${err.message}`);
+        }
+        if (!Number.isFinite(versionNum) || versionNum < MIN_PG_VERSION_NUM) {
+            throw new Error(`PostgreSQL 15+ is required (server_version_num=${versionNum}) — ` +
+                `the symbol index's unique index relies on NULLS NOT DISTINCT, added in PostgreSQL 15.`);
+        }
+    }
     async ensureDatabaseExists() {
         const { host, port, username, password, database } = this.config.db;
         const client = new pg_1.Client({ host, port, user: username, password, database: 'postgres' });

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

@@ -35,18 +35,6 @@ export declare class IndexerService {
     prepareEmbeddingSchema(): Promise<IndexMeta>;
     private reconcileIndex;
     private countChunks;
-    backfillSymbols(signal?: AbortSignal): Promise<{
-        total: number;
-        processed: number;
-        skipped: number;
-        failed: number;
-    }>;
-    backfillCalls(signal?: AbortSignal): Promise<{
-        total: number;
-        processed: number;
-        skipped: number;
-        failed: number;
-    }>;
     private writeDepEdges;
     scanAndIndex(dir: string, serviceName: string, force?: boolean, signal?: AbortSignal, preCollectedFiles?: string[], opts?: {
         rootTsConfigPath?: string;
@@ -55,8 +43,6 @@ export declare class IndexerService {
         removed: string[];
         failed: string[];
     }>;
-    private static inferRole;
-    private getEnrichedPrompt;
     private static hashContent;
     private ingestFile;
 }

package/dist/src/services/IndexerService.js

@@ -40,6 +40,8 @@ const crypto_1 = require("crypto");
 const cli_progress_1 = require("cli-progress");
 const drizzle_orm_1 = require("drizzle-orm");
 const owner_path_1 = require("../owner-path");
+const enriched_prompt_1 = require("../enriched-prompt");
+const symbol_rows_1 = require("../symbol-rows");
 const db_1 = require("../db");
 const file_utils_1 = require("../file-utils");
 const LoggerService_1 = require("./LoggerService");
@@ -124,97 +126,6 @@ class IndexerService {
             throw err;
         }
     }
-    async backfillSymbols(signal) {
-        const t0 = Date.now();
-        const rows = await this.db.query(`SELECT DISTINCT "serviceName", "filePath" FROM code_chunk ORDER BY "serviceName", "filePath"`);
-        this.logger.debug('IndexerService: backfillSymbols start', { total: rows.length });
-        let processed = 0, skipped = 0, failed = 0;
-        for (const { serviceName, filePath } of rows) {
-            if (signal?.aborted)
-                break;
-            const absPath = path.join(this.config.workspaceRoot, filePath);
-            const projectRoot = path.join(this.config.workspaceRoot, serviceName);
-            if (!fs.existsSync(absPath)) {
-                skipped++;
-                continue;
-            }
-            try {
-                const { symbols: rawSymbols } = await this.ast.analyzeFile(absPath, serviceName, projectRoot);
-                const symbols = [...new Map(rawSymbols.map(s => ({ ...s, filePath })).map(s => [`${s.name}:${s.kind}`, s])).values()].map(({ project, filePath: fp, name, kind, signature, line, col }) => ({ project, filePath: fp, name, kind, signature, line, col }));
-                await this.db.transaction(async (tx) => {
-                    await tx.delete(db_1.codeSymbol).where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(db_1.codeSymbol.project, serviceName), (0, drizzle_orm_1.eq)(db_1.codeSymbol.filePath, filePath)));
-                    if (symbols.length > 0) {
-                        await tx.insert(db_1.codeSymbol).values(symbols);
-                    }
-                });
-                processed++;
-            }
-            catch (err) {
-                const reason = err.message;
-                console.error(`  Failed: ${filePath} — ${reason}`);
-                this.logger.error('IndexerService: symbol backfill failed', { file: filePath, reason });
-                failed++;
-            }
-            const count = processed + failed;
-            if (count > 0 && count % 50 === 0) {
-                const msg = `  ${count}/${rows.length} files...`;
-                process.stdout.isTTY ? process.stdout.write(msg + '\r') : console.log(msg);
-            }
-        }
-        this.logger.debug('IndexerService: backfillSymbols done', { total: rows.length, processed, skipped, failed, ms: Date.now() - t0 });
-        return { total: rows.length, processed, skipped, failed };
-    }
-    async backfillCalls(signal) {
-        const t0 = Date.now();
-        const rows = await this.db.query(`SELECT DISTINCT "serviceName", "filePath" FROM code_chunk ORDER BY "serviceName", "filePath"`);
-        this.logger.debug('IndexerService: backfillCalls start', { total: rows.length });
-        let processed = 0, skipped = 0, failed = 0;
-        for (const { serviceName, filePath } of rows) {
-            if (signal?.aborted)
-                break;
-            const absPath = path.join(this.config.workspaceRoot, filePath);
-            const projectRoot = path.join(this.config.workspaceRoot, serviceName);
-            if (!fs.existsSync(absPath)) {
-                skipped++;
-                continue;
-            }
-            try {
-                const { calls: rawCalls } = await this.ast.analyzeFile(absPath, serviceName, projectRoot);
-                const calls = rawCalls
-                    .filter(c => c.calleeFile.startsWith(this.config.workspaceRoot))
-                    .map(c => ({
-                    project: serviceName,
-                    fromFile: filePath,
-                    fromSymbol: c.fromSymbol,
-                    calleeName: c.calleeName,
-                    calleeFile: path.relative(this.config.workspaceRoot, c.calleeFile),
-                    calleeSymbol: c.calleeSymbol,
-                    line: c.line,
-                    col: c.col,
-                }));
-                await this.db.transaction(async (tx) => {
-                    await tx.delete(db_1.codeCall).where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(db_1.codeCall.project, serviceName), (0, drizzle_orm_1.eq)(db_1.codeCall.fromFile, filePath)));
-                    if (calls.length > 0) {
-                        await tx.insert(db_1.codeCall).values(calls);
-                    }
-                });
-                processed++;
-            }
-            catch (err) {
-                const reason = err.message;
-                console.error(`  Failed: ${filePath} — ${reason}`);
-                this.logger.error('IndexerService: call backfill failed', { file: filePath, reason });
-                failed++;
-            }
-            const count = processed + failed;
-            if (count > 0 && count % 50 === 0) {
-                const msg = `  ${count}/${rows.length} files...`;
-                process.stdout.isTTY ? process.stdout.write(msg + '\r') : console.log(msg);
-            }
-        }
-        this.logger.debug('IndexerService: backfillCalls done', { total: rows.length, processed, skipped, failed, ms: Date.now() - t0 });
-        return { total: rows.length, processed, skipped, failed };
-    }
     async writeDepEdges(serviceName, relFilePath, edges, tx) {
         const run = async (t) => {
             await t.delete(db_1.codeDependency).where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(db_1.codeDependency.project, serviceName), (0, drizzle_orm_1.eq)(db_1.codeDependency.fromFile, relFilePath)));
@@ -231,7 +142,16 @@ class IndexerService {
         const startTime = Date.now();
         this.logger.debug('IndexerService: scanAndIndex start', { serviceName, dir, force });
         if (force) {
-            await this.db.query(`UPDATE code_chunk SET "lastModified" = NULL, "contentHash" = NULL WHERE "serviceName" = $1`, [serviceName]);
+            // Reset incremental state and clear the project's symbol/call rows in one
+            // transaction: a file whose re-ingestion later fails must hold no rows at
+            // all, never rows in the previous (pre-member-extraction) format.
+            await this.db.transaction(async (tx) => {
+                await tx.update(db_1.codeChunk)
+                    .set({ lastModified: null, contentHash: null })
+                    .where((0, drizzle_orm_1.eq)(db_1.codeChunk.serviceName, serviceName));
+                await tx.delete(db_1.codeSymbol).where((0, drizzle_orm_1.eq)(db_1.codeSymbol.project, serviceName));
+                await tx.delete(db_1.codeCall).where((0, drizzle_orm_1.eq)(db_1.codeCall.project, serviceName));
+            });
         }
         const files = preCollectedFiles ?? (0, file_utils_1.collectFiles)(dir, (0, file_utils_1.loadIgnore)(dir), dir);
         this.logger.debug('IndexerService: scanAndIndex files collected', { serviceName, count: files.length, force });
@@ -334,6 +254,12 @@ 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,
@@ -366,51 +292,6 @@ class IndexerService {
         }
         return { removed, failed };
     }
-    static inferRole(relPath) {
-        const p = relPath.toLowerCase();
-        if (p.includes('/services/') || p.endsWith('.service.ts'))
-            return 'Service';
-        if (p.includes('/controllers/') || p.endsWith('.controller.ts'))
-            return 'Controller';
-        if (p.includes('/entities/') || p.endsWith('.entity.ts'))
-            return 'Entity';
-        if (p.includes('/guards/') || p.endsWith('.guard.ts'))
-            return 'Guard';
-        if (p.includes('/commands/'))
-            return 'Command';
-        if (p.includes('/interfaces/'))
-            return 'Interface';
-        if (p.includes('/middleware/'))
-            return 'Middleware';
-        if (p.includes('/interceptors/'))
-            return 'Interceptor';
-        if (p.endsWith('.test.ts') || p.endsWith('.spec.ts') || p.includes('/tests/'))
-            return 'Test';
-        if (p.includes('/utils/') || p.includes('/helpers/') || p.endsWith('-utils.ts'))
-            return 'Utility';
-        return null;
-    }
-    getEnrichedPrompt(piece, relPath, serviceName, _meta, edges, symbols) {
-        const chunkStart = piece.startLine;
-        const chunkEnd = piece.endLine;
-        const lines = [];
-        lines.push(`Project: ${serviceName} | File: ${relPath}`);
-        const role = IndexerService.inferRole(relPath);
-        if (role)
-            lines.push(`Role: ${role}`);
-        const overlapping = symbols.filter(s => s.line != null &&
-            s.line <= chunkEnd &&
-            (s.endLine ?? s.line) >= chunkStart);
-        if (overlapping.length > 0) {
-            lines.push(`Symbols: ${overlapping.map(s => `${s.kind} ${s.name}`).join(', ')}`);
-        }
-        if (edges.length > 0) {
-            const depNames = [...new Set(edges.map(e => path.basename(e.toFile, path.extname(e.toFile)).split('.')[0]))];
-            lines.push(`Dependencies: ${depNames.join(', ')}`);
-        }
-        lines.push(`Code: ${piece.content}`);
-        return lines.join('\n');
-    }
     static hashContent(content) {
         return (0, crypto_1.createHash)('sha256').update(content).digest('hex');
     }
@@ -434,7 +315,7 @@ class IndexerService {
                 return { status: 'skipped', chunks: 0, pendingMtimeRefresh: relFilePath };
             }
             const tAst = Date.now();
-            const { edges: rawEdges, symbols: rawSymbols, calls: rawCalls, ownerRanges: rawOwnerRanges = [] } = analysis ?? { edges: [], symbols: [], calls: [] };
+            const { edges: rawEdges, symbols: rawSymbols, members: rawMembers = [], calls: rawCalls, ownerRanges: rawOwnerRanges = [], } = 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
@@ -457,8 +338,9 @@ class IndexerService {
                 line: c.line,
                 col: c.col,
             }));
-            // Normalize symbols: replace absolute filePath with workspace-relative, strip endLine (not stored)
-            const symbols = [...new Map(rawSymbols.map(s => ({ ...s, filePath: relFilePath })).map(s => [`${s.name}:${s.kind}`, s])).values()].map(({ project, filePath: fp, name, kind, signature, line, col }) => ({ project, filePath: fp, name, kind, signature, line, 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 }));
             const astMs = Date.now() - tAst;
             const chunks = await this.chunker.chunk(code, {
                 strategy: this.config.indexer.chunkStrategy,
@@ -466,20 +348,16 @@ class IndexerService {
                 symbols: rawSymbols,
             });
             const relPath = path.relative(projectRoot, filePath);
-            // Owner-path ranges: top-level symbols (container: null) + method ranges.
-            // Deepest range containing a chunk's start line wins → Class.method.
-            const ownerRanges = [
-                ...rawSymbols
-                    .filter(s => s.line != null)
-                    .map(s => ({ name: s.name, container: null, line: s.line, endLine: s.endLine ?? s.line })),
-                ...rawOwnerRanges,
-            ];
+            // Ownership ranges (decorator-inclusive, symbols ∪ members minus
+            // method_signature) are built by AstParserService — the deepest range
+            // containing a chunk's start line wins.
+            const ownerRanges = rawOwnerRanges;
             const t2 = Date.now();
             const records = [];
             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 => this.getEnrichedPrompt(piece, relPath, serviceName, meta ?? 'missing', edges, rawSymbols));
+                const prompts = batch.map(piece => (0, enriched_prompt_1.getEnrichedPrompt)(piece, relPath, serviceName, edges, rawSymbols));
                 const vectors = await this.embedder.embedBatch(prompts, 'document');
                 for (let j = 0; j < batch.length; j++) {
                     const piece = batch[j];
@@ -502,8 +380,8 @@ class IndexerService {
                 }
                 await this.writeDepEdges(serviceName, relFilePath, edges, tx);
                 await tx.delete(db_1.codeSymbol).where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(db_1.codeSymbol.project, serviceName), (0, drizzle_orm_1.eq)(db_1.codeSymbol.filePath, relFilePath)));
-                if (symbols.length > 0) {
-                    await tx.insert(db_1.codeSymbol).values(symbols);
+                if (symbolRows.length > 0) {
+                    await tx.insert(db_1.codeSymbol).values(symbolRows);
                 }
                 await tx.delete(db_1.codeCall).where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(db_1.codeCall.project, serviceName), (0, drizzle_orm_1.eq)(db_1.codeCall.fromFile, relFilePath)));
                 if (calls.length > 0) {

package/dist/src/services/McpServer.js

@@ -73,8 +73,8 @@ Pick one workflow based on what you need:
 - **read_file_range** — read a specific line range from any indexed file. Expects a **relative path** as returned by search_codebase.
 - **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 (function, class, type, interface, variable, method) is defined by exact name. Faster than semantic search when you know the name.
-- **get_callers** — find all call sites of a function or method by exact name. Uses the call graph index — faster and more precise than grep. Use after find_symbol to trace where a symbol is actually called.
+- **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.
 
@@ -86,7 +86,7 @@ Pick one workflow based on what you need:
 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 \`kind: "method"\` for class methods — grep matches lines where \`public\`, \`async\`, \`static\`, or \`override\` appears before the name. After locating a symbol, use \`get_callers\` to find all call sites — faster and more precise than grep (requires \`rag-index backfill --calls\` to have been run).
+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.
 
 ### Flow audit (mandatory steps — do not skip 3 and 4)

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

@@ -55,7 +55,7 @@ export interface GrepMatch {
     filePath: string;
     line: number;
 }
-export type SymbolKind = 'function' | 'class' | 'type' | 'interface' | 'variable' | 'method' | 'all';
+export type SymbolKind = 'function' | 'class' | 'type' | 'interface' | 'variable' | 'method' | 'get_accessor' | 'set_accessor' | 'constructor' | 'function_property' | 'method_signature' | 'all';
 export interface CallerRow {
     fromFile: string;
     fromSymbol: string | null;
@@ -69,6 +69,10 @@ export interface SymbolHit {
     column: number;
     kind: Exclude<SymbolKind, 'all'>;
     signature: string;
+    /** `container.name`, or `name` when the container is null. */
+    qualified: string;
+    isStatic: boolean;
+    source: 'index' | 'grep';
 }
 export declare class SearcherService {
     private db;
@@ -130,6 +134,14 @@ export declare class SearcherService {
     getDependencies(filePath: string, project: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
     getDependents(filePath: string, project: 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.
+     */
+    outdatedNotice(project: string | null): Promise<string | null>;
     grepSymbol(symbol: string, project: string, excludeFile: string): Promise<{
         matches: GrepMatch[];
         truncated: boolean;
@@ -137,6 +149,7 @@ export declare class SearcherService {
     findSymbol(name: string, project: string | null, kind: SymbolKind): Promise<{
         hits: SymbolHit[];
         truncated: boolean;
+        grepFailed: boolean;
     }>;
     private findSymbolFromIndex;
     private grepFindSymbol;
@@ -147,11 +160,19 @@ export declare class SearcherService {
     readFileAbsolute(absPath: string, maxLines: number): Promise<FileRangeResult>;
     readFileRange(filePath: string, startLine: number, endLine: number): Promise<FileRangeResult>;
     private walkDir;
+    /**
+     * 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`).
+     */
     private buildFindSymbolPattern;
+    /** 1-based index of the first whole-word occurrence of `name` in `line`, or -1. */
+    private static wholeWordIndex;
     private inferKind;
     /**
-     * Async wrapper around grep to avoid blocking the event loop.
-     * Returns stdout as a string, or null if grep returned no results or errored.
+     * 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`).
      */
     private spawnGrep;
 }