opencodekit 0.23.1 → 0.23.3

package/dist/template/.opencode/plugin/srcwalk.ts

@@ -5,9 +5,7 @@
  * Wraps available CLI tools (rg/grep, find, cat, ls) into unified srcwalk_* tools.
  *
  * Tools (matching pikit srcwalk extension surface):
- *   - srcwalk_search  — Search symbols/text/regex in codebase
  *   - srcwalk_read    — Read files with optional section/range
- *   - srcwalk_files   — Find files by glob pattern
  *   - srcwalk_deps    — Show imports and dependents for a file
  *   - srcwalk_map     — Directory tree overview
  *   - srcwalk_callers — Reverse call graph (grep-based)
@@ -16,14 +14,13 @@
  *   - srcwalk_impact  — Heuristic blast-radius triage
  */
 
-import { execFile, execFileSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import path from "node:path";
 import { tool } from "@opencode-ai/plugin/tool";
 import type { Plugin } from "@opencode-ai/plugin";
 
-const BIN_RG = "rg";
 const TIMEOUT_MS = 15_000;
 const MAX_BUFFER = 5 * 1024 * 1024;
 
@@ -31,637 +28,613 @@ const MAX_BUFFER = 5 * 1024 * 1024;
 // Helpers
 // ---------------------------------------------------------------------------
 
-function run(cmd: string, args: string[], cwd?: string): { stdout: string; stderr: string; code: number } {
-	try {
-		const result = execFileSync(cmd, args, {
-			encoding: "utf-8",
-			timeout: TIMEOUT_MS,
-			maxBuffer: MAX_BUFFER,
-			cwd: cwd ?? process.cwd(),
-			stdio: ["ignore", "pipe", "pipe"],
-		});
-		return { stdout: result.stdout ?? "", stderr: result.stderr ?? "", code: 0 };
-	} catch (err: unknown) {
-		const e = err as { stdout?: string; stderr?: string; status?: number; message?: string };
-		return {
-			stdout: e.stdout ?? "",
-			stderr: e.stderr ?? "",
-			code: e.status ?? 1,
-		};
-	}
-}
-
-function hasRg(): boolean {
-	try {
-		execFileSync(BIN_RG, ["--version"], { encoding: "utf-8", timeout: 1000, stdio: "ignore" });
-		return true;
-	} catch {
-		return false;
-	}
+function run(
+  cmd: string,
+  args: string[],
+  cwd?: string,
+): { stdout: string; stderr: string; code: number } {
+  try {
+    const result = execFileSync(cmd, args, {
+      encoding: "utf-8",
+      timeout: TIMEOUT_MS,
+      maxBuffer: MAX_BUFFER,
+      cwd: cwd ?? process.cwd(),
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { stdout: result.stdout ?? "", stderr: result.stderr ?? "", code: 0 };
+  } catch (err: unknown) {
+    const e = err as { stdout?: string; stderr?: string; status?: number; message?: string };
+    return {
+      stdout: e.stdout ?? "",
+      stderr: e.stderr ?? "",
+      code: e.status ?? 1,
+    };
+  }
 }
 
 function plural(n: number, word: string): string {
-	return `${n} ${word}${n !== 1 ? "s" : ""}`;
+  if (n === 1) return `${n} ${word}`;
+  if (
+    word.endsWith("ch") ||
+    word.endsWith("s") ||
+    word.endsWith("sh") ||
+    word.endsWith("x") ||
+    word.endsWith("z")
+  ) {
+    return `${n} ${word}es`;
+  }
+  if (
+    word.endsWith("y") &&
+    word.length > 1 &&
+    !["a", "e", "i", "o", "u"].includes(word[word.length - 2])
+  ) {
+    return `${n} ${word.slice(0, -1)}ies`;
+  }
+  return `${n} ${word}s`;
 }
 
 // ---------------------------------------------------------------------------
 // Plugin
 // ---------------------------------------------------------------------------
 
-interface PluginConfig {
-	directory?: string;
-}
-
 const srcwalkTools = {
-	// -----------------------------------------------------------------------
-	// srcwalk_search: Search codebase
-	// -----------------------------------------------------------------------
-	"srcwalk_search": tool({
-		description: `Search for symbols, text, or regex patterns in code.\n\nUses ripgrep (rg) when available, falls back to grep.\nSupports symbol search (definitions first), content search, and regex.`,
-		args: {
-			query: tool.schema.string().describe("Search query or regex pattern"),
-			scope: tool.schema.string().optional().describe("Subdirectory scope (default: project root)"),
-			kind: tool.schema.string().optional().describe("Search type: text (default), regex, content"),
-			context: tool.schema.number().optional().describe("Lines of context before/after each match"),
-			limit: tool.schema.number().optional().describe("Max results (default: 30)"),
-		},
-		execute: async (args, context) => {
-			const query = String(args.query ?? "").trim();
-			if (!query) return "❌ query is required.";
-			const scope = args.scope ? String(args.scope) : context.directory;
-			const limit = Math.min(args.limit ?? 30, 100);
-			const ctxLines = args.context ?? 0;
-			const kind = String(args.kind ?? "text");
-
-			const searchDir = path.resolve(context.directory, scope);
-
-			if (hasRg()) {
-				const rgArgs = ["--no-heading", "--line-number", "--color", "never"];
-				rgArgs.push("--max-count", String(limit * 2));
-				if (ctxLines > 0) {
-					rgArgs.push("-C", String(ctxLines));
-				}
-				if (kind === "regex") {
-					rgArgs.push("-E", "rust");
-				} else {
-					rgArgs.push("-F"); // literal
-				}
-				rgArgs.push(query, searchDir);
-
-				const result = run(BIN_RG, rgArgs);
-				if (result.code !== 0 && result.stderr) {
-					// Try plain grep fallback
-				} else {
-					const lines = result.stdout.split("\n").filter(Boolean).slice(0, limit);
-					if (lines.length === 0) return "No matches found.";
-					return lines.join("\n");
-				}
-			}
-
-			// Fallback to grep
-			const grepArgs = ["-rn", "--color=never"];
-			if (ctxLines > 0) grepArgs.push("-C", String(ctxLines));
-			if (kind === "regex") {
-				grepArgs.push("-E");
-			} else {
-				grepArgs.push("-F");
-			}
-			grepArgs.push(query, searchDir);
-
-			const result = run("grep", grepArgs);
-			const lines = result.stdout.split("\n").filter(Boolean).slice(0, limit);
-			if (lines.length === 0) return "No matches found.";
-			return lines.join("\n");
-		},
-	}),
-
-	// -----------------------------------------------------------------------
-	// srcwalk_read: Read files
-	// -----------------------------------------------------------------------
-	"srcwalk_read": tool({
-		description: `Read a file with optional section (line range, symbol, or path:line format).\n\nSmall files return full content; large files support outlining.\nUse path:start-end for range reads (e.g. "src/app.ts:44-89").`,
-		args: {
-			path: tool.schema.string().describe("File path to read (supports path:line or path:start-end)"),
-			section: tool.schema.string().optional().describe("Line range '44-89' or heading/symbol name"),
-			full: tool.schema.boolean().optional().describe("Force full content"),
-		},
-		execute: async (args, context) => {
-			const fileArg = String(args.path);
-			const fullFilePath = path.resolve(context.directory, fileArg);
-
-			// Parse path:line or path:start-end shortcut
-			let startLine: number | undefined;
-			let endLine: number | undefined;
-
-			const rangeMatch = fileArg.match(/^(.+?):(\d+)(?:-(\d+))?$/);
-			if (rangeMatch) {
-				const relPath = rangeMatch[1];
-				const resolved = path.resolve(context.directory, relPath);
-				startLine = parseInt(rangeMatch[2], 10);
-				endLine = rangeMatch[3] ? parseInt(rangeMatch[3], 10) : startLine;
-				return readFileRange(resolved, startLine, endLine, relPath);
-			}
-
-			if (!existsSync(fullFilePath)) return `File not found: ${fileArg}`;
-			const stats = statSync(fullFilePath);
-
-			// If section specified, try grep for symbol/heading
-			if (args.section) {
-				const section = String(args.section);
-				// Check if it's a line range
-				const lineMatch = section.match(/^(\d+)(?:-(\d+))?$/);
-				if (lineMatch) {
-					const start = parseInt(lineMatch[1], 10);
-					const end = lineMatch[2] ? parseInt(lineMatch[2], 10) : start + 30;
-					return readFileRange(fullFilePath, start, end);
-				}
-				// Symbol/heading: use grep to find location, then read around it
-				const grepArgs = ["-n", "--color=never", "-E", `^(function |const |let |class |interface |type |export |## |### )?.*${section}`, fullFilePath];
-				const result = run("grep", grepArgs);
-				if (result.stdout) {
-					const firstMatch = result.stdout.split("\n")[0];
-					const lineNum = parseInt(firstMatch.split(":")[0], 10);
-					if (!isNaN(lineNum)) {
-						return readFileRange(fullFilePath, Math.max(1, lineNum - 3), lineNum + 40);
-					}
-				}
-				return `Section "${section}" not found in ${fileArg}`;
-			}
-
-			// Full content for small files
-			if (stats.size < 50 * 1024 || args.full) {
-				const content = readFileSync(fullFilePath, "utf-8");
-				const lines = content.split("\n");
-				if (lines.length > 2000)
-					return `[File too large: ${plural(lines.length, "line")}. Showing first 2000 lines]\n\n${lines.slice(0, 2000).join("\n")}`;
-				return content;
-			}
-
-			// Large file: outline
-			const content = readFileSync(fullFilePath, "utf-8");
-			const lines = content.split("\n");
-			const headings: string[] = [];
-			for (let i = 0; i < Math.min(lines.length, 5000); i++) {
-				const l = lines[i].trim();
-				if (l.match(/^(export\s+)?(function|class|interface|type|const|enum|def|struct|impl|pub\s+fn)\s/) ||
-					l.match(/^(##|###)\s/) ||
-					l.match(/^\w+\s*[:=]/)) {
-					headings.push(`  ${i + 1}: ${l.slice(0, 120)}`);
-				}
-			}
-			const header = `[File: ${fileArg} — ${plural(lines.length, "line")}, ${(stats.size / 1024).toFixed(1)}KB]\n\n`;
-			const outline = headings.length > 0
-				? `Outline (${plural(headings.length, "entry")}):\n${headings.slice(0, 50).join("\n")}\n\nUse path:line or section to read a specific range.`
-				: `Use path:line to read a specific range (e.g., ${fileArg}:1-${Math.min(50, lines.length)}).`;
-			return header + outline;
-		},
-	}),
-
-	// -----------------------------------------------------------------------
-	// srcwalk_files: Find files
-	// -----------------------------------------------------------------------
-	"srcwalk_files": tool({
-		description: `Find files by glob pattern. Returns matched file paths with size estimates, grouped by directory. Respects .gitignore.`,
-		args: {
-			pattern: tool.schema.string().describe("Glob pattern (e.g. '*.ts', 'src/**/*.ts')"),
-			scope: tool.schema.string().optional().describe("Directory to search (default: project root)"),
-		},
-		execute: async (args, context) => {
-			const pattern = String(args.pattern ?? "").trim();
-			if (!pattern) return "❌ pattern is required.";
-			const scopeDir = path.resolve(context.directory, args.scope ? String(args.scope) : "");
-
-			// Use find with simple glob pattern
-			const findArgs: string[] = [scopeDir, "-type", "f"];
-
-			// Convert simple glob to -name pattern
-			if (pattern.includes("**")) {
-				// find handles ** naturally with -path
-				findArgs.push("-path", `*/${pattern.replace(/\*\*/g, "*")}`);
-			} else if (pattern.includes("*")) {
-				findArgs.push("-name", pattern);
-			} else if (pattern.includes(".")) {
-				findArgs.push("-name", pattern);
-			} else {
-				findArgs.push("-name", `*${pattern}*`);
-			}
-
-			// Exclude common dirs
-			for (const dir of [".git", "node_modules", "dist", "build", "coverage", ".next", ".opencode"]) {
-				findArgs.push("-not", "-path", `*/${dir}/*`);
-			}
-
-			const result = run("find", findArgs);
-			const files = result.stdout.split("\n").filter(Boolean).slice(0, 200);
-
-			if (files.length === 0) return `No files matching "${pattern}" found.`;
-
-			// Group by directory
-			const groups: Record<string, string[]> = {};
-			for (const f of files) {
-				const dir = path.dirname(f);
-				if (!groups[dir]) groups[dir] = [];
-				groups[dir].push(path.basename(f));
-			}
-
-			const lines: string[] = [`# Files matching "${pattern}" (${plural(files.length, "file")})\n`];
-			for (const [dir, files] of Object.entries(groups).sort()) {
-				const relDir = path.relative(context.directory, dir) || ".";
-				lines.push(`${relDir}/ (${plural(files.length, "file")})`);
-				for (const f of files) {
-					const fp = path.join(dir, f);
-					try {
-						const size = statSync(fp).size;
-						const tokenEst = Math.ceil(size / 4);
-						lines.push(`  ${f}  (~${tokenEst.toLocaleString()} tokens)`);
-					} catch {
-						lines.push(`  ${f}`);
-					}
-				}
-				lines.push("");
-			}
-			return lines.join("\n");
-		},
-	}),
-
-	// -----------------------------------------------------------------------
-	// srcwalk_deps: Import analysis
-	// -----------------------------------------------------------------------
-	"srcwalk_deps": tool({
-		description: `Show what imports a file (dependents) and what a file imports (dependencies).\nBlast-radius check before breaking changes.`,
-		args: {
-			path: tool.schema.string().describe("File path to analyze"),
-			scope: tool.schema.string().optional().describe("Search scope (default: project root)"),
-		},
-		execute: async (args, context) => {
-			const filePath = String(args.path);
-			const absPath = path.resolve(context.directory, filePath);
-			if (!existsSync(absPath)) return `File not found: ${filePath}`;
-
-			const scopeDir = path.resolve(context.directory, args.scope ? String(args.scope) : "");
-			const fileName = path.basename(filePath, path.extname(filePath));
-
-			// What this file imports
-			const content = readFileSync(absPath, "utf-8");
-			const importLines: string[] = [];
-			for (const line of content.split("\n")) {
-				const m = line.match(/(?:import|require)\s+.*?from\s+['"]([^'"]+)['"]|import\s+['"]([^'"]+)['"]/);
-				if (m) importLines.push(`  ${line.trim()}`);
-			}
-
-			// What imports this file (grep for the module name)
-			const searchName = fileName;
-			const grepResult = run("grep", [
-				"-rn",
-				"--color=never",
-				"-E",
-				`from ['"](\\./|\\.\\./|.*/)${searchName}['"]|require\\(['"](\\./|\\.\\./|.*/)${searchName}['"]`,
-				scopeDir,
-				"--include=*.ts",
-				"--include=*.tsx",
-				"--include=*.js",
-				"--include=*.jsx",
-				"--include=*.mjs",
-			]);
-			const importers = grepResult.stdout.split("\n").filter(Boolean).slice(0, 30);
-
-			const result: string[] = [`## Dependencies for ${filePath}\n`];
-			result.push(`### Imports (${plural(importLines.length, "module")})`);
-			if (importLines.length === 0) result.push("  (none)");
-			else result.push(...importLines);
-
-			result.push(`\n### Importers (${plural(importers.length, "file")})`);
-			if (importers.length === 0) result.push("  (no files import this module)");
-			else result.push(...importers.map(l => `  ${path.relative(context.directory, l.split(":")[0])}:${l.split(":")[1]}`));
-
-			return result.join("\n");
-		},
-	}),
-
-	// -----------------------------------------------------------------------
-	// srcwalk_map: Directory overview
-	// -----------------------------------------------------------------------
-	"srcwalk_map": tool({
-		description: `Token-annotated directory skeleton. Shows repo structure with file sizes and token estimates. Good for understanding codebase shape.`,
-		args: {
-			scope: tool.schema.string().optional().describe("Directory to map (default: project root)"),
-			depth: tool.schema.number().optional().describe("Max directory depth (default: 3)"),
-		},
-		execute: async (args, context) => {
-			const scopeDir = path.resolve(context.directory, args.scope ? String(args.scope) : "");
-			const maxDepth = args.depth ?? 3;
-
-			const treeArgs = ["-L", String(maxDepth), "--dirsfirst"];
-			// Use tree if available, else ls -R
-			const treeResult = run("tree", [
-				...treeArgs,
-				"-I", ".git|node_modules|dist|build|coverage|.next",
-				scopeDir,
-			]);
-			if (treeResult.code === 0) {
-				return treeResult.stdout.slice(0, 10_000);
-			}
-
-			// Fallback: simple directory listing
-			const result: string[] = [`## Directory: ${path.relative(context.directory, scopeDir) || "."}\n`];
-			await listDirRecursive(scopeDir, "", maxDepth, result, context.directory);
-			return result.join("\n");
-		},
-	}),
-
-	// -----------------------------------------------------------------------
-	// srcwalk_callers: Reverse call graph
-	// -----------------------------------------------------------------------
-	"srcwalk_callers": tool({
-		description: `Reverse call graph — find what calls a function.\nGrep-based: searches for symbol usage across the codebase.\nUse depth for transitive callers (multi-hop).`,
-		args: {
-			symbol: tool.schema.string().describe("Function/symbol name"),
-			scope: tool.schema.string().optional().describe("Search scope"),
-			depth: tool.schema.number().optional().describe("BFS hop depth (default: 1, max: 3)"),
-			filter: tool.schema.string().optional().describe("Optional filter (e.g. path:api)"),
-		},
-		execute: async (args, context) => {
-			const symbol = String(args.symbol ?? "").trim();
-			if (!symbol) return "❌ symbol is required.";
-			const scopeDir = path.resolve(context.directory, args.scope ? String(args.scope) : "");
-			const depth = Math.min(args.depth ?? 1, 3);
-
-			// Search for direct calls: symbol( or .symbol or symbol.
-			const grepArgs = [
-				"-rn",
-				"--color=never",
-				"-E",
-				`[.\\s]${symbol}\\s*\\(|[.]${symbol}\\b|\\b${symbol}\\.`,
-				scopeDir,
-				"--include=*.ts",
-				"--include=*.tsx",
-				"--include=*.js",
-				"--include=*.jsx",
-			];
-
-			if (args.filter) {
-				const filterStr = String(args.filter);
-				if (filterStr.startsWith("path:")) {
-					grepArgs.push(path.join(scopeDir, filterStr.slice(5)));
-				}
-			}
-
-			const result = run("grep", grepArgs);
-			const lines = result.stdout.split("\n").filter(Boolean).slice(0, 50);
-
-			if (lines.length === 0) return `No callers found for "${symbol}".`;
-
-			const output: string[] = [
-				`## Callers of \`${symbol}\` (${plural(lines.length, "result")})${depth > 1 ? ` (depth: ${depth})` : ""}\n`,
-			];
-			for (const line of lines) {
-				const parts = line.split(":");
-				if (parts.length >= 2) {
-					const relPath = path.relative(context.directory, parts[0]);
-					output.push(`  ${relPath}:${parts[1]}: ${parts.slice(2).join(":").trim().slice(0, 150)}`);
-				} else {
-					output.push(`  ${line.slice(0, 200)}`);
-				}
-			}
-
-			if (depth > 1) {
-				output.push(`\n_Note: Multi-hop depth (${depth}) requires re-running on each caller._`);
-			}
-			return output.join("\n");
-		},
-	}),
-
-	// -----------------------------------------------------------------------
-	// srcwalk_callees: Forward call graph
-	// -----------------------------------------------------------------------
-	"srcwalk_callees": tool({
-		description: `Forward call graph — what does this function call?\nReads the function body and extracts call sites.`,
-		args: {
-			symbol: tool.schema.string().describe("Function/symbol name"),
-			scope: tool.schema.string().optional().describe("Scope directory"),
-			detailed: tool.schema.boolean().optional().describe("Show ordered call sites with argument slots"),
-		},
-		execute: async (args, context) => {
-			const symbol = String(args.symbol ?? "").trim();
-			if (!symbol) return "❌ symbol is required.";
-			const scopeDir = path.resolve(context.directory, args.scope ? String(args.scope) : "");
-
-			// Find the function definition
-			const defArgs = [
-				"-rn",
-				"--color=never",
-				"-E",
-				`(export\\s+)?(function|const|let|async\\s+function)\\s+${symbol}\\b|${symbol}\\s*[:=]\\s*(async\\s+)?\\(`,
-				scopeDir,
-				"--include=*.ts",
-				"--include=*.tsx",
-				"--include=*.js",
-				"--include=*.jsx",
-			];
-			const defResult = run("grep", defArgs);
-			const defLines = defResult.stdout.split("\n").filter(Boolean).slice(0, 5);
-
-			if (defLines.length === 0) {
-				return `Definition not found for "${symbol}". Cannot trace callees without finding the function body.`;
-			}
-
-			const output: string[] = [`## Callees of \`${symbol}\`\n`];
-
-			// For each definition location, show the function and extract calls
-			for (const def of defLines) {
-				const parts = def.split(":");
-				if (parts.length >= 2) {
-					const relPath = path.relative(context.directory, parts[0]);
-					const lineNum = parseInt(parts[1], 10);
-					output.push(`**Definition:** ${relPath}:${lineNum}`);
-
-					// Read function body to extract calls
-					const filePath = path.resolve(context.directory, parts[0]);
-					if (existsSync(filePath)) {
-						const fileLines = readFileSync(filePath, "utf-8").split("\n");
-						let braceCount = 0;
-						let inFunc = false;
-						const calls: string[] = [];
-
-						for (let i = lineNum - 1; i < Math.min(lineNum + 80, fileLines.length); i++) {
-							const line = fileLines[i];
-							if (!inFunc) {
-								if (line.includes("{")) {
-									inFunc = true;
-									braceCount = (line.match(/{/g) || []).length;
-									braceCount -= (line.match(/}/g) || []).length;
-								}
-								continue;
-							}
-							braceCount += (line.match(/{/g) || []).length;
-							braceCount -= (line.match(/}/g) || []).length;
-
-							// Extract function calls
-							const callMatch = [...line.matchAll(/(?<![.\w])(\w+)\s*\(/g)];
-							for (const m of callMatch) {
-								const name = m[1];
-								if (!["if", "for", "while", "switch", "catch", "typeof", "instanceof", "return", "throw", "new", "delete", "await", "yield"].includes(name)) {
-									const argStart = line.indexOf("(", m.index!);
-									const argEnd = line.indexOf(")", argStart);
-									const args_s = argEnd > argStart ? line.slice(argStart + 1, argEnd).trim().slice(0, 60) : "";
-									calls.push(`  ${args.detailed ? `${name}(${args_s})` : `${name}()`}`);
-								}
-							}
-
-							if (braceCount <= 0) break;
-						}
-
-						if (calls.length > 0) {
-							output.push(...calls);
-						} else {
-							output.push("  (no internal calls found)");
-						}
-						output.push("");
-					}
-				}
-			}
-
-			return output.join("\n");
-		},
-	}),
-
-	// -----------------------------------------------------------------------
-	// srcwalk_flow: Compact orientation
-	// -----------------------------------------------------------------------
-	"srcwalk_flow": tool({
-		description: `Compact function orientation — ordered callees + direct callers.\nQuick understanding of a function's role in the call graph.`,
-		args: {
-			symbol: tool.schema.string().describe("Symbol name to analyze"),
-			scope: tool.schema.string().optional().describe("Search scope"),
-		},
-		execute: async (args, context) => {
-			const symbol = String(args.symbol ?? "").trim();
-			if (!symbol) return "❌ symbol is required.";
-			const scopeDir = path.resolve(context.directory, args.scope ? String(args.scope) : "");
-
-			// Get callers
-			const callersResult = run("grep", [
-				"-rn", "--color=never", "-E",
-				`[.\\s]${symbol}\\s*\\(|[.]${symbol}\\b`,
-				scopeDir,
-				"--include=*.ts", "--include=*.tsx", "--include=*.js", "--include=*.jsx",
-			]);
-			const callers = callersResult.stdout.split("\n").filter(Boolean).slice(0, 15);
-
-			// Get callees by reading function body
-			const defResult = run("grep", [
-				"-rn", "--color=never", "-E",
-				`(function|const|let)\\s+${symbol}\\b|${symbol}\\s*[:=]\\s*(async\\s+)?\\(`,
-				scopeDir,
-				"--include=*.ts", "--include=*.tsx", "--include=*.js", "--include=*.jsx",
-			]);
-			const defLine = defResult.stdout.split("\n").filter(Boolean)[0];
-			let callees: string[] = [];
-
-			if (defLine) {
-				const parts = defLine.split(":");
-				if (parts.length >= 2) {
-					const fp = path.resolve(context.directory, parts[0]);
-					const ln = parseInt(parts[1], 10);
-					if (existsSync(fp)) {
-						const fileLines = readFileSync(fp, "utf-8").split("\n");
-						let bc = 0, inF = false;
-						for (let i = ln - 1; i < Math.min(ln + 60, fileLines.length); i++) {
-							const l = fileLines[i];
-							if (!inF) { if (l.includes("{")) { inF = true; bc = (l.match(/{/g) || []).length - (l.match(/}/g) || []).length; } continue; }
-							bc += (l.match(/{/g) || []).length - (l.match(/}/g) || []).length;
-							for (const m of l.matchAll(/(\w+)\s*\(/g)) {
-								if (!["if","for","while","switch","catch","typeof","instanceof","return","throw","new","delete","await","yield"].includes(m[1]))
-									callees.push(m[1]);
-							}
-							if (bc <= 0) break;
-						}
-					}
-				}
-			}
-
-			const output: string[] = [`## Flow: \`${symbol}\``];
-			output.push(`\n**Callers (${plural(callers.length, "file")}):`);
-			if (callers.length === 0) output.push("  (none)");
-			else output.push(...callers.slice(0, 10).map(l => `  ${path.relative(context.directory, l.split(":")[0])}:${l.split(":")[1]}`));
-
-			output.push(`\n**Callees (${plural(callees.length, "call")}):`);
-			if (callees.length === 0) output.push("  (none)");
-			else output.push(...[...new Set(callees)].slice(0, 20).map(c => `  ${c}()`));
-			return output.join("\n");
-		},
-	}),
-
-	// -----------------------------------------------------------------------
-	// srcwalk_impact: Heuristic blast-radius
-	// -----------------------------------------------------------------------
-	"srcwalk_impact": tool({
-		description: `Heuristic blast-radius triage — broad 'what might be affected?' starting point.\nName-matched, not proof. Use as starting point before verifying with srcwalk_callers or exact reads.`,
-		args: {
-			symbol: tool.schema.string().describe("Symbol name to triage"),
-			scope: tool.schema.string().optional().describe("Search scope"),
-		},
-		execute: async (args, context) => {
-			const symbol = String(args.symbol ?? "").trim();
-			if (!symbol) return "❌ symbol is required.";
-			const scopeDir = path.resolve(context.directory, args.scope ? String(args.scope) : "");
-
-			// Count usages per directory
-			const grepResult = run("grep", [
-				"-rn",
-				"--color=never",
-				"-E",
-				`\\b${symbol}\\b`,
-				scopeDir,
-				"--include=*.ts",
-				"--include=*.tsx",
-				"--include=*.js",
-				"--include=*.jsx",
-			]);
-			const lines = grepResult.stdout.split("\n").filter(Boolean);
-
-			// Group by file
-			const fileCounts: Record<string, number> = {};
-			for (const line of lines) {
-				const filePath = line.split(":")[0];
-				fileCounts[filePath] = (fileCounts[filePath] || 0) + 1;
-			}
-
-			// Group by directory
-			const dirCounts: Record<string, { files: number; total: number }> = {};
-			for (const [filePath, count] of Object.entries(fileCounts)) {
-				const dir = path.dirname(filePath);
-				if (!dirCounts[dir]) dirCounts[dir] = { files: 0, total: 0 };
-				dirCounts[dir].files++;
-				dirCounts[dir].total += count;
-			}
-
-			const totalOccurrences = lines.length;
-			const totalFiles = Object.keys(fileCounts).length;
-
-			const output: string[] = [
-				`## Impact: \`${symbol}\``,
-				`Total: ${plural(totalOccurrences, "occurrence")} across ${plural(totalFiles, "file")}\n`,
-				`### By directory`,
-			];
-
-			const sortedDirs = Object.entries(dirCounts).sort((a, b) => b[1].total - a[1].total);
-			for (const [dir, info] of sortedDirs.slice(0, 15)) {
-				const relDir = path.relative(context.directory, dir) || ".";
-				output.push(`  ${relDir}/ — ${plural(info.total, "occurrence")} in ${plural(info.files, "file")}`);
-			}
-
-			const topFiles = Object.entries(fileCounts).sort((a, b) => b[1] - a[1]).slice(0, 20);
-			output.push(`\n### Top files`);
-			for (const [filePath, count] of topFiles) {
-				const relPath = path.relative(context.directory, filePath);
-				output.push(`  ${relPath} (${plural(count, "occurrence")})`);
-			}
-
-			output.push(`\n_Heuristic: name-matched, not proof. Follow up with srcwalk_callers for exact call sites._`);
-			return output.join("\n");
-		},
-	}),
+  // -----------------------------------------------------------------------
+  // srcwalk_read: Read files
+  // -----------------------------------------------------------------------
+  srcwalk_read: tool({
+    description: `Read a file with optional section (line range, symbol, or path:line format).\n\nSmall files return full content; large files support outlining.\nUse path:start-end for range reads (e.g. "src/app.ts:44-89").`,
+    args: {
+      path: tool.schema
+        .string()
+        .describe("File path to read (supports path:line or path:start-end)"),
+      section: tool.schema
+        .string()
+        .optional()
+        .describe("Line range '44-89' or heading/symbol name"),
+      full: tool.schema.boolean().optional().describe("Force full content"),
+    },
+    execute: async (args, context) => {
+      const fileArg = String(args.path);
+      const fullFilePath = path.resolve(context.directory, fileArg);
+
+      // Parse path:line or path:start-end shortcut
+      let startLine: number | undefined;
+      let endLine: number | undefined;
+
+      const rangeMatch = fileArg.match(/^(.+?):(\d+)(?:-(\d+))?$/);
+      if (rangeMatch) {
+        const relPath = rangeMatch[1];
+        const resolved = path.resolve(context.directory, relPath);
+        startLine = parseInt(rangeMatch[2], 10);
+        endLine = rangeMatch[3] ? parseInt(rangeMatch[3], 10) : startLine;
+        return readFileRange(resolved, startLine, endLine, relPath);
+      }
+
+      if (!existsSync(fullFilePath)) return `File not found: ${fileArg}`;
+      const stats = statSync(fullFilePath);
+
+      // If section specified, try grep for symbol/heading
+      if (args.section) {
+        const section = String(args.section);
+        // Check if it's a line range
+        const lineMatch = section.match(/^(\d+)(?:-(\d+))?$/);
+        if (lineMatch) {
+          const start = parseInt(lineMatch[1], 10);
+          const end = lineMatch[2] ? parseInt(lineMatch[2], 10) : start + 30;
+          return readFileRange(fullFilePath, start, end);
+        }
+        // Symbol/heading: use grep to find location, then read around it
+        const grepArgs = [
+          "-n",
+          "--color=never",
+          "-E",
+          `^(function |const |let |class |interface |type |export |## |### )?.*${section}`,
+          fullFilePath,
+        ];
+        const result = run("grep", grepArgs);
+        if (result.stdout) {
+          const firstMatch = result.stdout.split("\n")[0];
+          const lineNum = parseInt(firstMatch.split(":")[0], 10);
+          if (!isNaN(lineNum)) {
+            return readFileRange(fullFilePath, Math.max(1, lineNum - 3), lineNum + 40);
+          }
+        }
+        return `Section "${section}" not found in ${fileArg}`;
+      }
+
+      // Full content for small files
+      if (stats.size < 50 * 1024 || args.full) {
+        const content = readFileSync(fullFilePath, "utf-8");
+        const lines = content.split("\n");
+        if (lines.length > 2000)
+          return `[File too large: ${plural(lines.length, "line")}. Showing first 2000 lines]\n\n${lines.slice(0, 2000).join("\n")}`;
+        return content;
+      }
+
+      // Large file: outline
+      const content = readFileSync(fullFilePath, "utf-8");
+      const lines = content.split("\n");
+      const headings: string[] = [];
+      for (let i = 0; i < Math.min(lines.length, 5000); i++) {
+        const l = lines[i].trim();
+        if (
+          l.match(
+            /^(export\s+)?(function|class|interface|type|const|enum|def|struct|impl|pub\s+fn)\s/,
+          ) ||
+          l.match(/^(##|###)\s/) ||
+          l.match(/^\w+\s*[:=]/)
+        ) {
+          headings.push(`  ${i + 1}: ${l.slice(0, 120)}`);
+        }
+      }
+      const header = `[File: ${fileArg} — ${plural(lines.length, "line")}, ${(stats.size / 1024).toFixed(1)}KB]\n\n`;
+      const outline =
+        headings.length > 0
+          ? `Outline (${plural(headings.length, "entry")}):\n${headings.slice(0, 50).join("\n")}\n\nUse path:line or section to read a specific range.`
+          : `Use path:line to read a specific range (e.g., ${fileArg}:1-${Math.min(50, lines.length)}).`;
+      return header + outline;
+    },
+  }),
+
+  // -----------------------------------------------------------------------
+  // srcwalk_deps: Import analysis
+  // -----------------------------------------------------------------------
+  srcwalk_deps: tool({
+    description: `Show what imports a file (dependents) and what a file imports (dependencies).\nBlast-radius check before breaking changes.`,
+    args: {
+      path: tool.schema.string().describe("File path to analyze"),
+      scope: tool.schema.string().optional().describe("Search scope (default: project root)"),
+    },
+    execute: async (args, context) => {
+      const filePath = String(args.path);
+      const absPath = path.resolve(context.directory, filePath);
+      if (!existsSync(absPath)) return `File not found: ${filePath}`;
+
+      const scopeDir = path.resolve(context.directory, args.scope ? String(args.scope) : "");
+      const fileName = path.basename(filePath, path.extname(filePath));
+
+      // What this file imports
+      const content = readFileSync(absPath, "utf-8");
+      const importLines: string[] = [];
+      for (const line of content.split("\n")) {
+        const m = line.match(
+          /(?:import|require)\s+.*?from\s+['"]([^'"]+)['"]|import\s+['"]([^'"]+)['"]/,
+        );
+        if (m) importLines.push(`  ${line.trim()}`);
+      }
+
+      // What imports this file (grep for the module name)
+      const searchName = fileName;
+      const grepResult = run("grep", [
+        "-rn",
+        "--color=never",
+        "-E",
+        `from ['"](\\./|\\.\\./|.*/)${searchName}['"]|require\\(['"](\\./|\\.\\./|.*/)${searchName}['"]`,
+        scopeDir,
+        "--include=*.ts",
+        "--include=*.tsx",
+        "--include=*.js",
+        "--include=*.jsx",
+        "--include=*.mjs",
+      ]);
+      const importers = grepResult.stdout.split("\n").filter(Boolean).slice(0, 30);
+
+      const result: string[] = [`## Dependencies for ${filePath}\n`];
+      result.push(`### Imports (${plural(importLines.length, "module")})`);
+      if (importLines.length === 0) result.push("  (none)");
+      else result.push(...importLines);
+
+      result.push(`\n### Importers (${plural(importers.length, "file")})`);
+      if (importers.length === 0) result.push("  (no files import this module)");
+      else
+        result.push(
+          ...importers.map(
+            (l) => `  ${path.relative(context.directory, l.split(":")[0])}:${l.split(":")[1]}`,
+          ),
+        );
+
+      return result.join("\n");
+    },
+  }),
+
+  // -----------------------------------------------------------------------
+  // srcwalk_map: Directory overview
+  // -----------------------------------------------------------------------
+  srcwalk_map: tool({
+    description: `Token-annotated directory skeleton. Shows repo structure with file sizes and token estimates. Good for understanding codebase shape.`,
+    args: {
+      scope: tool.schema.string().optional().describe("Directory to map (default: project root)"),
+      depth: tool.schema.number().optional().describe("Max directory depth (default: 3)"),
+    },
+    execute: async (args, context) => {
+      const scopeDir = path.resolve(context.directory, args.scope ? String(args.scope) : "");
+      const maxDepth = args.depth ?? 3;
+
+      const treeArgs = ["-L", String(maxDepth), "--dirsfirst"];
+      // Use tree if available, else ls -R
+      const treeResult = run("tree", [
+        ...treeArgs,
+        "-I",
+        ".git|node_modules|dist|build|coverage|.next",
+        scopeDir,
+      ]);
+      if (treeResult.code === 0) {
+        return treeResult.stdout.slice(0, 10_000);
+      }
+
+      // Fallback: simple directory listing
+      const result: string[] = [
+        `## Directory: ${path.relative(context.directory, scopeDir) || "."}\n`,
+      ];
+      await listDirRecursive(scopeDir, "", maxDepth, result);
+      return result.join("\n");
+    },
+  }),
+
+  // -----------------------------------------------------------------------
+  // srcwalk_callers: Reverse call graph
+  // -----------------------------------------------------------------------
+  srcwalk_callers: tool({
+    description: `Reverse call graph — find what calls a function.\nGrep-based: searches for symbol usage across the codebase.\nUse depth for transitive callers (multi-hop).`,
+    args: {
+      symbol: tool.schema.string().describe("Function/symbol name"),
+      scope: tool.schema.string().optional().describe("Search scope"),
+      depth: tool.schema.number().optional().describe("BFS hop depth (default: 1, max: 3)"),
+      filter: tool.schema.string().optional().describe("Optional filter (e.g. path:api)"),
+    },
+    execute: async (args, context) => {
+      const symbol = String(args.symbol ?? "").trim();
+      if (!symbol) return "symbol is required.";
+      const scopeDir = path.resolve(context.directory, args.scope ? String(args.scope) : "");
+      const depth = Math.min(args.depth ?? 1, 3);
+
+      // Search for direct calls: symbol( or .symbol or symbol.
+      const grepArgs = [
+        "-rn",
+        "--color=never",
+        "-E",
+        `[.\\s]${symbol}\\s*\\(|[.]${symbol}\\b|\\b${symbol}\\.`,
+        scopeDir,
+        "--include=*.ts",
+        "--include=*.tsx",
+        "--include=*.js",
+        "--include=*.jsx",
+      ];
+
+      if (args.filter) {
+        const filterStr = String(args.filter);
+        if (filterStr.startsWith("path:")) {
+          grepArgs.push(path.join(scopeDir, filterStr.slice(5)));
+        }
+      }
+
+      const result = run("grep", grepArgs);
+      const lines = result.stdout.split("\n").filter(Boolean).slice(0, 50);
+
+      if (lines.length === 0) return `No callers found for "${symbol}".`;
+
+      const output: string[] = [
+        `## Callers of \`${symbol}\` (${plural(lines.length, "result")})${depth > 1 ? ` (depth: ${depth})` : ""}\n`,
+      ];
+      for (const line of lines) {
+        const parts = line.split(":");
+        if (parts.length >= 2) {
+          const relPath = path.relative(context.directory, parts[0]);
+          output.push(`  ${relPath}:${parts[1]}: ${parts.slice(2).join(":").trim().slice(0, 150)}`);
+        } else {
+          output.push(`  ${line.slice(0, 200)}`);
+        }
+      }
+
+      if (depth > 1) {
+        output.push(`\n_Note: Multi-hop depth (${depth}) requires re-running on each caller._`);
+      }
+      return output.join("\n");
+    },
+  }),
+
+  // -----------------------------------------------------------------------
+  // srcwalk_callees: Forward call graph
+  // -----------------------------------------------------------------------
+  srcwalk_callees: tool({
+    description: `Forward call graph — what does this function call?\nReads the function body and extracts call sites.`,
+    args: {
+      symbol: tool.schema.string().describe("Function/symbol name"),
+      scope: tool.schema.string().optional().describe("Scope directory"),
+      detailed: tool.schema
+        .boolean()
+        .optional()
+        .describe("Show ordered call sites with argument slots"),
+    },
+    execute: async (args, context) => {
+      const symbol = String(args.symbol ?? "").trim();
+      if (!symbol) return "symbol is required.";
+      const scopeDir = path.resolve(context.directory, args.scope ? String(args.scope) : "");
+
+      // Find the function definition
+      const defArgs = [
+        "-rn",
+        "--color=never",
+        "-E",
+        `(export\\s+)?(function|const|let|async\\s+function)\\s+${symbol}\\b|${symbol}\\s*[:=]\\s*(async\\s+)?\\(`,
+        scopeDir,
+        "--include=*.ts",
+        "--include=*.tsx",
+        "--include=*.js",
+        "--include=*.jsx",
+      ];
+      const defResult = run("grep", defArgs);
+      const defLines = defResult.stdout.split("\n").filter(Boolean).slice(0, 5);
+
+      if (defLines.length === 0) {
+        return `Definition not found for "${symbol}". Cannot trace callees without finding the function body.`;
+      }
+
+      const output: string[] = [`## Callees of \`${symbol}\`\n`];
+
+      // For each definition location, show the function and extract calls
+      for (const def of defLines) {
+        const parts = def.split(":");
+        if (parts.length >= 2) {
+          const relPath = path.relative(context.directory, parts[0]);
+          const lineNum = parseInt(parts[1], 10);
+          output.push(`**Definition:** ${relPath}:${lineNum}`);
+
+          // Read function body to extract calls
+          const filePath = path.resolve(context.directory, parts[0]);
+          if (existsSync(filePath)) {
+            const fileLines = readFileSync(filePath, "utf-8").split("\n");
+            let braceCount = 0;
+            let inFunc = false;
+            const calls: string[] = [];
+
+            for (let i = lineNum - 1; i < Math.min(lineNum + 80, fileLines.length); i++) {
+              const line = fileLines[i];
+              if (!inFunc) {
+                if (line.includes("{")) {
+                  inFunc = true;
+                  braceCount = (line.match(/{/g) || []).length;
+                  braceCount -= (line.match(/}/g) || []).length;
+                }
+                continue;
+              }
+              braceCount += (line.match(/{/g) || []).length;
+              braceCount -= (line.match(/}/g) || []).length;
+
+              // Extract function calls
+              const callMatch = [...line.matchAll(/(?<![.\w])(\w+)\s*\(/g)];
+              for (const m of callMatch) {
+                const name = m[1];
+                if (
+                  ![
+                    "if",
+                    "for",
+                    "while",
+                    "switch",
+                    "catch",
+                    "typeof",
+                    "instanceof",
+                    "return",
+                    "throw",
+                    "new",
+                    "delete",
+                    "await",
+                    "yield",
+                  ].includes(name)
+                ) {
+                  const argStart = line.indexOf("(", m.index!);
+                  const argEnd = line.indexOf(")", argStart);
+                  const args_s =
+                    argEnd > argStart
+                      ? line
+                          .slice(argStart + 1, argEnd)
+                          .trim()
+                          .slice(0, 60)
+                      : "";
+                  calls.push(`  ${args.detailed ? `${name}(${args_s})` : `${name}()`}`);
+                }
+              }
+
+              if (braceCount <= 0) break;
+            }
+
+            if (calls.length > 0) {
+              output.push(...calls);
+            } else {
+              output.push("  (no internal calls found)");
+            }
+            output.push("");
+          }
+        }
+      }
+
+      return output.join("\n");
+    },
+  }),
+
+  // -----------------------------------------------------------------------
+  // srcwalk_flow: Compact orientation
+  // -----------------------------------------------------------------------
+  srcwalk_flow: tool({
+    description: `Compact function orientation — ordered callees + direct callers.\nQuick understanding of a function's role in the call graph.`,
+    args: {
+      symbol: tool.schema.string().describe("Symbol name to analyze"),
+      scope: tool.schema.string().optional().describe("Search scope"),
+    },
+    execute: async (args, context) => {
+      const symbol = String(args.symbol ?? "").trim();
+      if (!symbol) return "symbol is required.";
+      const scopeDir = path.resolve(context.directory, args.scope ? String(args.scope) : "");
+
+      // Get callers
+      const callersResult = run("grep", [
+        "-rn",
+        "--color=never",
+        "-E",
+        `[.\\s]${symbol}\\s*\\(|[.]${symbol}\\b`,
+        scopeDir,
+        "--include=*.ts",
+        "--include=*.tsx",
+        "--include=*.js",
+        "--include=*.jsx",
+      ]);
+      const callers = callersResult.stdout.split("\n").filter(Boolean).slice(0, 15);
+
+      // Get callees by reading function body
+      const defResult = run("grep", [
+        "-rn",
+        "--color=never",
+        "-E",
+        `(function|const|let)\\s+${symbol}\\b|${symbol}\\s*[:=]\\s*(async\\s+)?\\(`,
+        scopeDir,
+        "--include=*.ts",
+        "--include=*.tsx",
+        "--include=*.js",
+        "--include=*.jsx",
+      ]);
+      const defLine = defResult.stdout.split("\n").filter(Boolean)[0];
+      let callees: string[] = [];
+
+      if (defLine) {
+        const parts = defLine.split(":");
+        if (parts.length >= 2) {
+          const fp = path.resolve(context.directory, parts[0]);
+          const ln = parseInt(parts[1], 10);
+          if (existsSync(fp)) {
+            const fileLines = readFileSync(fp, "utf-8").split("\n");
+            let bc = 0,
+              inF = false;
+            for (let i = ln - 1; i < Math.min(ln + 60, fileLines.length); i++) {
+              const l = fileLines[i];
+              if (!inF) {
+                if (l.includes("{")) {
+                  inF = true;
+                  bc = (l.match(/{/g) || []).length - (l.match(/}/g) || []).length;
+                }
+                continue;
+              }
+              bc += (l.match(/{/g) || []).length - (l.match(/}/g) || []).length;
+              for (const m of l.matchAll(/(\w+)\s*\(/g)) {
+                if (
+                  ![
+                    "if",
+                    "for",
+                    "while",
+                    "switch",
+                    "catch",
+                    "typeof",
+                    "instanceof",
+                    "return",
+                    "throw",
+                    "new",
+                    "delete",
+                    "await",
+                    "yield",
+                  ].includes(m[1])
+                )
+                  callees.push(m[1]);
+              }
+              if (bc <= 0) break;
+            }
+          }
+        }
+      }
+
+      const output: string[] = [`## Flow: \`${symbol}\``];
+      output.push(`\n**Callers (${plural(callers.length, "file")}):`);
+      if (callers.length === 0) output.push("  (none)");
+      else
+        output.push(
+          ...callers
+            .slice(0, 10)
+            .map(
+              (l) => `  ${path.relative(context.directory, l.split(":")[0])}:${l.split(":")[1]}`,
+            ),
+        );
+
+      output.push(`\n**Callees (${plural(callees.length, "call")}):`);
+      if (callees.length === 0) output.push("  (none)");
+      else output.push(...[...new Set(callees)].slice(0, 20).map((c) => `  ${c}()`));
+      return output.join("\n");
+    },
+  }),
+
+  // -----------------------------------------------------------------------
+  // srcwalk_impact: Heuristic blast-radius
+  // -----------------------------------------------------------------------
+  srcwalk_impact: tool({
+    description: `Heuristic blast-radius triage — broad 'what might be affected?' starting point.\nName-matched, not proof. Use as starting point before verifying with srcwalk_callers or exact reads.`,
+    args: {
+      symbol: tool.schema.string().describe("Symbol name to triage"),
+      scope: tool.schema.string().optional().describe("Search scope"),
+    },
+    execute: async (args, context) => {
+      const symbol = String(args.symbol ?? "").trim();
+      if (!symbol) return "symbol is required.";
+      const scopeDir = path.resolve(context.directory, args.scope ? String(args.scope) : "");
+
+      // Count usages per directory
+      const grepResult = run("grep", [
+        "-rn",
+        "--color=never",
+        "-E",
+        `\\b${symbol}\\b`,
+        scopeDir,
+        "--include=*.ts",
+        "--include=*.tsx",
+        "--include=*.js",
+        "--include=*.jsx",
+      ]);
+      const lines = grepResult.stdout.split("\n").filter(Boolean);
+
+      // Group by file
+      const fileCounts: Record<string, number> = {};
+      for (const line of lines) {
+        const filePath = line.split(":")[0];
+        fileCounts[filePath] = (fileCounts[filePath] || 0) + 1;
+      }
+
+      // Group by directory
+      const dirCounts: Record<string, { files: number; total: number }> = {};
+      for (const [filePath, count] of Object.entries(fileCounts)) {
+        const dir = path.dirname(filePath);
+        if (!dirCounts[dir]) dirCounts[dir] = { files: 0, total: 0 };
+        dirCounts[dir].files++;
+        dirCounts[dir].total += count;
+      }
+
+      const totalOccurrences = lines.length;
+      const totalFiles = Object.keys(fileCounts).length;
+
+      const output: string[] = [
+        `## Impact: \`${symbol}\``,
+        `Total: ${plural(totalOccurrences, "occurrence")} across ${plural(totalFiles, "file")}\n`,
+        `### By directory`,
+      ];
+
+      const sortedDirs = Object.entries(dirCounts).sort((a, b) => b[1].total - a[1].total);
+      for (const [dir, info] of sortedDirs.slice(0, 15)) {
+        const relDir = path.relative(context.directory, dir) || ".";
+        output.push(
+          `  ${relDir}/ — ${plural(info.total, "occurrence")} in ${plural(info.files, "file")}`,
+        );
+      }
+
+      const topFiles = Object.entries(fileCounts)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 20);
+      output.push(`\n### Top files`);
+      for (const [filePath, count] of topFiles) {
+        const relPath = path.relative(context.directory, filePath);
+        output.push(`  ${relPath} (${plural(count, "occurrence")})`);
+      }
+
+      output.push(
+        `\n_Heuristic: name-matched, not proof. Follow up with srcwalk_callers for exact call sites._`,
+      );
+      return output.join("\n");
+    },
+  }),
 };
 
 // ---------------------------------------------------------------------------
@@ -669,53 +642,59 @@ const srcwalkTools = {
 // ---------------------------------------------------------------------------
 
 function readFileRange(filePath: string, start: number, end: number, displayPath?: string): string {
-	try {
-		const content = readFileSync(filePath, "utf-8");
-		const lines = content.split("\n");
-		const from = Math.max(0, start - 1);
-		const to = Math.min(lines.length, end);
-		const result: string[] = [`File: ${displayPath ?? filePath} (lines ${start}-${end}):\n`];
-		for (let i = from; i < to; i++) {
-			result.push(`${i + 1}: ${lines[i]}`);
-		}
-		return result.join("\n");
-	} catch (err) {
-		return `Error reading file: ${err instanceof Error ? err.message : String(err)}`;
-	}
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const lines = content.split("\n");
+    const from = Math.max(0, start - 1);
+    const to = Math.min(lines.length, end);
+    const result: string[] = [`File: ${displayPath ?? filePath} (lines ${start}-${end}):\n`];
+    for (let i = from; i < to; i++) {
+      result.push(`${i + 1}: ${lines[i]}`);
+    }
+    return result.join("\n");
+  } catch (err) {
+    return `Error reading file: ${err instanceof Error ? err.message : String(err)}`;
+  }
 }
 
-async function listDirRecursive(dir: string, prefix: string, maxDepth: number, output: string[], rootDir: string): Promise<void> {
-	if (maxDepth <= 0) return;
-	try {
-		const entries = await readdir(dir, { withFileTypes: true });
-		const skipDirs = new Set([".git", "node_modules", "dist", "build", "coverage", ".next"]);
-		const dirs = entries.filter(e => e.isDirectory() && !skipDirs.has(e.name)).sort((a, b) => a.name.localeCompare(b.name));
-		const files = entries.filter(e => e.isFile()).sort((a, b) => a.name.localeCompare(b.name));
-
-		for (const d of dirs) {
-			const relPath = path.relative(rootDir, path.join(dir, d.name));
-			output.push(`${prefix}${d.name}/`);
-			await listDirRecursive(path.join(dir, d.name), prefix + "  ", maxDepth - 1, output, rootDir);
-		}
-		for (const f of files) {
-			const fp = path.join(dir, f.name);
-			try {
-				const size = statSync(fp).size;
-				const tokenEst = Math.ceil(size / 4);
-				output.push(`${prefix}${f.name}  (~${tokenEst.toLocaleString()} tokens)`);
-			} catch {
-				output.push(`${prefix}${f.name}`);
-			}
-		}
-	} catch {
-		// Permission denied, skip
-	}
+async function listDirRecursive(
+  dir: string,
+  prefix: string,
+  maxDepth: number,
+  output: string[],
+): Promise<void> {
+  if (maxDepth <= 0) return;
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const skipDirs = new Set([".git", "node_modules", "dist", "build", "coverage", ".next"]);
+    const dirs = entries
+      .filter((e) => e.isDirectory() && !skipDirs.has(e.name))
+      .sort((a, b) => a.name.localeCompare(b.name));
+    const files = entries.filter((e) => e.isFile()).sort((a, b) => a.name.localeCompare(b.name));
+
+    for (const d of dirs) {
+      output.push(`${prefix}${d.name}/`);
+      await listDirRecursive(path.join(dir, d.name), prefix + "  ", maxDepth - 1, output);
+    }
+    for (const f of files) {
+      const fp = path.join(dir, f.name);
+      try {
+        const size = statSync(fp).size;
+        const tokenEst = Math.ceil(size / 4);
+        output.push(`${prefix}${f.name}  (~${tokenEst.toLocaleString()} tokens)`);
+      } catch {
+        output.push(`${prefix}${f.name}`);
+      }
+    }
+  } catch {
+    // Permission denied, skip
+  }
 }
 
 export const SrcwalkPlugin: Plugin = async () => {
-	return {
-		tool: srcwalkTools,
-	};
+  return {
+    tool: srcwalkTools,
+  };
 };
 
 export default SrcwalkPlugin;