pi-read-map 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will Hampson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# pi-read-map
+
+![pi-read-map banner](banner.png)
+
+This pi extension augments the built-in `read` tool with structural file maps. When you open a file larger than 2,000 lines or 50 KB, the extension generates a map of every symbol and its line range. You navigate large codebases precisely instead of scanning sequentially.
+
+## Why This Exists
+
+**The problem:** pi sees only the first 2,000 lines of a 50,000-line source file. Ask "how does the type checker handle unions?" and the model either hallucinates or burns tokens re-reading until it finds the answer.
+
+**The trade-off:** `pi-read-map` spends ~2,000–10,000 tokens upfront to generate a map of the entire file. The extension triggers only for files exceeding the truncation limit (>2,000 lines and >50 KB); smaller files pass through unchanged.
+
+**The payoff:** The map stays in context. Ask "show me the merge implementation," "compare error handling in these three functions," or "what symbols exist after line 40,000?" without re-reading. The investment pays for itself when you analyze a large file beyond a single summary.
+
+## Demo
+
+See `pi-read-map` in action analyzing the TypeScript compiler's 54,000-line type checker:
+
+
+https://github.com/user-attachments/assets/4408f37b-b669-453f-a588-336a5332ae90
+
+
+## What It Does
+
+- **Generates structural maps** showing symbols, classes, functions, and their exact line ranges
+- **Supports 16 languages** through specialized parsers: TypeScript, JavaScript, Python, Go, Rust, C, C++, SQL, JSON, JSONL, YAML, TOML, CSV, Markdown
+- **Compresses aggressively** to ~3-5% of original file size (a 400 KB file yields an ~18 KB map)
+- **Enforces a 20 KB budget** through progressive detail reduction
+- **Caches maps** in memory by file path and modification time for instant re-reads
+- **Falls back** from language-specific parsers to ctags to grep heuristics
+
+## Installation
+
+### From Git (Recommended)
+
+```bash
+# Global install
+pi install https://github.com/Whamp/pi-read-map
+
+# Project-local install (adds to .pi/settings.json)
+pi install https://github.com/Whamp/pi-read-map -l
+```
+
+### From npm
+
+```bash
+# Global install
+pi install npm:pi-read-map
+
+# Project-local install
+pi install npm:pi-read-map -l
+```
+
+### From Local Directory
+
+```bash
+# Clone and install globally
+pi install ./path/to/pi-read-map
+
+# Or project-local
+pi install ./path/to/pi-read-map -l
+```
+
+### One-off Test
+
+Try the extension without installing:
+
+```bash
+pi -e https://github.com/Whamp/pi-read-map
+pi -e npm:pi-read-map
+pi -e ./path/to/pi-read-map
+```
+
+## Verification
+
+Start pi or run `/reload`. Then read a large file:
+
+```
+read path/to/large-file.ts
+```
+
+Output includes the truncated content followed by:
+
+```
+[Truncated: showing first 2000 lines of 10,247 (50 KB of 412 KB)]
+───────────────────────────────────────
+File Map: path/to/large-file.ts
+10,247 lines │ 412 KB │ TypeScript
+───────────────────────────────────────
+
+class ProcessorConfig: [18-32]
+class BatchProcessor: [34-890]
+  constructor(config: ProcessorConfig): [40-65]
+  async run(items: List<Item>): [67-180]
+  ...
+
+───────────────────────────────────────
+Use read(path, offset=LINE, limit=N) for targeted reads.
+───────────────────────────────────────
+```
+
+## Development
+
+```bash
+npm run typecheck      # Type checking
+npm run lint           # Linting with oxlint
+npm run lint:fix       # Auto-fix lint issues
+npm run format         # Format with oxfmt
+npm run format:check   # Check formatting
+npm run validate       # Run all checks
+npm run test           # Unit tests
+npm run test:watch     # Watch mode
+npm run test:integration  # Integration tests
+npm run test:e2e       # End-to-end tests
+npm run bench          # Benchmarks
+```
+
+## Project Structure
+
+```
+src/
+├── index.ts              # Extension entry: tool registration, caching, messages
+├── mapper.ts             # Dispatcher: routes files to language mappers
+├── formatter.ts          # Budget-aware formatting with detail reduction
+├── language-detect.ts    # Maps file extensions to languages
+├── types.ts              # Shared interfaces (FileMap, FileSymbol)
+├── enums.ts              # SymbolKind, DetailLevel
+├── constants.ts          # Thresholds (2,000 lines, 50 KB, 20 KB budget)
+└── mappers/              # Language-specific parsers
+    ├── typescript.ts     # ts-morph for TS/JS
+    ├── python.ts         # Python AST via subprocess
+    ├── go.ts             # Go AST via subprocess
+    ├── rust.ts           # tree-sitter
+    ├── cpp.ts            # tree-sitter for C/C++
+    ├── c.ts              # Regex patterns
+    ├── sql.ts            # Regex
+    ├── json.ts           # jq subprocess
+    ├── jsonl.ts          # Streaming parser
+    ├── yaml.ts           # Regex
+    ├── toml.ts           # Regex
+    ├── csv.ts            # In-process parser
+    ├── markdown.ts       # Regex
+    ├── ctags.ts          # universal-ctags fallback
+    └── fallback.ts       # Grep-based final fallback
+
+scripts/
+├── python_outline.py     # Python AST extraction
+└── go_outline.go         # Go AST extraction (compiles on first use)
+
+tests/
+├── unit/                 # Mapper and utility tests
+├── integration/          # Dispatcher, caching, budget enforcement
+├── e2e/                  # Real pi sessions via tmux
+└── fixtures/             # Sample files per language
+```
+
+## How It Works
+
+The extension intercepts `read` calls and decides:
+
+1. **Small files** (≤2,000 lines, ≤50 KB): Delegate to built-in read tool
+2. **Targeted reads** (offset or limit provided): Delegate to built-in read tool
+3. **Large files:**
+   - Call built-in read for the first chunk
+   - Detect language from file extension
+   - Dispatch to a mapper (language-specific → ctags → grep fallback)
+   - Format with budget enforcement
+   - Cache the map
+   - Send as a separate `file-map` message after `tool_result`
+
+## Dependencies
+
+**npm packages:**
+- `ts-morph` - TypeScript AST analysis
+- `tree-sitter` - Parser framework
+- `tree-sitter-cpp` - C/C++ parsing
+- `tree-sitter-rust` - Rust parsing
+
+**System tools (optional):**
+- `python3` - Python mapper
+- `go` - Go mapper
+- `jq` - JSON mapper
+- `universal-ctags` - Language fallback
+
+## Acknowledgments
+
+This project was inspired by and built upon the foundation of [codemap](https://github.com/kcosr/codemap) by [kcosr](https://github.com/kcosr). Check out the original project for the ideas that made this possible.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "pi-read-map",
+  "version": "1.0.0",
+  "description": "Pi extension that adds structural file maps for large files",
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint -c .oxlintrc.json src tests",
+    "lint:fix": "oxlint -c .oxlintrc.json src tests --fix",
+    "format": "oxfmt --config .oxfmtrc.jsonc src tests",
+    "format:check": "oxfmt --config .oxfmtrc.jsonc src tests --check",
+    "validate": "npm run typecheck && npm run lint && npm run format:check",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "vitest run tests/integration/",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "bench": "vitest bench"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "extension",
+    "read",
+    "file-map",
+    "code-navigation"
+  ],
+  "author": "Will Hampson",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Whamp/pi-read-map"
+  },
+  "homepage": "https://github.com/Whamp/pi-read-map#readme",
+  "bugs": {
+    "url": "https://github.com/Whamp/pi-read-map/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "tree-sitter": "0.22.4",
+    "tree-sitter-cpp": "0.23.4",
+    "tree-sitter-rust": "0.23.3",
+    "ts-morph": "27.0.2"
+  },
+  "devDependencies": {
+    "@factory/eslint-plugin": "^0.1.0",
+    "@mariozechner/pi-coding-agent": "^0.52.9",
+    "@sinclair/typebox": "^0.34.0",
+    "@types/node": "^22.0.0",
+    "oxfmt": "^0.28.0",
+    "typescript": "^5.7.0",
+    "ultracite": "^7.1.5",
+    "vitest": "^3.0.0"
+  },
+  "overrides": {
+    "tree-sitter": "$tree-sitter"
+  }
+}

