pi-readseek 0.1.0

package/src/readseek/constants.ts

@@ -0,0 +1,21 @@
+/**
+ * Constants for thresholds.
+ */
+export const THRESHOLDS = {
+  /** Maximum lines before truncation */
+  MAX_LINES: 2000,
+  /** Maximum bytes before truncation */
+  MAX_BYTES: 50 * 1024,
+  /** Maximum map size in bytes */
+  MAX_MAP_BYTES: 25 * 1024,
+  /** Target size for full detail */
+  FULL_TARGET_BYTES: 10 * 1024,
+  /** Target size for compact detail */
+  COMPACT_TARGET_BYTES: 20 * 1024,
+  /** Maximum size for outline level */
+  MAX_OUTLINE_BYTES: 50 * 1024,
+  /** Maximum size for truncated level (hard cap) */
+  MAX_TRUNCATED_BYTES: 100 * 1024,
+  /** Number of symbols to show at each end for truncated outline */
+  TRUNCATED_SYMBOLS_EACH: 50,
+} as const;

package/src/readseek/enums.ts

@@ -0,0 +1,38 @@
+/**
+ * Symbol kinds supported by mappers.
+ */
+export enum SymbolKind {
+  Class = "class",
+  Function = "function",
+  Method = "method",
+  Variable = "variable",
+  Constant = "constant",
+  Interface = "interface",
+  Type = "type",
+  Enum = "enum",
+  Struct = "struct",
+  Import = "import",
+  Module = "module",
+  Namespace = "namespace",
+  Property = "property",
+  Heading = "heading",
+  Table = "table",
+  View = "view",
+  Procedure = "procedure",
+  Trigger = "trigger",
+  Index = "index",
+  Schema = "schema",
+  Signal = "signal",
+  Unknown = "unknown",
+}
+
+/**
+ * Detail levels for map generation.
+ */
+export enum DetailLevel {
+  Full = "full",
+  Compact = "compact",
+  Minimal = "minimal",
+  Outline = "outline",
+  Truncated = "truncated",
+}

package/src/readseek/formatter.ts

