pi-readseek 0.1.0

package/src/grep-output.ts

@@ -0,0 +1,197 @@
+import type { ReadseekLine, ReadseekWarning } from "./readseek-value.js";
+import {
+  formatSize,
+  truncateHead,
+} from "@earendil-works/pi-coding-agent";
+import { resolveGrepOutputBudget } from "./grep-budget.js";
+import {
+  buildContextHygieneMetadata,
+  buildFileResource,
+  buildSymbolResource,
+  type ContextHygieneMetadata,
+  type ContextHygieneRehydrateDescriptor,
+  type ContextHygieneResource,
+} from "./context-hygiene.js";
+
+export interface GrepOutputRecord extends ReadseekLine {
+  path: string;
+  kind: "match" | "context";
+}
+
+export interface GrepOutputReadseekRecord {
+  path: string;
+  line: number;
+  anchor: string;
+  kind: "match" | "context";
+}
+
+export type GrepOutputEntry =
+  | { kind: "match" | "context"; line: ReadseekLine }
+  | { kind: "separator"; text: string };
+
+export interface GrepOutputScopeSymbol {
+  name: string;
+  kind: string;
+  startLine: number;
+  endLine: number;
+  parentName?: string;
+}
+
+export interface GrepScopeWarning extends ReadseekWarning {
+  path?: string;
+  line?: number;
+}
+
+export interface GrepOutputGroup {
+  displayPath: string;
+  absolutePath: string;
+  matchCount: number;
+  entries: GrepOutputEntry[];
+  scope?: {
+    mode: "symbol";
+    symbol: GrepOutputScopeSymbol;
+    matchLines: number[];
+    contextLines?: number;
+  };
+}
+
+export interface BuildGrepOutputInput {
+  summary: boolean;
+  totalMatches: number;
+  groups: GrepOutputGroup[];
+  limit?: number;
+  records: GrepOutputRecord[];
+  scopeMode?: "symbol";
+  scopeWarnings?: GrepScopeWarning[];
+  passthroughLines?: string[];
+  rehydrate?: ContextHygieneRehydrateDescriptor | null;
+}
+
+export interface GrepOutputResult {
+  text: string;
+  readseekValue: {
+    tool: "grep";
+    summary: boolean;
+    totalMatches: number;
+    records: GrepOutputReadseekRecord[];
+    scopes?: {
+      mode: "symbol";
+      groups: Array<{
+        path: string;
+        displayPath: string;
+        symbol: GrepOutputScopeSymbol;
+        matchCount: number;
+        matchLines: number[];
+        lineAnchors: string[];
+      }>;
+      warnings: GrepScopeWarning[];
+    };
+  };
+  contextHygiene: ContextHygieneMetadata;
+}
+
+function renderEntry(displayPath: string, entry: GrepOutputEntry): string {
+  if (entry.kind === "separator") return entry.text;
+  const marker = entry.kind === "match" ? ">>" : "  ";
+  return `${displayPath}:${marker}${entry.line.anchor}|${entry.line.display}`;
+}
+
+function renderGroupHeader(group: GrepOutputGroup): string {
+  if (!group.scope) {
+    return `--- ${group.displayPath} (${group.matchCount} matches) ---`;
+  }
+
+  const parent = group.scope.symbol.parentName ? ` in ${group.scope.symbol.parentName}` : "";
+  const suffix = group.scope.contextLines !== undefined ? `, scoped to ±${group.scope.contextLines} lines` : "";
+  return `--- ${group.displayPath} :: ${group.scope.symbol.kind} ${group.scope.symbol.name}${parent} (${group.scope.symbol.startLine}-${group.scope.symbol.endLine}, ${group.matchCount} matches${suffix}) ---`;
+}
+
+function buildScopeMetadata(groups: GrepOutputGroup[], warnings: GrepScopeWarning[]) {
+  return {
+    mode: "symbol" as const,
+    groups: groups
+      .filter((group) => group.scope)
+      .map((group) => ({
+        path: group.absolutePath,
+        displayPath: group.displayPath,
+        symbol: group.scope!.symbol,
+        matchCount: group.matchCount,
+        matchLines: [...group.scope!.matchLines],
+        lineAnchors: group.entries.flatMap((entry) => (entry.kind === "separator" ? [] : [entry.line.anchor])),
+      })),
+    warnings: [...warnings],
+  };
+}
+
+export function buildGrepOutput(input: BuildGrepOutputInput): GrepOutputResult {
+  const fileCount = new Set(input.groups.map((group) => group.absolutePath)).size;
+  const header = `[${input.totalMatches} matches in ${fileCount} files]`;
+  let text: string;
+  if (input.summary) {
+    const fileLines = [...input.groups]
+      .sort((a, b) => b.matchCount - a.matchCount)
+      .map((group) => `${group.absolutePath}: ${group.matchCount} matches`);
+    text = [header, ...fileLines].join("\n");
+  } else {
+    const blocks: string[] = [header];
+    for (const group of input.groups) {
+      blocks.push(renderGroupHeader(group));
+      for (const entry of group.entries) {
+        blocks.push(renderEntry(group.displayPath, entry));
+      }
+    }
+    text = blocks.join("\n");
+  }
+  if ((input.passthroughLines?.length ?? 0) > 0) {
+    text += `\n\n${input.passthroughLines!.join("\n")}`;
+  }
+  if (input.limit !== undefined && input.totalMatches === input.limit) {
+    text += `\n\n[Results truncated at ${input.limit} matches — refine pattern or increase limit]`;
+  }
+  if (!input.summary && input.scopeMode === "symbol" && (input.scopeWarnings?.length ?? 0) > 0) {
+    text = `${input.scopeWarnings!.map((warning) => warning.message).join("\n\n")}\n\n${text}`;
+  }
+  const budget = resolveGrepOutputBudget();
+  const truncated = truncateHead(text, {
+    maxLines: budget.maxLines,
+    maxBytes: budget.maxBytes,
+  });
+  if (truncated.truncated) {
+    text = `${truncated.content}\n\n[Output truncated: showing ${truncated.outputLines} of ${truncated.totalLines} lines (${formatSize(truncated.outputBytes)} of ${formatSize(truncated.totalBytes)}). Refine pattern or increase limit.]`;
+  }
+  const readseekValue: GrepOutputResult["readseekValue"] = {
+    tool: "grep",
+    summary: input.summary,
+    totalMatches: input.totalMatches,
+    records: input.records.map((record) => ({
+      path: record.path,
+      line: record.line,
+      anchor: record.anchor,
+      kind: record.kind,
+    })),
+  };
+  if (!input.summary && input.scopeMode === "symbol") {
+    readseekValue.scopes = buildScopeMetadata(input.groups, input.scopeWarnings ?? []);
+  }
+
+  const contextHygieneResources: ContextHygieneResource[] = [];
+  for (const record of input.records) {
+    contextHygieneResources.push(buildFileResource(record.path));
+  }
+  for (const group of input.groups) {
+    if (!group.scope) continue;
+    contextHygieneResources.push(buildFileResource(group.absolutePath));
+    contextHygieneResources.push(buildSymbolResource(group.absolutePath, group.scope.symbol.name, group.scope.symbol.kind));
+  }
+  const contextHygiene = buildContextHygieneMetadata({
+    tool: "grep",
+    classification: "search-context",
+    resources: contextHygieneResources,
+    rehydrate: input.rehydrate ?? undefined,
+  });
+  return {
+    text,
+    readseekValue,
+    contextHygiene,
+  };
+}

