codesearch-mcp 0.3.0-alpha → 0.4.0-alpha

package/dist/src/tools/SearchCodebaseTool.js

@@ -1,76 +1,94 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SearchCodebaseTool = void 0;
+const zod_1 = require("zod");
 const format_helpers_1 = require("./format-helpers");
+const McpTool_1 = require("./McpTool");
+const tool_args_1 = require("./tool-args");
 const result_shaping_1 = require("../search/result-shaping");
-class SearchCodebaseTool {
-    searcher;
-    defaultLimit;
-    maxLimit;
-    defaultThreshold;
-    logger;
-    constructor(searcher, defaultLimit, maxLimit, defaultThreshold, logger) {
-        this.searcher = searcher;
-        this.defaultLimit = defaultLimit;
-        this.maxLimit = maxLimit;
-        this.defaultThreshold = defaultThreshold;
-        this.logger = logger;
+const constants_1 = require("../constants");
+function searchArgs(defaultLimit, maxLimit, defaultThreshold) {
+    const shown = (0, constants_1.formatThreshold)(defaultThreshold);
+    const stricter = defaultThreshold > 0 ? ' Use a stricter value a little below the default for precise technical queries.' : '';
+    const raise = defaultThreshold < 1 ? ' Raise it (up to 1.0) when a search finds nothing.' : '';
+    return zod_1.z.object({
+        query: (0, tool_args_1.requiredText)(),
+        limit: (0, tool_args_1.intInRange)(`Max results (default ${defaultLimit}, max ${maxLimit})`, { min: 1, max: maxLimit, fallback: defaultLimit }),
+        project: (0, tool_args_1.optionalText)('Filter by project name (optional). Use list_projects to see available names.'),
+        include_neighbors: (0, tool_args_1.flag)('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: (0, tool_args_1.flag)('Append direct imports and dependents list to each result. Shows "Imports: X · Y" and "Used by: Z" without extra tool calls.'),
+        threshold: (0, tool_args_1.numberInRange)(`Max cosine distance (0–1). Lower = stricter. Default: ${shown}.${stricter}${raise}`, { min: 0, max: 1 }),
+        per_file: (0, tool_args_1.intInRange)(`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).`, { min: 1, fallback: result_shaping_1.DEFAULT_PER_FILE }),
+        rerank: (0, tool_args_1.flag)('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).'),
+    });
+}
+const DISTANCE_NOTE = '> Lower distance = closer match. Results may be reranked, so their order need not follow the distance.';
+function renderNoResults(cause, project, threshold) {
+    const first = 'No relevant results found.';
+    switch (cause) {
+        case 'empty-scope':
+            return `${first}\n${project
+                ? `Project \`${project}\` has no indexed chunks. Check the name with \`list_projects\`.`
+                : 'The index holds no chunks. Run `rag-index`.'}`;
+        case 'no-candidates': {
+            const steps = ['rephrase the query', 'use `find_symbol` for a known name'];
+            if (project)
+                steps.push('drop `project`');
+            if (threshold < 1)
+                steps.push('pass a higher `threshold`');
+            const last = steps.pop();
+            return `${first}\nNo chunk ${project ? `of project \`${project}\` ` : ''}came within the distance threshold, which does not show the code is absent. Next: ${steps.join(', ')}, or ${last}.`;
+        }
+        case 'lookup-failed':
+            return `${first}\nThe cause could not be determined, so this does not show the code is absent.`;
     }
-    definition() {
-        return {
+}
+class SearchCodebaseTool extends McpTool_1.McpTool {
+    chunks;
+    dependencies;
+    defaultThreshold;
+    constructor(chunks, dependencies, defaultLimit, maxLimit, defaultThreshold, logger) {
+        super({
             name: 'search_codebase',
-            description: 'Search local project codebase by semantic similarity. Each result shows File, Project, an optional Symbol breadcrumb (owning declaration, e.g. `IndexerService.ingestFile`), Line, the code, and Relevance.',
-            inputSchema: {
-                type: 'object',
-                properties: {
-                    query: { type: 'string' },
-                    limit: { type: 'number', description: `Max results (default ${this.defaultLimit}, max ${this.maxLimit})` },
-                    project: { type: 'string', description: 'Filter by project name (optional). Use list_projects to see available names.' },
-                    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.` },
-                    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'],
-            },
-        };
+            description: 'Search local project codebase by semantic similarity. Each result shows File, Project, an optional Symbol breadcrumb (owning declaration, e.g. `IndexerService.ingestFile`), Line, the code, and Distance (cosine distance: lower is closer).',
+            args: searchArgs(defaultLimit, maxLimit, defaultThreshold),
+        }, logger);
+        this.chunks = chunks;
+        this.dependencies = dependencies;
+        this.defaultThreshold = defaultThreshold;
     }
