codesearch-mcp 0.2.2-alpha → 0.3.0-alpha

package/dist/src/services/LoggerService.js

@@ -41,21 +41,20 @@ const pino_1 = __importDefault(require("pino"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const fs = __importStar(require("fs"));
+const async_hooks_1 = require("async_hooks");
+const error_record_1 = require("../error-record");
 const DEFAULT_LOG_DIR = path.join(os.homedir(), '.config', 'codesearch-mcp', 'logs');
 class LoggerService {
     logger;
-    // Dedicated `info`-level channel for search telemetry, independent of the
-    // main logger's configured level. Null when file logging is disabled so
-    // metrics never reach stdout (owned by the MCP JSON transport).
-    metricsLogger;
-    constructor(logger, metricsLogger = null) {
+    context;
+    constructor(logger, context) {
         this.logger = logger;
-        this.metricsLogger = metricsLogger;
+        this.context = context;
     }
     static silent() {
-        return new LoggerService((0, pino_1.default)({ level: 'silent' }));
+        return LoggerService.build('debug', undefined);
     }
-    static fromConfig(cfg, name) {
+    static fromConfig(cfg, name, bindings) {
         const level = cfg.level;
         const dirVal = cfg.dir;
         const enabled = dirVal !== 'false' && dirVal !== '0';
@@ -66,45 +65,42 @@ class LoggerService {
                 ? path.join(logDir, name, `${name}.log`)
                 : path.join(logDir, 'rag.log');
         }
-        return LoggerService.buildFromPath(level, filePath);
+        return LoggerService.build(level, filePath ? LoggerService.fileTransport(level, filePath) : undefined, bindings);
     }
-    static buildFromPath(level, filePath) {
-        if (filePath)
-            fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        // The transport target must accept `info` so the metrics channel can emit
-        // even when the main level is `warn`/`error`; the main logger still gates
-        // normal calls at `level`, so nothing else leaks below it.
-        const targetLevel = pino_1.default.levels.values[level] < pino_1.default.levels.values.info ? level : 'info';
-        const transport = filePath
-            ? pino_1.default.transport({
-                targets: [{
-                        target: 'pino-roll',
-                        options: {
-                            file: filePath,
-                            frequency: 'daily',
-                            dateFormat: 'yyyy-MM-dd',
-                            mkdir: true,
-                            symlink: true,
-                            limit: { count: 30 },
-                            size: '50m',
-                        },
-                        level: targetLevel,
-                    }],
-            })
-            : undefined;
-        const logger = transport
-            ? (0, pino_1.default)({ level }, transport)
+    static toStream(level, stream, bindings) {
+        return LoggerService.build(level, stream, bindings);
+    }
+    static fileTransport(level, filePath) {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        return pino_1.default.transport({
+            targets: [{
+                    target: 'pino-roll',
+                    options: {
+                        file: filePath,
+                        frequency: 'daily',
+                        dateFormat: 'yyyy-MM-dd',
+                        mkdir: true,
+                        symlink: true,
+                        limit: { count: 30 },
+                        size: '50m',
+                    },
+                    level,
+                }],
+        });
+    }
+    static build(level, destination, bindings) {
+        const context = new async_hooks_1.AsyncLocalStorage();
+        const base = destination
+            ? (0, pino_1.default)({ level, serializers: error_record_1.LOG_SERIALIZERS, mixin: () => ({ ...context.getStore() }) }, destination)
             : (0, pino_1.default)({ level: 'silent' });
-        // Child logger pinned at `info` regardless of the parent level; only used by
-        // metric(). Null when there is no file transport (default stdout must stay
-        // clean for the MCP transport).
-        const metricsLogger = transport ? logger.child({}, { level: 'info' }) : null;
-        return new LoggerService(logger, metricsLogger);
+        return new LoggerService(bindings ? base.child(bindings) : base, context);
     }
     debug(msg, data) { this.logger.debug(data ?? {}, msg); }
     info(msg, data) { this.logger.info(data ?? {}, msg); }
     warn(msg, data) { this.logger.warn(data ?? {}, msg); }
     error(msg, data) { this.logger.error(data ?? {}, msg); }
-    metric(msg, data) { this.metricsLogger?.info(data ?? {}, msg); }
+    withContext(context, fn) {
+        return this.context.run(context, fn);
+    }
 }
 exports.LoggerService = LoggerService;

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

@@ -1,12 +1,30 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { Config } from '../config';
 import type { ISearcher } from '../interfaces/ISearcher';
 import type { ILogger } from '../interfaces/ILogger';
-/**
- * McpServer — thin orchestration layer that delegates tool handling
- * to individual IMcpToolHandler implementations (Open/Closed Principle).
- *
- * To add a new tool: implement IMcpToolHandler and register it in createTools().
- */
+import type { IMcpToolHandler, ToolResponse } from '../interfaces/IMcpToolHandler';
+export declare function dispatchTool(tools: Map<string, IMcpToolHandler>, name: string, args: Record<string, unknown>, logger: ILogger): Promise<ToolResponse>;
+export interface ToolCallRequest {
+    name: string;
+    arguments?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+}
+export interface ToolCaller {
+    callId: number;
+    session: string | null;
+    client: {
+        name: string;
+        version: string;
+    } | null;
+    startupError?: Error;
+}
+export declare function handleToolCall(tools: Map<string, IMcpToolHandler>, req: ToolCallRequest, signal: AbortSignal, caller: ToolCaller, logger: ILogger): Promise<ToolResponse>;
+export declare function createToolCallHandler(tools: Map<string, IMcpToolHandler>, server: Pick<Server, 'getClientVersion'>, identity: Pick<ToolCaller, 'session' | 'startupError'>, logger: ILogger): (req: {
+    params: ToolCallRequest;
+}, extra: {
+    signal: AbortSignal;
+}) => Promise<ToolResponse>;
+export declare function buildInstructions(t: number): string;
 export declare class McpServer {
     private searcher;
     private config;
@@ -15,9 +33,6 @@ export declare class McpServer {
     private readonly tools;
     constructor(searcher: ISearcher, config: Config, logger: ILogger);
     start(startupError?: Error): Promise<void>;
-    /**
-     * Factory method: creates and registers all tool handlers.
-     * New tools are added here without modifying the dispatch logic above.
-     */
+    createServer(startupError?: Error): Server;
     private createTools;
 }

package/dist/src/services/McpServer.js

@@ -34,12 +34,18 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.McpServer = void 0;
+exports.dispatchTool = dispatchTool;
+exports.handleToolCall = handleToolCall;
+exports.createToolCallHandler = createToolCallHandler;
+exports.buildInstructions = buildInstructions;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const tools_1 = require("../tools");
+const tool_call_log_1 = require("../tool-call-log");
+const error_record_1 = require("../error-record");
 function readPackageVersion() {
     try {
         return JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf-8')).version ?? '0.0.0';
@@ -48,6 +54,72 @@ function readPackageVersion() {
         return '0.0.0';
     }
 }
+async function dispatchTool(tools, name, args, logger) {
+    const handler = tools.get(name);
+    if (!handler) {
+        return { isError: true, content: [{ type: 'text', text: `Unknown tool: ${name}` }] };
+    }
+    try {
+        return await handler.handle(args);
+    }
+    catch (err) {
+        logger.error('McpServer: tool handler error', { tool: name, err });
+        const reason = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: 'text', text: `Tool error: ${reason}` }] };
+    }
+}
+function unavailableResponse(startupError) {
+    return {
+        isError: true,
+        content: [{
+                type: 'text',
+                text: `MCP server is unavailable: ${(0, error_record_1.errorMessage)(startupError)}\n\nCheck the log file and fix the issue, then restart the MCP server.`,
+            }],
+    };
+}
+function metaForLog(meta) {
+    if (!meta)
+        return null;
+    const { progressToken: _, ...rest } = meta;
+    return Object.keys(rest).length ? (0, tool_call_log_1.truncateForLog)(rest) : null;
+}
+async function handleToolCall(tools, req, signal, caller, logger) {
+    const t0 = Date.now();
+    const toolUseId = req._meta?.['claudecode/toolUseId'];
+    const context = typeof toolUseId === 'string' ? { callId: caller.callId, toolUseId } : { callId: caller.callId };
+    return logger.withContext(context, async () => {
+        const args = req.arguments ?? {};
+        const response = caller.startupError
+            ? unavailableResponse(caller.startupError)
+            : await dispatchTool(tools, req.name, args, logger);
+        const ms = Date.now() - t0;
+        if (!response.isError)
+            logger.debug('McpServer: tool handled', { tool: req.name, ms });
+        logger.info('tool call', {
+            tool: req.name,
+            args: (0, tool_call_log_1.truncateForLog)(args),
+            isError: response.isError ?? false,
+            responseChars: response.content.reduce((n, c) => n + (typeof c.text === 'string' ? c.text.length : 0), 0),
+            ms,
+            client: caller.client,
+            session: caller.session,
+            meta: metaForLog(req._meta),
+            ...(signal.aborted ? { cancelled: true } : {}),
+        });
+        return response;
+    });
+}
+function createToolCallHandler(tools, server, identity, logger) {
+    let nextCallId = 1;
+    return (req, extra) => {
+        const client = server.getClientVersion();
+        return handleToolCall(tools, req.params, extra.signal, {
+            ...identity,
+            callId: nextCallId++,
+            client: client ? { name: client.name, version: client.version } : null,
+        }, logger);
+    };
+}
 function buildInstructions(t) {
     return `
 You have access to a local code intelligence server. Use these tools to search codebases by meaning, navigate import graphs, look up symbol definitions, and read source files.
@@ -58,7 +130,7 @@ Pick one workflow based on what you need:
 
 | Type | Signals | Workflow |
 |---|---|---|
-| **Lookup** | "where is X defined", "find Y" | find_symbol (if name known) → search_codebase (if not found) |
+| **Lookup** | "where is X defined", "find Y" | find_symbol first when the exact name is known — exact and faster. Call search_codebase too, in parallel, when you also want surrounding context or the name might not match verbatim; fall back to it alone if find_symbol comes back empty. |
 | **Caller trace** | "who calls X", "find usages of Y", "what invokes Z" | find_symbol → get_callers |
 | **Conceptual** | "how does X work", "what is Y" | search_codebase → read_file_range |
 | **Flow audit** | "how does X connect to Y", "audit this flow", "trace the path" | search_codebase → **get_dependencies + get_dependents** → Grep |
@@ -68,26 +140,28 @@ Pick one workflow based on what you need:
 
 ## Tools
 
-- **list_projects** — call this first to see what projects are indexed and their exact names.
-- **search_codebase** — semantic search across indexed source files. Returns file path, line number, and a code chunk.
-- **read_file_range** — read a specific line range from any indexed file. Expects a **relative path** as returned by search_codebase.
+Every file or directory argument (\`file_path\`, \`callee_file\`, \`path\`) is workspace-relative, exactly as printed by search_codebase (e.g. \`my-app/src/index.ts\`; \`.\` is the workspace root) — copy paths between tools unchanged.
+
+- **list_projects** — call this first to see what projects are indexed, their exact names and their directories (\`path:\`).
+- **search_codebase** — semantic search across indexed source files. Returns file path, line number, and a code chunk. **Pass \`project\` whenever the target project is known or guessable from the question** — this workspace indexes many projects at once, and an unscoped query competes against all of them, which \`rerank\` cannot fix (reranking only reorders whatever the vector search already retrieved). Pass \`rerank: false\` for "what does X do" / "where is X" lookups described without an exact name — measurement shows reranking hurts these (-0.13 MRR@10, hit@5 68% → 50%). If you already know the exact symbol name, use \`find_symbol\` instead, not \`search_codebase\` — it is faster and exact, and the rerank setting does not matter there. For conceptual/architectural queries reranking is roughly neutral (-0.05 MRR@10, not significant), so omitting \`rerank\` is fine.
+- **read_file_range** — read a specific line range from any file under the workspace, indexed or not.
 - **get_dependencies** — show what files a given file imports (direct or transitive). Use to understand what a file depends on.
 - **get_dependents** — show which files import a given file (reverse graph). Use before refactoring to find all callers.
 - **find_symbol** — find where a symbol is defined by exact name: top-level declarations, class/object-literal members (methods, get/set accessors, constructors, function properties), interface and type-literal method signatures, and namespace-level declarations. Accepts a bare name (\`assertUsersInOrg\`), a qualified name (\`RepairsService.assertUsersInOrg\`, \`NS.Parser.parse\`) to disambiguate same-named members, a quoted name for string-literal members (\`Router.'kebab-name'\`), or a computed name (\`Stack.[Symbol.iterator]\`). Faster than semantic search when you know the name.
 - **get_callers** — find all call sites of a function or method by exact name. Accepts a bare or qualified (\`Class.method\`) symbol, using the same suffix matching as \`find_symbol\`. Uses the call graph index — faster and more precise than grep. A call through an interface-typed receiver is recorded under the interface member (e.g. \`IEmbedder.embedBatch\`), not the implementing class. Use after find_symbol to trace where a symbol is actually called.
-- **list_files** — browse the directory tree of a project path. Use to understand project structure before reading files.
-- **read_file** — read a complete file by **absolute path** with line numbers. Truncates at max_lines with a hint to continue.
+- **list_files** — browse the directory tree of a directory. Use to understand project structure before reading files.
+- **read_file** — read a complete file with line numbers. Truncates at max_lines with a hint to continue.
 
 ## Recommended workflow
 
 ### Lookup / Conceptual
 1. Use \`list_projects\` to discover available projects before filtering by \`project\`.
-2. Use \`search_codebase\` to find relevant code by meaning. If your query uses an ambiguous term (e.g. "subscription" could mean pub/sub or billing), pass a lower \`threshold\` (e.g. \`0.40–0.45\`) to filter out weak matches.
+2. Use \`search_codebase\` to find relevant code by meaning. **Always pass \`project\` when the question names or implies one** — an unscoped search ranks candidates across every indexed project together, so an unrelated project's weak match can outrank the right project's real one. If your query uses an ambiguous term (e.g. "subscription" could mean pub/sub or billing), pass a lower \`threshold\` (e.g. \`0.40–0.45\`) to filter out weak matches.
 3. If a result looks **truncated or incomplete**, call \`read_file_range\` with the returned \`file_path\` and \`start_line\`.
-4. For exploratory searches where results span chunk boundaries, pass \`include_neighbors: true\`.
+4. For exploratory searches where results span chunk boundaries, pass \`include_neighbors: true\`. Results hold at most 2 chunks per file by default; pass \`per_file\` (e.g. \`5\`) when several answers are expected in one file, such as several methods of one class.
 5. To immediately see a file's imports and callers without extra tool calls, pass \`include_graph_context: true\` to \`search_codebase\`. Use this when doing a quick structural survey; switch to \`get_dependencies\`/\`get_dependents\` for full transitive graphs.
-6. Use \`find_symbol\` when you know the exact name — faster than semantic search. Use a qualified name (\`Class.method\`) to disambiguate same-named methods of different classes; a bare name searches every container. Hits marked \`(grep — not in index; may be stale or imprecise)\` come from a fallback text search, not the index — treat them as less reliable. After locating a symbol, use \`get_callers\` to find all call sites — faster and more precise than grep.
-7. Use \`list_files\` to explore project structure before diving into files. Use \`read_file\` to read a complete file by absolute path.
+6. Use \`find_symbol\` when you know the exact name — faster and exact, unlike semantic search. Use a qualified name (\`Class.method\`) to disambiguate same-named methods of different classes; a bare name searches every container. When you also want surrounding context (callers' intent, nearby helpers, how it's described elsewhere), call \`search_codebase\` in parallel rather than after — the two tools answer different questions and neither blocks the other. Hits marked \`(grep — not in index; may be stale or imprecise)\` come from a fallback text search, not the index — treat them as less reliable. After locating a symbol, use \`get_callers\` to find all call sites — faster and more precise than grep. For a NestJS GraphQL operation, resolve field or type, pass the matching \`graphql_query\`/\`graphql_mutation\`/\`graphql_subscription\`/\`graphql_field\`/\`graphql_type\` kind to look it up by the name the schema exposes, not the TypeScript declaration name.
+7. Use \`list_files\` to explore project structure before diving into files. Use \`read_file\` to read a complete file.
 
 ### Flow audit (mandatory steps — do not skip 3 and 4)
 1. Use \`list_projects\` to confirm project names.
@@ -97,8 +171,6 @@ Pick one workflow based on what you need:
 5. For each peripheral file found in steps 3–4: use \`read_file_range\` or \`find_symbol\` to inspect it.
 6. Only after steps 3–4 draw architectural conclusions — \`search_codebase\` alone misses peripheral files because they are semantically thin (configs, types, loaders contain no domain vocabulary).
 
-> **Note:** If \`get_dependencies\` / \`get_dependents\` return empty, the file likely uses path aliases (e.g. \`@core/\`, \`@/\`, \`@db/\`). Fall back to \`Grep\` on the symbol name across the project.
-
 ### Impact analysis
 1. \`get_dependents(target_file)\` — direct callers.
 2. \`get_dependents(target_file, transitive: true)\` — full reverse graph.
@@ -115,7 +187,7 @@ Pick one workflow based on what you need:
 
 ## Dependency graph
 
-\`get_dependencies\` and \`get_dependents\` require \`file_path\` (as returned by \`search_codebase\`) and \`project\` (from \`list_projects\`). Pass \`transitive: true\` for the full dependency chain. depType values: \`import\` | \`import-default\` | \`import-namespace\` | \`reexport\` | \`reexport-namespace\`. \`fromSymbol\` — the top-level class or function in the importing file that uses this import (null if ambiguous or not tracked).
+\`get_dependencies\` and \`get_dependents\` take \`file_path\` alone and list edges in every project. A path that names no file is an error, never an empty result. Pass \`transitive: true\` for the full dependency chain. The direct section prints one line per file, with the names imported from/by it (\`default\` / \`* as namespace\` / \`side-effect\` standing in for a nameless import, re-exports grouped after plain imports under one \`re-export \` prefix, \`export *\` for a namespace re-export); \`get_dependents\` also lists the enclosing declarations (\`· in \`PlansPage\`\`) that use the import — only those resolved unambiguously (a binding used in 2+ declarations yields none), so the list can be partial or absent.
 
 If \`get_dependents\` returns 0 results, add \`symbol\` (the exported name you care about) — this triggers a grep fallback that finds runtime usages in DI containers, string references, and dynamic lookups that the import graph misses.
 
@@ -124,12 +196,6 @@ If \`get_dependents\` returns 0 results, add \`symbol\` (the exported name you c
 Lower score = better match (cosine distance). Results above the configured threshold are filtered out automatically. Treat scores above 0.50 as weak hints — verify with \`read_file_range\` or \`Grep\`. Pass \`threshold\` to \`search_codebase\` to override per-query: \`0.40–0.45\` for precise technical queries (known term, exact concept); \`${t}\` default (broad but reliable). Avoid \`0.35\` — too strict for DSL files (GraphQL, Prisma) and infrastructure code.
 `.trim();
 }
-/**
- * McpServer — thin orchestration layer that delegates tool handling
- * to individual IMcpToolHandler implementations (Open/Closed Principle).
- *
- * To add a new tool: implement IMcpToolHandler and register it in createTools().
- */
 class McpServer {
     searcher;
     config;
@@ -145,62 +211,33 @@ class McpServer {
     }
     async start(startupError) {
         if (startupError) {
-            this.logger.error('McpServer: startup failed, server will report error on every tool call', { reason: startupError.message });
+            this.logger.error('McpServer: startup failed, server will report error on every tool call', { err: startupError });
         }
+        await this.createServer(startupError).connect(new stdio_js_1.StdioServerTransport());
+        this.logger.info('McpServer: started', { version: this.version });
+    }
+    createServer(startupError) {
         const server = new index_js_1.Server({ name: 'local-rag', version: this.version }, { capabilities: { tools: {} }, instructions: buildInstructions(this.config.search.similarityThreshold) });
         server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
             tools: [...this.tools.values()].map(t => t.definition()),
         }));
-        server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
-            if (startupError) {
-                return {
-                    isError: true,
-                    content: [{
-                            type: 'text',
-                            text: `MCP server is unavailable: ${startupError.message}\n\nCheck the log file and fix the issue, then restart the MCP server.`,
-                        }],
-                };
-            }
-            const handler = this.tools.get(req.params.name);
-            if (!handler) {
-                return {
-                    isError: true,
-                    content: [{ type: 'text', text: `Unknown tool: ${req.params.name}` }],
-                };
-            }
-            try {
-                const t0 = Date.now();
-                const result = await handler.handle((req.params.arguments ?? {}));
-                this.logger.debug('McpServer: tool handled', { tool: req.params.name, ms: Date.now() - t0 });
-                return result;
-            }
-            catch (err) {
-                const reason = err instanceof Error ? err.message : String(err);
-                this.logger.error('McpServer: tool handler error', { tool: req.params.name, reason });
-                return {
-                    isError: true,
-                    content: [{ type: 'text', text: `Tool error: ${reason}` }],
-                };
-            }
-        });
-        await server.connect(new stdio_js_1.StdioServerTransport());
-        this.logger.info('McpServer: started', { version: this.version });
+        server.setRequestHandler(types_js_1.CallToolRequestSchema, createToolCallHandler(this.tools, server, {
+            session: (0, tool_call_log_1.resolveSession)(process.env),
+            startupError,
+        }, this.logger));
+        return server;
     }