package/src/grep-render-helpers.ts

@@ -0,0 +1,77 @@
+export interface GrepCallTextResult {
+  pattern: string;
+  suffix: string | undefined;
+}
+
+export function formatGrepCallText(
+  args: Record<string, unknown> | undefined,
+): GrepCallTextResult {
+  const pattern = typeof args?.pattern === "string" ? args.pattern : "";
+
+  const parts: string[] = [];
+  if (typeof args?.path === "string" && args.path !== ".") {
+    parts.push(args.path as string);
+  }
+  if (typeof args?.glob === "string") {
+    parts.push(args.glob as string);
+  }
+
+  return {
+    pattern,
+    suffix: parts.length > 0 ? parts.join(" ") : undefined,
+  };
+}
+
+const GREP_TRUNCATION_THRESHOLD = 50;
+
+export interface GrepResultTextInput {
+  totalMatches: number;
+  summary: boolean;
+  records: unknown[];
+  fileCount: number;
+  hasBinaryWarning?: boolean;
+  isError?: boolean;
+  errorText?: string;
+}
+
+export interface GrepResultTextOutput {
+  summary: string;
+  badges: string[];
+  noMatches: boolean;
+  truncated: boolean;
+  errorText: string | undefined;
+}
+
+export function formatGrepResultText(input: GrepResultTextInput): GrepResultTextOutput {
+  // Error case
+  if (input.isError && input.errorText) {
+    return {
+      summary: "",
+      badges: [],
+      noMatches: false,
+      truncated: false,
+      errorText: input.errorText,
+    };
+  }
+
+  const { totalMatches, summary, fileCount } = input;
+  const noMatches = totalMatches === 0;
+  const truncated = totalMatches >= GREP_TRUNCATION_THRESHOLD;
+
+  const matchWord = totalMatches === 1 ? "match" : "matches";
+  const fileWord = fileCount === 1 ? "file" : "files";
+  const summaryText = noMatches ? "" : `\u2713 ${totalMatches} ${matchWord} in ${fileCount} ${fileWord}`;
+
+  const badges: string[] = [];
+  if (truncated) badges.push("10/file cap");
+  if (summary) badges.push("summary");
+  if (input.hasBinaryWarning) badges.push("\u26a0 binary");
+
+  return {
+    summary: summaryText,
+    badges,
+    noMatches,
+    truncated,
+    errorText: undefined,
+  };
+}

