codesearch-mcp 0.2.3-alpha → 0.3.0-alpha

package/dist/src/setup.js

@@ -35,6 +35,8 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EMBEDDING_PROVIDER_CHOICES = void 0;
 exports.dockerPromptDefault = dockerPromptDefault;
+exports.rerankerChoices = rerankerChoices;
+exports.promptReranker = promptReranker;
 exports.prepareComposeAndStartDb = prepareComposeAndStartDb;
 exports.provisionInfinity = provisionInfinity;
 exports.runSetup = runSetup;
@@ -43,6 +45,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const child_process_1 = require("child_process");
+const constants_1 = require("./constants");
 const config_store_1 = require("./config-store");
 const config_1 = require("./config");
 const infinity_provisioning_1 = require("./services/infinity-provisioning");
@@ -68,51 +71,115 @@ function expandHome(p) {
 }
 const PROVIDER_DEFAULTS = {
     'openai-compatible': { baseURL: 'https://api.openai.com/v1', model: 'text-embedding-3-small', envVar: 'OPENAI_API_KEY' },
-    'voyage': { baseURL: 'https://api.voyageai.com/v1', model: 'voyage-code-3', envVar: 'VOYAGE_API_KEY' },
+    'voyage': { baseURL: 'https://api.voyageai.com/v1', model: 'voyage-code-4', envVar: 'VOYAGE_API_KEY' },
     'infinity': { baseURL: 'http://localhost:7997', model: 'jinaai/jina-embeddings-v2-base-code', envVar: '' },
 };
-/** Providers the wizard offers, in prompt order; the first is the preselected default. Exported for unit testing. */
 exports.EMBEDDING_PROVIDER_CHOICES = ['infinity', 'openai-compatible', 'voyage'];
-/** Providers that run a local inference backend we can probe / provision. */
 function isLocalBackend(p) {
     return p === 'infinity';
 }
-/**
- * Probe whether the embedding backend is already reachable, so the "start
- * Docker?" prompt can default to no (mirrors the DB `checkRemoteDb` flow).
- * Cloud providers have no local backend → always "reachable" (nothing to start).
- */
 async function checkEmbeddingBackend(provider, baseURL) {
     if (!isLocalBackend(provider))
         return true;
     return (0, infinity_provisioning_1.probeInfinityHealth)(baseURL);
 }
-/**
- * Default answer for the "start Docker containers?" prompt: no only when both
- * the database and the embedding backend are already reachable. Pure — exported
- * for unit testing.
- */
 function dockerPromptDefault(dbReachable, embReachable) {
     return (dbReachable && embReachable) ? 'n' : 'y';
 }