@@ -0,0 +1,431 @@
+import { basename } from "node:path";
+
+import type { FileMap, FileSymbol } from "./types.js";
+
+import { THRESHOLDS } from "./constants.js";
+import { DetailLevel } from "./enums.js";
+
+const BOX_LINE = "───────────────────────────────────────";
+
+/**
+ * Format a file size for display.
+ */
+function formatSize(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * Format a number with comma separators.
+ */
+function formatNumber(n: number): string {
+  return n.toLocaleString("en-US");
+}
+
+/**
+ * Format a symbol for display.
+ */
+function formatSymbol(
+  symbol: FileSymbol,
+  level: DetailLevel,
+  indent = 0
+): string {
+  const prefix = "  ".repeat(indent);
+  const lineRange =
+    symbol.startLine === symbol.endLine
+      ? `[${symbol.startLine}]`
+      : `[${symbol.startLine}-${symbol.endLine}]`;
+
+  let { name } = symbol;
+
+  if (level === DetailLevel.Full) {
+    if (symbol.signature) {
+      // Check whether the signature already contains the symbol name.
+      // Full-declaration signatures (e.g. Rust "pub fn foo(x: i32) -> bool")
+      // include the name; partial signatures (e.g. Python "(x, y) -> None")
+      // do not and should be appended.
+      if (symbol.signature.includes(name)) {
+        name = symbol.signature;
+      } else {
+        if (symbol.modifiers?.length) {
+          name = `${symbol.modifiers.join(" ")} ${name}`;
+        }
+        name = `${name}${symbol.signature}`;
+      }
+    } else if (symbol.modifiers?.length) {
+      name = `${symbol.modifiers.join(" ")} ${name}`;
+    }
+  }
+
+  // Format based on kind
+  let formatted: string;
+  switch (symbol.kind) {
+    case "class":
+    case "interface":
+    case "struct":
+    case "enum":
+    case "type": {
+      formatted = `${prefix}${symbol.kind} ${name}: ${lineRange}`;
+      break;
+    }
+    case "function":
+    case "method": {
+      formatted = `${prefix}${name}: ${lineRange}`;
+      break;
+    }
+    case "variable":
+    case "constant": {
+      formatted = `${prefix}${name} = ... ${lineRange}`;
+      break;
+    }
+    default: {
+      formatted = `${prefix}${name}: ${lineRange}`;
+    }
+  }
+
+  // Append docstring at Full detail level
+  if (level === DetailLevel.Full && symbol.docstring) {
+    formatted += ` — ${symbol.docstring}`;
+  }
+
+  return formatted;
+}
+
+/**
+ * Format symbols recursively.
+ */
+function formatSymbols(
+  symbols: FileSymbol[],
+  level: DetailLevel,
+  indent = 0
+): string[] {
+  const lines: string[] = [];
+
+  for (const symbol of symbols) {
+    lines.push(formatSymbol(symbol, level, indent));
+
+    // Add children for full, compact, and minimal levels (not outline or truncated)
+    if (
+      level !== DetailLevel.Outline &&
+      level !== DetailLevel.Truncated &&
+      symbol.children?.length
+    ) {
+      // For minimal, flatten children
+      if (level === DetailLevel.Minimal) {
+        for (const child of symbol.children) {
+          lines.push(formatSymbol(child, level, indent + 1));
+        }
+      } else {
+        lines.push(...formatSymbols(symbol.children, level, indent + 1));
+      }
+    }
+  }
+
+  return lines;
+}
+
+/**
+ * Format a complete file map to a string.
+ */
+export function formatFileMap(map: FileMap, level?: DetailLevel): string {
+  const effectiveLevel = level ?? map.detailLevel;
+  const fileName = basename(map.path);
+
+  const lines: string[] = [
+    "",
+    BOX_LINE,
+    `File Map: ${fileName}`,
+    `${formatNumber(map.totalLines)} lines │ ${formatSize(map.totalBytes)} │ ${map.language}`,
+    BOX_LINE,
+    "",
+  ];
+
+  // Add detail level notice if reduced from Full
+  if (map.truncatedInfo) {
+    const { shownSymbols, totalSymbols } = map.truncatedInfo;
+    lines.push(
+      `[Map ≤${formatSize(THRESHOLDS.MAX_TRUNCATED_BYTES)} | ${shownSymbols} of ${formatNumber(totalSymbols)} symbols]`
+    );
+    lines.push("");
+  } else if (effectiveLevel === DetailLevel.Outline) {
+    lines.push(`[Map ≤${formatSize(THRESHOLDS.MAX_OUTLINE_BYTES)} | outline]`);
+    lines.push("");
+  } else if (effectiveLevel === DetailLevel.Minimal) {
+    lines.push(`[Map ≤${formatSize(THRESHOLDS.MAX_MAP_BYTES)} | minimal]`);
+    lines.push("");
+  } else if (effectiveLevel === DetailLevel.Compact) {
+    lines.push(
+      `[Map ≤${formatSize(THRESHOLDS.COMPACT_TARGET_BYTES)} | compact]`
+    );
+    lines.push("");
+  }
+
+  // Add imports if present and not outline or truncated level
+  if (
+    effectiveLevel !== DetailLevel.Outline &&
+    effectiveLevel !== DetailLevel.Truncated &&
+    map.imports.length > 0
+  ) {
+    const importList =
+      map.imports.length > 10
+        ? [...map.imports.slice(0, 10), `...${map.imports.length - 10} more`]
+        : map.imports;
+    lines.push(`imports: ${importList.join(", ")}`);
+    lines.push("");
+  }
+
+  // Add symbols
+  if (map.truncatedInfo) {
+    // Truncated format: first half, separator, second half
+    const half = Math.floor(map.symbols.length / 2);
+    const firstSymbols = map.symbols.slice(0, half);
+    const lastSymbols = map.symbols.slice(half);
+
+    // Format first batch
+    const firstLines = formatSymbols(firstSymbols, effectiveLevel);
+    lines.push(...firstLines);
+
+    // Add separator
+    lines.push("");
+    lines.push(
+      `  ─ ─ ─ ${formatNumber(map.truncatedInfo.omittedSymbols)} more symbols ─ ─ ─`
+    );
+    lines.push("");
+
+    // Format last batch
+    const lastLines = formatSymbols(lastSymbols, effectiveLevel);
+    lines.push(...lastLines);
+  } else {
+    // Normal format
+    const symbolLines = formatSymbols(map.symbols, effectiveLevel);
+    lines.push(...symbolLines);
+  }
+
+  // Add footer with appropriate guidance
+  lines.push("");
+  lines.push(BOX_LINE);
+  if (map.truncatedInfo) {
+    // For truncated maps, provide specific guidance on finding omitted symbols
+    const firstShown = map.symbols.slice(0, Math.floor(map.symbols.length / 2));
+    const lastShown = map.symbols.slice(Math.floor(map.symbols.length / 2));
+    const lastFirst = firstShown.at(-1);
+    const firstLast = lastShown.at(0);
+    if (lastFirst && firstLast) {
+      const omitStart = lastFirst.endLine + 1;
+      const omitEnd = firstLast.startLine - 1;
+      lines.push(
+        `Omitted symbols are in lines ${formatNumber(omitStart)}-${formatNumber(omitEnd)}.`
+      );
+    }
+    lines.push(
+      "Use read(path, offset=LINE, limit=N) to view specific sections."
+    );
+  } else {
+    lines.push("Use read(path, offset=LINE, limit=N) for targeted reads.");
+  }
+  lines.push(BOX_LINE);
+
+  return lines.join("\n");
+}
+
+/**
+ * Get the appropriate detail level for a map based on size.
+ */
+export function getDetailLevelForSize(currentSize: number): DetailLevel {
+  if (currentSize <= THRESHOLDS.FULL_TARGET_BYTES) {
+    return DetailLevel.Full;
+  }
+  if (currentSize <= THRESHOLDS.COMPACT_TARGET_BYTES) {
+    return DetailLevel.Compact;
+  }
+  if (currentSize <= THRESHOLDS.MAX_MAP_BYTES) {
+    return DetailLevel.Minimal;
+  }
+  return DetailLevel.Outline;
+}
+
+/**
+ * Reduce detail level of a file map.
+ */
+export function reduceToLevel(map: FileMap, level: DetailLevel): FileMap {
+  if (level === DetailLevel.Outline) {
+    // Remove all children and signatures
+    return {
+      ...map,
+      detailLevel: DetailLevel.Outline,
+      imports: [],
+      symbols: map.symbols.map((s) => ({
+        name: s.name,
+        kind: s.kind,
+        startLine: s.startLine,
+        endLine: s.endLine,
+      })),
+    };
+  }
+
+  if (level === DetailLevel.Minimal) {
+    // Remove signatures and docstrings but keep children flattened
+    return {
+      ...map,
+      detailLevel: DetailLevel.Minimal,
+      symbols: map.symbols.map((s) => ({
+        name: s.name,
+        kind: s.kind,
+        startLine: s.startLine,
+        endLine: s.endLine,
+        isExported: s.isExported,
+        children: s.children?.map((c) => ({
+          name: c.name,
+          kind: c.kind,
+          startLine: c.startLine,
+          endLine: c.endLine,
+          isExported: c.isExported,
+        })),
+      })),
+    };
+  }
+
+  if (level === DetailLevel.Compact) {
+    // Remove signatures but keep structure
+    return {
+      ...map,
+      detailLevel: DetailLevel.Compact,
+      symbols: map.symbols.map((s) => stripSignatures(s)),
+    };
+  }
+
+  return { ...map, detailLevel: DetailLevel.Full };
+}
+
+function stripSignatures(symbol: FileSymbol): FileSymbol {
+  return {
+    name: symbol.name,
+    kind: symbol.kind,
+    startLine: symbol.startLine,
+    endLine: symbol.endLine,
+    modifiers: symbol.modifiers,
+    docstring: symbol.docstring,
+    isExported: symbol.isExported,
+    children: symbol.children?.map(stripSignatures),
+  };
+}
+
+/**
+ * Reduce a file map to truncated form: first N + last N symbols only.
+ * Used when even Outline level exceeds budget.
+ */
+export function reduceToTruncated(
+  map: FileMap,
+  symbolsEach: number = THRESHOLDS.TRUNCATED_SYMBOLS_EACH
+): FileMap {
+  const { symbols } = map;
+  const total = symbols.length;
+
+  if (total <= symbolsEach * 2) {
+    // Not enough symbols to truncate, return as outline
+    return reduceToLevel(map, DetailLevel.Outline);
+  }
+
+  const firstSymbols = symbols.slice(0, symbolsEach).map((s) => ({
+    name: s.name,
+    kind: s.kind,
+    startLine: s.startLine,
+    endLine: s.endLine,
+  }));
+
+  const lastSymbols = symbols.slice(-symbolsEach).map((s) => ({
+    name: s.name,
+    kind: s.kind,
+    startLine: s.startLine,
+    endLine: s.endLine,
+  }));
+
+  return {
+    ...map,
+    symbols: [...firstSymbols, ...lastSymbols],
+    detailLevel: DetailLevel.Truncated,
+    imports: [],
+    truncatedInfo: {
+      totalSymbols: total,
+      shownSymbols: symbolsEach * 2,
+      omittedSymbols: total - symbolsEach * 2,
+    },
+  };
+}
+
+/**
+ * Format a file map with automatic budget enforcement.
+ * Reduces detail level until the map fits within the budget.
+ */
+export function formatFileMapWithBudget(
+  map: FileMap,
+  maxBytes = THRESHOLDS.MAX_TRUNCATED_BYTES
+): string {
+  // Tiered budgets: progressively reduce detail level
+  const tiers: { level: DetailLevel; budget: number }[] = [
+    { level: DetailLevel.Full, budget: THRESHOLDS.FULL_TARGET_BYTES },
+    { level: DetailLevel.Compact, budget: THRESHOLDS.COMPACT_TARGET_BYTES },
+    { level: DetailLevel.Minimal, budget: THRESHOLDS.MAX_MAP_BYTES },
+    { level: DetailLevel.Outline, budget: THRESHOLDS.MAX_OUTLINE_BYTES },
+  ];
+
+  for (const { level, budget } of tiers) {
+    const reduced = reduceToLevel(map, level);
+    const formatted = formatFileMap(reduced, level);
+    const size = Buffer.byteLength(formatted, "utf8");
+
+    if (size <= budget && size <= maxBytes) {
+      return formatted;
+    }
+  }
+
+  // Outline exceeded budget - need to truncate symbols
+  // First check if full outline fits in maxBytes (just not in outline budget)
+  const outline = reduceToLevel(map, DetailLevel.Outline);
+  const outlineFormatted = formatFileMap(outline, DetailLevel.Outline);
+  const outlineSize = Buffer.byteLength(outlineFormatted, "utf8");
+
+  if (outlineSize <= maxBytes) {
+    // Outline fits in truncated budget, use it
+    return outlineFormatted;
+  }
+
+  // Need to truncate - binary search for maximum symbols that fit
+  const totalSymbols = map.symbols.length;
+  const minSymbols = 10; // Guaranteed minimum
+  const maxSymbolsEach = Math.floor(totalSymbols / 2); // Can't show more than half on each side
+
+  let low = minSymbols;
+  let high = maxSymbolsEach;
+  let bestResult: string | null = null;
+
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    const truncated = reduceToTruncated(map, mid);
+    const formatted = formatFileMap(truncated, DetailLevel.Truncated);
+    const size = Buffer.byteLength(formatted, "utf8");
+
+    if (size <= maxBytes) {
+      // This fits, try to show more
+      bestResult = formatted;
+      low = mid + 1;
+    } else {
+      // Too big, show fewer
+      high = mid - 1;
+    }
+  }
+
+  // Return best result or fallback to minimum
+  if (bestResult) {
+    return bestResult;
+  }
+
+  // Absolute fallback: minimum symbols (guaranteed to fit)
+  const minimal = reduceToTruncated(map, minSymbols);
+  return formatFileMap(minimal, DetailLevel.Truncated);
+}