-    /**
-     * Factory method: creates and registers all tool handlers.
-     * New tools are added here without modifying the dispatch logic above.
-     */
     createTools() {
         const handlers = [
             new tools_1.ListProjectsTool(this.searcher),
             new tools_1.SearchCodebaseTool(this.searcher, this.config.search.defaultLimit, this.config.search.maxLimit, this.config.search.similarityThreshold, this.logger),
-            new tools_1.ReadFileRangeTool(this.searcher),
-            new tools_1.GetDependenciesTool(this.searcher),
-            new tools_1.GetDependentsTool(this.searcher),
+            new tools_1.ReadFileRangeTool(this.searcher, this.logger),
+            new tools_1.GetDependenciesTool(this.searcher, this.logger),
+            new tools_1.GetDependentsTool(this.searcher, this.logger),
             new tools_1.FindSymbolTool(this.searcher),
-            new tools_1.GetCallersTool(this.searcher),
-            new tools_1.ListFilesTool(this.searcher),
-            new tools_1.ReadFileTool(this.searcher),
+            new tools_1.GetCallersTool(this.searcher, this.logger),
+            new tools_1.ListFilesTool(this.searcher, this.logger),
+            new tools_1.ReadFileTool(this.searcher, this.logger),
         ];
         const map = new Map();
         for (const h of handlers) {

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

@@ -6,57 +6,13 @@ export interface WorkspaceInfo {
     rootTsConfigPath: string | null;
     projects: DiscoveredProject[];
 }
-/**
- * Expand discovery units into the leaf projects to index: a nested monorepo
- * unit (with `children`) becomes its sub-projects; an ordinary project stays
- * itself. Shared by IndexCommand (indexing loop) and SearcherService (name→path
- * resolution) so both agree on the leaf set.
- */
 export declare function toLeafProjects(projects: DiscoveredProject[]): DiscoveredProject[];
-/**
- * Project discovery that is monorepo-aware.
- *
- * When a monorepo is detected (via the resolver), it uses the resolver
- * to discover projects. Otherwise, it falls back to the original
- * flat-workspace discovery (directories with package.json). Cross-project
- * import resolution relies on the tsconfig `paths` attached via
- * `rootTsConfigPath` — no separate scope map is built.
- *
- * Single Responsibility: only discovers projects and workspace metadata.
- * Does not index or search.
- *
- * Implements {@link IProjectDiscovery} so it can be wired as the default
- * discovery in the container. `discover()` returns one entry per top-level
- * project: when the root itself is a monorepo, each entry carries the
- * workspace-wide `rootTsConfigPath`; under a flat root, an ordinary project
- * gets `rootTsConfigPath: null`, while a top-level directory that is itself a
- * nested monorepo is returned as a single unit with expanded `children` (see
- * `toLeafProjects`). `analyzeWorkspace()` exposes the full workspace metadata
- * (monorepo flag, root tsconfig, project list).
- */
 export declare class MonorepoAwareDiscoveryService implements IProjectDiscovery {
     private resolvers;
     private logger;
-    /** Discovery used when no monorepo is detected. Defaults to flat package.json scan. */
     private flatDiscovery;
-    constructor(resolvers: IMonorepoResolver[], logger: ILogger, 
-    /** Discovery used when no monorepo is detected. Defaults to flat package.json scan. */
-    flatDiscovery?: IProjectDiscovery);
-    /**
-     * IProjectDiscovery contract: enumerate projects in the workspace.
-     * Attaches the workspace-wide root tsconfig to every project so the
-     * indexer can resolve cross-project path aliases.
-     */
+    constructor(resolvers: IMonorepoResolver[], logger: ILogger, flatDiscovery?: IProjectDiscovery);
     discover(rootDir: string): DiscoveredProject[];
-    /**
-     * If `project`'s directory is itself a monorepo (resolver detects it),
-     * return it with expanded `children` named `<repo>/<sub-project>`, each
-     * carrying the repo's workspace-wide tsconfig. Otherwise return it unchanged.
-     */
     private expandIfNestedMonorepo;
-    /**
-     * Analyze the workspace root and return full workspace information:
-     * monorepo detection flag, root tsconfig path, and project list.
-     */
     analyzeWorkspace(rootDir: string): WorkspaceInfo;
 }

package/dist/src/services/MonorepoAwareDiscoveryService.js

@@ -3,71 +3,26 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MonorepoAwareDiscoveryService = void 0;
 exports.toLeafProjects = toLeafProjects;
 const ProjectDiscoveryService_1 = require("./ProjectDiscoveryService");
-/**
- * Expand discovery units into the leaf projects to index: a nested monorepo
- * unit (with `children`) becomes its sub-projects; an ordinary project stays
- * itself. Shared by IndexCommand (indexing loop) and SearcherService (name→path
- * resolution) so both agree on the leaf set.
- */
 function toLeafProjects(projects) {
     return projects.flatMap(p => (p.children && p.children.length > 0 ? p.children : [p]));
 }
-/**
- * Project discovery that is monorepo-aware.
- *
- * When a monorepo is detected (via the resolver), it uses the resolver
- * to discover projects. Otherwise, it falls back to the original
- * flat-workspace discovery (directories with package.json). Cross-project
- * import resolution relies on the tsconfig `paths` attached via
- * `rootTsConfigPath` — no separate scope map is built.
- *
- * Single Responsibility: only discovers projects and workspace metadata.
- * Does not index or search.
- *
- * Implements {@link IProjectDiscovery} so it can be wired as the default
- * discovery in the container. `discover()` returns one entry per top-level
- * project: when the root itself is a monorepo, each entry carries the
- * workspace-wide `rootTsConfigPath`; under a flat root, an ordinary project
- * gets `rootTsConfigPath: null`, while a top-level directory that is itself a
- * nested monorepo is returned as a single unit with expanded `children` (see
- * `toLeafProjects`). `analyzeWorkspace()` exposes the full workspace metadata
- * (monorepo flag, root tsconfig, project list).
- */
 class MonorepoAwareDiscoveryService {
     resolvers;
     logger;
     flatDiscovery;
-    constructor(resolvers, logger, 
-    /** Discovery used when no monorepo is detected. Defaults to flat package.json scan. */
-    flatDiscovery = new ProjectDiscoveryService_1.ProjectDiscoveryService()) {
+    constructor(resolvers, logger, flatDiscovery = new ProjectDiscoveryService_1.ProjectDiscoveryService()) {
         this.resolvers = resolvers;
         this.logger = logger;
         this.flatDiscovery = flatDiscovery;
     }
-    /**
-     * IProjectDiscovery contract: enumerate projects in the workspace.
-     * Attaches the workspace-wide root tsconfig to every project so the
-     * indexer can resolve cross-project path aliases.
-     */
     discover(rootDir) {
         const workspace = this.analyzeWorkspace(rootDir);
-        // Case A: workspaceRoot itself is a monorepo — attach the workspace-wide
-        // tsconfig to every project (original behavior).
         if (workspace.isMonorepo) {
             return workspace.projects.map(p => ({ ...p, rootTsConfigPath: workspace.rootTsConfigPath }));
         }
-        // Case B: flat workspaceRoot — a top-level project directory may itself be a
-        // nested monorepo (e.g. an Nx repo). Expand such a directory into its
-        // sub-projects as `children`, keeping the repo a single selectable unit.
         return workspace.projects.map(p => this.expandIfNestedMonorepo(p));
     }
-    /**
-     * If `project`'s directory is itself a monorepo (resolver detects it),
-     * return it with expanded `children` named `<repo>/<sub-project>`, each
-     * carrying the repo's workspace-wide tsconfig. Otherwise return it unchanged.
-     */
     expandIfNestedMonorepo(project) {
-        // Ordinary flat project — preserve the original contract (null root tsconfig).
         const flat = { ...project, rootTsConfigPath: null };
         const resolver = this.resolvers.find(r => r.isMonorepo(project.path));
         if (!resolver)
@@ -89,10 +44,6 @@ class MonorepoAwareDiscoveryService {
         });
         return { ...project, children };
     }
-    /**
-     * Analyze the workspace root and return full workspace information:
-     * monorepo detection flag, root tsconfig path, and project list.
-     */
     analyzeWorkspace(rootDir) {
         for (const resolver of this.resolvers) {
             if (resolver.isMonorepo(rootDir)) {
@@ -112,7 +63,6 @@ class MonorepoAwareDiscoveryService {
                 return { isMonorepo: true, rootTsConfigPath, projects };
             }
         }
-        // Fallback: flat workspace (original behavior) — delegated to the default discovery.
         this.logger.debug('MonorepoAwareDiscovery: no monorepo detected, using flat discovery', { rootDir });
         const projects = this.flatDiscovery.discover(rootDir);
         return {

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

@@ -1,40 +1,11 @@
 import type { IMonorepoResolver, MonorepoProject } from '../interfaces/IMonorepoResolver';
 import type { ILogger } from '../interfaces';
-/**
- * Nx monorepo resolver.
- *
- * Detection: presence of `nx.json` at the workspace root.
- *
- * Project discovery strategies (results deduplicated by absolute path):
- * 1. Read `workspace.json` or `angular.json` → projects map
- * 2. Scan standard Nx directories (`apps/`, `libs/`, `packages/`) for
- *    `project.json`, then `package.json` (only when strategy 1 found nothing)
- * 3. `tsconfig.base.json` `paths` — root-level libs referenced only by path
- *    alias (e.g. `contracts/`, `interfaces/`) that the directory scan misses
- * 4. Root-level fallback: treat the workspace root itself as a project
- *    (standalone Nx setup) when nothing else matched
- *
- * tsconfig resolution:
- * - Returns `tsconfig.base.json` at workspace root (Nx convention)
- * - Falls back to `tsconfig.json` at workspace root
- *
- * Cross-project import resolution is handled by the AST parser via the
- * workspace-wide tsconfig `paths` (tsconfig.base.json), so no scope map is built here.
- */
 export declare class NxMonorepoResolver implements IMonorepoResolver {
     private logger;
     constructor(logger: ILogger);
     isMonorepo(rootDir: string): boolean;
     discoverProjects(rootDir: string): MonorepoProject[];
-    /**
-     * Discover projects from `tsconfig.base.json` `compilerOptions.paths`. Each
-     * alias (e.g. `@scope/interfaces` → `interfaces/src/index.ts`) resolves to a
-     * lib root (the path before `/src/`), which for real Nx libs contains a
-     * project.json. Aliases pointing at non-projects (no project.json/package.json,
-     * e.g. `@env` → `environments/environment.ts`) are skipped.
-     */
     private discoverFromTsconfigPaths;
-    /** Parse JSON that may contain comments / trailing commas (tsconfig style). */
     private parseJsonc;
     getRootTsConfigPath(rootDir: string): string | null;
     private readWorkspaceJson;