-/**
- * Write (or replace) a single `KEY=VALUE` line in `~/.config/codesearch-mcp/.env`,
- * chmod 600. API keys live here — never in config.json — referenced as `env:KEY`.
- */
 function writeEnvKey(name, value) {
     fs.mkdirSync(config_store_1.CONFIG_DIR, { recursive: true });
     let existing = '';
     try {
         existing = fs.readFileSync(config_store_1.ENV_FILE, 'utf-8');
     }
-    catch { /* absent */ }
+    catch { }
     const kept = existing.split(/\r?\n/).filter(l => l.trim() && !l.trim().startsWith(`${name}=`));
     kept.push(`${name}=${value}`);
     fs.writeFileSync(config_store_1.ENV_FILE, kept.join('\n') + '\n', { mode: 0o600 });
     try {
         fs.chmodSync(config_store_1.ENV_FILE, 0o600);
     }
-    catch { /* best effort */ }
+    catch { }
+}
+const VOYAGE_RERANK_ENV = 'VOYAGE_RERANK_API_KEY';
+const RERANKER_ENV = 'RERANKER_API_KEY';
+function rerankerChoices(embProvider) {
+    if (embProvider === 'infinity')
+        return ['infinity', 'voyage', 'openai-compatible', 'none'];
+    if (embProvider === 'voyage')
+        return ['voyage', 'openai-compatible', 'none'];
+    return ['none', 'voyage', 'openai-compatible'];
+}
+async function askRequired(io, question) {
+    for (;;) {
+        const answer = (await io.ask(question)).trim();
+        if (answer)
+            return answer;
+        io.log('  A value is required.');
+    }
+}
+function isHttpUrl(value) {
+    try {
+        const { protocol, username, password } = new URL(value);
+        return (protocol === 'http:' || protocol === 'https:') && !username && !password;
+    }
+    catch {
+        return false;
+    }
+}
+async function askHttpUrl(io, question) {
+    for (;;) {
+        const answer = await askRequired(io, question);
+        if (isHttpUrl(answer))
+            return answer;
+        io.log('  Enter an absolute http(s):// URL without credentials, e.g. http://localhost:7997.');
+    }
+}
+async function promptReranker(embProvider, embBaseURL, io) {
+    const choices = rerankerChoices(embProvider);
+    io.log('\n--- Reranker ---');
+    if (choices.includes('infinity'))
+        io.log('  infinity          — served by the same Infinity container');
+    io.log('  voyage            — Voyage AI cloud (needs a Voyage API key)');
+    io.log('  openai-compatible — any /rerank server (Infinity, vLLM)');
+    io.log('  none              — no reranking');
+    let choice;
+    for (;;) {
+        choice = (await io.prompt(`Reranker (${choices.join('/')})`, choices[0])).trim();
+        if (choices.includes(choice))
+            break;
+        io.log(`  Invalid reranker. Choose: ${choices.join(', ')}`);
+    }
+    if (choice === 'none')
+        return { enabled: false };
+    if (choice === 'infinity') {
+        const model = (await io.prompt('Reranker model (served by the same Infinity container)', config_store_1.CONFIG_DEFAULTS['reranker.model'])).trim();
+        return { enabled: true, provider: 'openai-compatible', baseURL: embBaseURL, model };
+    }
+    if (choice === 'voyage') {
+        const model = (await io.prompt(`Reranker model (${constants_1.VOYAGE_RERANK_MODELS.join(' / ')})`, constants_1.VOYAGE_RERANK_MODELS[0])).trim();
+        for (;;) {
+            const key = (await io.ask(`Voyage reranker API key (stored in ${config_store_1.ENV_FILE} as ${VOYAGE_RERANK_ENV}): `)).trim();
+            if (key) {
+                io.writeEnvKey(VOYAGE_RERANK_ENV, key);
+                io.log(`  Saved reranker API key to ${config_store_1.ENV_FILE} as ${VOYAGE_RERANK_ENV}.`);
+                return { enabled: true, provider: 'voyage', model, apiKey: `env:${VOYAGE_RERANK_ENV}` };
+            }
+            io.log('  The Voyage reranker is not configured without an API key.');
+            const disable = (await io.prompt('Disable the reranker? (y/n)', 'y')).trim().toLowerCase();
+            if (disable === 'y')
+                return { enabled: false };
+        }
+    }
+    const baseURL = await askHttpUrl(io, 'Rerank server base URL: ');
+    const model = await askRequired(io, 'Reranker model: ');
+    const key = (await io.ask(`Reranker API key (stored in ${config_store_1.ENV_FILE} as ${RERANKER_ENV}, blank for none): `)).trim();
+    if (key)
+        io.writeEnvKey(RERANKER_ENV, key);
+    return {
+        enabled: true, provider: 'openai-compatible', baseURL, model,
+        ...(key ? { apiKey: `env:${RERANKER_ENV}` } : {}),
+    };
 }
 async function waitForDb(host, port, user, pass, db, maxWaitSec = 60, logger, steps) {
     const { Client } = await Promise.resolve().then(() => __importStar(require('pg')));
@@ -147,18 +214,10 @@ async function checkRemoteDb(host, port, user, pass, db, logger, steps) {
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(`  Connection failed: ${msg}`);
-        logger?.error('checkRemoteDb: connection failed', { reason: msg, steps: JSON.stringify(steps) });
+        logger?.error('checkRemoteDb: connection failed', { err, steps: JSON.stringify(steps) });
         return false;
     }
 }
