codesearch-mcp 0.2.3-alpha → 0.3.0-alpha

package/dist/src/services/OpenAICompatibleEmbedder.js

@@ -6,12 +6,6 @@ const config_1 = require("../config");
 const reranker_1 = require("./reranker");
 const http_retry_1 = require("./http-retry");
 const constants_1 = require("../constants");
-/**
- * Embedder for any server exposing an OpenAI-style `/embeddings` endpoint:
- * OpenAI cloud, Infinity, TEI, vLLM, LM Studio, LocalAI. One request carries all
- * inputs (`{ input: string[], model, dimensions? }`) and returns
- * `{ data: [{ embedding, index }] }`, re-ordered to input order.
- */
 class OpenAICompatibleEmbedder {
     config;
     logger;
@@ -24,7 +18,6 @@ class OpenAICompatibleEmbedder {
         this.config = config;
         this.logger = logger;
         const base = config.embedding.baseURL.replace(/\/+$/, '');
-        // Allow a baseURL that already includes the path (…/v1) or not.
         this.url = /\/embeddings$/.test(base) ? base : `${base}/embeddings`;
         this.doFetch = deps.fetchImpl ?? fetch;
         this.baseDelayMs = deps.baseDelayMs;
@@ -40,8 +33,6 @@ class OpenAICompatibleEmbedder {
             return [];
         return (0, http_retry_1.withRetry)(async () => {
             const headers = { 'Content-Type': 'application/json' };
-            // Resolve the key lazily — an unset `env:` ref throws here (request time),
-            // not at construction, so `rag-web`/`rag-mcp` still start.
             const apiKey = (0, config_1.resolveEnvRef)(this.config.embedding.apiKey);
             if (apiKey)
                 headers['Authorization'] = `Bearer ${apiKey}`;
@@ -51,7 +42,6 @@ class OpenAICompatibleEmbedder {
             const res = await this.doFetch(this.url, {
                 method: 'POST',
                 headers,
-                // CPU inference of one batch of token-dense text (e.g. pseudo-localized strings) takes well over 2 min.
                 signal: AbortSignal.timeout(240_000),
                 body: JSON.stringify(body),
             });
@@ -60,13 +50,9 @@ class OpenAICompatibleEmbedder {
                 throw new http_retry_1.HttpError(res.status, `embeddings request failed: ${res.status} ${errBody}`);
             }
             const data = await res.json();
-            // Guard against a partial/mismatched response — a missing vector would
-            // otherwise be inserted as "[undefined]" and fail the whole file, or (with
-            // reordering + no index) silently misalign vectors to the wrong chunks.
             if (!Array.isArray(data.data) || data.data.length !== texts.length) {
                 throw new Error(`embeddings response returned ${data.data?.length ?? 0} vectors for ${texts.length} inputs`);
             }
-            // Sort by `index` so vectors line up with input order regardless of server ordering.
             return [...data.data]
                 .sort((a, b) => (a.index ?? 0) - (b.index ?? 0))
                 .map(d => d.embedding);

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

@@ -1,8 +1,4 @@
 import type { IProjectDiscovery, DiscoveredProject } from '../interfaces/IProjectDiscovery';
-/**
- * Default project discovery: finds immediate subdirectories
- * of the workspace root that contain a package.json.
- */
 export declare class ProjectDiscoveryService implements IProjectDiscovery {
     discover(rootDir: string): DiscoveredProject[];
 }

package/dist/src/services/ProjectDiscoveryService.js

@@ -37,10 +37,6 @@ exports.ProjectDiscoveryService = void 0;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const file_utils_1 = require("../file-utils");
-/**
- * Default project discovery: finds immediate subdirectories
- * of the workspace root that contain a package.json.
- */
 class ProjectDiscoveryService {
     discover(rootDir) {
         return fs.readdirSync(rootDir, { withFileTypes: true })

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

@@ -5,6 +5,7 @@ import type { IDatabase } from '../interfaces';
 import { type IndexingExclusion, type ProjectMeta } from '../file-utils';
 import type { ILogger } from '../interfaces';
 import type { IProjectDiscovery } from '../interfaces';
+import type { StagedSearchResult } from '../interfaces/ISearcher';
 export interface ChunkRow {
     serviceName: string;
     filePath: string;
@@ -24,7 +25,6 @@ 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';
@@ -50,7 +50,6 @@ export type NotIndexedExplanation = IndexingExclusion | {
 } | {
     kind: 'unknown';
 };
-/** A well-formed path that leads to no readable data. */
 export type PathFailure = {
     ok: false;
     reason: 'outside_workspace';
@@ -106,7 +105,6 @@ export type GrepSymbolResult = {
 } | {
     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>;
@@ -121,17 +119,15 @@ export interface DependencyRow {
     depType: string;
     depth?: number;
     via?: string;
+    id?: 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 {
@@ -152,13 +148,12 @@ export interface SymbolHit {
     column: number;
     kind: Exclude<SymbolKind, 'all'>;
     signature: string;
-    /** `container.name`, or `name` when the container is null. */
     qualified: string;
     isStatic: boolean;
     source: 'index' | 'grep';
-    /** Qualified TypeScript name of the decorated declaration (GraphQL rows only); null otherwise. */
     target: string | null;
 }
+export declare function rerankDocument(row: ChunkRow): string;
 export declare class SearcherService {
     private db;
     private embedder;
@@ -167,93 +162,38 @@ export declare class SearcherService {
     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 pgvectorVersionRead?;
+    private degradedScanWarned;
+    private iterativeScanEnabled;
+    private warnDegradedScan;
     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;
@@ -262,81 +202,34 @@ export declare class SearcherService {
         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.
-     */
+    searchChunks(query: string, limit: number, project: string | null, threshold?: number, rerankOverride?: boolean, perFile?: number): Promise<SearchResult[]>;
+    searchChunksWithStages(query: string, limit: number, project: string | null, threshold?: number, rerankOverride?: boolean, perFile?: number): Promise<StagedSearchResult>;
     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;
 }