package/src/readseek/language-detect.ts

@@ -0,0 +1,29 @@
+import type { LanguageInfo } from "./types.js";
+
+const EXTENSION_LANGUAGE_MAP: Record<string, LanguageInfo> = {
+  ".rs": { id: "rust", name: "Rust" },
+  ".c": { id: "cpp", name: "C" },
+  ".cc": { id: "cpp", name: "C++" },
+  ".cpp": { id: "cpp", name: "C++" },
+  ".cxx": { id: "cpp", name: "C++" },
+  ".hpp": { id: "c-header", name: "C/C++ Header" },
+  ".h": { id: "c-header", name: "C/C++ Header" },
+  ".hxx": { id: "c-header", name: "C/C++ Header" },
+  ".java": { id: "java", name: "Java" },
+};
+
+export function detectLanguage(filePath: string): LanguageInfo | null {
+  const normalized = filePath.toLowerCase();
+  for (const [ext, language] of Object.entries(EXTENSION_LANGUAGE_MAP)) {
+    if (normalized.endsWith(ext)) return language;
+  }
+  return null;
+}
+
+export function isSupported(filePath: string): boolean {
+  return detectLanguage(filePath) !== null;
+}
+
+export function getSupportedExtensions(): string[] {
+  return Object.keys(EXTENSION_LANGUAGE_MAP);
+}