-/**
- * Regenerate `CONFIG_DIR/docker-compose.yml` from the shipped template
- * (carrying over an existing literal `INFINITY_MODEL_ID`, written atomically),
- * copy the GPU override, and start the DB container when requested. Runs
- * BEFORE the config file is written — its failure aborts setup unsaved,
- * matching the existing "abort without saving" behavior of the DB step. Does
- * NOT touch Infinity provisioning (moved after `writeConfigJson` — see D6a).
- */
 async function prepareComposeAndStartDb(opts) {
     const { dbPort, dbUser, dbPass, startDb, logger, steps } = opts;
     console.log('\nWriting docker-compose.yml to', DOCKER_COMPOSE_DST);
@@ -168,14 +227,11 @@ async function prepareComposeAndStartDb(opts) {
         .replace('POSTGRES_USER: dev', `POSTGRES_USER: ${yamlQuote(dbUser)}`)
         .replace('POSTGRES_PASSWORD: dev', `POSTGRES_PASSWORD: ${yamlQuote(dbPass)}`)
         .replace('"5433:5432"', `"${dbPort}:5432"`);
-    // Carry over an existing literal INFINITY_MODEL_ID — never the set of the
-    // config still being entered — so a setup that aborts before the config is
-    // written leaves a file consistent with the previously saved config.
     let existingModelId = null;
     try {
         existingModelId = (0, infinity_provisioning_1.extractModelIdValue)(fs.readFileSync(DOCKER_COMPOSE_DST, 'utf-8'));
     }
-    catch { /* no prior file */ }
+    catch { }
     if (existingModelId) {
         composeContent = composeContent.replace(/INFINITY_MODEL_ID:\s*"[^"]*"/, `INFINITY_MODEL_ID: "${existingModelId}"`);
     }
@@ -184,13 +240,12 @@ async function prepareComposeAndStartDb(opts) {
     try {
         existingMode = fs.statSync(DOCKER_COMPOSE_DST).mode;
     }
-    catch { /* first-ever write */ }
+    catch { }
     (0, infinity_provisioning_1.atomicWriteFile)(DOCKER_COMPOSE_DST, composeContent, existingMode);
-    // The GPU override is copied verbatim so the managed Infinity path can layer it.
     try {
         fs.copyFileSync(DOCKER_GPU_OVERRIDE_SRC, DOCKER_GPU_OVERRIDE_DST);
     }
-    catch { /* absent → CPU only */ }
+    catch { }
     if (!startDb)
         return;
     console.log('\nStarting the database container...');
@@ -202,30 +257,19 @@ async function prepareComposeAndStartDb(opts) {
     }
     await waitForDb('localhost', parseInt(dbPort), dbUser, dbPass, 'postgres', 60, logger, steps);
 }
-/**
- * Infinity provisioning (D6a) — runs AFTER the config file is written, so no
- * outcome here can leave the config unsaved. `savedConfig` is a fresh read of
- * the just-written file (never the process's own startup config). Exit-status
- * rules: 0 for served / timeout (warning) / external instructions / declined
- * Docker; 1 for any other provisioning failure — the cause is printed and the
- * remaining setup steps (DB schema init) still run.
- */
 async function provisionInfinity(savedConfig, startDocker, logger, deps = {}, composePathOverride) {
     const composePath = composePathOverride ?? DOCKER_COMPOSE_DST;
     const baseURL = savedConfig.embedding.baseURL;
     const base = (0, infinity_provisioning_1.serverRoot)(baseURL);
     const set = (0, infinity_provisioning_1.requiredModelSet)(savedConfig);
     const managed = (0, infinity_provisioning_1.isManagedInfinity)(baseURL, composePath);
-    // Targeted write happens for a managed backend regardless of what follows
-    // (yes/no, served/missing), so the compose file always matches the saved
-    // config — even when the running container already serves the set.
     if (managed) {
         try {
             (0, infinity_provisioning_1.writeComposeModelSet)(composePath, set);
         }
         catch (err) {
             console.error(`\nFailed to write the managed compose file: ${err.message}`);
-            logger?.error('provisionInfinity: compose write failed', { reason: err.message });
+            logger?.error('provisionInfinity: compose write failed', { err });
             process.exitCode = 1;
         }
     }
@@ -239,17 +283,16 @@ async function provisionInfinity(savedConfig, startDocker, logger, deps = {}, co
             if (/did not become ready within/.test(msg)) {
                 console.warn(`\nWarning: ${msg}`);
                 console.warn('The container is running and likely still warming up. Check again once /health responds, then run: rag-index');
-                logger?.warn('provisionInfinity: readiness timeout (non-fatal)', { reason: msg });
+                logger?.warn('provisionInfinity: readiness timeout (non-fatal)', { err });
             }
             else {
                 console.error(`\nInfinity provisioning failed: ${msg}`);
-                logger?.error('provisionInfinity: failed', { reason: msg });
+                logger?.error('provisionInfinity: failed', { err });
                 process.exitCode = 1;
             }
         }
         return;
     }
-    // Docker declined — no Docker command; print what would apply the set.
     const evaluation = await (0, infinity_provisioning_1.evaluateBackend)(baseURL, composePath, set, deps);
     if (evaluation.action === 'served')
         return;
@@ -311,12 +354,6 @@ async function runSetup(logger) {
     const pd = PROVIDER_DEFAULTS[embProvider];
     const embBaseURL = await loggedPrompt('Base URL', pd.baseURL);
     const embModel = await loggedPrompt('Embedding model', pd.model);
-    // Infinity serves a reranker from the same container — offer to provision one.
-    let rerankModel = '';
-    if (embProvider === 'infinity') {
-        rerankModel = (await loggedPrompt(`Reranker model (served by the same Infinity container; blank to disable)`, config_store_1.CONFIG_DEFAULTS['reranker.model'])).trim();
-    }
-    // API keys go into .env (chmod 600); config.json only stores the env: reference.
     let apiKeyRef = '';
     if (!isLocalBackend(embProvider)) {
         const key = (await loggedAsk(`API key (stored in ${config_store_1.ENV_FILE}, leave blank to set later): `)).trim();
@@ -330,6 +367,9 @@ async function runSetup(logger) {
             console.log(`  No key entered — set it later: echo '${pd.envVar}=sk-…' >> ${config_store_1.ENV_FILE}`);
         }
     }
+    const reranker = await promptReranker(embProvider, embBaseURL, {
+        prompt: loggedPrompt, ask: loggedAsk, writeEnvKey, log: msg => console.log(msg),
+    });
     console.log('\n--- Database ---');
     const dbHost = await loggedPrompt('DB host', 'localhost');
     const dbPort = await loggedPrompt('DB port', '5433');
@@ -339,8 +379,6 @@ async function runSetup(logger) {
     const dbReachable = await checkRemoteDb(dbHost, dbPort, dbUser, dbPass, 'postgres', logger, steps);
     if (dbReachable)
         console.log('  Database is already reachable.');
-    // Symmetric to the DB probe: a reachable embedding backend defaults "start
-    // Docker?" to no. Cloud providers have no local backend to start.
     process.stdout.write('Checking embedding backend...');
     const embReachable = await checkEmbeddingBackend(embProvider, embBaseURL);
     if (isLocalBackend(embProvider)) {
@@ -400,26 +438,15 @@ async function runSetup(logger) {
             model: embModel,
             ...(apiKeyRef ? { apiKey: apiKeyRef } : {}),
         },
+        reranker,
         logging: { level: logLevel },
         workspaceRoot,
     };
-    // Infinity serves the reranker from the same container — auto-wire reranker.*
-    // to that server. `url` derives from provider + baseURL in the Config constructor.
-    if (embProvider === 'infinity' && rerankModel) {
-        cfg.reranker = {
-            enabled: true,
-            provider: 'openai-compatible',
-            baseURL: embBaseURL,
-            model: rerankModel,
-        };
-    }
     if (logDir)
         cfg.logging.dir = logDir;
     (0, config_store_1.writeConfigJson)(cfg);
     console.log(`\nConfig saved to ${config_store_1.CONFIG_FILE}`);
     rl.close();
-    // Infinity provisioning happens only now — after the config is safely on
-    // disk — so a provisioning failure never leaves the wizard's answers unsaved.
     if (embProvider === 'infinity') {
         await provisionInfinity(new config_1.Config(), startDocker, logger);
     }
@@ -438,7 +465,7 @@ async function runSetup(logger) {
     }
     if (initError) {
         console.error(`Database schema init failed: ${initError.message}`);
-        logger?.error('runSetup: database schema init failed', { reason: initError.message, steps: JSON.stringify(steps) });
+        logger?.error('runSetup: database schema init failed', { err: initError, steps: JSON.stringify(steps) });
         process.exit(1);
     }
     console.log('\nSetup complete!');

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

@@ -16,22 +16,11 @@ export type FindSymbolQuery = {
     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;
@@ -40,5 +29,4 @@ export declare function parseCallerSymbol(input: string): {
     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

@@ -11,22 +11,15 @@ 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);
@@ -47,11 +40,6 @@ function parseFindSymbolName(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);
@@ -62,7 +50,6 @@ function parseCallerSymbol(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

@@ -1,17 +1,3 @@
 import type { SymbolEntry } from './interfaces/IAstParser';
 export type CodeSymbolRow = Pick<SymbolEntry, 'project' | 'filePath' | 'name' | 'kind' | 'signature' | 'line' | 'col' | 'container' | 'isStatic' | 'target'>;
-/**
- * Combine top-level symbols, members and GraphQL-named rows 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). `graphqlNames` bypass this collapse — decorators
- * cannot sit on overload signatures, so there is nothing to collapse, and the
- * collapse's `(container, name, kind, isStatic)` key would wrongly merge two
- * different methods exposing the same GraphQL name from two resolver classes
- * (both with container `Query`). A final dedup by `(container, name, kind,
- * line)` matches the DB's unique index.
- */
 export declare function buildSymbolRows(symbols: SymbolEntry[], members: SymbolEntry[], graphqlNames?: SymbolEntry[]): CodeSymbolRow[];

package/dist/src/symbol-rows.js

@@ -1,20 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildSymbolRows = buildSymbolRows;
-/**
- * Combine top-level symbols, members and GraphQL-named rows 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). `graphqlNames` bypass this collapse — decorators
- * cannot sit on overload signatures, so there is nothing to collapse, and the
- * collapse's `(container, name, kind, isStatic)` key would wrongly merge two
- * different methods exposing the same GraphQL name from two resolver classes
- * (both with container `Query`). A final dedup by `(container, name, kind,
- * line)` matches the DB's unique index.
- */
 function buildSymbolRows(symbols, members, graphqlNames = []) {
     const groups = new Map();
     for (const entry of [...symbols, ...members]) {

package/dist/src/tool-call-log.d.ts

@@ -0,0 +1,2 @@
+export declare function truncateForLog(value: unknown, depth?: number): unknown;
+export declare function resolveSession(env: Record<string, string | undefined>): string | null;

package/dist/src/tool-call-log.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.truncateForLog = truncateForLog;
+exports.resolveSession = resolveSession;
+const MAX_STRING = 500;
+const MAX_ITEMS = 20;
+const MAX_DEPTH = 4;
+function truncateForLog(value, depth = 1) {
+    if (typeof value === 'string') {
+        return value.length > MAX_STRING ? `${value.slice(0, MAX_STRING)}…(+${value.length - MAX_STRING})` : value;
+    }
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (depth > MAX_DEPTH)
+        return '[depth]';
+    if (Array.isArray(value)) {
+        const kept = value.slice(0, MAX_ITEMS).map(v => truncateForLog(v, depth + 1));
+        return value.length > MAX_ITEMS ? [...kept, `…(+${value.length - MAX_ITEMS})`] : kept;
+    }
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, truncateForLog(v, depth + 1)]));
+}
+function resolveSession(env) {
+    return env.CLAUDE_CODE_SESSION_ID ?? null;
+}

package/dist/src/tools/GetDependenciesTool.js

@@ -12,7 +12,7 @@ class GetDependenciesTool {
     definition() {
         return {
             name: 'get_dependencies',
-            description: 'Show what files a given file imports (direct or transitive), in any project. Use to understand what a file depends on before modifying it. depType values: import | import-default | import-namespace | import-side-effect | reexport | reexport-namespace.',
+            description: 'Show what files a given file imports (direct or transitive), in any project. Use to understand what a file depends on before modifying it. The direct section prints one line per imported file, with the names imported from it.',
             inputSchema: {
                 type: 'object',
                 properties: {

package/dist/src/tools/GetDependentsTool.js

@@ -12,7 +12,7 @@ class GetDependentsTool {
     definition() {
         return {
             name: 'get_dependents',
-            description: 'Show which files import a given file (reverse graph), in any project. Use before refactoring to find all callers and avoid breaking changes. depType values: import | import-default | import-namespace | import-side-effect | reexport | reexport-namespace.',
+            description: 'Show which files import a given file (reverse graph), in any project. Use before refactoring to find all callers and avoid breaking changes. The direct section prints one line per importing file, with the names imported and the enclosing declarations that use them — only those resolved unambiguously, so the list can be partial or absent.',
             inputSchema: {
                 type: 'object',
                 properties: {

package/dist/src/tools/SearchCodebaseTool.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SearchCodebaseTool = void 0;
 const format_helpers_1 = require("./format-helpers");
+const result_shaping_1 = require("../search/result-shaping");
 class SearchCodebaseTool {
     searcher;
     defaultLimit;
@@ -28,7 +29,8 @@ class SearchCodebaseTool {
                     include_neighbors: { type: 'boolean', description: 'Also include the chunk before and after each result from the same file (Small-to-Big retrieval). Useful when results look truncated.' },
                     include_graph_context: { type: 'boolean', description: 'Append direct imports and dependents list to each result. Shows "Imports: X · Y" and "Used by: Z" without extra tool calls.' },
                     threshold: { type: 'number', description: `Max cosine distance (0–1). Lower = stricter. Default: ${this.defaultThreshold}. Use 0.40–0.45 for precise technical queries, 0.55–0.60 for broad exploration.` },
-                    rerank: { type: 'boolean', description: 'Override whether this call reranks, regardless of config. false skips reranking (use for "what does X do" / "where is X" lookups described without an exact name — reranking measurably hurts these; if you know the exact symbol name, use find_symbol instead). true forces reranking on if a reranker is configured (no-op otherwise). Omit to use config.reranker.enabled (good default for conceptual/architectural queries).' },
+                    per_file: { type: 'number', description: `Max results from one file (integer ≥ 1, default ${result_shaping_1.DEFAULT_PER_FILE}). Skipped results are backfilled from the next candidates. Raise it when one file is expected to hold several answers (e.g. several methods of one class).` },
+                    rerank: { type: 'boolean', description: 'Override whether this call reranks, regardless of config. false skips reranking (use for "what does X do" / "where is X" lookups described without an exact name — reranking measurably hurts these; if you know the exact symbol name, use find_symbol instead). true forces reranking on if a reranker is configured (no-op otherwise). Omit to use config.reranker.enabled (fine for conceptual/architectural queries, where reranking is roughly neutral).' },
                 },
                 required: ['query'],
             },
@@ -47,11 +49,12 @@ class SearchCodebaseTool {
             ? Math.min(1, Math.max(0, parsedThreshold))
             : undefined;
         const rerank = typeof args.rerank === 'boolean' ? args.rerank : undefined;
+        const perFile = Number.isInteger(args.per_file) && args.per_file >= 1 ? args.per_file : result_shaping_1.DEFAULT_PER_FILE;
         const { query, translated } = await this.searcher.prepareQuery(raw);
-        const results = await this.searcher.searchChunks(query, limit, project, threshold, rerank);
+        const results = await this.searcher.searchChunks(query, limit, project, threshold, rerank, perFile);
         this.logger.debug('SearchCodebaseTool: handle', {
             query: raw.slice(0, 120), project, threshold: threshold ?? this.defaultThreshold,
-            limit, translated, count: results.length, ms: Date.now() - t0,
+            limit, perFile, translated, count: results.length, ms: Date.now() - t0,
         });
         if (results.length === 0) {
             return (0, format_helpers_1.textResponse)('No relevant results found.');

package/dist/src/tools/format-helpers.d.ts

@@ -9,15 +9,9 @@ export declare function formatDependencies(filePath: string, rows: DependencyRow
 export declare function formatDependents(filePath: string, rows: DependencyRow[], transitive: boolean): string;
 export type PathKind = 'file' | 'directory';
 export declare const PATH_EXAMPLE: Record<PathKind, string>;
-/** Description of a path argument; `kind` names what the path points at. */
 export declare function pathArgDescription(kind?: PathKind): string;
 export type PathError = PathRefusal | PathFailure | Extract<FileRangeResult, {
     reason: 'past_end' | 'bad_range';
 }>;
-/**
- * Text of a path error. `input` is the raw argument (echoed by refusals);
- * `relPath` its canonical form, printed by every other message.
- */
 export declare function pathErrorText(argName: string, input: string, relPath: string, err: PathError, kind?: PathKind): string;
-/** Error response for a path error, logged at `warn` — a caller or index-freshness problem, not a server fault. */
 export declare function pathErrorResponse(logger: ILogger, tool: string, argName: string, input: string, relPath: string, err: PathError, kind?: PathKind): ToolResponse;