codesearch-mcp 0.2.1-alpha → 0.2.3-alpha

package/dist/src/services/SearcherService.js

@@ -42,6 +42,7 @@ 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 dependency_traversal_1 = require("../dependency-traversal");
 const SILENT_LOGGER = {
     debug() { },
     info() { },
@@ -49,25 +50,71 @@ const SILENT_LOGGER = {
     error() { },
     metric() { },
 };
+const NODE_FS = {
+    realpath: p => fs.promises.realpath(p),
+    stat: p => fs.promises.stat(p),
+    readdir: p => fs.promises.readdir(p, { withFileTypes: true }),
+    createReadStream: p => fs.createReadStream(p, { encoding: 'utf-8' }),
+};
+const GRAPHQL_KINDS = new Set([
+    'graphql_query', 'graphql_mutation', 'graphql_subscription', 'graphql_field', 'graphql_type',
+]);
 const EMPTY_META = { description: null, stack: null, notes: null, relations: null };
 const GREP_MAX_RESULTS = 200;
 const GREP_RAW_LIMIT = GREP_MAX_RESULTS * 5;
 const GREP_EXCLUDE_DIRS = [...file_utils_1.IGNORE_DIRS].map(d => `--exclude-dir=${d}`);
 const FIND_SYMBOL_LIMIT = 50;
 const FIND_SYMBOL_RAW_LIMIT = FIND_SYMBOL_LIMIT * 10;
+const PATH_CANDIDATE_LIMIT = 3;
+/** Every path column of the index; `content` marks those whose file the indexer read. */
+const INDEX_PATH_COLUMNS = [
+    { table: 'code_chunk', column: '"filePath"', content: true },
+    { table: 'code_symbol', column: '"filePath"', content: true },
+    { table: 'code_dependency', column: '"fromFile"', content: true },
+    { table: 'code_call', column: '"fromFile"', content: true },
+    { table: 'code_dependency', column: '"toFile"', content: false },
+    { table: 'code_call', column: '"calleeFile"', content: false },
+];
+const OUTSIDE_WORKSPACE_VALUE = (col) => `(${col} = '..' OR ${col} LIKE '../%')`;
+function stripTrailingSlash(p) {
+    return p.length > 1 && p.endsWith('/') ? p.slice(0, -1) : p;
+}
+/** Segment-boundary containment: `/ws-other` is not within `/ws`; `.` contains every relative path. */
+function isWithin(p, root) {
+    if (root === '.')
+        return true;
+    if (root === '/')
+        return p.startsWith('/');
+    return p === root || p.startsWith(root + '/');
+}
+function errorCode(err) {
+    return err?.code ?? 'EIO';
+}
 class SearcherService {
     db;
     embedder;
     discovery;
     config;
     logger;
-    constructor(db, embedder, discovery, config, logger = SILENT_LOGGER) {
+    fs;
+    constructor(db, embedder, discovery, config, logger = SILENT_LOGGER, fsDeps = {}) {
         this.db = db;
         this.embedder = embedder;
         this.discovery = discovery;
         this.config = config;
         this.logger = logger;
+        this.fs = { ...NODE_FS, ...fsDeps };
     }
+    /**
+     * Whether `code_symbol.target` exists — `true` once a check finds it (never
+     * re-checked again in this process), `false` until then (re-checked on
+     * every lookup, so a `rag-index` run that adds the column takes effect
+     * without restarting `rag-mcp`). See "find_symbol works before the target
+     * column exists" (`graphql-symbols`).
+     */
+    targetColumnPresent = false;
+    /** Real path of `workspaceRoot`; cached only once resolved, so a transient failure is retried. */
+    realRootCache;
     /** Lazily-built, cached map of project name → real filesystem root. */
     rootMap;
     /** Cached, lazily-built map of leaf project name → real filesystem root (via discovery). */
@@ -95,6 +142,245 @@ class SearcherService {
         }
         return root ?? path.join(this.config.workspaceRoot, name);
     }
+    toRel(absPath) {
+        return path.relative(this.config.workspaceRoot, absPath) || '.';
+    }
+    toAbs(relPath) {
+        return relPath === '.' ? this.workspaceRoot() : path.join(this.workspaceRoot(), relPath);
+    }
+    workspaceRoot() {
+        return stripTrailingSlash(path.posix.normalize(this.config.workspaceRoot));
+    }
+    async realWorkspaceRoot() {
+        if (this.realRootCache !== undefined)
+            return this.realRootCache;
+        try {
+            this.realRootCache = await this.fs.realpath(this.workspaceRoot());
+            return this.realRootCache;
+        }
+        catch (err) {
+            this.logger.warn('SearcherService: workspaceRoot real path unavailable', { reason: errorCode(err) });
+            return null;
+        }
+    }
+    /**
+     * Lexical validation of a tool path argument: refusals for an empty value,
+     * `\`, an absolute path and a `..` escape; otherwise the canonical
+     * workspace-relative form. The only filesystem access is the cached real path
+     * of `workspaceRoot`.
+     */
+    async resolveToolPath(input) {
+        if (input == null || input === '')
+            return { ok: false, reason: 'invalid', missing: true };
+        if (input.includes('\\'))
+            return { ok: false, reason: 'invalid', missing: false };
+        if (path.posix.isAbsolute(input)) {
+            const abs = stripTrailingSlash(path.posix.normalize(input));
+            const realRoot = await this.realWorkspaceRoot();
+            for (const root of realRoot ? [this.workspaceRoot(), realRoot] : [this.workspaceRoot()]) {
+                if (!isWithin(abs, root))
+                    continue;
+                const relative = abs === root ? '.' : abs.slice(root === '/' ? 1 : root.length + 1);
+                return { ok: false, reason: 'absolute', relative };
+            }
+            return { ok: false, reason: 'outside_workspace' };
+        }
+        const relPath = stripTrailingSlash(path.posix.normalize(input));
+        if (relPath === '..' || relPath.startsWith('../'))
+            return { ok: false, reason: 'outside_workspace' };
+        return { ok: true, relPath, absPath: this.toAbs(relPath) };
+    }
+    /**
+     * Whether the real location of `absPath` — of the target, else of its nearest
+     * existing ancestor plus the remaining segments — lies under the real
+     * workspace root.
+     */
+    async realLocation(absPath) {
+        const root = (await this.realWorkspaceRoot()) ?? this.workspaceRoot();
+        let existing = absPath;
+        const rest = [];
+        for (;;) {
+            try {
+                const real = path.join(await this.fs.realpath(existing), ...rest);
+                return { ok: true, inside: isWithin(real, root) };
+            }
+            catch (err) {
+                if (errorCode(err) !== 'ENOENT')
+                    return { ok: false, code: errorCode(err) };
+                const parent = path.dirname(existing);
+                if (parent === existing)
+                    return { ok: true, inside: false };
+                rest.unshift(path.basename(existing));
+                existing = parent;
+            }
+        }
+    }
+    /**
+     * Workspace boundary of the disk tools. A real location outside the workspace
+     * is allowed only for content the indexer already read (a symlinked share):
+     * the file itself for `file`, any file below it for `dir`.
+     */
+    async checkRealLocation(relPath, absPath, kind) {
+        const loc = await this.realLocation(absPath);
+        if (!loc.ok)
+            return { ok: false, reason: 'unreadable', code: loc.code };
+        if (loc.inside)
+            return { ok: true };
+        const exempt = kind === 'file' ? await this.isContentPath(relPath) : await this.hasContentUnder(relPath);
+        return exempt ? { ok: true } : { ok: false, reason: 'outside_workspace' };
+    }
+    async pathExists(columns, predicate, param) {
+        const branches = columns.map(c => `SELECT 1 FROM ${c.table} WHERE ${predicate.replace(/\$col/g, c.column)}`);
+        const [{ exists }] = await this.db.query(`SELECT EXISTS (${branches.join(' UNION ALL ')}) AS exists`, [param]);
+        return exists;
+    }
+    /** Whether any table of the index holds `relPath` (a canonical path, never `../…`). */
+    isIndexedPath(relPath) {
+        return this.pathExists(INDEX_PATH_COLUMNS, '$col = $1', relPath);
+    }
+    /** Whether the indexer read the file at `relPath`. */
+    isContentPath(relPath) {
+        return this.pathExists(INDEX_PATH_COLUMNS.filter(c => c.content), '$col = $1', relPath);
+    }
+    hasContentUnder(relPath) {
+        const prefix = relPath === '.' ? '' : (0, symbol_name_1.escapeLike)(relPath) + '/';
+        return this.pathExists(INDEX_PATH_COLUMNS.filter(c => c.content), `$col LIKE $1 ESCAPE '\\'`, prefix + '%');
+    }
+    /**
+     * Up to three index paths ending in `/<relPath>` (`file`) or directories
+     * ending in `/<relPath>` that hold one (`dir`), in byte order. For `dir`, the
+     * root of a project named `relPath` comes first.
+     */
+    async findPathCandidates(relPath, kind) {
+        const union = INDEX_PATH_COLUMNS.map(c => `SELECT ${c.column} AS p FROM ${c.table}`).join(' UNION ALL ');
+        const notOutside = `NOT ${OUTSIDE_WORKSPACE_VALUE('p')}`;
+        if (kind === 'file') {
+            const substituted = await this.substituteProjectName(relPath);
+            const rows = await this.db.query(`SELECT p FROM (${union}) s
+         WHERE p LIKE $1 ESCAPE '\\' AND ${notOutside}
+         GROUP BY p ORDER BY p COLLATE "C" LIMIT ${PATH_CANDIDATE_LIMIT + 1}`, ['%/' + (0, symbol_name_1.escapeLike)(relPath)]);
+            const first = substituted ? [substituted] : [];
+            return [...first, ...rows.map(r => r.p).filter(p => p !== substituted)].slice(0, PATH_CANDIDATE_LIMIT);
+        }
+        const projectRoot = this.findProjectRootByName(relPath);
+        const first = projectRoot && projectRoot !== relPath ? [projectRoot] : [];
+        const rows = await this.db.query(`SELECT d AS p FROM (
+         SELECT substring(p FROM 1 FOR position($2::text IN p) + length($3::text)) AS d
+         FROM (${union}) s
+         WHERE p LIKE $1 ESCAPE '\\' AND ${notOutside}
+       ) dirs
+       GROUP BY d ORDER BY d COLLATE "C" LIMIT ${PATH_CANDIDATE_LIMIT + 1}`, ['%/' + (0, symbol_name_1.escapeLike)(relPath) + '/%', '/' + relPath + '/', relPath]);
+        const rest = rows.map(r => r.p).filter(p => !first.includes(p));
+        return [...first, ...rest].slice(0, PATH_CANDIDATE_LIMIT);
+    }
+    /** `findPathCandidates`, with a failed lookup logged and answered by no candidates. */
+    async candidatesOrNone(relPath, kind) {
+        try {
+            return await this.findPathCandidates(relPath, kind);
+        }
+        catch (err) {
+            this.logger.error('SearcherService: path candidate lookup failed', { relPath, reason: err.message });
+            return [];
+        }
+    }
+    /**
+     * `relPath` with a leading project name replaced by that project's root
+     * (`repo/app/src/x.ts` → `repo/apps/app/src/x.ts`), or null when no name
+     * prefixes it, the root equals the name, or the result names nothing.
+     */
+    async substituteProjectName(relPath) {
+        let named = [];
+        for (let attempt = 0; attempt < 2 && named.length === 0; attempt++) {
+            if (attempt === 1)
+                this.rootMap = undefined;
+            named = [...this.projectRootMap().entries()].filter(([name]) => relPath.startsWith(name + '/'));
+        }
+        const longest = named.sort((a, b) => b[0].length - a[0].length)[0];
+        if (!longest)
+            return null;
+        const [name, absRoot] = longest;
+        const root = this.toRel(absRoot);
+        if (root === name)
+            return null;
+        const candidate = (root === '.' ? '' : root + '/') + relPath.slice(name.length + 1);
+        if (await this.isIndexedPath(candidate))
+            return candidate;
+        try {
+            return (await this.fs.stat(this.toAbs(candidate))).isFile() ? candidate : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    findProjectRootByName(name) {
+        let root = this.projectRootMap().get(name);
+        if (root === undefined) {
+            this.rootMap = undefined;
+            root = this.projectRootMap().get(name);
+        }
+        return root === undefined ? null : this.toRel(root);
+    }
+    /** Longest workspace-relative project root accepted by `match`; discovery is re-run once before giving up. */
+    findProjectRoot(match) {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            if (attempt === 1)
+                this.rootMap = undefined;
+            const best = [...this.projectRootMap().entries()]
+                .map(([name, abs]) => ({ name, rel: this.toRel(abs) }))
+                .filter(r => match(r.rel))
+                .sort((a, b) => b.rel.length - a.rel.length)[0];
+            if (best)
+                return best;
+        }
+        return null;
+    }
+    /** Root directory (workspace-relative) of the project the text-search fallback for `relPath` runs in. */
+    fallbackRoot(relPath) {
+        return this.findProjectRoot(r => isWithin(relPath, r))?.rel ?? null;
+    }
+    /**
+     * Why a graph tool has no data for `relPath`, or null when the path is in the
+     * index path set. Touches the disk only for an unknown path, and answers a
+     * real location outside the workspace as `not_found` without looking at it.
+     */
+    async checkGraphPath(relPath) {
+        if (await this.isIndexedPath(relPath))
+            return null;
+        const absPath = this.toAbs(relPath);
+        const loc = await this.realLocation(absPath);
+        if (!loc.ok)
+            return { ok: false, reason: 'unreadable', code: loc.code };
+        if (!loc.inside)
+            return { ok: false, reason: 'not_found', candidates: await this.candidatesOrNone(relPath, 'file') };
+        let stat;
+        try {
+            stat = await this.fs.stat(absPath);
+        }
+        catch (err) {
+            if (errorCode(err) !== 'ENOENT')
+                return { ok: false, reason: 'unreadable', code: errorCode(err) };
+            return { ok: false, reason: 'not_found', candidates: await this.candidatesOrNone(relPath, 'file') };
+        }
+        if (!stat.isFile())
+            return { ok: false, reason: 'not_a_file' };
+        return { ok: false, reason: 'not_indexed', explanation: await this.explainNotIndexed(relPath) };
+    }
+    async explainNotIndexed(relPath) {
+        const owner = this.findProjectRoot(r => r !== relPath && isWithin(relPath, r));
+        if (!owner)
+            return { kind: 'no_project' };
+        const inProject = owner.rel === '.' ? relPath : relPath.slice(owner.rel.length + 1);
+        const exclusion = (0, file_utils_1.indexingExclusion)(inProject, (0, file_utils_1.loadIgnore)(this.toAbs(owner.rel)));
+        if (exclusion)
+            return exclusion;
+        const [{ exists }] = await this.db.query(`SELECT EXISTS (
+         SELECT 1 FROM code_chunk WHERE "serviceName" = $1
+         UNION ALL SELECT 1 FROM code_symbol WHERE project = $1
+         UNION ALL SELECT 1 FROM code_dependency WHERE project = $1
+         UNION ALL SELECT 1 FROM code_call WHERE project = $1
+       ) AS exists`, [owner.name]);
+        return exists ? { kind: 'unknown' } : { kind: 'project_not_indexed', project: owner.name };
+    }
     /**
      * Project-level dependency edges aggregated from `code_dependency`: an edge
      * `A → B` means some file in project A imports a file owned by project B.
@@ -182,17 +468,27 @@ class SearcherService {
        FROM code_chunk
        GROUP BY "serviceName"
        ORDER BY "serviceName"`);
-        return rows.map(r => {
+        return Promise.all(rows.map(async (r) => {
             const projectRoot = this.resolveProjectRoot(r.serviceName);
             const meta = (0, file_utils_1.readRagMeta)(projectRoot);
-            return { ...r, path: projectRoot, ...(typeof meta === 'object' ? meta : EMPTY_META) };
-        });
+            let rootError = null;
+            try {
+                await this.fs.stat(projectRoot);
+            }
+            catch (err) {
+                rootError = errorCode(err);
+            }
+            return {
+                ...r, path: projectRoot, relPath: this.toRel(projectRoot), rootError,
+                ...(typeof meta === 'object' ? meta : EMPTY_META),
+            };
+        }));
     }
-    async searchChunks(query, limit, project, threshold) {
+    async searchChunks(query, limit, project, threshold, rerankOverride) {
         const t0 = Date.now();
         await this.assertIndexMatches();
         const effectiveThreshold = threshold ?? this.config.search.similarityThreshold;
-        const reranking = !!this.embedder.rerank;
+        const reranking = rerankOverride === false ? false : !!this.embedder.rerank;
         // Candidate floor: decouple the pool size from `limit` so a small `limit`
         // (e.g. the default 5) still gives the reranker a large-enough menu. Without
         // a reranker the extra candidates are never reordered, so keep `limit`.
@@ -335,38 +631,28 @@ class SearcherService {
     }
     async fetchGraphContext(results) {
         const t0 = Date.now();
-        const seen = new Map();
-        for (const r of results) {
-            const key = `${r.serviceName}::${r.filePath}`;
-            if (!seen.has(key))
-                seen.set(key, { filePath: r.filePath, project: r.serviceName });
-        }
-        const pairs = [...seen.values()];
-        this.logger.debug('SearcherService: fetchGraphContext', { files: pairs.length });
-        if (pairs.length === 0)
+        const files = [...new Set(results.map(r => r.filePath))];
+        this.logger.debug('SearcherService: fetchGraphContext', { files: files.length });
+        if (files.length === 0)
             return new Map();
-        const n = pairs.length;
         // Use proportional limit: 50 imports + 50 usedBy per file
-        const proportionalLimit = Math.max(2000, n * 100);
-        const firstHalf = pairs.map((_, i) => `($${i * 2 + 1}::text, $${i * 2 + 2}::text)`).join(', ');
-        const secondHalf = pairs.map((_, i) => `($${n * 2 + i * 2 + 1}::text, $${n * 2 + i * 2 + 2}::text)`).join(', ');
-        const params = [
-            ...pairs.flatMap(p => [p.filePath, p.project]),
-            ...pairs.flatMap(p => [p.filePath, p.project]),
-        ];
+        const proportionalLimit = Math.max(2000, files.length * 100);
+        const values = files.map((_, i) => `($${i + 1}::text)`).join(', ');
         const rows = await this.db.query(`SELECT r.fp AS "filePath", 'import' AS direction, d."toFile" AS related
-         FROM (VALUES ${firstHalf}) AS r(fp, proj)
-         JOIN code_dependency d ON d."fromFile" = r.fp AND d.project = r.proj
+         FROM (VALUES ${values}) AS r(fp)
+         JOIN code_dependency d ON d."fromFile" = r.fp
+         WHERE NOT ${OUTSIDE_WORKSPACE_VALUE('d."toFile"')}
 
          UNION ALL
 
          SELECT r.fp AS "filePath", 'usedby' AS direction, d."fromFile" AS related
-         FROM (VALUES ${secondHalf}) AS r(fp, proj)
-         JOIN code_dependency d ON d."toFile" = r.fp AND d.project = r.proj
+         FROM (VALUES ${values}) AS r(fp)
+         JOIN code_dependency d ON d."toFile" = r.fp
+         WHERE NOT ${OUTSIDE_WORKSPACE_VALUE('d."fromFile"')}
 
-         LIMIT ${proportionalLimit}`, params);
+         LIMIT ${proportionalLimit}`, files);
         const ctx = new Map();
-        for (const { filePath } of pairs)
+        for (const filePath of files)
             ctx.set(filePath, { imports: new Set(), usedBy: new Set() });
         for (const row of rows) {
             const g = ctx.get(row.filePath);
@@ -375,7 +661,7 @@ class SearcherService {
             else
                 g.usedBy.add(row.related);
         }
-        this.logger.debug('SearcherService: fetchGraphContext result', { files: pairs.length, rows: rows.length, ms: Date.now() - t0 });
+        this.logger.debug('SearcherService: fetchGraphContext result', { files: files.length, rows: rows.length, ms: Date.now() - t0 });
         const result = new Map();
         for (const [fp, g] of ctx)
             result.set(fp, {
@@ -384,89 +670,63 @@ class SearcherService {
             });
         return result;
     }
-    async getDependencies(filePath, project, symbol = null, transitive = false) {
+    async getDependencies(filePath, symbol = null, transitive = false) {
         const t0 = Date.now();
-        this.logger.debug('SearcherService: getDependencies', { filePath, project, symbol, transitive });
-        const params = [filePath, project];
+        this.logger.debug('SearcherService: getDependencies', { filePath, symbol, transitive });
+        const params = [filePath];
         let symbolFilter = '';
         if (symbol) {
             params.push(symbol);
             symbolFilter = `AND "toSymbol" = $${params.length}`;
         }
-        const direct = await this.db.query(`SELECT "fromFile", "fromSymbol", "toFile", "toSymbol", "depType"
+        const direct = await this.db.query(`SELECT DISTINCT "fromFile", "fromSymbol", "toFile", "toSymbol", "depType"
        FROM code_dependency
-       WHERE "fromFile" = $1 AND project = $2
+       WHERE "fromFile" = $1 AND NOT ${OUTSIDE_WORKSPACE_VALUE('"toFile"')}
        ${symbolFilter}
        ORDER BY "toFile"`, params);
         if (!transitive) {
             this.logger.debug('SearcherService: getDependencies result', { direct: direct.length, ms: Date.now() - t0 });
             return direct;
         }
-        const indirect = await this.db.query(`WITH RECURSIVE deps AS (
-         SELECT "toFile", 1 AS depth, "toFile" AS via
-         FROM code_dependency
-         WHERE "fromFile" = $1 AND project = $2
-
-         UNION ALL
-
-         SELECT d."toFile", deps.depth + 1, deps."toFile" AS via
-         FROM code_dependency d
-         JOIN deps ON deps."toFile" = d."fromFile"
-         WHERE d.project = $2
-           AND d."toFile" <> $1
-           AND deps.depth < 20
-       )
-       SELECT "toFile", MIN(depth) AS depth,
-              (array_agg(via ORDER BY depth))[1] AS via,
-              NULL::text AS "fromFile", NULL::text AS "fromSymbol",
-              NULL::text AS "toSymbol", NULL::text AS "depType"
-       FROM deps
-       WHERE depth > 1
-       GROUP BY "toFile"
-       ORDER BY MIN(depth), "toFile"`, [filePath, project]);
+        const neighbours = async (frontier) => {
+            const rows = await this.db.query(`SELECT DISTINCT "fromFile", "toFile" FROM code_dependency
+         WHERE "fromFile" = ANY($1::text[]) AND NOT ${OUTSIDE_WORKSPACE_VALUE('"toFile"')}`, [frontier]);
+            return rows.map(r => ({ from: r.fromFile, to: r.toFile }));
+        };
+        const indirect = (await (0, dependency_traversal_1.traverse)(filePath, neighbours)).map(r => ({
+            toFile: r.file, depth: r.depth, via: r.via,
+            fromFile: null, fromSymbol: null, toSymbol: null, depType: null,
+        }));
         this.logger.debug('SearcherService: getDependencies result', { direct: direct.length, indirect: indirect.length, ms: Date.now() - t0 });
         return [...direct, ...indirect];
     }
-    async getDependents(filePath, project, symbol = null, transitive = false) {
+    async getDependents(filePath, symbol = null, transitive = false) {
         const t0 = Date.now();
-        this.logger.debug('SearcherService: getDependents', { filePath, project, symbol, transitive });
-        const params = [filePath, project];
+        this.logger.debug('SearcherService: getDependents', { filePath, symbol, transitive });
+        const params = [filePath];
         let symbolFilter = '';
         if (symbol) {
             params.push(symbol);
             symbolFilter = `AND "toSymbol" = $${params.length}`;
         }
-        const direct = await this.db.query(`SELECT "fromFile", "fromSymbol", "toFile", "toSymbol", "depType"
+        const direct = await this.db.query(`SELECT DISTINCT "fromFile", "fromSymbol", "toFile", "toSymbol", "depType"
        FROM code_dependency
-       WHERE "toFile" = $1 AND project = $2
+       WHERE "toFile" = $1 AND NOT ${OUTSIDE_WORKSPACE_VALUE('"fromFile"')}
        ${symbolFilter}
        ORDER BY "fromFile"`, params);
         if (!transitive) {
             this.logger.debug('SearcherService: getDependents result', { direct: direct.length, ms: Date.now() - t0 });
             return direct;
         }
-        const indirect = await this.db.query(`WITH RECURSIVE rdeps AS (
-         SELECT "fromFile", 1 AS depth, "fromFile" AS via
-         FROM code_dependency
-         WHERE "toFile" = $1 AND project = $2
-
-         UNION ALL
-
-         SELECT d."fromFile", rdeps.depth + 1, rdeps."fromFile" AS via
-         FROM code_dependency d
-         JOIN rdeps ON rdeps."fromFile" = d."toFile"
-         WHERE d.project = $2
-           AND d."fromFile" <> $1
-           AND rdeps.depth < 20
-       )
-       SELECT "fromFile", MIN(depth) AS depth,
-              (array_agg(via ORDER BY depth))[1] AS via,
-              NULL::text AS "toFile", NULL::text AS "fromSymbol",
-              NULL::text AS "toSymbol", NULL::text AS "depType"
-       FROM rdeps
-       WHERE depth > 1
-       GROUP BY "fromFile"
-       ORDER BY MIN(depth), "fromFile"`, [filePath, project]);
+        const neighbours = async (frontier) => {
+            const rows = await this.db.query(`SELECT DISTINCT "fromFile", "toFile" FROM code_dependency
+         WHERE "toFile" = ANY($1::text[]) AND NOT ${OUTSIDE_WORKSPACE_VALUE('"fromFile"')}`, [frontier]);
+            return rows.map(r => ({ from: r.toFile, to: r.fromFile }));
+        };
+        const indirect = (await (0, dependency_traversal_1.traverse)(filePath, neighbours)).map(r => ({
+            fromFile: r.file, depth: r.depth, via: r.via,
+            toFile: null, fromSymbol: null, toSymbol: null, depType: null,
+        }));
         this.logger.debug('SearcherService: getDependents result', { direct: direct.length, indirect: indirect.length, ms: Date.now() - t0 });
         return [...direct, ...indirect];
     }
@@ -504,41 +764,25 @@ class SearcherService {
         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.
+     * Whole-word text search for `symbol` under `rootDir` (workspace-relative).
+     * grep exiting ≥ 2 after printing matches is a partial result; without
+     * matches, or when grep cannot be spawned, the search failed.
      */
-    async 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) {
+    async grepSymbol(symbol, rootDir, excludeFile) {
         const t0 = Date.now();
-        this.logger.debug('SearcherService: grepSymbol', { symbol, project, excludeFile });
-        const projectDir = this.resolveProjectRoot(project);
+        this.logger.debug('SearcherService: grepSymbol', { symbol, rootDir, excludeFile });
         const result = await this.spawnGrep([
             '-rn', '-F', '-w',
             '-m', String(GREP_RAW_LIMIT),
             '--include=*.ts', '--include=*.tsx', '--include=*.js', '--include=*.jsx',
             ...GREP_EXCLUDE_DIRS,
             symbol,
-            projectDir,
+            this.toAbs(rootDir),
         ]);
-        if (!result.ok || result.output === null) {
-            return { matches: [], truncated: false };
-        }
+        if (!result.ok && result.output === null)
+            return { ok: false };
         const excludeAbsPath = path.join(this.config.workspaceRoot, excludeFile);
-        const all = result.output.split('\n').flatMap(line => {
+        const all = (result.output ?? '').split('\n').flatMap(line => {
             const match = line.match(/^(.+?):(\d+):/);
             if (!match)
                 return [];
@@ -548,8 +792,8 @@ class SearcherService {
             return [{ filePath: path.relative(this.config.workspaceRoot, absFile), line: parseInt(lineNum, 10) }];
         });
         const truncated = all.length > GREP_MAX_RESULTS;
-        this.logger.debug('SearcherService: grepSymbol result', { matches: Math.min(all.length, GREP_MAX_RESULTS), truncated, ms: Date.now() - t0 });
-        return { matches: all.slice(0, GREP_MAX_RESULTS), truncated };
+        this.logger.debug('SearcherService: grepSymbol result', { matches: Math.min(all.length, GREP_MAX_RESULTS), truncated, partial: !result.ok, ms: Date.now() - t0 });
+        return { ok: true, matches: all.slice(0, GREP_MAX_RESULTS), truncated, partial: !result.ok };
     }
     // Sync wrapper: validates name (throws synchronously), then returns Promise.
     // Every kind, including 'method', is looked up in the index first.
@@ -559,11 +803,30 @@ class SearcherService {
             throw new Error('Invalid symbol name');
         return this.findSymbolFromIndex(parsed, project, kind);
     }
+    /**
+     * Whether `code_symbol.target` exists. A present result is cached for the
+     * process; an absent one is re-checked on every call. Propagates on a
+     * failing check, same as any other failed index query.
+     */
+    async hasTargetColumn() {
+        if (this.targetColumnPresent)
+            return true;
+        const rows = await this.db.query(`SELECT EXISTS (
+         SELECT 1 FROM information_schema.columns
+         WHERE table_schema = 'public' AND table_name = 'code_symbol' AND column_name = 'target'
+       ) AS present`);
+        const present = !!rows[0]?.present;
+        if (present)
+            this.targetColumnPresent = true;
+        return present;
+    }
     async findSymbolFromIndex(parsed, project, kind) {
         const t0 = Date.now();
         this.logger.debug('SearcherService: findSymbol', { parsed, project, kind, source: 'index' });
         const container = 'container' in parsed ? parsed.container : null;
+        const isGraphqlKind = GRAPHQL_KINDS.has(kind);
         try {
+            const hasTarget = await this.hasTargetColumn();
             const params = [parsed.name];
             let nameFilter = 'name = $1';
             let orderPrefix = '';
@@ -586,10 +849,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, container, "isStatic"
+            const targetSelect = hasTarget ? '"target"' : 'NULL AS target';
+            const rows = await this.db.query(`SELECT "filePath", name, kind, signature, line, col, container, "isStatic", ${targetSelect}
          FROM code_symbol
          WHERE ${nameFilter} ${projectFilter} ${kindFilter}
-         ORDER BY ${orderPrefix}project, "filePath", line
+         ORDER BY ${orderPrefix}project, "filePath", line, col, kind COLLATE "C", container COLLATE "C" NULLS FIRST
          LIMIT $${params.length}`, params);
             const truncated = rows.length > FIND_SYMBOL_LIMIT;
             const hits = rows.slice(0, FIND_SYMBOL_LIMIT).map(row => ({
@@ -601,16 +865,23 @@ class SearcherService {
                 qualified: row.container ? `${row.container}.${row.name}` : row.name,
                 isStatic: !!row.isStatic,
                 source: 'index',
+                target: row.target ?? null,
             }));
             this.logger.debug('SearcherService: findSymbol result', { source: 'index', hits: hits.length, truncated, ms: Date.now() - t0 });
             if (hits.length > 0)
                 return { hits, truncated, grepFailed: false };
+            // GraphQL kinds never grep — an empty result just means no row yet (stale index).
+            if (isGraphqlKind)
+                return { hits: [], truncated: false, grepFailed: false };
             if (parsed.form === 'quoted' || parsed.form === 'computed')
                 return { hits: [], truncated: false, grepFailed: false };
             return this.grepFindSymbol(parsed, project, kind);
         }
         catch (err) {
-            this.logger.warn('SearcherService: symbol index unavailable, falling back to grep', { reason: err.message, ms: Date.now() - t0 });
+            this.logger.warn('SearcherService: symbol index unavailable', { reason: err.message, ms: Date.now() - t0 });
+            // GraphQL kinds never grep — a failing index query propagates as an error response instead.
+            if (isGraphqlKind)
+                throw err;
             if (parsed.form === 'quoted' || parsed.form === 'computed')
                 return { hits: [], truncated: false, grepFailed: false };
             return this.grepFindSymbol(parsed, project, kind);
@@ -661,124 +932,146 @@ class SearcherService {
                 qualified: grepName,
                 isStatic: false,
                 source: 'grep',
+                target: null,
             });
         }
         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) {
+    async listFiles(relPath, depth, pattern) {
         const t0 = Date.now();
-        this.logger.debug('SearcherService: listFiles', { relativePath, project, depth, pattern });
-        const projectRoot = this.resolveProjectRoot(project);
-        const resolvedTarget = path.resolve(projectRoot, relativePath);
-        const resolvedProject = path.resolve(projectRoot);
-        if (resolvedTarget !== resolvedProject && !resolvedTarget.startsWith(resolvedProject + path.sep)) {
-            return { tree: '', error: 'Path escapes project root' };
-        }
-        if (!fs.existsSync(resolvedTarget)) {
-            return { tree: '', error: `Path not found: ${relativePath}` };
+        this.logger.debug('SearcherService: listFiles', { relPath, depth, pattern });
+        const absPath = this.toAbs(relPath);
+        const loc = await this.checkRealLocation(relPath, absPath, 'dir');
+        if (!loc.ok)
+            return loc;
+        let stat;
+        try {
+            stat = await this.fs.stat(absPath);
         }
-        if (!fs.statSync(resolvedTarget).isDirectory()) {
-            return { tree: '', error: `Not a directory: ${relativePath}` };
+        catch (err) {
+            if (errorCode(err) !== 'ENOENT')
+                return { ok: false, reason: 'unreadable', code: errorCode(err) };
+            return { ok: false, reason: 'not_found', candidates: await this.candidatesOrNone(relPath, 'dir') };
         }
+        if (!stat.isDirectory())
+            return { ok: false, reason: 'not_a_directory' };
         const clampedDepth = Math.min(5, Math.max(1, depth));
         const lines = [];
-        this.walkDir(resolvedTarget, 0, clampedDepth - 1, pattern, lines);
+        try {
+            await this.walkDir(absPath, 0, clampedDepth - 1, pattern, lines);
+        }
+        catch (err) {
+            return { ok: false, reason: 'unreadable', code: errorCode(err) };
+        }
         this.logger.debug('SearcherService: listFiles result', { entries: lines.length, ms: Date.now() - t0 });
         if (lines.length === 0) {
-            return { tree: pattern ? `No files matching "${pattern}" found.` : '(empty directory)' };
+            return { ok: true, tree: pattern ? `No files matching "${pattern}" found.` : '(empty directory)' };
         }
-        return { tree: lines.join('\n') };
+        return { ok: true, tree: lines.join('\n') };
     }
-    async readFileAbsolute(absPath, maxLines) {
-        const t0 = Date.now();
-        this.logger.debug('SearcherService: readFileAbsolute', { absPath, maxLines });
-        const resolvedRoot = path.resolve(this.config.workspaceRoot);
-        const resolved = path.resolve(absPath);
-        if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + path.sep)) {
-            return { ok: false, reason: 'invalid_path' };
-        }
-        if (!fs.existsSync(resolved))
-            return { ok: false, reason: 'not_on_disk' };
-        const lines = [];
-        const stream = fs.createReadStream(resolved, { encoding: 'utf-8' });
+    /**
+     * The read tools' common front: workspace boundary, then existence and type.
+     * A missing file still in the index is `deleted`; otherwise `not_found`.
+     */
+    async openableFile(relPath, absPath) {
+        const loc = await this.checkRealLocation(relPath, absPath, 'file');
+        if (!loc.ok)
+            return loc;
+        let stat;
+        try {
+            stat = await this.fs.stat(absPath);
+        }
+        catch (err) {
+            if (errorCode(err) !== 'ENOENT')
+                return { ok: false, reason: 'unreadable', code: errorCode(err) };
+            if (await this.isIndexedPath(relPath))
+                return { ok: false, reason: 'deleted' };
+            return { ok: false, reason: 'not_found', candidates: await this.candidatesOrNone(relPath, 'file') };
+        }
+        // Checked before opening: a FIFO or device would block the reader.
+        return stat.isFile() ? null : { ok: false, reason: 'not_a_file' };
+    }
+    /**
+     * Streams the file's lines (as `readline` yields them) to `onLine` until it
+     * returns false. An open or read error discards everything read so far.
+     */
+    async readLines(absPath, onLine) {
+        const stream = this.fs.createReadStream(absPath);
         const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
         let lineNo = 0;
-        let hasMore = false;
         try {
             for await (const line of rl) {
                 lineNo++;
-                if (lineNo <= maxLines) {
-                    lines.push(line);
-                }
-                else {
-                    hasMore = true;
-                    rl.close();
-                    stream.destroy();
+                if (!onLine(line, lineNo))
                     break;
-                }
             }
+            return { ok: true, lineCount: lineNo };
         }
         catch (err) {
+            return { ok: false, code: errorCode(err) };
+        }
+        finally {
             rl.close();
-            stream.destroy();
-            throw err;
+            stream.destroy?.();
         }
-        const relPath = path.relative(resolvedRoot, resolved);
-        this.logger.debug('SearcherService: readFileAbsolute result', { linesRead: lines.length, hasMore, ms: Date.now() - t0 });
+    }
+    async readFile(relPath, maxLines) {
+        const t0 = Date.now();
+        this.logger.debug('SearcherService: readFile', { relPath, maxLines });
+        const absPath = this.toAbs(relPath);
+        const failure = await this.openableFile(relPath, absPath);
+        if (failure)
+            return failure;
+        const lines = [];
+        let hasMore = false;
+        const read = await this.readLines(absPath, line => {
+            if (lines.length < maxLines) {
+                lines.push(line);
+                return true;
+            }
+            hasMore = true;
+            return false;
+        });
+        if (!read.ok)
+            return { ok: false, reason: 'unreadable', code: read.code };
+        this.logger.debug('SearcherService: readFile result', { linesRead: lines.length, hasMore, ms: Date.now() - t0 });
         return { ok: true, filePath: relPath, startLine: 1, endLine: lines.length, lines, hasMore };
     }
-    async readFileRange(filePath, startLine, endLine) {
+    async readFileRange(relPath, startLine, endLine) {
         const t0 = Date.now();
-        this.logger.debug('SearcherService: readFileRange', { filePath, startLine, endLine });
-        const resolvedRoot = path.resolve(this.config.workspaceRoot);
-        const absPath = path.resolve(resolvedRoot, filePath);
-        if (absPath !== resolvedRoot && !absPath.startsWith(resolvedRoot + path.sep)) {
-            return { ok: false, reason: 'invalid_path' };
-        }
-        const [{ exists }] = await this.db.query(`SELECT EXISTS (SELECT 1 FROM code_chunk WHERE "filePath" = $1) AS exists`, [filePath]);
-        if (!exists)
-            return { ok: false, reason: 'not_indexed' };
-        if (!fs.existsSync(absPath))
-            return { ok: false, reason: 'not_on_disk' };
+        this.logger.debug('SearcherService: readFileRange', { relPath, startLine, endLine });
+        if (endLine < startLine)
+            return { ok: false, reason: 'bad_range', startLine, endLine };
+        const absPath = this.toAbs(relPath);
+        const failure = await this.openableFile(relPath, absPath);
+        if (failure)
+            return failure;
         const lines = [];
-        const stream = fs.createReadStream(absPath, { encoding: 'utf-8' });
-        const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
-        let lineNo = 0;
         let lastRead = 0;
         let hasMore = false;
-        try {
-            for await (const line of rl) {
-                lineNo++;
-                if (lineNo >= startLine && lineNo <= endLine)
-                    lines.push(line);
-                if (lineNo <= endLine)
-                    lastRead = lineNo;
-                if (lineNo > endLine) {
-                    hasMore = true;
-                    rl.close();
-                    stream.destroy();
-                    break;
-                }
+        const read = await this.readLines(absPath, (line, lineNo) => {
+            if (lineNo > endLine) {
+                hasMore = true;
+                return false;
             }
-        }
-        catch (err) {
-            rl.close();
-            stream.destroy();
-            throw err;
+            if (lineNo >= startLine)
+                lines.push(line);
+            lastRead = lineNo;
+            return true;
+        });
+        if (!read.ok)
+            return { ok: false, reason: 'unreadable', code: read.code };
+        if (!hasMore && startLine > Math.max(read.lineCount, 1)) {
+            return { ok: false, reason: 'past_end', lineCount: read.lineCount, startLine };
         }
         this.logger.debug('SearcherService: readFileRange result', { linesRead: lines.length, hasMore, ms: Date.now() - t0 });
-        return { ok: true, filePath, startLine, endLine: Math.min(endLine, lastRead), lines, hasMore };
+        return { ok: true, filePath: relPath, startLine, endLine: Math.min(endLine, lastRead), lines, hasMore };
     }
-    walkDir(absDir, currentDepth, maxDepth, pattern, lines) {
-        let entries;
-        try {
-            entries = fs.readdirSync(absDir, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
+    /** Throws when `absDir` itself cannot be read; an unreadable subdirectory is marked in place. */
+    async walkDir(absDir, currentDepth, maxDepth, pattern, lines) {
+        const entries = await this.fs.readdir(absDir);
         entries.sort((a, b) => {
             const ad = a.isDirectory() ? 0 : 1;
             const bd = b.isDirectory() ? 0 : 1;
@@ -791,9 +1084,14 @@ class SearcherService {
                 continue;
             const indent = '  '.repeat(currentDepth);
             if (entry.isDirectory()) {
-                lines.push(`${indent}${entry.name}/`);
+                const at = lines.push(`${indent}${entry.name}/`) - 1;
                 if (currentDepth < maxDepth) {
-                    this.walkDir(path.join(absDir, entry.name), currentDepth + 1, maxDepth, pattern, lines);
+                    try {
+                        await this.walkDir(path.join(absDir, entry.name), currentDepth + 1, maxDepth, pattern, lines);
+                    }
+                    catch {
+                        lines[at] += ' (unreadable)';
+                    }
                 }
             }
             else {
@@ -811,6 +1109,8 @@ class SearcherService {
     buildFindSymbolPattern(name, kind) {
         if (kind === 'function_property' || kind === 'method_signature')
             return null;
+        if (GRAPHQL_KINDS.has(kind))
+            return null;
         if (kind === 'constructor')
             return name === 'constructor' ? `(^|[[:space:]])constructor[[:space:]]*\\(` : null;
         const esc = name.replace(/\$/g, '\\$'); // ERE end-of-line metachar
@@ -862,8 +1162,9 @@ class SearcherService {
     }
     /**
      * 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`.
      */
     spawnGrep(args) {
         return new Promise((resolve) => {
@@ -880,16 +1181,17 @@ class SearcherService {
             proc.stderr.on('data', () => { });
             proc.on('error', (err) => {
                 this.logger.error('SearcherService: grep spawn failed', { reason: err.message });
-                resolve({ ok: false });
+                resolve({ ok: false, output: null });
             });
             proc.on('close', (code) => {
+                const output = chunks.length === 0 ? null : Buffer.concat(chunks).toString('utf-8');
                 // grep returns 1 for "no matches" — not an error; 2+ is a real failure
                 if (code !== null && code >= 2) {
                     this.logger.warn('SearcherService: grep exited with code', { code });
-                    resolve({ ok: false });
+                    resolve({ ok: false, output });
                     return;
                 }
-                resolve({ ok: true, output: chunks.length === 0 ? null : Buffer.concat(chunks).toString('utf-8') });
+                resolve({ ok: true, output });
             });
         });
     }