codesearch-mcp 0.2.1-alpha → 0.2.3-alpha

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

@@ -1,7 +1,8 @@
+import * as fs from 'fs';
 import type { Config } from '../config';
 import type { IEmbedder } from '../interfaces';
 import type { IDatabase } from '../interfaces';
-import { type ProjectMeta } from '../file-utils';
+import { type IndexingExclusion, type ProjectMeta } from '../file-utils';
 import type { ILogger } from '../interfaces';
 import type { IProjectDiscovery } from '../interfaces';
 export interface ChunkRow {
@@ -23,6 +24,58 @@ export interface GraphContext {
     imports: string[];
     usedBy: string[];
 }
+/** A tool path argument refused on its form alone, before any lookup. */
+export type PathRefusal = {
+    ok: false;
+    reason: 'invalid';
+    missing: boolean;
+} | {
+    ok: false;
+    reason: 'absolute';
+    relative: string;
+} | {
+    ok: false;
+    reason: 'outside_workspace';
+};
+export type ResolvedToolPath = {
+    ok: true;
+    relPath: string;
+    absPath: string;
+} | PathRefusal;
+export type NotIndexedExplanation = IndexingExclusion | {
+    kind: 'no_project';
+} | {
+    kind: 'project_not_indexed';
+    project: string;
+} | {
+    kind: 'unknown';
+};
+/** A well-formed path that leads to no readable data. */
+export type PathFailure = {
+    ok: false;
+    reason: 'outside_workspace';
+} | {
+    ok: false;
+    reason: 'unreadable';
+    code: string;
+} | {
+    ok: false;
+    reason: 'not_found';
+    candidates: string[];
+} | {
+    ok: false;
+    reason: 'deleted';
+} | {
+    ok: false;
+    reason: 'not_indexed';
+    explanation: NotIndexedExplanation;
+} | {
+    ok: false;
+    reason: 'not_a_file';
+} | {
+    ok: false;
+    reason: 'not_a_directory';
+};
 export type FileRangeResult = {
     ok: true;
     filePath: string;
@@ -30,10 +83,36 @@ export type FileRangeResult = {
     endLine: number;
     lines: string[];
     hasMore: boolean;
+} | PathFailure | {
+    ok: false;
+    reason: 'past_end';
+    lineCount: number;
+    startLine: number;
+} | {
+    ok: false;
+    reason: 'bad_range';
+    startLine: number;
+    endLine: number;
+};
+export type ListFilesResult = {
+    ok: true;
+    tree: string;
+} | PathFailure;
+export type GrepSymbolResult = {
+    ok: true;
+    matches: GrepMatch[];
+    truncated: boolean;
+    partial: boolean;
 } | {
     ok: false;
-    reason: 'not_indexed' | 'not_on_disk' | 'invalid_path';
 };
+/** Filesystem access of the path tools — injectable so error codes are testable without permissions. */
+export interface SearcherFs {
+    realpath(p: string): Promise<string>;
+    stat(p: string): Promise<fs.Stats>;
+    readdir(p: string): Promise<fs.Dirent[]>;
+    createReadStream(p: string): NodeJS.ReadableStream;
+}
 export interface DependencyRow {
     fromFile: string;
     fromSymbol: string | null;
@@ -50,12 +129,16 @@ export interface ProjectRow extends ProjectMeta {
     type?: 'app' | 'lib';
     /** Real filesystem root of the project (resolved via discovery). */
     path?: string;
+    /** `path` in workspace-relative form (`.` for the workspace root). */
+    relPath?: string;
+    /** Error code of `stat` on `path`, null when it exists. */
+    rootError?: string | null;
 }
 export interface GrepMatch {
     filePath: string;
     line: number;
 }
-export type SymbolKind = 'function' | 'class' | 'type' | 'interface' | 'variable' | 'method' | 'get_accessor' | 'set_accessor' | 'constructor' | 'function_property' | 'method_signature' | 'all';
+export type SymbolKind = 'function' | 'class' | 'type' | 'interface' | 'variable' | 'method' | 'get_accessor' | 'set_accessor' | 'constructor' | 'function_property' | 'method_signature' | 'graphql_query' | 'graphql_mutation' | 'graphql_subscription' | 'graphql_field' | 'graphql_type' | 'all';
 export interface CallerRow {
     fromFile: string;
     fromSymbol: string | null;
@@ -73,6 +156,8 @@ export interface SymbolHit {
     qualified: string;
     isStatic: boolean;
     source: 'index' | 'grep';
+    /** Qualified TypeScript name of the decorated declaration (GraphQL rows only); null otherwise. */
+    target: string | null;
 }
 export declare class SearcherService {
     private db;
@@ -80,7 +165,18 @@ export declare class SearcherService {
     private discovery;
     private config;
     private logger;
-    constructor(db: IDatabase, embedder: IEmbedder, discovery: IProjectDiscovery, config: Config, logger?: ILogger);
+    private readonly fs;
+    constructor(db: IDatabase, embedder: IEmbedder, discovery: IProjectDiscovery, config: Config, logger?: ILogger, fsDeps?: Partial<SearcherFs>);
+    /**
+     * Whether `code_symbol.target` exists — `true` once a check finds it (never
+     * re-checked again in this process), `false` until then (re-checked on
+     * every lookup, so a `rag-index` run that adds the column takes effect
+     * without restarting `rag-mcp`). See "find_symbol works before the target
+     * column exists" (`graphql-symbols`).
+     */
+    private targetColumnPresent;
+    /** Real path of `workspaceRoot`; cached only once resolved, so a transient failure is retried. */
+    private realRootCache?;
     /** Lazily-built, cached map of project name → real filesystem root. */
     private rootMap?;
     /** Cached, lazily-built map of leaf project name → real filesystem root (via discovery). */
@@ -92,6 +188,65 @@ export declare class SearcherService {
      * project since removed from disk, or a flat project not surfaced by discovery).
      */
     private resolveProjectRoot;
+    private toRel;
+    private toAbs;
+    private workspaceRoot;
+    private realWorkspaceRoot;
+    /**
+     * Lexical validation of a tool path argument: refusals for an empty value,
+     * `\`, an absolute path and a `..` escape; otherwise the canonical
+     * workspace-relative form. The only filesystem access is the cached real path
+     * of `workspaceRoot`.
+     */
+    resolveToolPath(input: string | null | undefined): Promise<ResolvedToolPath>;
+    /**
+     * Whether the real location of `absPath` — of the target, else of its nearest
+     * existing ancestor plus the remaining segments — lies under the real
+     * workspace root.
+     */
+    private realLocation;
+    /**
+     * Workspace boundary of the disk tools. A real location outside the workspace
+     * is allowed only for content the indexer already read (a symlinked share):
+     * the file itself for `file`, any file below it for `dir`.
+     */
+    checkRealLocation(relPath: string, absPath: string, kind: 'file' | 'dir'): Promise<{
+        ok: true;
+    } | Extract<PathFailure, {
+        reason: 'outside_workspace' | 'unreadable';
+    }>>;
+    private pathExists;
+    /** Whether any table of the index holds `relPath` (a canonical path, never `../…`). */
+    isIndexedPath(relPath: string): Promise<boolean>;
+    /** Whether the indexer read the file at `relPath`. */
+    isContentPath(relPath: string): Promise<boolean>;
+    private hasContentUnder;
+    /**
+     * Up to three index paths ending in `/<relPath>` (`file`) or directories
+     * ending in `/<relPath>` that hold one (`dir`), in byte order. For `dir`, the
+     * root of a project named `relPath` comes first.
+     */
+    findPathCandidates(relPath: string, kind: 'file' | 'dir'): Promise<string[]>;
+    /** `findPathCandidates`, with a failed lookup logged and answered by no candidates. */
+    private candidatesOrNone;
+    /**
+     * `relPath` with a leading project name replaced by that project's root
+     * (`repo/app/src/x.ts` → `repo/apps/app/src/x.ts`), or null when no name
+     * prefixes it, the root equals the name, or the result names nothing.
+     */
+    private substituteProjectName;
+    private findProjectRootByName;
+    /** Longest workspace-relative project root accepted by `match`; discovery is re-run once before giving up. */
+    private findProjectRoot;
+    /** Root directory (workspace-relative) of the project the text-search fallback for `relPath` runs in. */
+    fallbackRoot(relPath: string): string | null;
+    /**
+     * Why a graph tool has no data for `relPath`, or null when the path is in the
+     * index path set. Touches the disk only for an unknown path, and answers a
+     * real location outside the workspace as `not_found` without looking at it.
+     */
+    checkGraphPath(relPath: string): Promise<PathFailure | null>;
+    private explainNotIndexed;
     /**
      * Project-level dependency edges aggregated from `code_dependency`: an edge
      * `A → B` means some file in project A imports a file owned by project B.
@@ -119,7 +274,7 @@ export declare class SearcherService {
     assertIndexMatches(): Promise<void>;
     private compareIndexed;
     listProjects(): Promise<ProjectRow[]>;
-    searchChunks(query: string, limit: number, project: string | null, threshold?: number): Promise<SearchResult[]>;
+    searchChunks(query: string, limit: number, project: string | null, threshold?: number, rerankOverride?: boolean): Promise<SearchResult[]>;
     /**
      * Emit one structured search-tuning line (via `logger.metric`, at `info`
      * regardless of `logging.level`). `candidates` are in cosine order, so a
@@ -131,34 +286,42 @@ export declare class SearcherService {
     private emitSearchMetrics;
     fetchNeighbors(results: SearchResult[]): Promise<NeighborResult[]>;
     fetchGraphContext(results: SearchResult[]): Promise<Map<string, GraphContext>>;
-    getDependencies(filePath: string, project: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
-    getDependents(filePath: string, project: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
+    getDependencies(filePath: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
+    getDependents(filePath: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
     getCallers(symbol: string, project: string, calleeFile?: string | null): Promise<CallerRow[]>;
     /**
-     * One-line warning when any project in `scope` (the given `project`, or
-     * every project with `code_chunk`/`code_symbol` rows) is outdated — shown
-     * first in `find_symbol`/`get_callers` output. Any failure to determine the
-     * scope or read markers only drops the notice (warn logged); the lookup
-     * itself is unaffected.
+     * Whole-word text search for `symbol` under `rootDir` (workspace-relative).
+     * grep exiting ≥ 2 after printing matches is a partial result; without
+     * matches, or when grep cannot be spawned, the search failed.
      */
-    outdatedNotice(project: string | null): Promise<string | null>;
-    grepSymbol(symbol: string, project: string, excludeFile: string): Promise<{
-        matches: GrepMatch[];
-        truncated: boolean;
-    }>;
+    grepSymbol(symbol: string, rootDir: string, excludeFile: string): Promise<GrepSymbolResult>;
     findSymbol(name: string, project: string | null, kind: SymbolKind): Promise<{
         hits: SymbolHit[];
         truncated: boolean;
         grepFailed: boolean;
     }>;
+    /**
+     * Whether `code_symbol.target` exists. A present result is cached for the
+     * process; an absent one is re-checked on every call. Propagates on a
+     * failing check, same as any other failed index query.
+     */
+    private hasTargetColumn;
     private findSymbolFromIndex;
     private grepFindSymbol;
-    listFiles(relativePath: string, project: string, depth: number, pattern: string | null): {
-        tree: string;
-        error?: string;
-    };
-    readFileAbsolute(absPath: string, maxLines: number): Promise<FileRangeResult>;
-    readFileRange(filePath: string, startLine: number, endLine: number): Promise<FileRangeResult>;
+    listFiles(relPath: string, depth: number, pattern: string | null): Promise<ListFilesResult>;
+    /**
+     * The read tools' common front: workspace boundary, then existence and type.
+     * A missing file still in the index is `deleted`; otherwise `not_found`.
+     */
+    private openableFile;
+    /**
+     * Streams the file's lines (as `readline` yields them) to `onLine` until it
+     * returns false. An open or read error discards everything read so far.
+     */
+    private readLines;
+    readFile(relPath: string, maxLines: number): Promise<FileRangeResult>;
+    readFileRange(relPath: string, startLine: number, endLine: number): Promise<FileRangeResult>;
+    /** Throws when `absDir` itself cannot be read; an unreadable subdirectory is marked in place. */
     private walkDir;
     /**
      * ERE pattern for a grep-fallback kind, or null when that kind is never
@@ -171,8 +334,9 @@ export declare class SearcherService {
     private inferKind;
     /**
      * Async wrapper around grep to avoid blocking the event loop. `ok: false`
-     * means grep could not be spawned or exited with status ≥ 2 (distinguishable
-     * from a clean "no matches", which is `ok: true, output: null`).
+     * means grep could not be spawned (`output: null`) or exited with status ≥ 2,
+     * keeping whatever it printed — distinguishable from a clean "no matches",
+     * which is `ok: true, output: null`.
      */
     private spawnGrep;
 }