pi-readseek 0.1.0

package/src/read-output.ts

@@ -0,0 +1,212 @@
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+  truncateHead,
+} from "@earendil-works/pi-coding-agent";
+import { buildReadseekLines, renderReadseekLines, type ReadseekLine, type ReadseekWarning } from "./readseek-value.js";
+import {
+  buildContextHygieneMetadata,
+  buildFileResource,
+  buildSymbolResource,
+  type ContextHygieneMetadata,
+  type ContextHygieneRehydrateDescriptor,
+  type ContextHygieneResource,
+} from "./context-hygiene.js";
+
+export interface ReadSymbolMetadata {
+  query: string;
+  name: string;
+  kind: string;
+  parentName?: string;
+  startLine: number;
+  endLine: number;
+}
+
+export interface ReadTruncationMetadata {
+  outputLines: number;
+  totalLines: number;
+  outputBytes: number;
+  totalBytes: number;
+}
+
+export interface ReadMapMetadata {
+  requested: boolean;
+  appended: boolean;
+  text?: string | null;
+}
+
+export interface ReadContinuationMetadata {
+  nextOffset: number;
+}
+
+export interface ReadBundleSupportItem {
+  symbol: ReadSymbolMetadata;
+  lines: string[];
+}
+
+export interface ReadBundleMetadata {
+  mode: "local";
+  applied: boolean;
+  localSupport: ReadBundleSupportItem[];
+  warnings?: ReadseekWarning[];
+}
+
+export interface ReadOutputInput {
+  path: string;
+  startLine: number;
+  endLine: number;
+  totalLines: number;
+  selectedLines?: string[];
+  lines?: ReadseekLine[];
+  warnings?: ReadseekWarning[];
+  truncation?: ReadTruncationMetadata | null;
+  continuation?: ReadContinuationMetadata | null;
+  symbol?: ReadSymbolMetadata | null;
+  map?: ReadMapMetadata;
+  bundle?: ReadBundleMetadata | null;
+  rehydrate?: ContextHygieneRehydrateDescriptor | null;
+}
+
+export interface ReadOutputResult {
+  text: string;
+  lines: ReadseekLine[];
+  readseekValue: {
+    tool: "read";
+    path: string;
+    range: {
+      startLine: number;
+      endLine: number;
+      totalLines: number;
+    };
+    warnings: ReadseekWarning[];
+    truncation: ReadTruncationMetadata | null;
+    symbol: ReadSymbolMetadata | null;
+    map: {
+      requested: boolean;
+      appended: boolean;
+    };
+    lines: ReadseekLine[];
+    bundle?: {
+      mode: "local";
+      applied: boolean;
+      localSupport: Array<{
+        name: string;
+        kind: string;
+        parentName?: string;
+        startLine: number;
+        endLine: number;
+        lineAnchors: string[];
+      }>;
+      warnings: ReadseekWarning[];
+    };
+  };
+  contextHygiene: ContextHygieneMetadata;
+}
+
+export function buildReadOutput(input: ReadOutputInput): ReadOutputResult {
+  const selectedLines = input.selectedLines ?? input.lines?.map((line) => line.raw) ?? [];
+  const lines = input.lines ?? buildReadseekLines(input.startLine, selectedLines);
+  const warnings = input.warnings ?? [];
+  const renderedLines = renderReadseekLines(lines);
+  const truncated = truncateHead(renderedLines, {
+    maxLines: DEFAULT_MAX_LINES,
+    maxBytes: DEFAULT_MAX_BYTES,
+  });
+
+  let text = input.truncation ? truncated.content : renderedLines;
+
+  if (input.truncation) {
+    text += `\n\n[Output truncated: showing ${input.truncation.outputLines} of ${input.totalLines} lines (${formatSize(input.truncation.outputBytes)} of ${formatSize(input.truncation.totalBytes)}). Use offset=${input.startLine + input.truncation.outputLines} to continue.]`;
+  } else if (input.continuation) {
+    text += `\n\n[Showing lines ${input.startLine}-${input.endLine} of ${input.totalLines}. Use offset=${input.continuation.nextOffset} to continue.]`;
+  }
+
+  if (input.bundle?.applied) {
+    const supportBlocks = input.bundle.localSupport.map((item) => {
+      const supportLines = buildReadseekLines(item.symbol.startLine, item.lines);
+      return renderReadseekLines(supportLines);
+    });
+
+    text = [
+      "## Requested symbol",
+      text,
+      "",
+      "## Local support",
+      ...supportBlocks,
+    ].join("\n");
+  }
+
+  if (input.map?.appended && input.map.text) {
+    text += `\n\n${input.map.text}`;
+  }
+
+  if (input.symbol) {
+    const parentInfo = input.symbol.parentName ? ` in ${input.symbol.parentName}` : "";
+    text = `[Symbol: ${input.symbol.name} (${input.symbol.kind})${parentInfo}, lines ${input.symbol.startLine}-${input.symbol.endLine} of ${input.totalLines}]\n\n${text}`;
+  }
+
+  if (warnings.length) {
+    text = `${warnings.map((warning) => warning.message).join("\n\n")}\n\n${text}`;
+  }
+
+  const readseekValue: ReadOutputResult["readseekValue"] = {
+    tool: "read",
+    path: input.path,
+    range: {
+      startLine: input.startLine,
+      endLine: input.endLine,
+      totalLines: input.totalLines,
+    },
+    warnings,
+    truncation: input.truncation ?? null,
+    symbol: input.symbol ?? null,
+    map: {
+      requested: input.map?.requested ?? false,
+      appended: input.map?.appended ?? false,
+    },
+    lines,
+  };
+
+  if (input.bundle) {
+    readseekValue.bundle = {
+      mode: input.bundle.mode,
+      applied: input.bundle.applied,
+      localSupport: input.bundle.localSupport.map((item) => {
+        const supportLines = buildReadseekLines(item.symbol.startLine, item.lines);
+        return {
+          name: item.symbol.name,
+          kind: item.symbol.kind,
+          parentName: item.symbol.parentName,
+          startLine: item.symbol.startLine,
+          endLine: item.symbol.endLine,
+          lineAnchors: supportLines.map((line) => line.anchor),
+        };
+      }),
+      warnings: input.bundle.warnings ?? [],
+    };
+  }
+
+  const contextHygieneResources: ContextHygieneResource[] = [buildFileResource(input.path)];
+  if (input.symbol) {
+    contextHygieneResources.push(buildSymbolResource(input.path, input.symbol.name, input.symbol.kind));
+  }
+  if (input.bundle?.applied) {
+    for (const support of input.bundle.localSupport) {
+      contextHygieneResources.push(buildSymbolResource(input.path, support.symbol.name, support.symbol.kind));
+    }
+  }
+  const contextHygiene = buildContextHygieneMetadata({
+    tool: "read",
+    classification: "read-context",
+    resources: contextHygieneResources,
+    rehydrate: input.rehydrate ?? undefined,
+  });
+
+  return {
+    text,
+    lines,
+    readseekValue,
+    contextHygiene,
+  };
+}

