codesearch-mcp 0.2.3-alpha → 0.4.0-alpha

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

@@ -1,342 +0,0 @@
-import * as fs from 'fs';
-import type { Config } from '../config';
-import type { IEmbedder } from '../interfaces';
-import type { IDatabase } from '../interfaces';
-import { type IndexingExclusion, type ProjectMeta } from '../file-utils';
-import type { ILogger } from '../interfaces';
-import type { IProjectDiscovery } from '../interfaces';
-export interface ChunkRow {
-    serviceName: string;
-    filePath: string;
-    startLine: number;
-    content: string;
-    ownerPath?: string | null;
-}
-export interface SearchResult extends ChunkRow {
-    score: number;
-}
-export interface NeighborResult {
-    result: SearchResult;
-    prevChunk: ChunkRow | null;
-    nextChunk: ChunkRow | null;
-}
-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;
-    startLine: number;
-    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;
-};
-/** 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;
-    toFile: string;
-    toSymbol: string | null;
-    depType: string;
-    depth?: number;
-    via?: string;
-}
-export interface ProjectRow extends ProjectMeta {
-    serviceName: string;
-    chunks: number;
-    packageName?: string | null;
-    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' | 'graphql_query' | 'graphql_mutation' | 'graphql_subscription' | 'graphql_field' | 'graphql_type' | 'all';
-export interface CallerRow {
-    fromFile: string;
-    fromSymbol: string | null;
-    calleeName: string;
-    calleeFile: string;
-    line: number | null;
-}
-export interface SymbolHit {
-    filePath: string;
-    line: number;
-    column: number;
-    kind: Exclude<SymbolKind, 'all'>;
-    signature: string;
-    /** `container.name`, or `name` when the container is null. */
-    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;
-    private embedder;
-    private discovery;
-    private config;
-    private logger;
-    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). */
-    private projectRootMap;
-    /**
-     * Resolve a project name to its real filesystem root. Uses discovery (leaf
-     * projects) so nested-monorepo names like `repo/app` map to their true path;
-     * falls back to `join(workspaceRoot, name)` when the name is unknown (e.g. a
-     * 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.
-     * Used by the graph to draw links between a monorepo's sub-projects. Only
-     * edges whose target file belongs to an indexed project are returned (targets
-     * outside any indexed project — e.g. unindexed libs — are skipped).
-     */
-    getProjectEdges(): Promise<{
-        from: string;
-        to: string;
-    }[]>;
-    prepareQuery(raw: string): Promise<{
-        query: string;
-        translated: boolean;
-    }>;
-    /**
-     * Refuse when the configured embedding model disagrees with the one that built
-     * the index — embedding a query into a foreign vector space returns noise. A
-     * missing `index_meta` row with an empty (or altogether absent) `code_chunk`
-     * does not block — but a *populated* `code_chunk` with no `index_meta` row is a
-     * pre-`index_meta` install, treated as the legacy `ollama`/`bge-m3` index (same
-     * interpretation as the `rag-index` legacy-Ollama guard), read-only — this check
-     * never writes `index_meta`.
-     */
-    assertIndexMatches(): Promise<void>;
-    private compareIndexed;
-    listProjects(): Promise<ProjectRow[]>;
-    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
-     * candidate's array index is its cosine rank — `maxCosineRankSurvived` is the
-     * deepest cosine position that survived reranking into the returned set. Read
-     * it alongside `poolSaturated` to tune `candidateFloor`/`overfetch`/threshold
-     * per hardware. Never logs chunk content, embeddings, or credentials.
-     */
-    private emitSearchMetrics;
-    fetchNeighbors(results: SearchResult[]): Promise<NeighborResult[]>;
-    fetchGraphContext(results: SearchResult[]): Promise<Map<string, GraphContext>>;
-    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[]>;
-    /**
-     * 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.
-     */
-    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(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
-     * 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. `ok: false`
-     * 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;
-}