opencodekit 0.21.10 → 0.23.0

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

@@ -0,0 +1,721 @@
+/**
+ * Srcwalk Plugin — Code Intelligence Tools
+ *
+ * Provides structured code navigation tools for OpenCode agents.
+ * 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)
+ *   - srcwalk_callees — Forward call graph (grep-based)
+ *   - srcwalk_flow    — Compact function orientation
+ *   - srcwalk_impact  — Heuristic blast-radius triage
+ */
+
+import { execFile, 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;
+
+// ---------------------------------------------------------------------------
+// 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 plural(n: number, word: string): string {
+	return `${n} ${word}${n !== 1 ? "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");
+		},
+	}),
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+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)}`;
+	}
+}
+
+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
+	}
+}
+
+export const SrcwalkPlugin: Plugin = async () => {
+	return {
+		tool: srcwalkTools,
+	};
+};
+
+export default SrcwalkPlugin;