package/src/grep-symbol-scope.ts

@@ -0,0 +1,197 @@
+import { buildReadseekLine } from "./readseek-value.js";
+import type { GrepOutputEntry, GrepOutputGroup, GrepOutputScopeSymbol, GrepScopeWarning } from "./grep-output.js";
+import type { FileMap, FileSymbol } from "./readseek/types.js";
+
+interface FlatSymbol extends GrepOutputScopeSymbol {
+  rangeSize: number;
+}
+
+function flattenSymbols(symbols: FileSymbol[], parentName?: string): FlatSymbol[] {
+  const flattened: FlatSymbol[] = [];
+  for (const symbol of symbols) {
+    flattened.push({
+      name: symbol.name,
+      kind: symbol.kind,
+      startLine: symbol.startLine,
+      endLine: symbol.endLine,
+      parentName,
+      rangeSize: symbol.endLine - symbol.startLine,
+    });
+    if (symbol.children?.length) flattened.push(...flattenSymbols(symbol.children, symbol.name));
+  }
+  return flattened;
+}
+
+function findEnclosingSymbol(map: FileMap, lineNumber: number): GrepOutputScopeSymbol | null {
+  const candidates = flattenSymbols(map.symbols)
+    .filter((s) => lineNumber >= s.startLine && lineNumber <= s.endLine)
+    .sort((a, b) => {
+      if (a.rangeSize !== b.rangeSize) return a.rangeSize - b.rangeSize;
+      if (a.startLine !== b.startLine) return a.startLine - b.startLine;
+      return a.name.localeCompare(b.name);
+    });
+  if (!candidates.length) return null;
+  const { rangeSize: _rangeSize, ...symbol } = candidates[0];
+  return symbol;
+}
+
+function firstLineNumber(group: GrepOutputGroup): number {
+  const first = group.entries.find((e) => e.kind !== "separator");
+  return first ? first.line.line : Number.MAX_SAFE_INTEGER;
+}
+
+function buildSymbolEntries(
+  fileLines: string[],
+  symbol: GrepOutputScopeSymbol,
+  matchLines: Set<number>,
+  scopeContext: number | undefined,
+): GrepOutputEntry[] {
+  if (scopeContext === undefined) {
+    const entries: GrepOutputEntry[] = [];
+    for (let lineNumber = symbol.startLine; lineNumber <= symbol.endLine; lineNumber++) {
+      const built = buildReadseekLine(lineNumber, fileLines[lineNumber - 1] ?? "");
+      entries.push({ kind: matchLines.has(lineNumber) ? "match" : "context", line: built });
+    }
+    return entries;
+  }
+  // Windowed path: ±scopeContext lines, clipped, merged, with '--' separators between non-overlapping ranges.
+  const ranges = [...matchLines].sort((a, b) => a - b).map((ln) => ({
+    startLine: Math.max(symbol.startLine, ln - scopeContext),
+    endLine: Math.min(symbol.endLine, ln + scopeContext),
+  }));
+  const merged: Array<{ startLine: number; endLine: number }> = [];
+  for (const r of ranges) {
+    const last = merged[merged.length - 1];
+    if (last && r.startLine <= last.endLine + 1) {
+      last.endLine = Math.max(last.endLine, r.endLine);
+    } else {
+      merged.push({ ...r });
+    }
+  }
+  const entries: GrepOutputEntry[] = [];
+  for (let i = 0; i < merged.length; i++) {
+    if (i > 0) entries.push({ kind: "separator", text: "--" });
+    const range = merged[i];
+    for (let ln = range.startLine; ln <= range.endLine; ln++) {
+      const built = buildReadseekLine(ln, fileLines[ln - 1] ?? "");
+      entries.push({ kind: matchLines.has(ln) ? "match" : "context", line: built });
+    }
+  }
+  return entries;
+}
+
+function buildFallbackEntries(fileLines: string[], matchLines: number[], contextLines: number): GrepOutputEntry[] {
+  const lineMap = new Map<number, GrepOutputEntry>();
+  for (const matchLine of matchLines) {
+    const start = Math.max(1, matchLine - contextLines);
+    const end = Math.min(fileLines.length, matchLine + contextLines);
+    for (let lineNumber = start; lineNumber <= end; lineNumber++) {
+      const built = buildReadseekLine(lineNumber, fileLines[lineNumber - 1] ?? "");
+      const candidate: GrepOutputEntry = { kind: lineNumber === matchLine ? "match" : "context", line: built };
+      const existing = lineMap.get(lineNumber);
+      if (!existing || (existing.kind === "context" && candidate.kind === "match")) {
+        lineMap.set(lineNumber, candidate);
+      }
+    }
+  }
+  const ordered = [...lineMap.entries()].sort(([a], [b]) => a - b);
+  const entries: GrepOutputEntry[] = [];
+  for (let i = 0; i < ordered.length; i++) {
+    if (i > 0 && ordered[i][0] > ordered[i - 1][0] + 1) entries.push({ kind: "separator", text: "--" });
+    entries.push(ordered[i][1]);
+  }
+  return entries;
+}
+
+export function scopeGrepGroupsToSymbols(input: {
+  groups: GrepOutputGroup[];
+  fileLinesByPath: Map<string, string[]>;
+  fileMapsByPath: Map<string, FileMap | null>;
+  contextLines: number;
+  scopeContext?: number;
+}): { groups: GrepOutputGroup[]; warnings: GrepScopeWarning[] } {
+  const warnings: GrepScopeWarning[] = [];
+  const rendered: Array<{ order: number; group: GrepOutputGroup }> = [];
+
+  for (const group of input.groups) {
+    const fileLines = input.fileLinesByPath.get(group.absolutePath);
+    const fileMap = input.fileMapsByPath.get(group.absolutePath) ?? null;
+
+    if (!fileLines || !fileMap) {
+      warnings.push({
+        code: "unmappable-file",
+        message: `[Warning: symbol scoping unavailable for ${group.absolutePath} — showing normal grep lines for this file]`,
+        path: group.absolutePath,
+      });
+      rendered.push({ order: firstLineNumber(group), group });
+      continue;
+    }
+
+    const symbolBuckets = new Map<string, { symbol: GrepOutputScopeSymbol; matchLines: Set<number> }>();
+    const fallbackMatchLines: number[] = [];
+
+    for (const entry of group.entries) {
+      if (entry.kind !== "match") continue;
+      const symbol = findEnclosingSymbol(fileMap, entry.line.line);
+      if (!symbol) {
+        fallbackMatchLines.push(entry.line.line);
+        warnings.push({
+          code: "no-enclosing-symbol",
+          message: `[Warning: no enclosing symbol for ${group.absolutePath}:${entry.line.line} — showing normal grep lines for this match]`,
+          path: group.absolutePath,
+          line: entry.line.line,
+        });
+        continue;
+      }
+
+      const key = `${symbol.startLine}:${symbol.endLine}:${symbol.parentName ?? ""}:${symbol.name}`;
+      const bucket = symbolBuckets.get(key) ?? { symbol, matchLines: new Set<number>() };
+      bucket.matchLines.add(entry.line.line);
+      symbolBuckets.set(key, bucket);
+    }
+
+    const scopedGroups = [...symbolBuckets.values()]
+      .sort((a, b) => {
+        if (a.symbol.startLine !== b.symbol.startLine) return a.symbol.startLine - b.symbol.startLine;
+        return a.symbol.name.localeCompare(b.symbol.name);
+      })
+      .map(({ symbol, matchLines }) => ({
+        displayPath: group.displayPath,
+        absolutePath: group.absolutePath,
+        matchCount: matchLines.size,
+        scope: {
+          mode: "symbol" as const,
+          symbol,
+          matchLines: [...matchLines].sort((a, b) => a - b),
+          ...(input.scopeContext !== undefined ? { contextLines: input.scopeContext } : {}),
+        },
+        entries: buildSymbolEntries(fileLines, symbol, matchLines, input.scopeContext),
+      }));
+
+    for (const scopedGroup of scopedGroups) rendered.push({ order: scopedGroup.scope!.symbol.startLine, group: scopedGroup });
+
+    if (fallbackMatchLines.length > 0) {
+      rendered.push({
+        order: Math.min(...fallbackMatchLines),
+        group: {
+          displayPath: group.displayPath,
+          absolutePath: group.absolutePath,
+          matchCount: fallbackMatchLines.length,
+          entries: buildFallbackEntries(fileLines, fallbackMatchLines, input.contextLines),
+        },
+      });
+    }
+
+    if (scopedGroups.length === 0 && fallbackMatchLines.length === 0) {
+      rendered.push({ order: firstLineNumber(group), group });
+    }
+  }
+
+  rendered.sort((a, b) => {
+    if (a.order !== b.order) return a.order - b.order;
+    if (a.group.absolutePath !== b.group.absolutePath) return a.group.absolutePath.localeCompare(b.group.absolutePath);
+    return a.group.displayPath.localeCompare(b.group.displayPath);
+  });
+
+  return { groups: rendered.map((item) => item.group), warnings };
+}