Method handleExplore

src/mcp/tools.ts:4064–7558

* Handle codegraph_explore — deep exploration in a single call * * Strategy: find relevant symbols via graph traversal, group by file, * then read contiguous file sections covering all symbols per file. * This replaces multiple codegraph_node + Read calls. * * Output size is adapti

(args: Record<string, unknown>)

   * tax on small projects while earning its keep on large ones.
   */
  private async handleExplore(args: Record<string, unknown>): Promise<ToolResult> {
    const rawQuery = this.validateString(args.query, 'query');
    if (typeof rawQuery !== 'string') return rawQuery;
    // One normalization point so the flow-builder, relevance search, and
    // ranking all see the same canonical spelling (Erlang `mod:fn/arity`).
    const query = normalizeQuerySpelling(rawQuery);

    const cg = this.getCodeGraph(args.projectPath as string | undefined);
    const projectRoot = cg.getProjectRoot();

    // Resolve adaptive output budget from project size. Falls back to the
    // largest-tier defaults if stats aren't available, which preserves
    // pre-#185 behavior for callers that hit the rare stats failure.
    let budget: ExploreOutputBudget;
    let indexedFileCount = -1;
    let indexedNodeCount = -1;
    try {
      const stats = cg.getStats();
      indexedFileCount = stats.fileCount;
      indexedNodeCount = stats.nodeCount;
      budget = getExploreOutputBudget(indexedFileCount);
    } catch {
      budget = getExploreOutputBudget(Infinity);
    }
    const maxFiles = clamp((args.maxFiles as number) || budget.defaultMaxFiles, 1, 20);

    // File paths named in the query become PINNED files: guaranteed admission,
    // top of the rank order, funded first — and their span is REMOVED from the
    // matching query. Runs on the RAW query (normalizeQuerySpelling strips
    // `/digits` tails, which would mangle numeric path segments). Without this,
    // a SvelteKit path like `runs/[runId]/+page.svelte` was shredded by the
    // seeding tokenizer (splits on brackets → `runId` seeded as a "named
    // symbol") and by FTS (`page`/`runs` fragments admitted every sibling
    // `+page.svelte`), starving the very files the agent asked for.
    let pinnedFiles: string[] = [];
    let unresolvedPathSpans: string[] = [];
    let lineAnchors: QueryLineAnchor[] = [];
    let setAsideMatches: QuerySetAsideMatch[] = [];
    let matchQuery = query;
    if (queryMightContainPaths(rawQuery)) {
      try {
        const extraction = extractQueryPaths(
          rawQuery,
          cg.getFiles().map((f) => f.path),
          {
            maxPins: maxFiles,
            existsOnDisk: (rel) => pathIsProjectFile(projectRoot, rel),
            symbolFiles: (symbol) => filesDefiningSymbol(cg, symbol),
          },
        );
        if (extraction.pinnedFiles.length > 0 || extraction.unresolvedPathSpans.length > 0) {
          pinnedFiles = extraction.pinnedFiles;
          unresolvedPathSpans = extraction.unresolvedPathSpans;
          lineAnchors = extraction.lineAnchors;
          setAsideMatches = extraction.setAsideMatches;
          matchQuery = normalizeQuerySpelling(extraction.strippedQuery);
        }
      } catch { /* path pinning must never fail an explore call */ }