Method execute

src/tools/codegraph/quality.ts:93–148

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

  argsSchema = ExplainCodebaseArgs;

  async execute(args: z.infer<typeof ExplainCodebaseArgs>, ctx: ToolContext): Promise<ToolResult> {
    const root = args.path ? path.join(ctx.cwd, args.path) : ctx.cwd;
    const maxFiles = args.max_files ?? 5000;
    const files = await walkSource(root, maxFiles);

    const layers = new Map<string, { count: number; lines: number; samples: { rel: string; lines: number }[] }>();
    for (const f of files) {
      const cat = categorizeFile(f.rel);
      let entry = layers.get(cat);
      if (!entry) {
        entry = { count: 0, lines: 0, samples: [] };
        layers.set(cat, entry);
      }
      entry.count++;
      entry.lines += f.lines;
      // Keep top 3 by line count as representatives
      entry.samples.push({ rel: f.rel, lines: f.lines });
      entry.samples.sort((a, b) => b.lines - a.lines);
      if (entry.samples.length > 3) entry.samples = entry.samples.slice(0, 3);
    }

    const out: string[] = [];
    out.push(`# Codebase Architecture`);
    out.push(`Scope: ${args.path ?? '.'}`);
    out.push(`Files: ${files.length}, Total LOC: ${files.reduce((a, b) => a + b.lines, 0).toLocaleString()}`);
    out.push('');

    const orderedLayers = [
      'entry', 'routes/controllers', 'services', 'middleware', 'data/models',
      'ui', 'hooks', 'utils', 'types', 'config', 'migrations', 'tests', 'other',
    ];
    for (const layer of orderedLayers) {
      const l = layers.get(layer);
      if (!l || l.count === 0) continue;
      out.push(`## ${layer} (${l.count} files, ${l.lines.toLocaleString()} lines)`);
      for (const s of l.samples) out.push(`  - ${s.rel} (${s.lines} lines)`);
      out.push('');
    }

    // Layering hint
    out.push(`## Hint`);
    const entry = layers.get('entry')?.count ?? 0;
    const routes = layers.get('routes/controllers')?.count ?? 0;
    const services = layers.get('services')?.count ?? 0;
    const data = layers.get('data/models')?.count ?? 0;
    const ui = layers.get('ui')?.count ?? 0;
    if (entry > 0 && routes > 0 && services > 0 && data > 0) {
      out.push(`  Looks like a typical layered backend (entry → routes → services → models). Trace a feature top-down via these layers.`);
    } else if (ui > 0 && (layers.get('hooks')?.count ?? 0) > 0) {
      out.push(`  Looks like a frontend app (UI components + hooks). State likely lives in hooks; rendering in components.`);
    } else {
      out.push(`  Mixed or atypical layout — use code_graph_find_symbol to navigate.`);
    }

    return { content: out.join('\n'), metadata: { layers: Object.fromEntries(layers) } };
  }
}