package/src/readseek/mapper.ts

@@ -0,0 +1,69 @@
+import { stat } from "node:fs/promises";
+
+import { readseekMap, readseekMapContent } from "../readseek-client.js";
+import { THRESHOLDS } from "./constants.js";
+import type { FileMap, MapOptions } from "./types.js";
+
+export const READSEEK_MAPPER_NAME = "readseek";
+export const READSEEK_MAPPER_VERSION = 1;
+
+export interface MapperIdentity {
+  mapperName: string;
+  mapperVersion: number;
+}
+
+export interface MapResultWithIdentity extends MapperIdentity {
+  map: FileMap | null;
+}
+
+export const READSEEK_MAPPER_IDENTITY: MapperIdentity = {
+  mapperName: READSEEK_MAPPER_NAME,
+  mapperVersion: READSEEK_MAPPER_VERSION,
+};
+
+export const ALL_MAPPER_IDENTITIES: Record<string, MapperIdentity> = {
+  readseek: READSEEK_MAPPER_IDENTITY,
+};
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (!signal?.aborted) return;
+  const reason = signal.reason;
+  throw reason instanceof Error ? reason : new Error("aborted");
+}
+
+export async function generateMapWithIdentity(
+  filePath: string,
+  options: MapOptions = {},
+): Promise<MapResultWithIdentity> {
+  throwIfAborted(options.signal);
+  const fileStat = await stat(filePath);
+  throwIfAborted(options.signal);
+  const map = await readseekMap(filePath, fileStat.size);
+  throwIfAborted(options.signal);
+  return { map, ...READSEEK_MAPPER_IDENTITY };
+}
+
+export async function generateMap(
+  filePath: string,
+  options: MapOptions = {},
+): Promise<FileMap | null> {
+  return (await generateMapWithIdentity(filePath, options)).map;
+}
+
+export async function generateMapFromContent(
+  filePath: string,
+  content: string,
+  options: MapOptions = {},
+): Promise<FileMap | null> {
+  throwIfAborted(options.signal);
+  const map = await readseekMapContent(filePath, content);
+  throwIfAborted(options.signal);
+  return map;
+}
+
+export function shouldGenerateMap(
+  totalLines: number,
+  totalBytes: number,
+): boolean {
+  return totalLines > THRESHOLDS.MAX_LINES || totalBytes > THRESHOLDS.MAX_BYTES;
+}

package/src/readseek/parser-errors.ts

@@ -0,0 +1,22 @@
+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)}`);
+}
+
+export function __resetParserErrorReporterForTests(): void {
+  emitted.clear();
+}

package/src/readseek/parser-loader.ts

@@ -0,0 +1,83 @@
+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;
+  }
+}
+
+export function __resetWasmParserLoaderForTests(): void {
+  initPromise = null;
+  languages.clear();
+  languageLoads.clear();
+}