codesearch-mcp 0.2.0-alpha → 0.2.1-alpha

package/dist/src/services/SearcherService.js

@@ -41,6 +41,7 @@ const child_process_1 = require("child_process");
 const file_utils_1 = require("../file-utils");
 const MonorepoAwareDiscoveryService_1 = require("./MonorepoAwareDiscoveryService");
 const legacy_ollama_index_1 = require("./legacy-ollama-index");
+const symbol_name_1 = require("../symbol-name");
 const SILENT_LOGGER = {
     debug() { },
     info() { },
@@ -472,7 +473,22 @@ class SearcherService {
     async getCallers(symbol, project, calleeFile = null) {
         const t0 = Date.now();
         this.logger.debug('SearcherService: getCallers', { symbol, project, calleeFile });
-        const params = [symbol, project];
+        const parsed = (0, symbol_name_1.parseCallerSymbol)(symbol);
+        if (!parsed)
+            throw new Error('Invalid symbol name');
+        const params = [project];
+        let nameFilter;
+        if (parsed.form === 'bare') {
+            params.push(parsed.name);
+            nameFilter = `"calleeName" = $${params.length}`;
+        }
+        else {
+            params.push(`${parsed.container}.${parsed.name}`);
+            const exactParam = params.length;
+            params.push(`%.${(0, symbol_name_1.escapeLike)(parsed.container)}.${(0, symbol_name_1.escapeLike)(parsed.name)}`);
+            const suffixParam = params.length;
+            nameFilter = `("calleeSymbol" = $${exactParam} OR "calleeSymbol" LIKE $${suffixParam} ESCAPE '\\')`;
+        }
         let fileFilter = '';
         if (calleeFile) {
             params.push(calleeFile);
@@ -480,13 +496,32 @@ class SearcherService {
         }
         const rows = await this.db.query(`SELECT "fromFile", "fromSymbol", "calleeName", "calleeFile", line
        FROM code_call
-       WHERE "calleeName" = $1 AND project = $2
+       WHERE project = $1 AND ${nameFilter}
        ${fileFilter}
        ORDER BY "fromFile", line
        LIMIT 200`, params);
         this.logger.debug('SearcherService: getCallers result', { count: rows.length, ms: Date.now() - t0 });
         return rows;
     }
+    /**
+     * 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.
+     */
+    async outdatedNotice(project) {
+        try {
+            const outdated = await this.db.listOutdatedProjects(project ? [project] : null);
+            if (outdated.length === 0)
+                return null;
+            return `⚠ Indexed before member indexing: ${[...outdated].sort().join(', ')} — run rag-index --reindex; methods and qualified names may be missing.`;
+        }
+        catch (err) {
+            this.logger.warn('SearcherService: failed to determine outdated-index scope', { reason: err.message });
+            return null;
+        }
+    }
     async grepSymbol(symbol, project, excludeFile) {
         const t0 = Date.now();
         this.logger.debug('SearcherService: grepSymbol', { symbol, project, excludeFile });
@@ -499,11 +534,11 @@ class SearcherService {
             symbol,
             projectDir,
         ]);
-        if (!result) {
+        if (!result.ok || result.output === null) {
             return { matches: [], truncated: false };
         }
         const excludeAbsPath = path.join(this.config.workspaceRoot, excludeFile);
-        const all = result.split('\n').flatMap(line => {
+        const all = result.output.split('\n').flatMap(line => {
             const match = line.match(/^(.+?):(\d+):/);
             if (!match)
                 return [];
@@ -517,19 +552,29 @@ class SearcherService {
         return { matches: all.slice(0, GREP_MAX_RESULTS), truncated };
     }
     // Sync wrapper: validates name (throws synchronously), then returns Promise.
-    // Methods are never indexed — always resolved via grep. Other kinds use index with grep fallback.
+    // Every kind, including 'method', is looked up in the index first.
     findSymbol(name, project, kind) {
-        if (!/^[\w$]+$/.test(name))
+        const parsed = (0, symbol_name_1.parseFindSymbolName)(name);
+        if (!parsed)
             throw new Error('Invalid symbol name');
-        if (kind === 'method')
-            return this.grepFindSymbol(name, project, kind);
-        return this.findSymbolFromIndex(name, project, kind);
+        return this.findSymbolFromIndex(parsed, project, kind);
     }
-    async findSymbolFromIndex(name, project, kind) {
+    async findSymbolFromIndex(parsed, project, kind) {
         const t0 = Date.now();
-        this.logger.debug('SearcherService: findSymbol', { name, project, kind, source: 'index' });
+        this.logger.debug('SearcherService: findSymbol', { parsed, project, kind, source: 'index' });
+        const container = 'container' in parsed ? parsed.container : null;
         try {
-            const params = [name];
+            const params = [parsed.name];
+            let nameFilter = 'name = $1';
+            let orderPrefix = '';
+            if (container !== null) {
+                params.push(container);
+                const exactParam = params.length;
+                params.push(`%.${(0, symbol_name_1.escapeLike)(container)}`);
+                const suffixParam = params.length;
+                nameFilter += ` AND (container = $${exactParam} OR container LIKE $${suffixParam} ESCAPE '\\')`;
+                orderPrefix = `(CASE WHEN container = $${exactParam} THEN 0 ELSE 1 END), `;
+            }
             let projectFilter = '';
             if (project) {
                 params.push(project);
@@ -541,11 +586,11 @@ class SearcherService {
                 kindFilter = `AND kind = $${params.length}`;
             }
             params.push(FIND_SYMBOL_LIMIT + 1);
-            const rows = await this.db.query(`SELECT "filePath", name, kind, signature, line, col
-           FROM code_symbol
-           WHERE name = $1 ${projectFilter} ${kindFilter}
-           ORDER BY project, "filePath"
-           LIMIT $${params.length}`, params);
+            const rows = await this.db.query(`SELECT "filePath", name, kind, signature, line, col, container, "isStatic"
+         FROM code_symbol
+         WHERE ${nameFilter} ${projectFilter} ${kindFilter}
+         ORDER BY ${orderPrefix}project, "filePath", line
+         LIMIT $${params.length}`, params);
             const truncated = rows.length > FIND_SYMBOL_LIMIT;
             const hits = rows.slice(0, FIND_SYMBOL_LIMIT).map(row => ({
                 filePath: row.filePath,
@@ -553,22 +598,34 @@ class SearcherService {
                 column: row.col ?? 1,
                 kind: row.kind,
                 signature: row.signature ?? row.name,
+                qualified: row.container ? `${row.container}.${row.name}` : row.name,
+                isStatic: !!row.isStatic,
+                source: 'index',
             }));
             this.logger.debug('SearcherService: findSymbol result', { source: 'index', hits: hits.length, truncated, ms: Date.now() - t0 });
-            return { hits, truncated };
+            if (hits.length > 0)
+                return { hits, truncated, grepFailed: false };
+            if (parsed.form === 'quoted' || parsed.form === 'computed')
+                return { hits: [], truncated: false, grepFailed: false };
+            return this.grepFindSymbol(parsed, project, kind);
         }
-        catch {
-            this.logger.warn('SearcherService: symbol index unavailable, falling back to grep', { name, project, ms: Date.now() - t0 });
-            return this.grepFindSymbol(name, project, kind);
+        catch (err) {
+            this.logger.warn('SearcherService: symbol index unavailable, falling back to grep', { reason: err.message, ms: Date.now() - t0 });
+            if (parsed.form === 'quoted' || parsed.form === 'computed')
+                return { hits: [], truncated: false, grepFailed: false };
+            return this.grepFindSymbol(parsed, project, kind);
         }
     }
-    async grepFindSymbol(name, project, kind) {
+    async grepFindSymbol(parsed, project, kind) {
         const t0 = Date.now();
-        this.logger.debug('SearcherService: findSymbol', { name, project, kind, source: 'grep' });
+        const grepName = parsed.name; // qualified names are grepped by their last segment, no container filter
+        this.logger.debug('SearcherService: findSymbol', { grepName, project, kind, source: 'grep' });
+        const pattern = this.buildFindSymbolPattern(grepName, kind);
+        if (pattern === null)
+            return { hits: [], truncated: false, grepFailed: false };
         const searchDir = project
             ? this.resolveProjectRoot(project)
             : this.config.workspaceRoot;
-        const pattern = this.buildFindSymbolPattern(name, kind);
         const result = await this.spawnGrep([
             '-rn', '-E',
             '-m', String(FIND_SYMBOL_RAW_LIMIT),
@@ -577,12 +634,14 @@ class SearcherService {
             pattern,
             searchDir,
         ]);
-        if (!result)
-            return { hits: [], truncated: false };
-        const hits = [];
-        for (const raw of result.split('\n')) {
-            if (hits.length >= FIND_SYMBOL_LIMIT)
-                break;
+        if (!result.ok) {
+            this.logger.warn('SearcherService: findSymbol grep failed', { grepName, project });
+            return { hits: [], truncated: false, grepFailed: true };
+        }
+        if (result.output === null)
+            return { hits: [], truncated: false, grepFailed: false };
+        const parsedHits = [];
+        for (const raw of result.output.split('\n')) {
             const m = raw.match(/^(.+?):(\d+):(.*)$/);
             if (!m)
                 continue;
@@ -590,19 +649,23 @@ class SearcherService {
             const lineNum = parseInt(lineNumStr, 10);
             if (isNaN(lineNum))
                 continue;
-            const col = matchedLine.indexOf(name);
+            const col = SearcherService.wholeWordIndex(matchedLine, grepName);
             if (col === -1)
                 continue;
-            hits.push({
+            parsedHits.push({
                 filePath: path.relative(this.config.workspaceRoot, absFile),
                 line: lineNum,
                 column: col + 1,
-                kind: this.inferKind(matchedLine, name),
+                kind: this.inferKind(matchedLine, grepName),
                 signature: matchedLine.trim(),
+                qualified: grepName,
+                isStatic: false,
+                source: 'grep',
             });
         }
-        this.logger.debug('SearcherService: findSymbol result', { source: 'grep', hits: hits.length, truncated: hits.length >= FIND_SYMBOL_LIMIT, ms: Date.now() - t0 });
-        return { hits, truncated: hits.length >= FIND_SYMBOL_LIMIT };
+        const truncated = parsedHits.length > FIND_SYMBOL_LIMIT;
+        this.logger.debug('SearcherService: findSymbol result', { source: 'grep', hits: Math.min(parsedHits.length, FIND_SYMBOL_LIMIT), truncated, ms: Date.now() - t0 });
+        return { hits: parsedHits.slice(0, FIND_SYMBOL_LIMIT), truncated, grepFailed: false };
     }
     listFiles(relativePath, project, depth, pattern) {
         const t0 = Date.now();
@@ -740,36 +803,67 @@ 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;
+        if (kind === 'constructor')
+            return name === 'constructor' ? `(^|[[:space:]])constructor[[:space:]]*\\(` : null;
+        const esc = name.replace(/\$/g, '\\$'); // ERE end-of-line metachar
+        const MODIFIER = '(public|private|protected|static|abstract|async|override)';
+        const BOUNDARY = '(^|[^[:alnum:]_$])';
         const patterns = {
-            function: `(export[[:space:]]+)?(async[[:space:]]+)?function[[:space:]]+${name}[[:space:](<]`,
-            class: `(export[[:space:]]+)?(abstract[[:space:]]+)?class[[:space:]]+${name}[[:space:]{<]`,
-            type: `(export[[:space:]]+)?type[[:space:]]+${name}[[:space:]=<]`,
-            interface: `(export[[:space:]]+)?interface[[:space:]]+${name}[[:space:]{<]`,
-            variable: `(export[[:space:]]+)?(const|let|var)[[:space:]]+${name}[[:space:]=:]`,
-            method: `(public[[:space:]]+|async[[:space:]]+|static[[:space:]]+|override[[:space:]]+)+(async[[:space:]]+)?${name}[[:space:]]*[(<]`,
+            function: `(export[[:space:]]+)?(async[[:space:]]+)?function[[:space:]]+${esc}[[:space:](<]`,
+            class: `(export[[:space:]]+)?(abstract[[:space:]]+)?class[[:space:]]+${esc}[[:space:]{<]`,
+            type: `(export[[:space:]]+)?type[[:space:]]+${esc}[[:space:]=<]`,
+            interface: `(export[[:space:]]+)?interface[[:space:]]+${esc}[[:space:]{<]`,
+            variable: `(export[[:space:]]+)?(const|let|var)[[:space:]]+${esc}[[:space:]=:]`,
+            method: `${BOUNDARY}(${MODIFIER}[[:space:]]+)+\\*?[[:space:]]*${esc}[[:space:]]*[(<]`,
+            get_accessor: `(^|[[:space:]])get[[:space:]]+${esc}[[:space:]]*\\(`,
+            set_accessor: `(^|[[:space:]])set[[:space:]]+${esc}[[:space:]]*\\(`,
         };
         if (kind === 'all')
             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$#])`);
+        const m = re.exec(line);
+        return m ? m.index : -1;
+    }
     inferKind(line, name) {
-        const before = line.slice(0, line.indexOf(name));
-        if (/\bfunction\s+$/.test(before))
+        if (name === 'constructor')
+            return 'constructor';
+        const idx = SearcherService.wholeWordIndex(line, name);
+        const before = idx === -1 ? line : line.slice(0, idx);
+        const tokens = before.trim().split(/\s+/).filter(Boolean);
+        const last = (tokens[tokens.length - 1] ?? '').replace(/\*$/, '');
+        if (last === 'get')
+            return 'get_accessor';
+        if (last === 'set')
+            return 'set_accessor';
+        if (last === 'function')
             return 'function';
-        if (/\bclass\s+$/.test(before))
+        if (last === 'class')
             return 'class';
-        if (/\binterface\s+$/.test(before))
+        if (last === 'interface')
             return 'interface';
-        if (/\btype\s+$/.test(before))
+        if (last === 'type')
             return 'type';
-        if (/\b(public|async|static|override)\s+$/.test(before))
+        if (['public', 'private', 'protected', 'static', 'abstract', 'async', 'override'].includes(last))
             return 'method';
         return 'variable';
     }
     /**
-     * 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`).
      */
     spawnGrep(args) {
         return new Promise((resolve) => {
@@ -786,19 +880,16 @@ class SearcherService {
             proc.stderr.on('data', () => { });
             proc.on('error', (err) => {
                 this.logger.error('SearcherService: grep spawn failed', { reason: err.message });
-                resolve(null);
+                resolve({ ok: false });
             });
             proc.on('close', (code) => {
-                // grep returns 1 for "no matches" — not an error
-                if (code !== 0 && code !== 1) {
+                // 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 });
+                    return;
                 }
-                if (chunks.length === 0) {
-                    resolve(null);
-                }
-                else {
-                    resolve(Buffer.concat(chunks).toString('utf-8'));
-                }
+                resolve({ ok: true, output: chunks.length === 0 ? null : Buffer.concat(chunks).toString('utf-8') });
             });
         });
     }

package/dist/src/symbol-name.d.ts

@@ -0,0 +1,44 @@
+export declare const BARE_NAME_RE: RegExp;
+export declare const QUALIFIED_NAME_RE: RegExp;
+export type FindSymbolQuery = {
+    form: 'bare';
+    name: string;
+} | {
+    form: 'qualified';
+    container: string;
+    name: string;
+} | {
+    form: 'quoted';
+    container: string | null;
+    name: string;
+} | {
+    form: 'computed';
+    container: string | null;
+    name: string;
+};
+/** Split `P.n` into container `P` and last segment `n`. Requires a qualified name. */
+export declare function splitQualified(input: string): {
+    container: string;
+    name: string;
+};
+/**
+ * Parse a `find_symbol` name into one of the four accepted forms (bare,
+ * qualified, quoted, computed), or null when it matches none — the caller
+ * should reject with `Invalid symbol name` without querying anything.
+ */
+export declare function parseFindSymbolName(input: string): FindSymbolQuery | null;
+/**
+ * Parse a `get_callers` symbol into bare or qualified form only — the quoted
+ * and computed forms of `find_symbol` are meaningless here (calls through
+ * element access are never recorded in the call graph).
+ */
+export declare function parseCallerSymbol(input: string): {
+    form: 'bare';
+    name: string;
+} | {
+    form: 'qualified';
+    container: string;
+    name: string;
+} | null;
+/** Escape `%`, `_` and `\` for a `LIKE ... ESCAPE '\'` pattern. */
+export declare function escapeLike(s: string): string;

package/dist/src/symbol-name.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUALIFIED_NAME_RE = exports.BARE_NAME_RE = void 0;
+exports.splitQualified = splitQualified;
+exports.parseFindSymbolName = parseFindSymbolName;
+exports.parseCallerSymbol = parseCallerSymbol;
+exports.escapeLike = escapeLike;
+exports.BARE_NAME_RE = /^#?[\w$]+$/;
+exports.QUALIFIED_NAME_RE = /^#?[\w$]+(\.#?[\w$]+)+$/;
+const PFX_SRC = '(?:#?[\\w$]+(?:\\.#?[\\w$]+)*\\.)?';
+const QUOTED_RE = new RegExp(`^(${PFX_SRC})('[^'\\r\\n]+'|"[^"\\r\\n]+")$`);
+const COMPUTED_RE = new RegExp(`^(${PFX_SRC})(\\[[^\\]\\r\\n]+\\])$`);
+const MAX_QUOTED_COMPUTED_LEN = 256;
+/** Strip a qualified name's trailing `.` container prefix, if present. */
+function stripTrailingDot(prefix) {
+    if (!prefix)
+        return null;
+    return prefix.slice(0, -1);
+}
+/** Split `P.n` into container `P` and last segment `n`. Requires a qualified name. */
+function splitQualified(input) {
+    const idx = input.lastIndexOf('.');
+    return { container: input.slice(0, idx), name: input.slice(idx + 1) };
+}
+/**
+ * Parse a `find_symbol` name into one of the four accepted forms (bare,
+ * qualified, quoted, computed), or null when it matches none — the caller
+ * should reject with `Invalid symbol name` without querying anything.
+ */
+function parseFindSymbolName(input) {
+    if (input.length <= MAX_QUOTED_COMPUTED_LEN) {
+        const quoted = input.match(QUOTED_RE);
+        if (quoted) {
+            return { form: 'quoted', container: stripTrailingDot(quoted[1]), name: quoted[2].slice(1, -1) };
+        }
+        const computed = input.match(COMPUTED_RE);
+        if (computed) {
+            return { form: 'computed', container: stripTrailingDot(computed[1]), name: computed[2].replace(/\s+/g, '') };
+        }
+    }
+    if (exports.QUALIFIED_NAME_RE.test(input)) {
+        const { container, name } = splitQualified(input);
+        return { form: 'qualified', container, name };
+    }
+    if (exports.BARE_NAME_RE.test(input)) {
+        return { form: 'bare', name: input };
+    }
+    return null;
+}
+/**
+ * Parse a `get_callers` symbol into bare or qualified form only — the quoted
+ * and computed forms of `find_symbol` are meaningless here (calls through
+ * element access are never recorded in the call graph).
+ */
+function parseCallerSymbol(input) {
+    if (exports.QUALIFIED_NAME_RE.test(input)) {
+        const { container, name } = splitQualified(input);
+        return { form: 'qualified', container, name };
+    }
+    if (exports.BARE_NAME_RE.test(input)) {
+        return { form: 'bare', name: input };
+    }
+    return null;
+}
+/** Escape `%`, `_` and `\` for a `LIKE ... ESCAPE '\'` pattern. */
+function escapeLike(s) {
+    return s.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
+}

package/dist/src/symbol-rows.d.ts

@@ -0,0 +1,12 @@
+import type { SymbolEntry } from './interfaces/IAstParser';
+export type CodeSymbolRow = Pick<SymbolEntry, 'project' | 'filePath' | 'name' | 'kind' | 'signature' | 'line' | 'col' | 'container' | 'isStatic'>;
+/**
+ * Combine top-level symbols and members into the rows written to `code_symbol`.
+ * Overload signatures of one declaration — same `(container, name, kind,
+ * isStatic)` — collapse to a single representative row: the one with a body
+ * (the implementation) when present, otherwise the earliest by line (the first
+ * signature in source order). Static and instance members sharing a name are
+ * never collapsed into each other (`isStatic` is part of the group key). A
+ * final dedup by `(container, name, kind, line)` matches the DB's unique index.
+ */
+export declare function buildSymbolRows(symbols: SymbolEntry[], members: SymbolEntry[]): CodeSymbolRow[];

package/dist/src/symbol-rows.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSymbolRows = buildSymbolRows;
+/**
+ * Combine top-level symbols and members into the rows written to `code_symbol`.
+ * Overload signatures of one declaration — same `(container, name, kind,
+ * isStatic)` — collapse to a single representative row: the one with a body
+ * (the implementation) when present, otherwise the earliest by line (the first
+ * signature in source order). Static and instance members sharing a name are
+ * never collapsed into each other (`isStatic` is part of the group key). A
+ * final dedup by `(container, name, kind, line)` matches the DB's unique index.
+ */
+function buildSymbolRows(symbols, members) {
+    const groups = new Map();
+    for (const entry of [...symbols, ...members]) {
+        const key = JSON.stringify([entry.container, entry.name, entry.kind, entry.isStatic]);
+        const group = groups.get(key);
+        if (group)
+            group.push(entry);
+        else
+            groups.set(key, [entry]);
+    }
+    const collapsed = [];
+    for (const group of groups.values()) {
+        if (group.length === 1) {
+            collapsed.push(group[0]);
+            continue;
+        }
+        const implementation = group.find(e => e.hasBody);
+        collapsed.push(implementation ?? group.reduce((a, b) => ((a.line ?? 0) <= (b.line ?? 0) ? a : b)));
+    }
+    const dedup = new Map();
+    for (const entry of collapsed) {
+        const key = JSON.stringify([entry.container, entry.name, entry.kind, entry.line]);
+        dedup.set(key, entry);
+    }
+    return [...dedup.values()].map(({ project, filePath, name, kind, signature, line, col, container, isStatic }) => ({ project, filePath, name, kind, signature, line, col, container, isStatic }));
+}

package/dist/src/tools/FindSymbolTool.js

@@ -2,7 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FindSymbolTool = void 0;
 const format_helpers_1 = require("./format-helpers");
-const VALID_KINDS = ['function', 'class', 'type', 'interface', 'variable', 'method', 'all'];
+const VALID_KINDS = [
+    'function', 'class', 'type', 'interface', 'variable',
+    'method', 'get_accessor', 'set_accessor', 'constructor', 'function_property', 'method_signature',
+    'all',
+];
 class FindSymbolTool {
     searcher;
     constructor(searcher) {
@@ -11,11 +15,16 @@ class FindSymbolTool {
     definition() {
         return {
             name: 'find_symbol',
-            description: 'Find TypeScript/JavaScript symbol definitions (functions, classes, types, interfaces, variables, methods) by exact name. Use when you know the symbol name and want its definition location fast.',
+            description: 'Find TypeScript/JavaScript symbol definitions by exact name: top-level declarations (functions, classes, types, ' +
+                'interfaces, variables), 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 ' +
+                '(any container), a qualified name (`Class.method`, `NS.Class.method`), a quoted name for string-literal members ' +
+                "(`Router.'kebab-name'`), or a computed name (`Stack.[Symbol.iterator]`). Use when you know the symbol name and " +
+                'want its definition location fast.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    name: { type: 'string', description: 'Exact symbol name (case-sensitive, whole-word match)' },
+                    name: { type: 'string', description: 'Bare, qualified (Class.method), quoted, or computed symbol name (case-sensitive)' },
                     project: { type: 'string', description: 'Limit search to this project (optional). Use list_projects to find names.' },
                     kind: { type: 'string', enum: VALID_KINDS, description: 'Symbol kind filter. Default: all.' },
                 },
@@ -28,15 +37,29 @@ class FindSymbolTool {
         const project = args.project ? String(args.project) : null;
         const rawKind = args.kind;
         const kind = VALID_KINDS.includes(rawKind) ? rawKind : 'all';
-        const { hits, truncated } = await this.searcher.findSymbol(name, project, kind);
-        if (hits.length === 0) {
-            return (0, format_helpers_1.textResponse)(`No definitions found for symbol: ${name}`);
+        let parsed;
+        try {
+            parsed = await this.searcher.findSymbol(name, project, kind);
+        }
+        catch (err) {
+            return (0, format_helpers_1.errorResponse)(err.message);
         }
+        const { hits, truncated, grepFailed } = parsed;
+        const notice = await this.searcher.outdatedNotice(project);
         const lines = [];
+        if (notice)
+            lines.push(notice + '\n');
+        if (hits.length === 0) {
+            const suffix = grepFailed ? ' (grep fallback failed — see log)' : '';
+            lines.push(`No definitions found for symbol: ${name}${suffix}`);
+            return (0, format_helpers_1.textResponse)(lines.join('\n'));
+        }
         if (truncated)
             lines.push(`*(truncated to ${hits.length} results)*\n`);
         for (const h of hits) {
-            lines.push(`**${h.kind}** \`${h.filePath}\` line ${h.line}, col ${h.column}`);
+            const staticTag = h.isStatic ? ' static' : '';
+            const grepTag = h.source === 'grep' ? ' (grep — not in index; may be stale or imprecise)' : '';
+            lines.push(`**${h.kind}** \`${h.qualified}\`${staticTag} \`${h.filePath}\` line ${h.line}, col ${h.column}${grepTag}`);
             lines.push(`\`\`\`\n${h.signature}\n\`\`\``);
         }
         return (0, format_helpers_1.textResponse)(lines.join('\n'));

package/dist/src/tools/GetCallersTool.js

@@ -10,11 +10,15 @@ class GetCallersTool {
     definition() {
         return {
             name: 'get_callers',
-            description: '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. Returns empty if rag-index backfill --calls has not been run.',
+            description: 'Find all call sites of a function or method by exact name. Accepts a bare name (every call site with that ' +
+                'callee name) or a qualified name (`Class.method`, from find_symbol output) to disambiguate same-named methods ' +
+                'of different classes. 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.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    symbol: { type: 'string', description: 'Exact function or method name (case-sensitive)' },
+                    symbol: { type: 'string', description: 'Bare or qualified (Class.method) function/method name (case-sensitive)' },
                     project: { type: 'string', description: 'Project name (from list_projects)' },
                     callee_file: { type: 'string', description: 'Optional: filter by definition file path (as returned by find_symbol) to disambiguate overloaded names' },
                 },
@@ -26,11 +30,22 @@ class GetCallersTool {
         const symbol = String(args.symbol ?? '');
         const project = String(args.project ?? '');
         const calleeFile = args.callee_file ? String(args.callee_file) : null;
-        const rows = await this.searcher.getCallers(symbol, project, calleeFile);
+        let rows;
+        try {
+            rows = await this.searcher.getCallers(symbol, project, calleeFile);
+        }
+        catch (err) {
+            return (0, format_helpers_1.errorResponse)(err.message);
+        }
+        const notice = await this.searcher.outdatedNotice(project);
+        const lines = [];
+        if (notice)
+            lines.push(notice + '\n');
         if (rows.length === 0) {
-            return (0, format_helpers_1.textResponse)(`No call sites found for \`${symbol}\` in project \`${project}\`. Run \`rag-index backfill --calls\` if the call graph has not been populated yet.`);
+            lines.push(`No call sites found for \`${symbol}\` in project \`${project}\`. Run \`rag-index --reindex\` if the call graph has not been populated yet.`);
+            return (0, format_helpers_1.textResponse)(lines.join('\n'));
         }
-        const lines = [`**Call sites of \`${symbol}\`** (${rows.length} found)\n`];
+        lines.push(`**Call sites of \`${symbol}\`** (${rows.length} found)\n`);
         for (const r of rows) {
             const loc = r.line != null ? ` line ${r.line}` : '';
             const ctx = r.fromSymbol ? `, in \`${r.fromSymbol}\`` : '';