package/src/read-render-helpers.ts

@@ -0,0 +1,104 @@
+import type { ReadseekWarning } from "./readseek-value.js";
+export interface ReadCallTextResult {
+  path: string | null;
+  suffix: string | undefined;
+}
+
+export function formatReadCallText(
+  args: Record<string, unknown> | undefined,
+): ReadCallTextResult {
+  const rawPath = typeof args?.path === "string" ? args.path : null;
+
+  if (typeof args?.symbol === "string" && args.symbol) {
+    return { path: rawPath, suffix: `→ symbol ${args.symbol}` };
+  }
+
+  if (args?.map === true) {
+    return { path: rawPath, suffix: "+ map" };
+  }
+
+  if (typeof args?.offset === "number") {
+    const offset = args.offset as number;
+    const limit = typeof args?.limit === "number" ? (args.limit as number) : undefined;
+    if (offset < 1) {
+      return { path: rawPath, suffix: undefined };
+    }
+    if (limit !== undefined) {
+      if (limit < 1) {
+        return { path: rawPath, suffix: undefined };
+      }
+      return { path: rawPath, suffix: `lines ${offset}-${offset + limit - 1}` };
+    }
+    return { path: rawPath, suffix: `from line ${offset}` };
+  }
+
+  return { path: rawPath, suffix: undefined };
+}
+
+
+export interface ReadResultTextInput {
+  range: { startLine: number; endLine: number; totalLines: number };
+  truncation: { outputLines: number; totalLines: number; outputBytes: number; totalBytes: number } | null;
+  symbol: { query: string; name: string; kind: string; parentName?: string; startLine: number; endLine: number } | null;
+  map: { requested: boolean; appended: boolean };
+  warnings: ReadseekWarning[];
+  isError?: boolean;
+  errorText?: string;
+}
+
+export interface ReadResultTextOutput {
+  summary: string;
+  symbolBadge: string | undefined;
+  badges: string[];
+  truncated: boolean;
+  errorText: string | undefined;
+}
+
+export function formatReadResultText(input: ReadResultTextInput): ReadResultTextOutput {
+  const { range, truncation, symbol, map, warnings } = input;
+
+  // Error case
+  if (input.isError && input.errorText) {
+    return {
+      summary: "",
+      symbolBadge: undefined,
+      badges: [],
+      truncated: false,
+      errorText: input.errorText,
+    };
+  }
+
+  // Line count
+  const lineCount = range.endLine - range.startLine + 1;
+  const isFullFile = range.startLine === 1 && range.endLine === range.totalLines;
+  const isTruncated = !!truncation;
+
+  let summary: string;
+  if (isTruncated) {
+    summary = `\u2713 ${truncation!.outputLines} of ${truncation!.totalLines} lines (truncated)`;
+  } else if (isFullFile) {
+    summary = `\u2713 ${lineCount} lines`;
+  } else {
+    summary = `\u2713 ${lineCount} lines (${range.startLine}-${range.endLine} of ${range.totalLines})`;
+  }
+
+  // Symbol badge
+  const symbolBadge = symbol ? `${symbol.kind} ${symbol.name}` : undefined;
+
+  // Badges
+  const badges: string[] = [];
+  if (map.appended) badges.push("\ud83d\udcd0 map");
+  for (const w of warnings) {
+    if (w.code === "binary-content") badges.push("\u26a0 binary");
+    if (w.code === "bare-cr") badges.push("\u26a0 bare CR");
+    if (w.code === "fuzzy-symbol-match") badges.push("⚠ fuzzy match");
+  }
+
+  return {
+    summary,
+    symbolBadge,
+    badges,
+    truncated: isTruncated,
+    errorText: undefined,
+  };
+}