package/scripts/go_outline.go

@@ -0,0 +1,239 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"os"
+	"strings"
+)
+
+type Symbol struct {
+	Name      string   `json:"name"`
+	Kind      string   `json:"kind"`
+	StartLine int      `json:"startLine"`
+	EndLine   int      `json:"endLine"`
+	Signature string   `json:"signature,omitempty"`
+	Modifiers []string `json:"modifiers,omitempty"`
+	Children  []Symbol `json:"children,omitempty"`
+}
+
+type OutlineResult struct {
+	Package string   `json:"package"`
+	Imports []string `json:"imports,omitempty"`
+	Symbols []Symbol `json:"symbols"`
+	Error   string   `json:"error,omitempty"`
+}
+
+func formatType(expr ast.Expr) string {
+	if expr == nil {
+		return ""
+	}
+	switch t := expr.(type) {
+	case *ast.Ident:
+		return t.Name
+	case *ast.SelectorExpr:
+		return formatType(t.X) + "." + t.Sel.Name
+	case *ast.StarExpr:
+		return "*" + formatType(t.X)
+	case *ast.ArrayType:
+		return "[]" + formatType(t.Elt)
+	case *ast.MapType:
+		return "map[" + formatType(t.Key) + "]" + formatType(t.Value)
+	case *ast.InterfaceType:
+		return "interface{}"
+	case *ast.StructType:
+		return "struct{}"
+	case *ast.FuncType:
+		return "func(...)"
+	case *ast.ChanType:
+		return "chan " + formatType(t.Value)
+	case *ast.Ellipsis:
+		return "..." + formatType(t.Elt)
+	default:
+		return "?"
+	}
+}
+
+func formatParams(fields *ast.FieldList) string {
+	if fields == nil || len(fields.List) == 0 {
+		return "()"
+	}
+	var parts []string
+	for _, f := range fields.List {
+		typeStr := formatType(f.Type)
+		if len(f.Names) == 0 {
+			parts = append(parts, typeStr)
+		} else {
+			for _, name := range f.Names {
+				parts = append(parts, name.Name+" "+typeStr)
+			}
+		}
+	}
+	return "(" + strings.Join(parts, ", ") + ")"
+}
+
+func formatResults(fields *ast.FieldList) string {
+	if fields == nil || len(fields.List) == 0 {
+		return ""
+	}
+	if len(fields.List) == 1 && len(fields.List[0].Names) == 0 {
+		return " " + formatType(fields.List[0].Type)
+	}
+	var parts []string
+	for _, f := range fields.List {
+		typeStr := formatType(f.Type)
+		if len(f.Names) == 0 {
+			parts = append(parts, typeStr)
+		} else {
+			for _, name := range f.Names {
+				parts = append(parts, name.Name+" "+typeStr)
+			}
+		}
+	}
+	return " (" + strings.Join(parts, ", ") + ")"
+}
+
+func extractSymbols(fset *token.FileSet, file *ast.File) []Symbol {
+	var symbols []Symbol
+
+	for _, decl := range file.Decls {
+		switch d := decl.(type) {
+		case *ast.GenDecl:
+			switch d.Tok {
+			case token.TYPE:
+				for _, spec := range d.Specs {
+					ts := spec.(*ast.TypeSpec)
+					sym := Symbol{
+						Name:      ts.Name.Name,
+						StartLine: fset.Position(d.Pos()).Line,
+						EndLine:   fset.Position(d.End()).Line,
+					}
+					switch t := ts.Type.(type) {
+					case *ast.StructType:
+						sym.Kind = "struct"
+						// Extract struct fields as children
+						if t.Fields != nil {
+							for _, field := range t.Fields.List {
+								for _, name := range field.Names {
+									sym.Children = append(sym.Children, Symbol{
+										Name:      name.Name,
+										Kind:      "field",
+										StartLine: fset.Position(field.Pos()).Line,
+										EndLine:   fset.Position(field.End()).Line,
+										Signature: formatType(field.Type),
+									})
+								}
+							}
+						}
+					case *ast.InterfaceType:
+						sym.Kind = "interface"
+						// Extract interface methods as children
+						if t.Methods != nil {
+							for _, method := range t.Methods.List {
+								for _, name := range method.Names {
+									if ft, ok := method.Type.(*ast.FuncType); ok {
+										sym.Children = append(sym.Children, Symbol{
+											Name:      name.Name,
+											Kind:      "method",
+											StartLine: fset.Position(method.Pos()).Line,
+											EndLine:   fset.Position(method.End()).Line,
+											Signature: formatParams(ft.Params) + formatResults(ft.Results),
+										})
+									}
+								}
+							}
+						}
+					default:
+						sym.Kind = "type"
+					}
+					symbols = append(symbols, sym)
+				}
+			case token.CONST, token.VAR:
+				kind := "variable"
+				if d.Tok == token.CONST {
+					kind = "constant"
+				}
+				for _, spec := range d.Specs {
+					vs := spec.(*ast.ValueSpec)
+					for _, name := range vs.Names {
+						if name.Name == "_" {
+							continue
+						}
+						sym := Symbol{
+							Name:      name.Name,
+							Kind:      kind,
+							StartLine: fset.Position(vs.Pos()).Line,
+							EndLine:   fset.Position(vs.End()).Line,
+						}
+						if vs.Type != nil {
+							sym.Signature = formatType(vs.Type)
+						}
+						symbols = append(symbols, sym)
+					}
+				}
+			}
+		case *ast.FuncDecl:
+			sym := Symbol{
+				Name:      d.Name.Name,
+				StartLine: fset.Position(d.Pos()).Line,
+				EndLine:   fset.Position(d.End()).Line,
+				Signature: formatParams(d.Type.Params) + formatResults(d.Type.Results),
+			}
+			if d.Recv != nil && len(d.Recv.List) > 0 {
+				sym.Kind = "method"
+				// Add receiver info
+				recv := d.Recv.List[0]
+				recvType := formatType(recv.Type)
+				sym.Signature = "(" + recvType + ") " + sym.Name + sym.Signature
+				sym.Name = recvType + "." + d.Name.Name
+			} else {
+				sym.Kind = "function"
+			}
+			symbols = append(symbols, sym)
+		}
+	}
+
+	return symbols
+}
+
+func extractImports(file *ast.File) []string {
+	var imports []string
+	for _, imp := range file.Imports {
+		path := strings.Trim(imp.Path.Value, `"`)
+		if imp.Name != nil && imp.Name.Name != "." && imp.Name.Name != "_" {
+			imports = append(imports, imp.Name.Name+" "+path)
+		} else {
+			imports = append(imports, path)
+		}
+	}
+	return imports
+}
+
+func main() {
+	if len(os.Args) < 2 {
+		result := OutlineResult{Error: "usage: go_outline <file.go>"}
+		json.NewEncoder(os.Stdout).Encode(result)
+		os.Exit(1)
+	}
+
+	filePath := os.Args[1]
+
+	fset := token.NewFileSet()
+	file, err := parser.ParseFile(fset, filePath, nil, parser.ParseComments)
+	if err != nil {
+		result := OutlineResult{Error: fmt.Sprintf("parse error: %v", err)}
+		json.NewEncoder(os.Stdout).Encode(result)
+		os.Exit(1)
+	}
+
+	result := OutlineResult{
+		Package: file.Name.Name,
+		Imports: extractImports(file),
+		Symbols: extractSymbols(fset, file),
+	}
+
+	json.NewEncoder(os.Stdout).Encode(result)
+}