pi-readseek 0.1.0

package/src/readseek-value.ts

@@ -0,0 +1,144 @@
+import { computeLineHash, escapeControlCharsForDisplay } from "./hashline.js";
+import type { DiffData } from "./diff-data.js";
+
+export interface ReadseekLine {
+  line: number;
+  hash: string;
+  anchor: string;
+  raw: string;
+  display: string;
+}
+
+export interface ReadseekWarningSymbol {
+  name: string;
+  kind: string;
+  startLine: number;
+  endLine: number;
+  parentName?: string;
+}
+export interface ReadseekWarning {
+  code: string;
+  message: string;
+  tier?: "camelCase" | "substring";
+  symbol?: ReadseekWarningSymbol;
+  otherCandidates?: ReadseekWarningSymbol[];
+}
+
+export interface ReadseekError {
+  code: string;
+  message: string;
+  hint?: string;
+  details?: unknown;
+}
+
+export interface ReadseekRange {
+  startLine: number;
+  endLine: number;
+  totalLines?: number;
+}
+
+export interface ReadseekFileGroup {
+  path: string;
+  ranges: ReadseekRange[];
+  lines: ReadseekLine[];
+}
+
+export interface SemanticSummary {
+  classification: "no-op" | "whitespace-only" | "semantic" | "mixed";
+  difftasticAvailable: boolean;
+  movedBlocks?: number;
+}
+export interface ReadseekEditResult {
+  tool: "edit";
+  ok: boolean;
+  path: string;
+  summary: string;
+  diff: string;
+  diffData?: DiffData;
+  firstChangedLine: number | undefined;
+  warnings: string[];
+  noopEdits: unknown[];
+  semanticSummary?: SemanticSummary;
+}
+
+export function buildReadseekLine(line: number, raw: string): ReadseekLine {
+  const hash = computeLineHash(line, raw);
+  return {
+    line,
+    hash,
+    anchor: `${line}:${hash}`,
+    raw,
+    display: escapeControlCharsForDisplay(raw),
+  };
+}
+
+export function buildReadseekLines(startLine: number, rawLines: string[]): ReadseekLine[] {
+  return rawLines.map((raw, index) => buildReadseekLine(startLine + index, raw));
+}
+
+export function renderReadseekLine(line: ReadseekLine): string {
+  return `${line.anchor}|${line.display}`;
+}
+
+export function renderReadseekLines(lines: ReadseekLine[]): string {
+  return lines.map(renderReadseekLine).join("\n");
+}
+
+export function buildReadseekWarning(
+  code: string,
+  message: string,
+  metadata: Omit<ReadseekWarning, "code" | "message"> = {},
+): ReadseekWarning {
+  return { code, message, ...metadata };
+}
+
+export function buildReadseekError(
+  code: string,
+  message: string,
+  hint?: string,
+  details?: unknown,
+): ReadseekError {
+  return {
+    code,
+    message,
+    ...(hint !== undefined ? { hint } : {}),
+    ...(details !== undefined ? { details } : {}),
+  };
+}
+
+export function buildReadseekRange(startLine: number, endLine: number, totalLines?: number): ReadseekRange {
+  return totalLines === undefined ? { startLine, endLine } : { startLine, endLine, totalLines };
+}
+
+export function buildReadseekFileGroup(path: string, ranges: ReadseekRange[], lines: ReadseekLine[]): ReadseekFileGroup {
+  return {
+    path,
+    ranges: ranges.map((range) => ({ ...range })),
+    lines: lines.map((line) => ({ ...line })),
+  };
+}
+
+export function buildReadseekEditResult(input: {
+  ok?: boolean;
+  path: string;
+  summary: string;
+  diff: string;
+  diffData?: DiffData;
+  firstChangedLine: number | undefined;
+  warnings: string[];
+  noopEdits: unknown[];
+  semanticSummary?: SemanticSummary;
+}): ReadseekEditResult {
+  return {
+    tool: "edit",
+    ok: input.ok ?? true,
+    path: input.path,
+    summary: input.summary,
+    diff: input.diff,
+    ...(input.diffData ? { diffData: input.diffData } : {}),
+    firstChangedLine: input.firstChangedLine,
+    warnings: [...input.warnings],
+    noopEdits: [...input.noopEdits],
+    ...(input.semanticSummary ? { semanticSummary: input.semanticSummary } : {}),
+  };
+}

package/src/replace-symbol.ts

