pi-readseek 0.3.15 → 0.3.17

package/README.md

@@ -34,6 +34,9 @@ npm install --save-dev @jarkkojs/readseek
   follow-up `read`.
 - **search** — searches code by structural pattern (AST) and returns anchored
   matches. Use when syntax matters more than raw text.
+- **refs** — finds binding-accurate references to an identifier and returns
+  anchored usages with their enclosing symbols. Use before renaming or deleting
+  a symbol.
 - **write** — creates or overwrites whole files and returns anchors for
   immediate follow-up edits.
 

package/index.ts

@@ -3,6 +3,7 @@ import { registerReadTool } from "./src/read.js";
 import { registerEditTool } from "./src/edit.js";
 import { registerGrepTool } from "./src/grep.js";
 import { registerSgTool, isSgAvailable } from "./src/sg.js";
+import { registerRefsTool } from "./src/refs.js";
 import { registerWriteTool } from "./src/write.js";
 export default function piReadseekExtension(pi: ExtensionAPI): void {
 	const readPaths = new Set<string>();
@@ -20,5 +21,6 @@ export default function piReadseekExtension(pi: ExtensionAPI): void {
 
 	registerGrepTool(pi, { searchGuideline, onFileAnchored: noteRead });
 	registerSgTool(pi, { onFileAnchored: noteRead });
+	registerRefsTool(pi, { onFileAnchored: noteRead });
 	registerWriteTool(pi, { onFileAnchored: noteRead });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readseek",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "description": "Pi extension for readseek-backed hash-anchored read/edit/grep, structural code maps, structural search, and file exploration",
   "type": "module",
   "exports": {
@@ -39,12 +39,10 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@jarkkojs/readseek": "^0.3.14",
+    "@jarkkojs/readseek": "^0.3.17",
     "diff": "^8.0.3",
     "ignore": "^7.0.5",
     "picomatch": "^4.0.4",
-    "tree-sitter-wasms": "0.1.13",
-    "web-tree-sitter": "0.25.10",
     "xxhash-wasm": "^1.1.0"
   },
   "peerDependencies": {

package/prompts/edit.md

@@ -80,7 +80,7 @@ Syntax validation runs before writing when supported:
 - Default `warn`: write succeeds, but warnings include `syntax-regression: lines X-Y`.
 - `block`: aborts without writing.
 - `off`: skips validation.
-- `PI_HASHLINE_SYNTAX_VALIDATE` can set the default mode.
+- `READSEEK_SYNTAX_VALIDATE` can set the default mode.
 
 Existing syntax errors are tolerated; warnings are for newly introduced parser errors.
 

package/prompts/refs.md

@@ -0,0 +1,23 @@
+Find binding-accurate references to an identifier with readseek. Use it when you need every place a name is used — before renaming, deleting, or changing a symbol — and plain text search would be too broad. Results are grouped by file with edit-ready hashline anchors and the enclosing symbol for each reference.
+
+## Parameters
+
+- `name` — identifier to find references for.
+- `path` — file or directory, default cwd.
+- `lang` — language hint; set it when syntax is ambiguous, extensionless, or generated.
+- `scope` — restrict results to the binding under `line`/`column` in a single file. Requires `line`.
+- `line` — one-based cursor line, used with `scope`.
+- `column` — one-based cursor byte column, used with `scope`.
+- `cached` — in a Git repository, search tracked/indexed files.
+- `others` — in a Git repository, search untracked files.
+- `ignored` — with `others`, include ignored untracked files.
+
+## Scope
+
+Without `scope`, references match by identifier name across the target. With `scope` plus `line` (and optionally `column`), results are limited to the specific binding under that cursor in a single file, so shadowed or unrelated same-named identifiers are excluded.
+
+## Git selection
+
+When searching a directory inside a Git repository, readseek defaults to tracked/indexed files plus untracked non-ignored files. Use `cached`, `others`, and `ignored` to narrow or expand that selection. `ignored` requires `others`.
+
+Use `grep` for plain text, `search` for code shape, and `refs` for identifier usage.

package/src/edit-syntax-validate.ts

@@ -1,6 +1,4 @@
-import type { Node as SyntaxNode, Parser as WasmParser, Tree } from "web-tree-sitter";
-import { getWasmParser, type WasmLanguageId } from "./readseek/parser-loader.js";
-import { reportParserError } from "./readseek/parser-errors.js";
+import { readseekCheck, type ReadseekCheckOutput, type ReadseekDiagnostic } from "./readseek-client.js";
 
 export interface ValidateInput {
   filePath: string;
@@ -14,122 +12,53 @@ export interface ValidateResult {
   newMissingCount: number;
 }
 
-interface NodeStats {
-  errors: Array<{ startLine: number; endLine: number }>;
-  missing: Array<{ startLine: number; endLine: number }>;
-}
-
-function countNodes(parser: WasmParser, source: string): NodeStats {
-  const tree: Tree | null = parser.parse(source);
-  const errors: Array<{ startLine: number; endLine: number }> = [];
-  const missing: Array<{ startLine: number; endLine: number }> = [];
-  if (!tree) return { errors, missing };
-  try {
-    const stack: SyntaxNode[] = [tree.rootNode];
-    while (stack.length > 0) {
-      const node = stack.pop()!;
-      if (node.type === "ERROR") {
-        errors.push({
-          startLine: node.startPosition.row + 1,
-          endLine: node.endPosition.row + 1,
-        });
-      }
-      if (node.isMissing) {
-        missing.push({
-          startLine: node.startPosition.row + 1,
-          endLine: node.endPosition.row + 1,
-        });
-      }
-      for (let i = 0; i < node.namedChildCount; i++) {
-        const c = node.namedChild(i);
-        if (c) stack.push(c);
-      }
-      // Also descend into anonymous children to find MISSING tokens.
-      for (let i = 0; i < node.childCount; i++) {
-        const c = node.child(i);
-        if (c && !c.isNamed) stack.push(c);
-      }
-    }
-    return { errors, missing };
-  } finally {
-    tree.delete();
-  }
-}
-
-function dedupeSortLines(
-  ranges: Array<{ startLine: number; endLine: number }>,
-): string[] {
+function dedupeSortLines(diagnostics: ReadseekDiagnostic[]): string[] {
   const seen = new Set<string>();
   const out: Array<{ key: string; start: number }> = [];
-  for (const r of ranges) {
-    const key = r.startLine === r.endLine
-      ? String(r.startLine)
-      : `${r.startLine}-${r.endLine}`;
+  for (const diagnostic of diagnostics) {
+    const key =
+      diagnostic.start_line === diagnostic.end_line
+        ? String(diagnostic.start_line)
+        : `${diagnostic.start_line}-${diagnostic.end_line}`;
     if (!seen.has(key)) {
       seen.add(key);
-      out.push({ key, start: r.startLine });
+      out.push({ key, start: diagnostic.start_line });
     }
   }
   out.sort((a, b) => a.start - b.start);
   return out.map((o) => o.key);
 }
 
-const EXTENSION_TO_LANGUAGE: Record<string, WasmLanguageId> = {
-	".rs": "rust",
-	".c": "cpp",
-	".cc": "cpp",
-	".cpp": "cpp",
-	".cxx": "cpp",
-	".h": "c-header",
-	".hpp": "c-header",
-	".hxx": "c-header",
-	".java": "java",
-};
-
-function detectWasmLang(filePath: string): WasmLanguageId | null {
-	for (const [ext, langId] of Object.entries(EXTENSION_TO_LANGUAGE)) {
-		if (filePath.toLowerCase().endsWith(ext)) return langId;
-	}
-	return null;
-}
+const EMPTY: ReadseekCheckOutput = { errorCount: 0, missingCount: 0, diagnostics: [] };
 
+/**
+ * Compare parse diagnostics between `before` and `after` and report any newly
+ * introduced syntax errors. Uses readseek's native `check`, so every language
+ * with a tree-sitter parser is validated.
+ *
+ * Returns `null` when nothing new appears or when readseek cannot parse the
+ * file, so a validator failure never blocks an edit.
+ */
 export async function validateSyntaxRegression(
-	input: ValidateInput,
+  input: ValidateInput,
 ): Promise<ValidateResult | null> {
-	const langId = detectWasmLang(input.filePath);
-	if (!langId) return null;
-	const parser = await getWasmParser(langId);
-  if (!parser) return null;
-
+  let before: ReadseekCheckOutput;
+  let after: ReadseekCheckOutput;
   try {
-    const beforeStats = input.before === undefined
-      ? { errors: [], missing: [] }
-      : countNodes(parser, input.before);
-    const afterStats = countNodes(parser, input.after);
+    before = input.before === undefined ? EMPTY : await readseekCheck(input.filePath, input.before);
+    after = await readseekCheck(input.filePath, input.after);
+  } catch {
+    return null;
+  }
 
-    // ±1 tolerance on ERROR count, no tolerance on MISSING.
-    const newErrorCount = Math.max(
-      0,
-      afterStats.errors.length - beforeStats.errors.length - 1,
-    );
-    const newMissingCount = Math.max(
-      0,
-      afterStats.missing.length - beforeStats.missing.length,
-    );
+  const newErrorCount = Math.max(0, after.errorCount - before.errorCount - 1);
+  const newMissingCount = Math.max(0, after.missingCount - before.missingCount);
 
-    if (newErrorCount === 0 && newMissingCount === 0) return null;
+  if (newErrorCount === 0 && newMissingCount === 0) return null;
 
-    const errorLines = dedupeSortLines([
-      ...afterStats.errors,
-      ...afterStats.missing,
-    ]);
-    return { errorLines, newErrorCount, newMissingCount };
-	} catch (err) {
-		reportParserError(`wasm:syntax-validate:${langId}:${err instanceof Error ? err.message : String(err)}`, err, {
-			context: `tree-sitter syntax validation failed for ${langId}`,
-		});
-		return null;
-	} finally {
-		parser.delete();
-  }
+  return {
+    errorLines: dedupeSortLines(after.diagnostics),
+    newErrorCount,
+    newMissingCount,
+  };
 }

package/src/edit.ts

@@ -269,7 +269,7 @@ export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}
 			// Error-precedence order: replace_symbol resolution > anchor-overlap > anchored-edit.
 			//
 			// AC 4: store successful probe results and reuse them in the apply loop so
-			// generateMapFromContent is invoked at most once per replace_symbol edit.
+			// readseekMapContent is invoked at most once per replace_symbol edit.
 			const replaceSymbolRanges: { start: number; end: number }[] = [];
 			const rsProbeResults: { type: "ok"; content: string; replacement: string; warnings: string[]; range: { start: number; end: number } }[] = [];
 			for (const rs of replaceSymbolEdits) {
@@ -342,7 +342,7 @@ export function registerEditTool(pi: ExtensionAPI, options: EditToolOptions = {}
 			// Apply pass: reuse all probe results (AC 4). The probe pass resolved every
 			// replace_symbol against originalNormalized; apply those replacements in
 			// reverse source order so original line ranges stay valid and no second
-			// replaceSymbol/generateMapFromContent call is needed.
+			// replaceSymbol/readseekMapContent call is needed.
 			const replaceSymbolWarnings: string[] = [];
 			if (rsProbeResults.length > 0) {
 				const lines = originalNormalized.split("\n");

package/src/grep-budget.ts

@@ -4,7 +4,7 @@ import { resolveReadseekJsonSettings } from "./readseek-settings.js";
 const POSITIVE_BASE10_INT = /^[1-9][0-9]*$/;
 
 /**
- * Strict positive base-10 integer parser used by hashline env knobs.
+ * Strict positive base-10 integer parser used by readseek env knobs.
  *
  * Accepts: trimmed strings matching /^[1-9][0-9]*$/ that parse to a finite
  * positive integer.
@@ -66,12 +66,12 @@ export function resolveGrepOutputBudget(): GrepOutputBudget {
 	const settings = resolveReadseekJsonSettings().settings.grep;
 	return {
 		maxLines: resolveDimension(
-			process.env.PI_HASHLINE_GREP_MAX_LINES,
+			process.env.READSEEK_GREP_MAX_LINES,
 			settings?.maxLines,
 			GREP_OUTPUT_DEFAULT_MAX_LINES,
 		),
 		maxBytes: resolveDimension(
-			process.env.PI_HASHLINE_GREP_MAX_BYTES,
+			process.env.READSEEK_GREP_MAX_BYTES,
 			settings?.maxBytes,
 			GREP_OUTPUT_DEFAULT_MAX_BYTES,
 		),

package/src/map-cache.ts

@@ -1,6 +1,6 @@
 import { stat } from "node:fs/promises";
 import type { FileMap } from "./readseek/types.js";
-import { generateMap } from "./readseek/mapper.js";
+import { readseekMap } from "./readseek-client.js";
 
 interface CacheEntry {
 	mtimeMs: number;
@@ -60,7 +60,7 @@ export async function getOrGenerateMap(absPath: string): Promise<FileMap | null>
 		if (inflight) return inflight;
 
 		const generation = (async () => {
-			const map = await generateMap(absPath);
+			const map = await readseekMap(absPath, fileStat.size);
 			rememberInMemory(absPath, { mtimeMs, map });
 			return map;
 		})()

package/src/readseek/types.ts

@@ -58,16 +58,6 @@ export interface FileMap {
   truncatedInfo?: TruncatedInfo;
 }
 
-/**
- * Map generation options.
- */
-export interface MapOptions {
-  /** Maximum map size in bytes (default: 20KB) */
-  maxBytes?: number;
-  /** Abort signal */
-  signal?: AbortSignal;
-}
-
 /**
  * Language information.
  */

package/src/readseek-client.ts

@@ -70,6 +70,42 @@ interface ReadseekSearchOutput {
 	results: ReadseekSearchFileOutput[];
 }
 
+export interface ReadseekReference {
+	file: string;
+	line: number;
+	column: number;
+	line_hash: string;
+	text: string;
+	enclosingSymbol?: string;
+}
+
+interface ReadseekRefsOutput {
+	references: ReadseekReference[];
+}
+
+export interface ReadseekRefsOptions {
+	scope?: boolean;
+	line?: number;
+	column?: number;
+	language?: string;
+	cached?: boolean;
+	others?: boolean;
+	ignored?: boolean;
+	signal?: AbortSignal;
+}
+
+export interface ReadseekDiagnostic {
+	kind: "error" | "missing";
+	start_line: number;
+	end_line: number;
+}
+
+export interface ReadseekCheckOutput {
+	errorCount: number;
+	missingCount: number;
+	diagnostics: ReadseekDiagnostic[];
+}
+
 export interface ReadseekSearchOptions {
 	language?: string;
 	cached?: boolean;
@@ -398,7 +434,87 @@ export async function readseekMapContent(
 	options: { signal?: AbortSignal } = {},
 ): Promise<FileMap | null> {
 	const output = parseMapOutput(
-		await runReadseek(["map", "--stdin", "--path", filePath], { signal: options.signal, stdin: content }),
+		await runReadseek(["map", "--stdin", filePath], { signal: options.signal, stdin: content }),
 	);
 	return fileMapFromReadseekOutput(output, filePath, Buffer.byteLength(content, "utf8"));
 }
+
+function optionalString(value: unknown, field: string): string | undefined {
+	if (value === undefined || value === null) return undefined;
+	return requireString(value, field);
+}
+
+function parseRefsOutput(value: unknown): ReadseekRefsOutput {
+	if (!value || typeof value !== "object") throw new Error("invalid readseek refs output");
+	const output = value as Record<string, unknown>;
+	if (!Array.isArray(output.references)) throw new Error("invalid readseek references");
+	return {
+		references: output.references.map((reference) => {
+			if (!reference || typeof reference !== "object") throw new Error("invalid readseek reference");
+			const item = reference as Record<string, unknown>;
+			const symbol = item.symbol;
+			const enclosing =
+				symbol && typeof symbol === "object"
+					? optionalString((symbol as Record<string, unknown>).qualified_name, "reference.symbol.qualified_name")
+					: undefined;
+			return {
+				file: requireString(item.file, "reference.file"),
+				line: requireNumber(item.line, "reference.line"),
+				column: requireNumber(item.column, "reference.column"),
+				line_hash: requireString(item.line_hash, "reference.line_hash"),
+				text: requireString(item.text, "reference.text"),
+				enclosingSymbol: enclosing,
+			};
+		}),
+	};
+}
+
+export async function readseekRefs(
+	target: string,
+	name: string,
+	options: ReadseekRefsOptions = {},
+): Promise<ReadseekReference[]> {
+	const args = ["refs", target, name];
+	if (options.scope) args.push("--scope");
+	if (options.line !== undefined) args.push("--line", String(options.line));
+	if (options.column !== undefined) args.push("--column", String(options.column));
+	if (options.language) args.push("--language", options.language);
+	if (options.cached) args.push("--cached");
+	if (options.others) args.push("--others");
+	if (options.ignored) args.push("--ignored");
+	return parseRefsOutput(await runReadseek(args, { signal: options.signal })).references;
+}
+
+function parseDiagnosticKind(value: unknown): ReadseekDiagnostic["kind"] {
+	if (value === "error" || value === "missing") return value;
+	throw new Error("invalid readseek diagnostic.kind");
+}
+
+function parseCheckOutput(value: unknown): ReadseekCheckOutput {
+	if (!value || typeof value !== "object") throw new Error("invalid readseek check output");
+	const output = value as Record<string, unknown>;
+	if (!Array.isArray(output.diagnostics)) throw new Error("invalid readseek diagnostics");
+	return {
+		errorCount: requireNumber(output.error_count, "error_count"),
+		missingCount: requireNumber(output.missing_count, "missing_count"),
+		diagnostics: output.diagnostics.map((diagnostic) => {
+			if (!diagnostic || typeof diagnostic !== "object") throw new Error("invalid readseek diagnostic");
+			const item = diagnostic as Record<string, unknown>;
+			return {
+				kind: parseDiagnosticKind(item.kind),
+				start_line: requireNumber(item.start_line, "diagnostic.start_line"),
+				end_line: requireNumber(item.end_line, "diagnostic.end_line"),
+			};
+		}),
+	};
+}
+
+export async function readseekCheck(
+	filePath: string,
+	content: string,
+	options: { signal?: AbortSignal } = {},
+): Promise<ReadseekCheckOutput> {
+	return parseCheckOutput(
+		await runReadseek(["check", "--stdin", filePath], { signal: options.signal, stdin: content }),
+	);
+}

package/src/readseek-settings.ts

@@ -121,7 +121,7 @@ export function resolveReadseekJsonSettings(): ReadseekSettingsResult {
 }
 
 export function resolveEditDiffDisplay(env: NodeJS.ProcessEnv = process.env): "collapsed" | "expanded" {
-  const raw = env.PI_HASHLINE_EDIT_DIFF_DISPLAY;
+  const raw = env.READSEEK_EDIT_DIFF_DISPLAY;
   if (typeof raw === "string") {
     const normalized = raw.trim().toLowerCase();
     if (normalized === "expanded" || normalized === "collapsed") return normalized;

package/src/refs-output.ts

@@ -0,0 +1,56 @@
+import type { ReadseekLine } from "./readseek-value.js";
+
+export interface RefsOutputLine extends ReadseekLine {
+  enclosingSymbol?: string;
+}
+
+export interface RefsOutputFile {
+  displayPath: string;
+  path: string;
+  lines: RefsOutputLine[];
+}
+
+export interface BuildRefsOutputInput {
+  name: string;
+  files: RefsOutputFile[];
+}
+
+export interface RefsOutputResult {
+  text: string;
+  readseekValue: {
+    tool: "refs";
+    files: Array<{
+      path: string;
+      lines: RefsOutputLine[];
+    }>;
+  };
+}
+
+export function buildRefsOutput(input: BuildRefsOutputInput): RefsOutputResult {
+  if (input.files.length === 0) {
+    return {
+      text: `No references found for: ${input.name}`,
+      readseekValue: { tool: "refs", files: [] },
+    };
+  }
+
+  const blocks: string[] = [];
+  for (const file of input.files) {
+    blocks.push(`--- ${file.displayPath} ---`);
+    for (const line of file.lines) {
+      const suffix = line.enclosingSymbol ? ` (in ${line.enclosingSymbol})` : "";
+      blocks.push(`>>${line.anchor}|${line.display}${suffix}`);
+    }
+  }
+
+  return {
+    text: blocks.join("\n"),
+    readseekValue: {
+      tool: "refs",
+      files: input.files.map((file) => ({
+        path: file.path,
+        lines: file.lines.map((line) => ({ ...line })),
+      })),
+    },
+  };
+}

package/src/refs.ts

@@ -0,0 +1,202 @@
+import type { ExtensionAPI, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "@sinclair/typebox";
+import path from "node:path";
+import { stat as fsStat } from "node:fs/promises";
+import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
+import { escapeControlCharsForDisplay } from "./hashline.js";
+import { buildToolErrorResult } from "./readseek-value.js";
+import { resolveToCwd } from "./path-utils.js";
+import { isReadseekAvailable, readseekRefs, type ReadseekReference } from "./readseek-client.js";
+import { buildRefsOutput, type RefsOutputFile, type RefsOutputLine } from "./refs-output.js";
+
+import { clampLineToWidth, clampLinesToWidth, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+
+type RefsParams = {
+  name: string;
+  path?: string;
+  lang?: string;
+  scope?: boolean;
+  line?: number;
+  column?: number;
+  cached?: boolean;
+  others?: boolean;
+  ignored?: boolean;
+};
+
+const REFS_PROMPT_METADATA = defineToolPromptMetadata({
+  promptUrl: new URL("../prompts/refs.md", import.meta.url),
+  promptSnippet: "Find references to an identifier with readseek and return edit-ready anchors",
+});
+
+export function isRefsAvailable(): boolean {
+  return isReadseekAvailable();
+}
+
+interface RefsToolOptions {
+  onFileAnchored?: (absolutePath: string) => void;
+}
+
+function refsLine(reference: ReadseekReference): RefsOutputLine {
+  return {
+    line: reference.line,
+    hash: reference.line_hash,
+    anchor: `${reference.line}:${reference.line_hash}`,
+    raw: reference.text,
+    display: escapeControlCharsForDisplay(reference.text),
+    enclosingSymbol: reference.enclosingSymbol,
+  };
+}
+
+function groupReferences(references: ReadseekReference[], cwd: string): RefsOutputFile[] {
+  const files = new Map<string, RefsOutputFile>();
+  const seen = new Set<string>();
+  for (const reference of references) {
+    const abs = path.isAbsolute(reference.file) ? reference.file : path.resolve(cwd, reference.file);
+    const dedupeKey = `${abs}:${reference.line}:${reference.column}`;
+    if (seen.has(dedupeKey)) continue;
+    seen.add(dedupeKey);
+    let file = files.get(abs);
+    if (!file) {
+      file = { displayPath: path.relative(cwd, abs) || abs, path: abs, lines: [] };
+      files.set(abs, file);
+    }
+    file.lines.push(refsLine(reference));
+  }
+  return [...files.values()];
+}
+
+export function registerRefsTool(pi: ExtensionAPI, options: RefsToolOptions = {}) {
+  const toolConfig = {
+    callable: true,
+    enabled: true,
+    policy: "read-only" as const,
+    readOnly: true,
+    pythonName: "refs",
+    defaultExposure: "opt-in" as const,
+  };
+
+  const tool = {
+    name: "refs",
+    label: "References",
+    description: REFS_PROMPT_METADATA.description,
+    promptSnippet: REFS_PROMPT_METADATA.promptSnippet,
+    promptGuidelines: REFS_PROMPT_METADATA.promptGuidelines,
+    parameters: Type.Object({
+      name: Type.String({ description: "Identifier to find references for" }),
+      path: Type.Optional(Type.String({ description: "Search path" })),
+      lang: Type.Optional(Type.String({ description: "Language hint" })),
+      scope: Type.Optional(Type.Boolean({ description: "Restrict to the binding under line/column (single file)" })),
+      line: Type.Optional(Type.Number({ description: "One-based cursor line, used with scope" })),
+      column: Type.Optional(Type.Number({ description: "One-based cursor byte column, used with scope" })),
+      cached: Type.Optional(Type.Boolean({ description: "In a Git repository, search tracked/indexed files" })),
+      others: Type.Optional(Type.Boolean({ description: "In a Git repository, search untracked files" })),
+      ignored: Type.Optional(Type.Boolean({ description: "With others=true, include ignored untracked files" })),
+    }),
+    ptc: toolConfig,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const p = params as RefsParams;
+      if (p.ignored && !p.others) {
+        return buildToolErrorResult("refs", "invalid-parameter", "Error: refs parameter 'ignored' requires 'others'");
+      }
+      if (p.scope && p.line === undefined) {
+        return buildToolErrorResult("refs", "invalid-parameter", "Error: refs parameter 'scope' requires 'line'");
+      }
+      const searchPath = resolveToCwd(p.path ?? ".", ctx.cwd);
+
+      try {
+        await fsStat(searchPath);
+      } catch (err: any) {
+        if (err?.code === "ENOENT") {
+          return buildToolErrorResult("refs", "path-not-found", `Error: path '${p.path ?? "."}' does not exist`, {
+            path: p.path ?? searchPath,
+          });
+        }
+        if (err?.code === "EACCES" || err?.code === "EPERM") {
+          return buildToolErrorResult("refs", "permission-denied", `Error: permission denied for path '${p.path ?? "."}'`, {
+            path: p.path ?? searchPath,
+          });
+        }
+        const message = `Error: could not access path '${p.path ?? "."}': ${err?.message ?? String(err)}`;
+        return buildToolErrorResult("refs", "fs-error", message, {
+          path: p.path ?? searchPath,
+          details: { fsCode: err?.code, fsMessage: err?.message },
+        });
+      }
+
+      try {
+        const references = await readseekRefs(searchPath, p.name, {
+          scope: p.scope,
+          line: p.line,
+          column: p.column,
+          language: p.lang,
+          cached: p.cached,
+          others: p.others,
+          ignored: p.ignored,
+          signal,
+        });
+        const files = groupReferences(references, ctx.cwd);
+        const builtOutput = buildRefsOutput({ name: p.name, files });
+        for (const file of files) {
+          options.onFileAnchored?.(file.path);
+        }
+        return {
+          content: [{ type: "text", text: builtOutput.text }],
+          details: { readseekValue: builtOutput.readseekValue },
+        };
+      } catch (err: any) {
+        const message = String(err?.message || err);
+        const missingReadseek = err?.code === "ENOENT" || /Cannot find package|Cannot find module|no such file/i.test(message);
+        return buildToolErrorResult(
+          "refs",
+          missingReadseek ? "readseek-not-installed" : "readseek-execution-error",
+          message,
+          missingReadseek ? { hint: "Run npm install to install @jarkkojs/readseek." } : {},
+        );
+      }
+    },
+    renderCall(args: any, theme: any, ...rest: any[]) {
+      const context = rest[0] ?? {};
+      let text = `${renderToolLabel(theme, "refs")} ${theme.fg("accent", args.name)}`;
+      text += theme.fg("dim", ` in ${args.path ?? "."}`);
+      if (args.lang) text += theme.fg("dim", ` (${args.lang})`);
+      const flags = [args.scope && "scope", args.cached && "cached", args.others && "others", args.ignored && "ignored"].filter(Boolean);
+      if (flags.length > 0) text += theme.fg("dim", ` [${flags.join(",")}]`);
+      return new Text(clampLineToWidth(text, context.width), 0, 0);
+    },
+    renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
+      const { isPartial, isError, expanded, cwd, width } = resolveRenderResultContext(options, rest);
+
+      if (isPartial) return new Text(clampLinesToWidth([summaryLine("pending refs")], width).join("\n"), 0, 0);
+
+      const content = result.content?.[0];
+      const textContent = content?.type === "text" ? content.text : "";
+      if (isError || result.isError) {
+        const firstLine = textContent.split("\n")[0] || "Error";
+        const body = expanded && textContent ? textContent : firstLine;
+        return new Text(clampLinesToWidth(summaryLine(body).split("\n"), width).join("\n"), 0, 0);
+      }
+      const readseekValue = (result.details as any)?.readseekValue as
+        | { tool: "refs"; files: Array<{ path: string; lines: any[] }> }
+        | undefined;
+      const files = readseekValue?.files ?? [];
+      if (files.length === 0) return new Text(summaryLine("no references"), 0, 0);
+      const fileCount = files.length;
+      const totalRefs = files.reduce((sum: number, f: any) => sum + f.lines.length, 0);
+      const refWord = totalRefs === 1 ? "reference" : "references";
+      const fileWord = fileCount === 1 ? "file" : "files";
+      let text = summaryLine(`${totalRefs} ${refWord} in ${fileCount} ${fileWord}`, { hidden: !expanded });
+      if (expanded) {
+        for (const file of files.slice(0, 20)) {
+          const display = path.relative(cwd, file.path) || file.path;
+          text += "\n" + theme.fg("dim", `  ${display} (${file.lines.length})`);
+        }
+        if (files.length > 20) text += "\n" + theme.fg("muted", `  … and ${files.length - 20} more files`);
+      }
+      return new Text(clampLinesToWidth(text.split("\n"), width).join("\n"), 0, 0);
+    },
+  } satisfies Parameters<ExtensionAPI["registerTool"]>[0] & { ptc: typeof toolConfig };
+
+  pi.registerTool(tool);
+  return tool;
+}

package/src/replace-symbol.ts

@@ -1,4 +1,4 @@
-import { generateMapFromContent } from "./readseek/mapper.js";
+import { readseekMapContent } from "./readseek-client.js";
 import { findSymbol } from "./readseek/symbol-lookup.js";
 import { formatAmbiguous, formatNotFound } from "./readseek/symbol-error-format.js";
 
@@ -32,7 +32,7 @@ function reindent(text: string, indent: string): string {
 }
 
 export async function replaceSymbol(input: ReplaceSymbolInput): Promise<ReplaceSymbolResult> {
-	const map = await generateMapFromContent(input.filePath, input.content);
+	const map = await readseekMapContent(input.filePath, input.content);
 	if (!map) {
 		return {
 			type: "unsupported",

package/src/syntax-validate-mode.ts

@@ -19,7 +19,7 @@ export function resolveSyntaxValidateMode(
 ): SyntaxValidateMode {
   const fromOpt = coerce(opts.syntaxValidate);
   if (fromOpt) return fromOpt;
-  const fromEnv = coerce(process.env.PI_HASHLINE_SYNTAX_VALIDATE);
+  const fromEnv = coerce(process.env.READSEEK_SYNTAX_VALIDATE);
   if (fromEnv) return fromEnv;
   return DEFAULT;
 }

package/src/tool-prompt-metadata.ts

@@ -8,6 +8,7 @@ const COMPACT_DESCRIPTIONS: Record<string, string> = {
 
   "write.md": "Create or overwrite a complete file and return anchors.",
   "sg.md": "Search code by AST pattern and return anchored matches.",
+  "refs.md": "Find references to an identifier and return anchored usages with enclosing symbols.",
 };
 
 const COMPACT_GUIDELINES: Record<string, string[]> = {
@@ -33,6 +34,10 @@ const COMPACT_GUIDELINES: Record<string, string[]> = {
     "Use search for AST-shaped code patterns.",
     "Use grep instead of search for plain text.",
   ],
+  "refs.md": [
+    "Use refs to find every usage of an identifier before renaming or deleting it.",
+    "Use refs with scope plus line/column to follow a specific binding instead of every same-named identifier.",
+  ],
 };
 
 export interface ToolPromptMetadata {

package/src/readseek/mapper.ts

@@ -1,28 +0,0 @@
-import { stat } from "node:fs/promises";
-
-import { readseekMap, readseekMapContent } from "../readseek-client.js";
-import { throwIfAborted } from "../runtime.js";
-import type { FileMap, MapOptions } from "./types.js";
-
-export async function generateMap(
-	filePath: string,
-	options: MapOptions = {},
-): Promise<FileMap | null> {
-	throwIfAborted(options.signal);
-	const fileStat = await stat(filePath);
-	throwIfAborted(options.signal);
-	const map = await readseekMap(filePath, fileStat.size, { signal: options.signal });
-	throwIfAborted(options.signal);
-	return map;
-}
-
-export async function generateMapFromContent(
-	filePath: string,
-	content: string,
-	options: MapOptions = {},
-): Promise<FileMap | null> {
-	throwIfAborted(options.signal);
-	const map = await readseekMapContent(filePath, content, { signal: options.signal });
-	throwIfAborted(options.signal);
-	return map;
-}

package/src/readseek/parser-errors.ts

@@ -1,19 +0,0 @@
-const emitted = new Set<string>();
-
-function causeMessage(err: unknown): string {
-  if (err instanceof Error) return err.message;
-  return String(err);
-}
-
-export function reportParserError(
-  onceKey: string,
-  err: unknown,
-  options: { context?: string } = {},
-): void {
-  if (!process.env.PI_READSEEK_DEBUG) return;
-  if (emitted.has(onceKey)) return;
-  emitted.add(onceKey);
-  const context = options.context ?? onceKey;
-  console.error(`[readseek] ${context}: ${causeMessage(err)}`);
-}
-

package/src/readseek/parser-loader.ts

@@ -1,78 +0,0 @@
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-import { Language, Parser } from "web-tree-sitter";
-import { reportParserError } from "./parser-errors.js";
-
-export type WasmLanguageId = "rust" | "cpp" | "c-header" | "java";
-export type WasmParser = Parser;
-
-const require_ = createRequire(import.meta.url);
-const wasmNames: Record<WasmLanguageId, string> = {
-  rust: "rust",
-  cpp: "cpp",
-  "c-header": "cpp",
-  java: "java",
-};
-let initPromise: Promise<void> | null = null;
-const languages = new Map<WasmLanguageId, Language>();
-const languageLoads = new Map<WasmLanguageId, Promise<Language | null>>();
-
-function isBun(): boolean {
-  return typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
-}
-
-function wasmPath(langId: WasmLanguageId): string {
-  const pkg = require_.resolve("tree-sitter-wasms/package.json");
-  return join(dirname(pkg), "out", `tree-sitter-${wasmNames[langId]}.wasm`);
-}
-
-async function init(): Promise<void> {
-  initPromise ??= Parser.init().catch((err: unknown) => {
-    initPromise = null;
-    reportParserError("wasm:init", err, { context: "web-tree-sitter initialization failed" });
-    throw err;
-  });
-  return initPromise;
-}
-
-async function language(langId: WasmLanguageId): Promise<Language | null> {
-  const loaded = languages.get(langId);
-  if (loaded) return loaded;
-
-  const inFlight = languageLoads.get(langId);
-  if (inFlight) return inFlight;
-
-  const loadPromise = (async () => {
-    try {
-      await init();
-      const lang = await Language.load(wasmPath(langId));
-      languages.set(langId, lang);
-      return lang;
-    } catch (err) {
-      reportParserError(`wasm:load:${langId}`, err, {
-        context: `tree-sitter WASM grammar load failed for ${langId}`,
-      });
-      return null;
-    } finally {
-      languageLoads.delete(langId);
-    }
-  })();
-
-  languageLoads.set(langId, loadPromise);
-  return loadPromise;
-}
-
-export async function getWasmParser(langId: WasmLanguageId): Promise<WasmParser | null> {
-  if (isBun()) return null;
-  const lang = await language(langId);
-  if (!lang) return null;
-  try {
-    const parser = new Parser();
-    parser.setLanguage(lang);
-    return parser;
-  } catch (err) {
-    reportParserError(`wasm:parser:${langId}`, err, { context: `tree-sitter WASM parser creation failed for ${langId}` });
-    return null;
-  }
-}
-