pi-read-map 1.0.0

package/src/index.ts

@@ -0,0 +1,259 @@
+import type { ExtensionAPI, Theme } from "@mariozechner/pi-coding-agent";
+
+import {
+  createReadTool,
+  DEFAULT_MAX_LINES,
+  DEFAULT_MAX_BYTES,
+} from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { Type } from "@sinclair/typebox";
+import { exec } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { promisify } from "node:util";
+
+import type { FileMapMessageDetails } from "./types.js";
+
+import { formatFileMapWithBudget } from "./formatter.js";
+import { generateMap, shouldGenerateMap } from "./mapper.js";
+
+export type { FileMapMessageDetails } from "./types.js";
+
+const execAsync = promisify(exec);
+
+// In-memory cache for maps
+const mapCache = new Map<string, { mtime: number; map: string }>();
+
+// Pending maps waiting to be sent after tool_result
+const pendingMaps = new Map<
+  string,
+  {
+    path: string;
+    map: string;
+    details: FileMapMessageDetails;
+  }
+>();
+
+/**
+ * Reset the map cache. Exported for testing purposes only.
+ */
+export function resetMapCache(): void {
+  mapCache.clear();
+}
+
+/**
+ * Reset the pending maps. Exported for testing purposes only.
+ */
+export function resetPendingMaps(): void {
+  pendingMaps.clear();
+}
+
+/**
+ * Get pending maps for testing inspection.
+ */
+export function getPendingMaps(): Map<
+  string,
+  { path: string; map: string; details: FileMapMessageDetails }
+> {
+  return pendingMaps;
+}
+
+export default function piReadMapExtension(pi: ExtensionAPI): void {
+  // Get the current working directory
+  const cwd = process.cwd();
+
+  // Create the built-in read tool to delegate to
+  const builtInRead = createReadTool(cwd);
+
+  // Register tool_result handler to send pending maps
+  pi.on("tool_result", (event, _ctx) => {
+    if (event.toolName !== "read") {
+      return;
+    }
+
+    const pending = pendingMaps.get(event.toolCallId);
+    if (!pending) {
+      return;
+    }
+
+    // Send the map as a custom message
+    pi.sendMessage({
+      customType: "file-map",
+      content: pending.map,
+      display: true,
+      details: pending.details,
+    });
+
+    // Clean up
+    pendingMaps.delete(event.toolCallId);
+  });
+
+  // Register custom message renderer for file-map type
+  pi.registerMessageRenderer<FileMapMessageDetails>(
+    "file-map",
+    (message, options, theme: Theme) => {
+      const { expanded } = options;
+      const { details } = message;
+
+      if (expanded) {
+        // Expanded: show full formatted map
+        // message.content can be string or array of content blocks
+        const content =
+          typeof message.content === "string"
+            ? message.content
+            : message.content
+                .filter((c) => c.type === "text")
+                .map((c) => (c as { type: "text"; text: string }).text)
+                .join("\n");
+        return new Text(content, 0, 0);
+      }
+
+      // Collapsed: show summary
+      const fileName = details ? basename(details.filePath) : "file";
+      const symbolCount = details?.symbolCount ?? 0;
+      const totalLines = details?.totalLines ?? 0;
+      const detailLanguage = details?.language ?? "unknown";
+
+      let summary = theme.fg("accent", "📄 File Map: ");
+      summary += theme.fg("toolTitle", theme.bold(fileName));
+      summary += theme.fg("muted", ` │ `);
+      summary += theme.fg("dim", `${symbolCount} symbols`);
+      summary += theme.fg("muted", ` │ `);
+      summary += theme.fg("dim", `${totalLines.toLocaleString()} lines`);
+      summary += theme.fg("muted", ` │ `);
+      summary += theme.fg("dim", detailLanguage);
+      summary += theme.fg("muted", ` │ `);
+      summary += theme.fg("warning", "Ctrl+O to expand");
+
+      return new Text(summary, 0, 0);
+    }
+  );
+
+  // Register our enhanced read tool
+  pi.registerTool({
+    name: "read",
+    label: "Read",
+    description: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${Math.round(DEFAULT_MAX_BYTES / 1024)}KB (whichever is hit first). If truncated, a structural map of the file is included to enable targeted reads. Use offset/limit for large files.`,
+    parameters: Type.Object({
+      path: Type.String({
+        description: "Path to the file to read (relative or absolute)",
+      }),
+      offset: Type.Optional(
+        Type.Number({
+          description: "Line number to start reading from (1-indexed)",
+        })
+      ),
+      limit: Type.Optional(
+        Type.Number({ description: "Maximum number of lines to read" })
+      ),
+    }),
+
+    async execute(toolCallId, params, signal, onUpdate) {
+      const { path: inputPath, offset, limit } = params;
+
+      // If offset or limit provided, delegate directly (targeted read)
+      if (offset !== undefined || limit !== undefined) {
+        return builtInRead.execute(toolCallId, params, signal, onUpdate);
+      }
+
+      // Resolve path
+      const absPath = resolve(cwd, inputPath.replace(/^@/, ""));
+
+      // Check file size and line count
+      let stats;
+      try {
+        stats = await stat(absPath);
+      } catch {
+        // Let built-in handle the error
+        return builtInRead.execute(toolCallId, params, signal, onUpdate);
+      }
+
+      // For small files or non-regular files, delegate directly
+      if (!stats.isFile()) {
+        return builtInRead.execute(toolCallId, params, signal, onUpdate);
+      }
+
+      // Quick check: if file is small enough by bytes, delegate
+      if (stats.size <= DEFAULT_MAX_BYTES) {
+        return builtInRead.execute(toolCallId, params, signal, onUpdate);
+      }
+
+      // Need to check line count too
+      let totalLines: number;
+      try {
+        const { stdout } = await execAsync(`wc -l < "${absPath}"`, { signal });
+        totalLines = Number.parseInt(stdout.trim(), 10) || 0;
+      } catch {
+        // If we can't count lines, delegate
+        return builtInRead.execute(toolCallId, params, signal, onUpdate);
+      }
+
+      // If within threshold, delegate
+      if (!shouldGenerateMap(totalLines, stats.size)) {
+        return builtInRead.execute(toolCallId, params, signal, onUpdate);
+      }
+
+      // File exceeds threshold - generate map
+      // First, get the built-in result
+      const result = await builtInRead.execute(
+        toolCallId,
+        params,
+        signal,
+        onUpdate
+      );
+
+      // Check cache
+      const cached = mapCache.get(absPath);
+      let mapText: string;
+      let symbolCount: number;
+      let language: string;
+
+      if (cached && cached.mtime === stats.mtimeMs) {
+        // Cache hit - we need to regenerate map for metadata
+        // (alternatively, cache could store metadata too)
+        const fileMap = await generateMap(absPath, { signal });
+        if (fileMap) {
+          mapText = cached.map;
+          ({ language } = fileMap);
+          symbolCount = fileMap.symbols.length;
+        } else {
+          return result;
+        }
+      } else {
+        // Generate new map
+        const fileMap = await generateMap(absPath, { signal });
+
+        if (fileMap) {
+          mapText = formatFileMapWithBudget(fileMap);
+          ({ language } = fileMap);
+          symbolCount = fileMap.symbols.length;
+          // Cache it
+          mapCache.set(absPath, { mtime: stats.mtimeMs, map: mapText });
+        } else {
+          // Map generation failed, return original result
+          return result;
+        }
+      }
+
+      // Store map in pendingMaps for delivery after tool_result event
+      pendingMaps.set(toolCallId, {
+        path: absPath,
+        map: mapText,
+        details: {
+          filePath: absPath,
+          totalLines,
+          totalBytes: stats.size,
+          symbolCount,
+          language,
+        },
+      });
+
+      // Return the built-in result unmodified (with cleared truncation details
+      // since we're providing a map separately)
+      return {
+        ...result,
+        details: undefined,
+      };
+    },
+  });
+}

package/src/language-detect.ts

@@ -0,0 +1,88 @@
+import { extname } from "node:path";
+
+import type { LanguageInfo } from "./types.js";
+
+/**
+ * Map of file extensions to language info.
+ */
+const EXTENSION_MAP: Record<string, LanguageInfo> = {
+  // Python
+  ".py": { id: "python", name: "Python" },
+  ".pyw": { id: "python", name: "Python" },
+  ".pyi": { id: "python", name: "Python" },
+
+  // TypeScript
+  ".ts": { id: "typescript", name: "TypeScript" },
+  ".tsx": { id: "typescript", name: "TypeScript" },
+  ".mts": { id: "typescript", name: "TypeScript" },
+  ".cts": { id: "typescript", name: "TypeScript" },
+
+  // JavaScript
+  ".js": { id: "javascript", name: "JavaScript" },
+  ".jsx": { id: "javascript", name: "JavaScript" },
+  ".mjs": { id: "javascript", name: "JavaScript" },
+  ".cjs": { id: "javascript", name: "JavaScript" },
+
+  // Go
+  ".go": { id: "go", name: "Go" },
+
+  // Rust
+  ".rs": { id: "rust", name: "Rust" },
+
+  // C/C++
+  ".c": { id: "c", name: "C" },
+  ".h": { id: "c-header", name: "C Header" },
+  ".cpp": { id: "cpp", name: "C++" },
+  ".cc": { id: "cpp", name: "C++" },
+  ".cxx": { id: "cpp", name: "C++" },
+  ".hpp": { id: "cpp", name: "C++" },
+  ".hxx": { id: "cpp", name: "C++" },
+
+  // SQL
+  ".sql": { id: "sql", name: "SQL" },
+
+  // JSON
+  ".json": { id: "json", name: "JSON" },
+  ".jsonc": { id: "json", name: "JSON" },
+
+  // JSON Lines
+  ".jsonl": { id: "jsonl", name: "JSON Lines" },
+
+  // Markdown
+  ".md": { id: "markdown", name: "Markdown" },
+  ".mdx": { id: "markdown", name: "Markdown" },
+
+  // YAML
+  ".yml": { id: "yaml", name: "YAML" },
+  ".yaml": { id: "yaml", name: "YAML" },
+
+  // TOML
+  ".toml": { id: "toml", name: "TOML" },
+
+  // CSV
+  ".csv": { id: "csv", name: "CSV" },
+  ".tsv": { id: "csv", name: "TSV" },
+};
+
+/**
+ * Detect language from file path.
+ * Returns null for unknown file types.
+ */
+export function detectLanguage(filePath: string): LanguageInfo | null {
+  const ext = extname(filePath).toLowerCase();
+  return EXTENSION_MAP[ext] ?? null;
+}
+
+/**
+ * Get all supported extensions.
+ */
+export function getSupportedExtensions(): string[] {
+  return Object.keys(EXTENSION_MAP);
+}
+
+/**
+ * Check if a file extension is supported.
+ */
+export function isSupported(filePath: string): boolean {
+  return detectLanguage(filePath) !== null;
+}

package/src/mapper.ts

@@ -0,0 +1,116 @@
+import type { FileMap, MapOptions } from "./types.js";
+
+import { THRESHOLDS } from "./constants.js";
+import { detectLanguage } from "./language-detect.js";
+import { cMapper } from "./mappers/c.js";
+import { cppMapper } from "./mappers/cpp.js";
+import { csvMapper } from "./mappers/csv.js";
+import { ctagsMapper } from "./mappers/ctags.js";
+import { fallbackMapper } from "./mappers/fallback.js";
+import { goMapper } from "./mappers/go.js";
+import { jsonMapper } from "./mappers/json.js";
+import { jsonlMapper } from "./mappers/jsonl.js";
+import { markdownMapper } from "./mappers/markdown.js";
+import { pythonMapper } from "./mappers/python.js";
+import { rustMapper } from "./mappers/rust.js";
+import { sqlMapper } from "./mappers/sql.js";
+import { tomlMapper } from "./mappers/toml.js";
+import { typescriptMapper } from "./mappers/typescript.js";
+import { yamlMapper } from "./mappers/yaml.js";
+
+type MapperFn = (
+  filePath: string,
+  signal?: AbortSignal
+) => Promise<FileMap | null>;
+
+/**
+ * Registry of language-specific mappers.
+ *
+ * Uses internal tree-sitter/ts-morph mappers for all supported languages.
+ */
+const MAPPERS: Record<string, MapperFn> = {
+  // Phase 1: Python AST-based
+  python: pythonMapper,
+
+  // Phase 2: Go AST-based
+  go: goMapper,
+
+  // Phase 3: Internal ts-morph mappers
+  typescript: typescriptMapper,
+  javascript: typescriptMapper,
+
+  // Phase 3: Internal regex-based markdown
+  markdown: markdownMapper,
+
+  // Phase 3: Internal tree-sitter mappers
+  rust: rustMapper,
+  cpp: cppMapper,
+  "c-header": cppMapper, // .h files
+
+  // Phase 2: Regex/subprocess mappers
+  sql: sqlMapper,
+  json: jsonMapper,
+  jsonl: jsonlMapper,
+  c: cMapper, // .c files use regex
+
+  // Phase 4: Extended coverage
+  yaml: yamlMapper,
+  toml: tomlMapper,
+  csv: csvMapper,
+};
+
+/**
+ * Generate a structural map for a file.
+ *
+ * Dispatches to the appropriate language-specific mapper,
+ * falling back to ctags (if available) then grep-based extraction.
+ */
+export async function generateMap(
+  filePath: string,
+  options: MapOptions = {}
+): Promise<FileMap | null> {
+  const { signal } = options;
+
+  // Detect language
+  const langInfo = detectLanguage(filePath);
+
+  if (!langInfo) {
+    // Unknown language, try ctags then fallback
+    const ctagsResult = await ctagsMapper(filePath, signal);
+    if (ctagsResult) {
+      return ctagsResult;
+    }
+    return fallbackMapper(filePath, signal);
+  }
+
+  // Try language-specific mapper
+  const mapper = MAPPERS[langInfo.id];
+
+  if (mapper) {
+    const result = await mapper(filePath, signal);
+    if (result) {
+      return result;
+    }
+    // Mapper failed, fall through to ctags/fallback
+  }
+
+  // Try ctags as intermediate fallback (better than grep when available)
+  const ctagsResult = await ctagsMapper(filePath, signal);
+  if (ctagsResult) {
+    return ctagsResult;
+  }
+
+  // Use grep-based fallback mapper
+  return fallbackMapper(filePath, signal);
+}
+
+/**
+ * Check if a file should have a map generated.
+ * Returns true if the file exceeds the truncation threshold.
+ */
+export function shouldGenerateMap(
+  totalLines: number,
+  totalBytes: number
+): boolean {
+  return totalLines > THRESHOLDS.MAX_LINES || totalBytes > THRESHOLDS.MAX_BYTES;
+}

package/src/mappers/c.ts

@@ -0,0 +1,236 @@
+import { readFile, stat } from "node:fs/promises";
+
+import type { FileMap, FileSymbol } from "../types.js";
+
+import { DetailLevel, SymbolKind } from "../enums.js";
+
+/**
+ * Regex patterns for C language constructs.
+ */
+const C_PATTERNS = {
+  // Function definition: type name(params) { or type name(params);
+  function: /^(\w+(?:\s*\*)?)\s+(\w+)\s*\(([^)]*)\)\s*(?:\{|;)?/,
+
+  // Struct definition: struct name { or typedef struct { ... } name;
+  struct: /^(?:typedef\s+)?struct\s+(\w+)?\s*\{/,
+
+  // Enum definition
+  enum: /^(?:typedef\s+)?enum\s+(\w+)?\s*\{/,
+
+  // Union definition
+  union: /^(?:typedef\s+)?union\s+(\w+)?\s*\{/,
+
+  // #define macro
+  define: /^#define\s+(\w+)(?:\([^)]*\))?\s*/,
+
+  // Global variable declaration
+  variable:
+    /^(?:static\s+)?(?:const\s+)?(?:volatile\s+)?(\w+(?:\s*\*)?)\s+(\w+)\s*(?:=|;)/,
+
+  // Typedef
+  typedef: /^typedef\s+(?:struct|enum|union)?\s*\w*\s*\{?[^}]*\}?\s*(\w+)\s*;/,
+};
+
+interface CMatch {
+  name: string;
+  kind: SymbolKind;
+  startLine: number;
+  signature?: string;
+  modifiers?: string[];
+}
+
+/**
+ * Find the end of a brace-delimited block.
+ */
+function findBlockEnd(lines: string[], startIdx: number): number {
+  let braceCount = 0;
+  let foundOpen = false;
+
+  for (let i = startIdx; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line) {
+      continue;
+    }
+    for (const char of line) {
+      if (char === "{") {
+        braceCount++;
+        foundOpen = true;
+      } else if (char === "}") {
+        braceCount--;
+        if (foundOpen && braceCount === 0) {
+          return i + 1; // 1-indexed
+        }
+      }
+    }
+  }
+
+  return startIdx + 1; // Single line if no block found
+}
+
+/**
+ * Check if a line is inside a function body.
+ */
+function isInsideFunction(lines: string[], lineIdx: number): boolean {
+  let braceCount = 0;
+  for (let i = 0; i < lineIdx; i++) {
+    const line = lines[i];
+    if (!line) {
+      continue;
+    }
+    for (const char of line) {
+      if (char === "{") {
+        braceCount++;
+      } else if (char === "}") {
+        braceCount--;
+      }
+    }
+  }
+  return braceCount > 0;
+}
+
+/**
+ * Generate a file map for a C file using regex patterns.
+ */
+export async function cMapper(
+  filePath: string,
+  _signal?: AbortSignal
+): Promise<FileMap | null> {
+  try {
+    const stats = await stat(filePath);
+    const totalBytes = stats.size;
+
+    const content = await readFile(filePath, "utf8");
+    const lines = content.split("\n");
+    const totalLines = lines.length;
+
+    const matches: CMatch[] = [];
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (!line) {
+        continue;
+      }
+      const trimmed = line.trim();
+      const lineNum = i + 1;
+
+      // Skip empty lines and comments
+      if (!trimmed || trimmed.startsWith("//") || trimmed.startsWith("/*")) {
+        continue;
+      }
+
+      // Skip lines inside function bodies (only want top-level)
+      if (isInsideFunction(lines, i) && !C_PATTERNS.define.test(trimmed)) {
+        continue;
+      }
+
+      // Check for #define
+      const defineMatch = C_PATTERNS.define.exec(trimmed);
+      if (defineMatch) {
+        const [, matchName] = defineMatch;
+        if (matchName) {
+          matches.push({
+            name: matchName,
+            kind: SymbolKind.Constant,
+            startLine: lineNum,
+          });
+        }
+        continue;
+      }
+
+      // Check for struct
+      const structMatch = C_PATTERNS.struct.exec(trimmed);
+      if (structMatch) {
+        matches.push({
+          name: structMatch[1] ?? "(anonymous)",
+          kind: SymbolKind.Class,
+          startLine: lineNum,
+        });
+        continue;
+      }
+
+      // Check for enum
+      const enumMatch = C_PATTERNS.enum.exec(trimmed);
+      if (enumMatch) {
+        matches.push({
+          name: enumMatch[1] ?? "(anonymous)",
+          kind: SymbolKind.Enum,
+          startLine: lineNum,
+        });
+        continue;
+      }
+
+      // Check for union
+      const unionMatch = C_PATTERNS.union.exec(trimmed);
+      if (unionMatch) {
+        matches.push({
+          name: unionMatch[1] ?? "(anonymous)",
+          kind: SymbolKind.Class,
+          startLine: lineNum,
+          modifiers: ["union"],
+        });
+        continue;
+      }
+
+      // Check for function
+      const funcMatch = C_PATTERNS.function.exec(trimmed);
+      if (funcMatch) {
+        const [, returnType, name, params] = funcMatch;
+
+        // Skip if it's a variable declaration or control statement
+        if (
+          !trimmed.includes("(") ||
+          !name ||
+          /^(if|while|for|switch|return)$/.test(name)
+        ) {
+          continue;
+        }
+
+        matches.push({
+          name,
+          kind: SymbolKind.Function,
+          startLine: lineNum,
+          signature: `(${params ?? ""}): ${returnType ?? "void"}`,
+        });
+        continue;
+      }
+    }
+
+    // Convert to symbols with end lines
+    const symbols: FileSymbol[] = matches.map((m) => {
+      const { startLine } = m;
+      const endLine =
+        m.kind === SymbolKind.Constant
+          ? startLine
+          : findBlockEnd(lines, startLine - 1);
+
+      const symbol: FileSymbol = {
+        name: m.name,
+        kind: m.kind,
+        startLine,
+        endLine,
+      };
+
+      if (m.signature) {
+        symbol.signature = m.signature;
+      }
+
+      if (m.modifiers) {
+        symbol.modifiers = m.modifiers;
+      }
+
+      return symbol;
+    });
+
+    return {
+      path: filePath,
+      totalLines,
+      totalBytes,
+      language: "C",
+      symbols,
+      detailLevel: DetailLevel.Full,
+    };
+  } catch (error) {
+    console.error(`C mapper failed: ${error}`);
+    return null;
+  }
+}