Method execute

src/codegraph/tools.ts:355–436

(args: z.infer<typeof ExplainSymbolArgs>, ctx: ToolContext)

  argsSchema = ExplainSymbolArgs;

  async execute(args: z.infer<typeof ExplainSymbolArgs>, ctx: ToolContext): Promise<ToolResult> {
    const db = requireDB();
    if ('error' in db) return { content: db.error, isError: true };

    const rows = db.findSymbolsByName(args.name, args.kind);
    if (rows.length === 0) {
      const hints = db.searchSymbolsByPrefix(args.name, args.kind, 8);
      if (hints.length > 0) {
        const hintList = hints.map(h => `  ${h.kind} ${h.name}  → ${path.relative(ctx.cwd, h.file_path)}:${h.start_line}`).join('\n');
        return { content: `[NOT_FOUND] No exact match for "${args.name}". Similar:\n${hintList}` };
      }
      return { content: `[NOT_FOUND] No symbol named "${args.name}" in the indexed codebase.` };
    }

    const maxBody = args.max_body_lines ?? 60;
    const sections: string[] = [];
    const MAX_MATCHES = 5;

    for (const row of rows.slice(0, MAX_MATCHES)) {
      const rel = path.relative(ctx.cwd, row.file_path);
      let body: string[] = [];
      let leading: string[] = [];

      try {
        const buf = await fs.readFile(row.file_path, 'utf-8');
        const lines = buf.split('\n');
        const startIdx = Math.max(0, row.start_line - 1);
        const endIdx = Math.min(lines.length - 1, row.end_line - 1);

        // Capture leading docstring/comment block (look up to 15 lines above for comments)
        for (let i = startIdx - 1; i >= Math.max(0, startIdx - 15); i--) {
          const ln = lines[i] ?? '';
          const trimmed = ln.trim();
          if (trimmed === '') {
            if (leading.length > 0) break; // blank line ends the comment block
            continue;
          }
          if (
            trimmed.startsWith('//') ||
            trimmed.startsWith('*') ||
            trimmed.startsWith('/*') ||
            trimmed.startsWith('#') ||
            trimmed.startsWith('"""') ||
            trimmed.endsWith('*/') ||
            trimmed.startsWith("'''")
          ) {
            leading.unshift(ln);
          } else {
            break;
          }
        }

        // Body, capped at maxBody lines
        const totalLines = endIdx - startIdx + 1;
        const sliceEnd = Math.min(endIdx, startIdx + maxBody - 1);
        body = lines.slice(startIdx, sliceEnd + 1);
        if (sliceEnd < endIdx) {
          body.push(`  /* ... ${totalLines - maxBody} more lines (use read_file to see the rest) */`);