-    async handle(args) {
+    async run(args) {
         const t0 = Date.now();
-        const raw = String(args.query);
-        const limit = Math.min(Math.max(1, Number(args.limit) || this.defaultLimit), this.maxLimit);
-        const project = args.project ? String(args.project) : null;
-        const includeNeighbors = Boolean(args.include_neighbors);
-        const includeGraphContext = Boolean(args.include_graph_context);
-        const rawThreshold = args.threshold;
-        const parsedThreshold = Number(rawThreshold);
-        const threshold = rawThreshold != null && !isNaN(parsedThreshold)
-            ? 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, perFile);
+        const raw = args.query;
+        const limit = args.limit;
+        const project = args.project ?? null;
+        const includeNeighbors = args.include_neighbors ?? false;
+        const includeGraphContext = args.include_graph_context ?? false;
+        const threshold = args.threshold;
+        const rerank = args.rerank;
+        const perFile = args.per_file;
+        const { query, translated } = await this.chunks.prepareQuery(raw);
+        const results = await this.chunks.searchChunks(query, limit, project, threshold, rerank, perFile);
         this.logger.debug('SearchCodebaseTool: handle', {
             query: raw.slice(0, 120), project, threshold: threshold ?? this.defaultThreshold,
             limit, perFile, translated, count: results.length, ms: Date.now() - t0,
         });
         if (results.length === 0) {
-            return (0, format_helpers_1.textResponse)('No relevant results found.');
+            const cause = await this.chunks.explainNoResults(project);
+            return (0, format_helpers_1.textResponse)(renderNoResults(cause, project, threshold ?? this.defaultThreshold));
         }
-        const header = translated ? `> Query translated: "${raw}" → "${query}"\n\n` : '';
+        const header = `${translated ? `> Query translated: "${raw}" → "${query}"\n` : ''}${DISTANCE_NOTE}\n\n`;
         let graphCtx = null;
         if (includeGraphContext) {
-            graphCtx = await this.searcher.fetchGraphContext(results);
+            graphCtx = await this.dependencies.fetchGraphContext(results);
         }
         if (includeNeighbors) {
-            const withNeighbors = await this.searcher.fetchNeighbors(results);
+            const withNeighbors = await this.chunks.fetchNeighbors(results);
             const blocks = withNeighbors.map(({ result, prevChunk, nextChunk }) => {
                 const parts = [];
                 if (prevChunk)
                     parts.push((0, format_helpers_1.formatChunk)(prevChunk, 'prev chunk'));
-                parts.push(`${(0, format_helpers_1.formatChunk)(result)}\n**Relevance:** ${result.score}${(0, format_helpers_1.formatGraphContext)(graphCtx?.get(result.filePath))}`);
+                parts.push(`${(0, format_helpers_1.formatChunk)(result)}\n**Distance:** ${result.score}${(0, format_helpers_1.formatGraphContext)(graphCtx?.get(result.filePath))}`);
                 if (nextChunk)
                     parts.push((0, format_helpers_1.formatChunk)(nextChunk, 'next chunk'));
                 return parts.join('\n\n');
@@ -78,7 +96,7 @@ class SearchCodebaseTool {
             return (0, format_helpers_1.textResponse)(header + blocks.join('\n\n---\n\n'));
         }
         const text = results
-            .map(r => `${(0, format_helpers_1.formatChunk)(r)}\n**Relevance:** ${r.score}${(0, format_helpers_1.formatGraphContext)(graphCtx?.get(r.filePath))}`)
+            .map(r => `${(0, format_helpers_1.formatChunk)(r)}\n**Distance:** ${r.score}${(0, format_helpers_1.formatGraphContext)(graphCtx?.get(r.filePath))}`)
             .join('\n\n---\n\n');
         return (0, format_helpers_1.textResponse)(header + text);
     }

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

@@ -1,12 +1,18 @@
-import type { ChunkRow, DependencyRow, GraphContext, FileRangeResult, PathFailure, PathRefusal } from '../services/SearcherService';
+import type { ChunkRow } from '../interfaces/IChunkSearch';
+import type { DependencyRow, GraphContext } from '../interfaces/IDependencyGraph';
+import type { FileRangeResult } from '../interfaces/IWorkspaceFiles';
+import type { PathFailure, PathRefusal } from '../interfaces/IToolPaths';
 import type { ToolResponse } from '../interfaces/IMcpToolHandler';
 import type { ILogger } from '../interfaces/ILogger';
 export declare function textResponse(text: string): ToolResponse;
 export declare function errorResponse(text: string): ToolResponse;
 export declare function formatChunk(r: ChunkRow, label?: string): string;
 export declare function formatGraphContext(ctx: GraphContext | undefined): string;
-export declare function formatDependencies(filePath: string, rows: DependencyRow[], transitive: boolean): string;
-export declare function formatDependents(filePath: string, rows: DependencyRow[], transitive: boolean): string;
+export declare function formatDependencies(filePath: string, rows: DependencyRow[], transitive: boolean, symbol?: string | null): string;
+export declare function formatDependents(filePath: string, rows: DependencyRow[], transitive: boolean, symbol?: string | null): string;
+export declare function formatTransitiveSection(rows: DependencyRow[], symbol: string | null, side: 'dependencies' | 'dependents'): string;
+export declare function formatDependenciesFilterMiss(filePath: string, symbol: string, unfiltered: DependencyRow[]): string;
+export declare function formatDependentsFilterMiss(filePath: string, symbol: string, unfiltered: DependencyRow[]): string;
 export type PathKind = 'file' | 'directory';
 export declare const PATH_EXAMPLE: Record<PathKind, string>;
 export declare function pathArgDescription(kind?: PathKind): string;

package/dist/src/tools/format-helpers.js

@@ -7,6 +7,9 @@ exports.formatChunk = formatChunk;
 exports.formatGraphContext = formatGraphContext;
 exports.formatDependencies = formatDependencies;
 exports.formatDependents = formatDependents;
+exports.formatTransitiveSection = formatTransitiveSection;
+exports.formatDependenciesFilterMiss = formatDependenciesFilterMiss;
+exports.formatDependentsFilterMiss = formatDependentsFilterMiss;
 exports.pathArgDescription = pathArgDescription;
 exports.pathErrorText = pathErrorText;
 exports.pathErrorResponse = pathErrorResponse;
@@ -101,7 +104,13 @@ function groupByFile(rows, key) {
 function directHeader(fileCount) {
     return `**Direct:** ${fileCount} file${fileCount === 1 ? '' : 's'}`;
 }
-function formatDependencies(filePath, rows, transitive) {
+function transitiveLines(indirect, symbol, line) {
+    const note = symbol ? ' *(not filtered by `symbol`, which applies to direct imports only)*' : '';
+    return [`**Transitive:**${note}`, ...indirect.map(line)];
+}
+const dependencyLine = (r) => `  → \`${r.toFile}\` (depth ${r.depth}, via \`${r.via}\`)`;
+const dependentLine = (r) => `  ← \`${r.fromFile}\` (depth ${r.depth}, via \`${r.via}\`)`;
+function formatDependencies(filePath, rows, transitive, symbol = null) {
     const direct = rows.filter(r => !transitive || (r.depth ?? 1) === 1);
     const indirect = transitive ? rows.filter(r => (r.depth ?? 1) > 1) : [];
     const groups = groupByFile(direct, 'toFile');
@@ -110,15 +119,11 @@ function formatDependencies(filePath, rows, transitive) {
         const names = groupNames(groupRows);
         lines.push(`  → \`${toFile}\`${names ? ` — ${names}` : ''}`);
     }
-    if (indirect.length > 0) {
-        lines.push('\n**Transitive:**');
-        for (const r of indirect) {
-            lines.push(`  → \`${r.toFile}\` (depth ${r.depth}, via \`${r.via}\`)`);
-        }
-    }
+    if (indirect.length > 0)
+        lines.push('', ...transitiveLines(indirect, symbol, dependencyLine));
     return lines.join('\n');
 }
-function formatDependents(filePath, rows, transitive) {
+function formatDependents(filePath, rows, transitive, symbol = null) {
     const direct = rows.filter(r => !transitive || (r.depth ?? 1) === 1);
     const indirect = transitive ? rows.filter(r => (r.depth ?? 1) > 1) : [];
     const groups = groupByFile(direct, 'fromFile');
@@ -131,14 +136,53 @@ function formatDependents(filePath, rows, transitive) {
             line += ` · in ${inPart}`;
         lines.push(line);
     }
-    if (indirect.length > 0) {
-        lines.push('\n**Transitive:**');
-        for (const r of indirect) {
-            lines.push(`  ← \`${r.fromFile}\` (depth ${r.depth}, via \`${r.via}\`)`);
-        }
-    }
+    if (indirect.length > 0)
+        lines.push('', ...transitiveLines(indirect, symbol, dependentLine));
     return lines.join('\n');
 }
+function formatTransitiveSection(rows, symbol, side) {
+    const indirect = rows.filter(r => (r.depth ?? 1) > 1);
+    if (indirect.length === 0)
+        return '';
+    return transitiveLines(indirect, symbol, side === 'dependencies' ? dependencyLine : dependentLine).join('\n');
+}
+function filterMissSummary(rows, key) {
+    const groups = groupByFile(rows, key);
+    const names = [];
+    for (const r of rows) {
+        if (r.toSymbol !== null && !names.includes(r.toSymbol))
+            names.push(r.toSymbol);
+    }
+    const nameless = [...groups.values()].filter(g => g.some(r => r.toSymbol === null)).length;
+    return { files: groups.size, names: capped(names, MAX_NAMES), nameless };
+}
+function filterMissTail(nameless) {
+    const lines = [];
+    if (nameless > 0) {
+        lines.push(`${nameless} of them ${nameless === 1 ? 'uses' : 'use'} a default, namespace, side-effect or \`export *\` import, which the \`symbol\` filter cannot match.`);
+    }
+    lines.push('Retry without `symbol` to list them.');
+    return lines;
+}
+function formatDependenciesFilterMiss(filePath, symbol, unfiltered) {
+    const { files, names, nameless } = filterMissSummary(unfiltered, 'toFile');
+    const importing = names ? `, importing: ${names}` : '';
+    return [
+        `No import of \`${symbol}\` found in: ${filePath}`,
+        `It has ${files} direct ${files === 1 ? 'dependency' : 'dependencies'}${importing}.`,
+        ...filterMissTail(nameless),
+    ].join('\n');
+}
+function formatDependentsFilterMiss(filePath, symbol, unfiltered) {
+    const { files, names, nameless } = filterMissSummary(unfiltered, 'fromFile');
+    const using = names ? `, using: ${names}` : '';
+    return [
+        `**Dependents of** \`${filePath}\``,
+        '',
+        `**Direct:** No direct import of \`${symbol}\`. ${files} ${files === 1 ? 'file imports' : 'files import'} this file${using}.`,
+        ...filterMissTail(nameless),
+    ].join('\n');
+}
 exports.PATH_EXAMPLE = { file: 'my-app/src/index.ts', directory: 'my-app/src' };
 function pathArgDescription(kind = 'file') {
     const root = kind === 'directory' ? ', "." for the workspace root' : '';
@@ -184,6 +228,7 @@ function pathErrorText(argName, input, relPath, err, kind = 'file') {
             return `Not indexed: ${relPath}\n${notIndexedExplanation(err.explanation)}`;
         case 'not_a_file': return `Not a file: ${relPath}`;
         case 'not_a_directory': return `Not a directory: ${relPath}`;
+        case 'binary': return `Binary file: ${relPath}`;
         case 'unreadable': return `Cannot read: ${relPath} (${err.code})`;
         case 'past_end': return `${relPath} has ${err.lineCount} lines; start_line ${err.startLine} is past the end`;
         case 'bad_range': return `end_line ${err.endLine} is before start_line ${err.startLine}`;

package/dist/src/tools/tool-args.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import type { PathKind } from './format-helpers';
+export declare function requiredText(description?: string): z.ZodType<string>;
+export declare function optionalText(description?: string): z.ZodType<string | undefined>;
+export declare function pathArg(description: string, kind?: PathKind): z.ZodType<string>;
+export declare function optionalPathArg(description: string): z.ZodType<string | undefined>;
+interface IntRange {
+    min?: number;
+    max?: number;
+}
+export declare function intInRange(description: string, range: IntRange & {
+    fallback: number;
+}): z.ZodType<number>;
+export declare function intInRange(description: string, range?: IntRange): z.ZodType<number | undefined>;
+export declare function numberInRange(description: string, range: {
+    min: number;
+    max: number;
+}): z.ZodType<number | undefined>;
+export declare function flag(description: string): z.ZodType<boolean | undefined>;
+export declare function oneOf<T extends string>(description: string, values: readonly T[], fallback: T): z.ZodType<T>;
+export declare function toInputSchema(schema: z.ZodObject): Record<string, unknown>;
+export type ArgFailure = {
+    kind: 'missing-path';
+    arg: string;
+    pathKind: PathKind;
+} | {
+    kind: 'invalid';
+    text: string;
+};
+export type ParsedArgs<T> = {
+    ok: true;
+    args: T;
+} | {
+    ok: false;
+    failure: ArgFailure;
+};
+export declare function parseToolArgs<S extends z.ZodObject>(schema: S, raw: Record<string, unknown>): ParsedArgs<z.output<S>>;
+export {};

package/dist/src/tools/tool-args.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requiredText = requiredText;
+exports.optionalText = optionalText;
+exports.pathArg = pathArg;
+exports.optionalPathArg = optionalPathArg;
+exports.intInRange = intInRange;
+exports.numberInRange = numberInRange;
+exports.flag = flag;
+exports.oneOf = oneOf;
+exports.toInputSchema = toInputSchema;
+exports.parseToolArgs = parseToolArgs;
+const zod_1 = require("zod");
+const requiredPaths = zod_1.z.registry();
+const isBlank = (value) => value == null || (typeof value === 'string' && !value.trim());
+const blankToUndefined = (value) => (isBlank(value) ? undefined : value);
+const emptyPathToUndefined = (value) => (value === '' ? undefined : value ?? undefined);
+const readNumber = (value) => {
+    const present = blankToUndefined(value);
+    return typeof present === 'string' ? Number(present) : present;
+};
+const readFlag = (value) => {
+    const present = blankToUndefined(value);
+    if (present === 'true')
+        return true;
+    if (present === 'false')
+        return false;
+    return present;
+};
+const clamp = (value, min = -Infinity, max = Infinity) => Math.min(Math.max(min, value), max);
+function described(schema, description) {
+    return description === undefined ? schema : schema.describe(description);
+}
+function requiredText(description) {
+    return described(zod_1.z.preprocess(blankToUndefined, zod_1.z.string()), description);
+}
+function optionalText(description) {
+    return described(zod_1.z.preprocess(blankToUndefined, zod_1.z.string().optional()), description);
+}
+function pathArg(description, kind = 'file') {
+    const schema = zod_1.z.preprocess(emptyPathToUndefined, zod_1.z.string()).describe(description);
+    requiredPaths.add(schema, { pathKind: kind });
+    return schema;
+}
+function optionalPathArg(description) {
+    return zod_1.z.preprocess(emptyPathToUndefined, zod_1.z.string().optional()).describe(description);
+}
+function intInRange(description, range = {}) {
+    const { min, max, fallback } = range;
+    const inRange = zod_1.z.number().optional().transform(value => {
+        const picked = value === undefined ? fallback : Math.trunc(value);
+        return picked === undefined ? undefined : clamp(picked, min, max);
+    });
+    return zod_1.z.preprocess(readNumber, inRange).describe(description);
+}
+function numberInRange(description, range) {
+    const inRange = zod_1.z.number().optional().transform(value => value === undefined ? undefined : clamp(value, range.min, range.max));
+    return zod_1.z.preprocess(readNumber, inRange).describe(description);
+}
+function flag(description) {
+    return zod_1.z.preprocess(readFlag, zod_1.z.boolean().optional()).describe(description);
+}
+function oneOf(description, values, fallback) {
+    const member = zod_1.z.enum(values).optional().transform(value => (value ?? fallback));
+    return zod_1.z.preprocess(blankToUndefined, member).describe(description);
+}
+function toInputSchema(schema) {
+    const { $schema: _, ...inputSchema } = zod_1.z.toJSONSchema(schema, { io: 'input' });
+    return inputSchema;
+}
+function expectation(issue) {
+    return issue.code === 'invalid_value'
+        ? `one of ${issue.values.join(', ')}`
+        : `a ${issue.expected}`;
+}
+function parseToolArgs(schema, raw) {
+    const parsed = schema.safeParse(raw);
+    if (parsed.success)
+        return { ok: true, args: parsed.data };
+    const lines = [];
+    for (const [arg, argSchema] of Object.entries(schema.shape)) {
+        const issue = parsed.error.issues.find(i => i.path[0] === arg);
+        if (!issue)
+            continue;
+        if (!isBlank(raw[arg])) {
+            lines.push(`Invalid ${arg}: expected ${expectation(issue)}`);
+            continue;
+        }
+        const path = requiredPaths.get(argSchema);
+        if (path)
+            return { ok: false, failure: { kind: 'missing-path', arg, pathKind: path.pathKind } };
+        lines.push(`Missing ${arg}`);
+    }
+    return { ok: false, failure: { kind: 'invalid', text: lines.join('\n') } };
+}

package/dist/src/workspace/GrepRunner.d.ts

@@ -0,0 +1,15 @@
+import type { ILogger } from '../interfaces';
+export interface GrepRun {
+    ok: boolean;
+    output: string | null;
+    failure: string | null;
+}
+export declare class GrepRunner {
+    private logger;
+    private readonly liveGreps;
+    private readonly killLiveGreps;
+    constructor(logger: ILogger);
+    run(args: string[]): Promise<GrepRun>;
+    private trackGrep;
+    private untrackGrep;
+}

package/dist/src/workspace/GrepRunner.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrepRunner = void 0;
+const child_process_1 = require("child_process");
+const fs_access_1 = require("./fs-access");
+const GREP_TIMEOUT_MS = 60_000;
+const FAILURE_MAX_CHARS = 200;
+const STDERR_MAX_BYTES = 4096;
+const capFailure = (text) => {
+    const capped = text.slice(0, FAILURE_MAX_CHARS);
+    return /[\uD800-\uDBFF]$/.test(capped) ? capped.slice(0, -1) : capped;
+};
+class GrepRunner {
+    logger;
+    liveGreps = new Set();
+    killLiveGreps = () => {
+        for (const proc of this.liveGreps)
+            proc.kill('SIGKILL');
+    };
+    constructor(logger) {
+        this.logger = logger;
+    }
+    run(args) {
+        return new Promise((resolve) => {
+            let proc;
+            try {
+                proc = (0, child_process_1.spawn)('grep', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+            }
+            catch (err) {
+                this.logger.error('GrepRunner: grep spawn failed', { err });
+                resolve({ ok: false, output: null, failure: capFailure((0, fs_access_1.errorCode)(err)) });
+                return;
+            }
+            this.trackGrep(proc);
+            const chunks = [];
+            let totalBytes = 0;
+            const MAX_BUFFER = 10 * 1024 * 1024;
+            const printed = () => (chunks.length === 0 ? null : Buffer.concat(chunks).toString('utf-8'));
+            const stderrChunks = [];
+            let stderrBytes = 0;
+            const stderrLine = () => {
+                const text = Buffer.concat(stderrChunks).toString('utf-8');
+                const line = text.split('\n').map(l => l.trim()).find(l => l !== '');
+                return line ?? null;
+            };
+            const timer = setTimeout(() => {
+                this.logger.warn('GrepRunner: grep timed out', { ms: GREP_TIMEOUT_MS });
+                finish({ ok: false, output: printed(), failure: `timed out after ${GREP_TIMEOUT_MS / 1000} seconds` });
+                proc.kill('SIGKILL');
+                proc.stdout?.destroy();
+                proc.stderr?.destroy();
+            }, GREP_TIMEOUT_MS);
+            timer.unref();
+            let settled = false;
+            const finish = (result) => {
+                settled = true;
+                clearTimeout(timer);
+                this.untrackGrep(proc);
+                resolve(result);
+            };
+            proc.stdout?.on('data', (chunk) => {
+                totalBytes += chunk.length;
+                if (totalBytes <= MAX_BUFFER) {
+                    chunks.push(chunk);
+                }
+            });
+            proc.stderr?.on('data', (chunk) => {
+                if (stderrBytes >= STDERR_MAX_BYTES)
+                    return;
+                stderrChunks.push(chunk);
+                stderrBytes += chunk.length;
+            });
+            proc.on('error', (err) => {
+                if (settled)
+                    return;
+                this.logger.error('GrepRunner: grep spawn failed', { err });
+                finish({ ok: false, output: null, failure: capFailure((0, fs_access_1.errorCode)(err)) });
+            });
+            proc.on('close', (code, signal) => {
+                if (settled)
+                    return;
+                const output = printed();
+                if (code === 0 || code === 1) {
+                    finish({ ok: true, output, failure: null });
+                    return;
+                }
+                this.logger.warn('GrepRunner: grep exited with code', { code, signal });
+                const cause = stderrLine() ?? (code !== null ? `exit status ${code}` : `signal ${signal}`);
+                finish({ ok: false, output, failure: capFailure(cause) });
+            });
+        });
+    }
+    trackGrep(proc) {
+        if (this.liveGreps.size === 0)
+            process.on('exit', this.killLiveGreps);
+        this.liveGreps.add(proc);
+    }
+    untrackGrep(proc) {
+        this.liveGreps.delete(proc);
+        if (this.liveGreps.size === 0)
+            process.off('exit', this.killLiveGreps);
+    }
+}
+exports.GrepRunner = GrepRunner;

package/dist/src/workspace/ProjectRoots.d.ts

@@ -0,0 +1,22 @@
+import type { Config } from '../config';
+import type { IProjectDiscovery } from '../interfaces';
+import type { IProjectRoots } from '../interfaces/IProjectRoots';
+export declare class ProjectRoots implements IProjectRoots {
+    private discovery;
+    private config;
+    private rootMap?;
+    constructor(discovery: IProjectDiscovery, config: Config);
+    private projectRootMap;
+    entries(): IterableIterator<[string, string]>;
+    refresh(): void;
+    resolveProjectRoot(name: string): string;
+    toRel(absPath: string): string;
+    toAbs(relPath: string): string;
+    workspaceRoot(): string;
+    findProjectRootByName(name: string): string | null;
+    findProjectRoot(match: (rel: string) => boolean): {
+        name: string;
+        rel: string;
+    } | null;
+    fallbackRoot(relPath: string): string | null;
+}