@@ -0,0 +1,74 @@
+import { generateMapFromContent } from "./readseek/mapper.js";
+import { findSymbol } from "./readseek/symbol-lookup.js";
+import { formatAmbiguous, formatNotFound } from "./readseek/symbol-error-format.js";
+
+export interface ReplaceSymbolInput {
+	filePath: string;
+	content: string;
+	symbol: string;
+	newBody: string;
+}
+
+export type ReplaceSymbolResult =
+	| { type: "ok"; content: string; replacement: string; warnings: string[]; range: { start: number; end: number } }
+	| { type: "not-found"; message: string }
+	| { type: "ambiguous"; message: string }
+	| { type: "unsupported"; message: string };
+
+function detectIndent(line: string): string {
+	return line.match(/^\s*/)?.[0] ?? "";
+}
+
+function dedent(text: string): string {
+	const lines = text.split("\n");
+	const nonEmpty = lines.filter((l) => l.trim().length);
+	if (!nonEmpty.length) return text;
+	const minIndent = Math.min(...nonEmpty.map((l) => l.match(/^\s*/)?.[0].length ?? 0));
+	return lines.map((l) => l.slice(minIndent)).join("\n");
+}
+
+function reindent(text: string, indent: string): string {
+	return text.split("\n").map((l) => (l.length ? indent + l : l)).join("\n");
+}
+
+export async function replaceSymbol(input: ReplaceSymbolInput): Promise<ReplaceSymbolResult> {
+	const map = await generateMapFromContent(input.filePath, input.content);
+	if (!map) {
+		return {
+			type: "unsupported",
+			message: `Unsupported file for replace_symbol: readseek could not map '${input.filePath}'. Use anchored edits for this file type.`,
+		};
+	}
+	const lookup = findSymbol(map, input.symbol);
+	if (lookup.type === "not-found") {
+		return { type: "not-found", message: formatNotFound(input.symbol, map) };
+	}
+	if (lookup.type === "ambiguous") {
+		return { type: "ambiguous", message: formatAmbiguous(input.symbol, lookup.candidates) };
+	}
+	const sym = lookup.symbol;
+	const lines = input.content.split("\n");
+	const sigLine = lines[sym.startLine - 1] ?? "";
+	const indent = detectIndent(sigLine);
+	const reindented = reindent(dedent(input.newBody), indent);
+	const warnings: string[] = [];
+	const leaf = input.symbol.replace(/@\d+$/, "").split(".").pop() ?? "";
+	const firstDeclName =
+		reindented.match(/\b(?:function|class|method|const|let|var)\s+([A-Za-z_$][\w$]*)/)?.[1]
+		?? reindented.match(/^\s*(?:[\w$<>,?\s]+\s+)?([A-Za-z_$][\w$]*)\s*\(/)?.[1];
+	if (leaf && firstDeclName && firstDeclName !== leaf) {
+		warnings.push(`name-mismatch: expected ${leaf}, got ${firstDeclName}`);
+	}
+	const before = lines.slice(0, sym.startLine - 1).join("\n");
+	const after = lines.slice(sym.endLine).join("\n");
+	const beforePart = before.length ? before + "\n" : "";
+	const afterPart = after.length ? "\n" + after : "";
+	const newContent = beforePart + reindented + afterPart;
+	return {
+		type: "ok",
+		content: newContent,
+		replacement: reindented,
+		warnings,
+		range: { start: sym.startLine, end: sym.endLine },
+	};
+}

package/src/runtime.ts

@@ -0,0 +1,3 @@
+export function throwIfAborted(signal?: AbortSignal): void {
+	if (signal?.aborted) throw new Error("Operation aborted");
+}

package/src/sg-output.ts

@@ -0,0 +1,88 @@
+import type { ReadseekLine, ReadseekRange } from "./readseek-value.js";
+import {
+  buildContextHygieneMetadata,
+  buildFileResource,
+  buildSymbolResource,
+  type ContextHygieneMetadata,
+  type ContextHygieneRehydrateDescriptor,
+  type ContextHygieneResource,
+} from "./context-hygiene.js";
+
+export interface SgOutputFile {
+  displayPath: string;
+  path: string;
+  ranges: ReadseekRange[];
+  lines: ReadseekLine[];
+  symbols?: Array<{ name: string; kind?: string }>;
+}
+
+export interface BuildSgOutputInput {
+  pattern: string;
+  files: SgOutputFile[];
+  rehydrate?: ContextHygieneRehydrateDescriptor | null;
+}
+
+export interface SgOutputResult {
+  text: string;
+  readseekValue: {
+    tool: "search";
+    files: Array<{
+      path: string;
+      ranges: ReadseekRange[];
+      lines: ReadseekLine[];
+    }>;
+  };
+  contextHygiene: ContextHygieneMetadata;
+}
+
+export function buildSgOutput(input: BuildSgOutputInput): SgOutputResult {
+  if (input.files.length === 0) {
+    return {
+      text: `No matches found for pattern: ${input.pattern}`,
+      readseekValue: {
+        tool: "search",
+        files: [],
+      },
+      contextHygiene: buildContextHygieneMetadata({
+        tool: "search",
+        classification: "search-context",
+        resources: [],
+        rehydrate: input.rehydrate ?? undefined,
+      }),
+    };
+  }
+
+  const blocks: string[] = [];
+  for (const file of input.files) {
+    blocks.push(`--- ${file.displayPath} ---`);
+    for (const line of file.lines) {
+      blocks.push(`>>${line.anchor}|${line.display}`);
+    }
+  }
+
+  const contextHygieneResources: ContextHygieneResource[] = [];
+  for (const file of input.files) {
+    contextHygieneResources.push(buildFileResource(file.path));
+    for (const symbol of file.symbols ?? []) {
+      contextHygieneResources.push(buildSymbolResource(file.path, symbol.name, symbol.kind));
+    }
+  }
+
+  return {
+    text: blocks.join("\n"),
+    readseekValue: {
+      tool: "search",
+      files: input.files.map((file) => ({
+        path: file.path,
+        ranges: file.ranges.map((range) => ({ ...range })),
+        lines: file.lines.map((line) => ({ ...line })),
+      })),
+    },
+    contextHygiene: buildContextHygieneMetadata({
+      tool: "search",
+      classification: "search-context",
+      resources: contextHygieneResources,
+      rehydrate: input.rehydrate ?? undefined,
+    }),
+  };
+}

package/src/sg.ts

@@ -0,0 +1,308 @@
+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 { ensureHashInit } from "./hashline.js";
+import { buildReadseekError, buildReadseekLine, type ReadseekLine } from "./readseek-value.js";
+import { resolveToCwd } from "./path-utils.js";
+import { isReadseekAvailable, readseekSearch, type ReadseekSearchFileOutput } from "./readseek-client.js";
+import { buildSgOutput } from "./sg-output.js";
+import { buildSearchRehydrateDescriptor } from "./context-hygiene.js";
+import { clampLineToWidth, clampLinesToWidth, isRendererExpanded, renderToolLabel, summaryLine } from "./tui-render-utils.js";
+
+type SgParams = { pattern: string; lang?: string; path?: string };
+
+export interface SgRange {
+  startLine: number;
+  endLine: number;
+}
+
+export interface SgEnclosingSymbol {
+  name: string;
+  kind: string;
+}
+
+export function mergeRanges(ranges: SgRange[]): SgRange[] {
+  if (ranges.length === 0) return [];
+  if (ranges.length === 1) return [{ ...ranges[0] }];
+
+  const sorted = [...ranges].sort((a, b) => a.startLine - b.startLine);
+  const merged: SgRange[] = [{ ...sorted[0] }];
+
+  for (let i = 1; i < sorted.length; i++) {
+    const current = sorted[i];
+    const last = merged[merged.length - 1];
+    if (current.startLine <= last.endLine + 2) {
+      last.endLine = Math.max(last.endLine, current.endLine);
+    } else {
+      merged.push({ ...current });
+    }
+  }
+
+  return merged;
+}
+
+const SG_PROMPT_METADATA = defineToolPromptMetadata({
+  promptUrl: new URL("../prompts/sg.md", import.meta.url),
+  promptSnippet: "Search code structurally with readseek and return edit-ready anchors",
+  promptGuidelines: [
+    "Use search when text search is too broad or brittle and the query depends on code shape.",
+    "Use search for calls, imports, declarations, JSX, and similar syntax patterns.",
+    "Use grep instead of search for plain text search.",
+  ],
+});
+
+export function isSgAvailable(): boolean {
+  return isReadseekAvailable();
+}
+
+interface SgToolOptions {
+  onFileAnchored?: (absolutePath: string) => void;
+}
+
+function readseekLineFromSearch(line: { line: number; text: string }): ReadseekLine {
+  return buildReadseekLine(line.line, line.text);
+}
+
+function linesFromSearchResult(result: ReadseekSearchFileOutput, ranges: SgRange[]): ReadseekLine[] {
+  const lineMap = new Map<number, ReadseekLine>();
+  for (const match of result.matches) {
+    for (const line of match.hashlines) {
+      lineMap.set(line.line, readseekLineFromSearch(line));
+    }
+  }
+
+  const lines: ReadseekLine[] = [];
+  const seen = new Set<number>();
+  for (const range of ranges) {
+    for (let line = range.startLine; line <= range.endLine; line++) {
+      if (seen.has(line)) continue;
+      const readseekLine = lineMap.get(line);
+      if (!readseekLine) continue;
+      seen.add(line);
+      lines.push(readseekLine);
+    }
+  }
+  return lines;
+}
+
+function readseekLanguageForPath(language: string | undefined, searchPath: string, isFile: boolean): string | undefined {
+  if (language === "typescript" && isFile && path.extname(searchPath).toLowerCase() === ".tsx") return "tsx";
+  return language;
+}
+
+export function registerSgTool(pi: ExtensionAPI, options: SgToolOptions = {}) {
+  const toolConfig = {
+    callable: true,
+    enabled: true,
+    policy: "read-only" as const,
+    readOnly: true,
+    pythonName: "search",
+    defaultExposure: "opt-in" as const,
+  };
+
+  const tool = {
+    name: "search",
+    label: "Structural Search",
+    description: SG_PROMPT_METADATA.description,
+    promptSnippet: SG_PROMPT_METADATA.promptSnippet,
+    promptGuidelines: SG_PROMPT_METADATA.promptGuidelines,
+    parameters: Type.Object({
+      pattern: Type.String({ description: "AST pattern" }),
+      lang: Type.Optional(Type.String({ description: "Language hint" })),
+      path: Type.Optional(Type.String({ description: "Search path" })),
+    }),
+    ptc: toolConfig,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      await ensureHashInit();
+      const p = params as SgParams;
+      const rehydrate = buildSearchRehydrateDescriptor({
+        pattern: p.pattern,
+        lang: p.lang,
+        path: p.path,
+      });
+
+      const searchPath = resolveToCwd(p.path ?? ".", ctx.cwd);
+      let searchPathIsFile = false;
+
+      try {
+        const stat = await fsStat(searchPath);
+        searchPathIsFile = stat.isFile();
+      } catch (err: any) {
+        if (err?.code === "ENOENT") {
+          const message = `Error: path '${p.path ?? "."}' does not exist`;
+          return {
+            content: [{ type: "text", text: message }],
+            isError: true,
+            details: {
+              readseekValue: {
+                tool: "search",
+                ok: false,
+                path: p.path ?? searchPath,
+                error: buildReadseekError("path-not-found", message),
+              },
+            },
+          };
+        }
+        if (err?.code === "EACCES" || err?.code === "EPERM") {
+          const message = `Error: permission denied for path '${p.path ?? "."}'`;
+          return {
+            content: [{ type: "text", text: message }],
+            isError: true,
+            details: {
+              readseekValue: {
+                tool: "search",
+                ok: false,
+                path: p.path ?? searchPath,
+                error: buildReadseekError("permission-denied", message),
+              },
+            },
+          };
+        }
+        const message = `Error: could not access path '${p.path ?? "."}': ${err?.message ?? String(err)}`;
+        return {
+          content: [{ type: "text", text: message }],
+          isError: true,
+          details: {
+            readseekValue: {
+              tool: "search",
+              ok: false,
+              path: p.path ?? searchPath,
+              error: buildReadseekError("fs-error", message, undefined, { fsCode: err?.code, fsMessage: err?.message }),
+            },
+          },
+        };
+      }
+
+      try {
+        const effectiveLang = readseekLanguageForPath(p.lang, searchPath, searchPathIsFile);
+        const results = await readseekSearch(searchPath, p.pattern, effectiveLang, signal);
+        if (results.length === 0) {
+          const emptyOutput = buildSgOutput({ pattern: p.pattern, files: [], rehydrate });
+          return {
+            content: [{ type: "text", text: emptyOutput.text }],
+            details: {
+              readseekValue: emptyOutput.readseekValue,
+              contextHygiene: emptyOutput.contextHygiene,
+            },
+          };
+        }
+
+        const readseekFiles: Array<{
+          displayPath: string;
+          path: string;
+          ranges: SgRange[];
+          lines: ReadseekLine[];
+          symbols?: SgEnclosingSymbol[];
+        }> = [];
+
+        for (const result of results) {
+          const abs = path.isAbsolute(result.file) ? result.file : path.resolve(ctx.cwd, result.file);
+          const display = path.relative(ctx.cwd, abs) || abs;
+          const ranges = result.matches.map((match) => ({ startLine: match.start_line, endLine: match.end_line }));
+          const mergedRanges = mergeRanges(ranges);
+          const lines = linesFromSearchResult(result, mergedRanges);
+          if (lines.length === 0) continue;
+          readseekFiles.push({
+            displayPath: display,
+            path: abs,
+            ranges: mergedRanges.map((range) => ({ ...range })),
+            lines,
+          });
+        }
+
+        if (readseekFiles.length === 0) {
+          const emptyOutput = buildSgOutput({ pattern: p.pattern, files: [], rehydrate });
+          return {
+            content: [{ type: "text", text: emptyOutput.text }],
+            details: {
+              readseekValue: emptyOutput.readseekValue,
+              contextHygiene: emptyOutput.contextHygiene,
+            },
+          };
+        }
+
+        const builtOutput = buildSgOutput({
+          pattern: p.pattern,
+          files: readseekFiles,
+          rehydrate,
+        });
+        for (const readseekFile of readseekFiles) {
+          options.onFileAnchored?.(readseekFile.path);
+        }
+        return {
+          content: [{ type: "text", text: builtOutput.text }],
+          details: {
+            readseekValue: builtOutput.readseekValue,
+            contextHygiene: builtOutput.contextHygiene,
+          },
+        };
+      } 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 {
+          content: [{ type: "text", text: message }],
+          isError: true,
+          details: {
+            readseekValue: {
+              tool: "search",
+              ok: false,
+              error: missingReadseek
+                ? buildReadseekError("readseek-not-installed", message, "Run npm install to install @jarkkojs/readseek.")
+                : buildReadseekError("readseek-execution-error", message),
+            },
+          },
+        };
+      }
+    },
+    renderCall(args: any, theme: any, ...rest: any[]) {
+      const context = rest[0] ?? {};
+      let text = `${renderToolLabel(theme, "search")} ${theme.fg("accent", `/${args.pattern}/`)}`;
+      text += theme.fg("dim", ` in ${args.path ?? "."}`);
+      if (args.lang) text += theme.fg("dim", ` (${args.lang})`);
+      return new Text(clampLineToWidth(text, context.width), 0, 0);
+    },
+    renderResult(result: any, options: ToolRenderResultOptions, theme: any, ...rest: any[]) {
+      const context: { isPartial?: boolean; isError?: boolean; expanded?: boolean; cwd?: string; width?: number } =
+        rest[0] ?? options ?? {};
+      const isPartial = context.isPartial ?? (options as any)?.isPartial ?? false;
+      const isError = context.isError ?? false;
+      const expanded = isRendererExpanded(options as any, context as any);
+      const cwd = context.cwd ?? process.cwd();
+      const width = (context as any).width ?? (options as any)?.width;
+
+      if (isPartial) return new Text(clampLinesToWidth([summaryLine("pending search")], 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: "search"; files: Array<{ path: string; lines: any[] }> }
+        | undefined;
+      const files = readseekValue?.files ?? [];
+      if (files.length === 0) return new Text(summaryLine("no matches"), 0, 0);
+      const fileCount = files.length;
+      const totalMatches = files.reduce((sum: number, f: any) => sum + f.lines.length, 0);
+      const matchWord = totalMatches === 1 ? "match" : "matches";
+      const fileWord = fileCount === 1 ? "file" : "files";
+      let text = summaryLine(`${totalMatches} ${matchWord} in ${fileCount} ${fileWord}`, { hidden: files.length > 0 && !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/syntax-validate-mode.ts

@@ -0,0 +1,25 @@
+export type SyntaxValidateMode = "warn" | "block" | "off";
+
+export interface SyntaxValidateOptions {
+  syntaxValidate?: SyntaxValidateMode;
+}
+
+const VALID = new Set<SyntaxValidateMode>(["warn", "block", "off"]);
+const DEFAULT: SyntaxValidateMode = "warn";
+
+function coerce(value: unknown): SyntaxValidateMode | undefined {
+  if (typeof value !== "string") return undefined;
+  return VALID.has(value as SyntaxValidateMode)
+    ? (value as SyntaxValidateMode)
+    : undefined;
+}
+
+export function resolveSyntaxValidateMode(
+  opts: SyntaxValidateOptions,
+): SyntaxValidateMode {
+  const fromOpt = coerce(opts.syntaxValidate);
+  if (fromOpt) return fromOpt;
+  const fromEnv = coerce(process.env.PI_HASHLINE_SYNTAX_VALIDATE);
+  if (fromEnv) return fromEnv;
+  return DEFAULT;
+}