Method handleCallers

src/mcp/tools.ts:3080–3158

* Handle codegraph_callers

(args: Record<string, unknown>)

   * Handle codegraph_callers
   */
  private async handleCallers(args: Record<string, unknown>): Promise<ToolResult> {
    const symbol = this.validateString(args.symbol, 'symbol');
    if (typeof symbol !== 'string') return symbol;

    const cg = this.getCodeGraph(args.projectPath as string | undefined);
    const limit = clamp((args.limit as number) || 20, 1, 100);
    const fileFilter = typeof args.file === 'string' ? args.file : undefined;

    const allMatches = this.findAllSymbols(cg, symbol);
    if (allMatches.nodes.length === 0) {
      return this.textResult(`Symbol "${symbol}" not found in the codebase${allMatches.note}`);
    }

    const { groups, filteredOut } = this.groupDefinitions(allMatches.nodes, fileFilter);
    const answerPaths = new Set(groups.flat().map(node => node.filePath));
    const filterNote = filteredOut
      ? `\n\n> **Note:** no definition of "${symbol}" matches file "${fileFilter}" — showing all definitions instead.`
      : '';

    const collect = (defNodes: Node[]) => {
      const seen = new Set<string>();
      const callers: Node[] = [];
      const labels = new Map<string, string>();
      for (const node of defNodes) {
        for (const c of cg.getCallers(node.id)) {
          if (!seen.has(c.node.id)) {
            seen.add(c.node.id);
            callers.push(c.node);
            answerPaths.add(c.node.filePath);
            const label = this.edgeLabel(c.edge);
            if (label) labels.set(c.node.id, label);
          }
        }
      }
      return { callers, labels };
    };

    // Single definition (or same-file overloads): the familiar flat list.
    if (groups.length === 1) {
      const { callers, labels } = collect(groups[0]!);
      if (callers.length === 0) {
        return this.answerResult(cg, `No callers found for "${symbol}"${allMatches.note}${filterNote}`, answerPaths);
      }
      // A successful `file` narrowing makes the multi-symbol aggregation note
      // stale — suppress it.
      const note = fileFilter && !filteredOut ? '' : allMatches.note;
      // Say when the cap cut the list (#1639, #1674): a truncated answer with
      // no marker reads as the complete set, and an agent under-counts from it.
      const cut = callers.length > limit
        ? `\n\n> Showing ${limit} of ${callers.length} callers; pass \`limit\` (up to 100) to widen.`
        : '';
      const formatted = this.formatNodeList(callers.slice(0, limit), `Callers of ${symbol}`, labels) + cut + note + filterNote;
      return this.answerResult(cg, this.truncateOutput(formatted), answerPaths);
    }

    // Multiple DISTINCT definitions (#764): one section per definition so an
    // agent never mistakes one app's callers for another's. Narrow with
    // `file` to focus a single definition.