pi-read-map 1.0.0 → 1.2.0

package/.husky/pre-commit

@@ -0,0 +1 @@
+npm run validate && npm run test -- --exclude='**/e2e/**'

package/.jscpd.json

@@ -0,0 +1,7 @@
+{
+  "threshold": 15,
+  "minTokens": 50,
+  "minLines": 5,
+  "reporters": ["console"],
+  "ignore": ["**/fixtures/**", "**/node_modules/**"]
+}

package/AGENTS.md

@@ -0,0 +1,158 @@
+# AGENTS.md
+
+> Last updated: 2026-02-14
+
+Pi extension that augments the built-in `read` tool with structural file maps for large files (>2,000 lines or >50 KB). Intercepts `read` calls, generates symbol maps via language-specific parsers, and sends them as separate `file-map` messages after the tool result.
+
+## Commands (verified 2026-02-14)
+
+| Command | Purpose | ~Time |
+|---------|---------|-------|
+| `npm run test` | Unit + integration tests (vitest) | ~2s |
+| `npm run test:integration` | Integration tests only | ~1s |
+| `npm run test:e2e` | E2E tests (requires pi + tmux) | ~60s |
+| `npm run bench` | Benchmarks | ~5s |
+| `npm run typecheck` | `tsc --noEmit` | ~2s |
+| `npm run lint` | oxlint (via npx) | ~1s |
+| `npm run lint:fix` | Auto-fix lint issues | ~1s |
+| `npm run format` | Format with oxfmt | ~1s |
+| `npm run format:check` | Check formatting | ~1s |
+| `npm run validate` | typecheck + lint + format:check | ~4s |
+
+## File Map
+
+```
+src/
+├── index.ts              → Extension entry: tool registration, caching, message rendering
+├── mapper.ts             → Dispatcher: routes files to language mappers, fallback chain
+├── formatter.ts          → Budget-aware formatting with progressive detail reduction
+├── language-detect.ts    → File extension → language mapping
+├── types.ts              → FileMap, FileSymbol, MapOptions, FileMapMessageDetails
+├── enums.ts              → SymbolKind (21 kinds), DetailLevel (5 levels)
+├── constants.ts          → THRESHOLDS: lines, bytes, budget tiers
+└── mappers/              → One mapper per language (17 total)
+    ├── typescript.ts     → ts-morph (handles TS + JS)
+    ├── rust.ts           → tree-sitter-rust
+    ├── cpp.ts            → tree-sitter-cpp (C++ and .h files)
+    ├── clojure.ts        → tree-sitter-clojure (.clj, .cljs, .cljc, .edn)
+    ├── python.ts         → subprocess: scripts/python_outline.py
+    ├── go.ts             → subprocess: scripts/go_outline.go
+    ├── json.ts           → subprocess: jq
+    ├── c.ts              → Regex patterns
+    ├── sql.ts            → Regex
+    ├── markdown.ts       → Regex
+    ├── yaml.ts           → Regex
+    ├── toml.ts           → Regex
+    ├── csv.ts            → In-process streaming
+    ├── jsonl.ts          → In-process streaming
+    ├── ctags.ts          → universal-ctags fallback
+    └── fallback.ts       → Grep-based final fallback
+
+scripts/
+├── python_outline.py     → Python AST extraction (called by python mapper)
+├── go_outline.go         → Go AST extraction (compiled on first use)
+└── go_outline             → Compiled Go binary
+
+tests/
+├── unit/                 → Mapper tests, formatter tests, language detection
+├── integration/          → Dispatch, caching, budget enforcement, map messages
+├── e2e/                  → Real pi sessions via tmux (vitest.e2e.config.ts)
+├── fixtures/             → Sample files per language
+├── benchmarks/           → Mapper performance benchmarks
+└── helpers/              → Test utilities (pi-runner, constants, tree-sitter)
+
+docs/
+├── plans/                → Implementation plans (phased)
+├── handoffs/             → Session handoff notes
+├── reviews/              → Phase review documents
+└── todo/                 → Outstanding work items
+```
+
+## Architecture
+
+Dispatch chain: `index.ts` → `mapper.ts` → language mapper → ctags → fallback.
+
+Budget enforcement in `formatter.ts` uses progressive detail reduction:
+- 10 KB: full detail (signatures, modifiers)
+- 15 KB: compact (drop signatures)
+- 20 KB: minimal (names + line ranges only)
+- 50 KB: outline (top-level symbols only)
+- 100 KB: truncated (first/last 50 symbols, hard cap)
+
+Maps are cached in-memory by `(filePath, mtime)`. Delivered as custom `file-map` messages via `pi.sendMessage()` after the `tool_result` event.
+
+## Golden Samples
+
+| For | Reference | Key patterns |
+|-----|-----------|--------------|
+| New mapper | `src/mappers/csv.ts` | Simple, clean, regex-free in-process parsing |
+| Complex mapper | `src/mappers/typescript.ts` | ts-morph AST walk, nested symbols, modifiers |
+| Tree-sitter mapper | `src/mappers/clojure.ts` | tree-sitter AST walk, reader conditionals, platform modifiers |
+| Subprocess mapper | `src/mappers/python.ts` | Calls external script, parses JSON output |
+| Unit test | `tests/unit/mappers/csv.test.ts` | Fixture-based, edge cases, null returns |
+| Integration test | `tests/integration/budget-enforcement.test.ts` | Tests progressive detail reduction |
+
+## Heuristics
+
+| When | Do |
+|------|-----|
+| Adding a new language | Create `src/mappers/<lang>.ts`, add to `MAPPERS` in `mapper.ts`, add extension in `language-detect.ts`, add unit test |
+| Mapper returns too many symbols | Rely on `formatter.ts` budget system, don't filter in mappers |
+| Mapper can't parse a file | Return `null` — the dispatch chain falls through to ctags then fallback |
+| Adding a new SymbolKind | Add to `enums.ts`, update formatter if display differs |
+| Testing mappers | Use fixture files in `tests/fixtures/`, never mock file reads |
+| E2E tests | Require pi installed + tmux; use `tests/helpers/pi-runner.ts` |
+
+## Boundaries
+
+**Always:**
+- Return `FileMap` or `null` from mappers (never throw)
+- Include `startLine` and `endLine` for every symbol (1-indexed)
+- Run `npm run validate` before committing
+- Use existing `FileSymbol` interface for all symbol data
+
+**Ask first:**
+- Changing budget thresholds in `constants.ts`
+- Adding new `DetailLevel` variants
+- Modifying the tool description in `index.ts`
+- Changes to the `tool_result` event handler
+
+**Never:**
+- Filter symbols in mappers based on budget (formatter handles this)
+- Add runtime dependencies without discussing (binary size matters for pi extensions)
+- Use `any` types
+- Disable lint rules
+
+## Codebase State
+
+- `oxlint` installed as devDependency; `npm run lint` exits cleanly (0 errors, 0 warnings)
+- `tree-sitter` pinned to 0.22.4 due to peer dependency conflicts (see `docs/todo/upgrade-tree-sitter-0.26.md`)
+- `tree-sitter-clojure` pinned to commit SHA from `github:ghoseb/tree-sitter-clojure` (third-party fork)
+- Go outline script auto-compiles on first use; compiled binary checked in at `scripts/go_outline`
+- Phase 1-5 of implementation plan complete; remaining TODOs in `docs/todo/`
+
+| Docstrings / JSDoc | `FileSymbol.docstring?: string` | First-line summary of doc comments |
+| Exported flag | `FileSymbol.isExported?: boolean` | Whether symbol is part of public API |
+| Required imports | `FileMap.imports: string[]` | Always an array, never undefined |
+
+## Terminology
+
+| Docstring | First line of a JSDoc / doc comment on a symbol |
+| isExported | Boolean flag: true if symbol is part of the module's public API |
+| Term | Means |
+|------|-------|
+| Map | Structural outline of a file's symbols with line ranges |
+| Mapper | Language-specific parser that produces a `FileMap` |
+| Budget | Maximum byte size for formatted map output |
+| Detail level | How much information each symbol carries (full → truncated) |
+| Fallback chain | mapper → ctags → grep when parsers fail |
+| Pending map | Map waiting to be sent after `tool_result` event fires |
+
+## Tech Stack
+
+- **Runtime:** Node.js (ES2022 modules)
+- **Language:** TypeScript (strict, `noUncheckedIndexedAccess`)
+- **Testing:** Vitest (unit/integration: 10s timeout, e2e: 60s timeout)
+- **Linting:** oxlint + oxfmt
+- **Parsing:** ts-morph, tree-sitter (rust, cpp, clojure), regex, subprocess (Python/Go/jq)
+- **Framework:** pi extension API (`@mariozechner/pi-coding-agent`)

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.2.0] - 2026-02-14
+
+### Added
+
+- **Clojure mapper** — tree-sitter-based parser for `.clj`, `.cljs`, `.cljc`, and `.edn` files. Extracts `ns`, `defn`, `defn-`, `def`, `defonce`, `defmacro`, `defmulti`, `defmethod`, `defprotocol`, `defrecord`, and `deftype` forms with docstrings, signatures, modifiers, and protocol method children. Supports reader conditionals (`#?`) with per-platform annotations. Contributed by [Baishampayan Ghose](https://github.com/ghoseb). ([#2](https://github.com/Whamp/pi-read-map/pull/2))
+- Clojure demo asset (`clojure/core.clj` from the official Clojure repo)
+
+### Changed
+
+- Tree-sitter tests use `describe.runIf` for conditional execution
+
+## [1.1.0] - 2026-02-10
+
+### Added
+
+- Docstring extraction (`FileSymbol.docstring`) across all mappers
+- Export flag (`FileSymbol.isExported`) across all mappers
+- Required imports (`FileMap.imports`) across all mappers
+- Skipped read recovery — detects reads cancelled by steering queue and re-issues them
+- JSONL session-aware maps for pi session files
+- Directory read handling with EISDIR error and `ls` fallback
+
+### Fixed
+
+- Symbol duplication in file map output
+- oxlint warnings and errors resolved across codebase
+
+### Changed
+
+- Test helpers refactored; `models.ts` renamed to `constants.ts`
+
+## [1.0.0] - 2026-02-09
+
+Initial release.
+
+### Added
+
+- Structural file maps for large files (>2,000 lines or >50 KB)
+- 14 language mappers: TypeScript, JavaScript, Python, Go, Rust, C, C++, SQL, JSON, JSONL, YAML, TOML, CSV, Markdown
+- Budget-aware formatting with progressive detail reduction (10 KB full → 100 KB truncated)
+- In-memory caching by file path and modification time
+- Fallback chain: language mapper → universal-ctags → grep
+- Custom `file-map` messages delivered after `tool_result` events
+- E2E test infrastructure via tmux
+- Demo assets from 10 major open-source projects

package/README.md

@@ -23,22 +23,20 @@ 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
+- **Supports 17 languages** through specialized parsers: TypeScript, JavaScript, Python, Go, Rust, C, C++, Clojure, ClojureScript, SQL, JSON, JSONL, YAML, TOML, CSV, Markdown, EDN
+- **Extracts structural outlines** — functions, classes, and their line ranges — typically under 1% of file size
+- **Enforces budgets** through progressive detail reduction (10 KB full → 15 KB compact → 20 KB minimal → 50 KB outline → 100 KB hard cap)
 - **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)
+### From Git
 
 ```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
@@ -132,6 +130,7 @@ src/
     ├── go.ts             # Go AST via subprocess
     ├── rust.ts           # tree-sitter
     ├── cpp.ts            # tree-sitter for C/C++
+    ├── clojure.ts        # tree-sitter for Clojure/ClojureScript/EDN
     ├── c.ts              # Regex patterns
     ├── sql.ts            # Regex
     ├── json.ts           # jq subprocess
@@ -175,6 +174,7 @@ The extension intercepts `read` calls and decides:
 - `tree-sitter` - Parser framework
 - `tree-sitter-cpp` - C/C++ parsing
 - `tree-sitter-rust` - Rust parsing
+- `tree-sitter-clojure` - Clojure parsing
 
 **System tools (optional):**
 - `python3` - Python mapper
@@ -186,6 +186,10 @@ The extension intercepts `read` calls and decides:
 
 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.
 
+### Contributors
+
+- [Baishampayan Ghose](https://github.com/ghoseb) — Clojure tree-sitter mapper and [tree-sitter-clojure](https://github.com/ghoseb/tree-sitter-clojure) grammar
+
 ## License
 
 MIT

package/demo.md

@@ -0,0 +1,108 @@
+# Skipped Read Recovery
+
+*2026-02-12T16:06:08Z*
+
+When pi-read-map generates a file map for a large file, it sends the map via `pi.sendMessage()`. During streaming, this defaults to `deliverAs: "steer"`, which pushes the message into the agent's steering queue. After each tool execution, the agent loop checks the steering queue — if non-empty, it skips all remaining tool calls with 'Skipped due to queued user message.'
+
+This means: if the agent requests 3 parallel reads and the first file triggers a map, the other 2 reads are cancelled.
+
+**Skipped Read Recovery** detects these cancelled reads at `turn_end` and sends a `followUp` message instructing the agent to re-issue them.
+
+## How It Works
+
+1. A `turn_end` event handler inspects all tool results for the turn
+2. It identifies read results containing 'Skipped due to queued user message.'
+3. It extracts the file paths from the assistant message's `toolCall` entries
+4. It sends a `read-recovery` followUp message listing the interrupted paths
+5. The followUp triggers a new turn where the agent re-reads the skipped files
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+| `src/index.ts` | Added `turn_end` handler and `read-recovery` message renderer |
+| `tests/integration/skipped-read-recovery.test.ts` | 9 new tests covering detection, edge cases, and rendering |
+
+## Tests
+
+The new test suite covers:
+
+```bash
+cd /home/will/projects/pi-read-map && npx vitest run tests/integration/skipped-read-recovery.test.ts 2>&1 | tail -20
+```
+
+```output
+
+ RUN  v3.2.4 /home/will/projects/pi-read-map
+
+ ✓ tests/integration/skipped-read-recovery.test.ts (9 tests) 6ms
+
+ Test Files  1 passed (1)
+      Tests  9 passed (9)
+   Start at  08:06:28
+   Duration  845ms (transform 139ms, setup 0ms, collect 625ms, tests 6ms, environment 0ms, prepare 61ms)
+
+```
+
+## Full Validation
+
+Typecheck, lint, format, and dead-code detection all pass:
+
+```bash
+cd /home/will/projects/pi-read-map && npm run validate 2>&1
+```
+
+```output
+
+> pi-read-map@1.0.0 validate
+> npm run typecheck && npm run lint && npm run format:check && npm run dead-code
+
+
+> pi-read-map@1.0.0 typecheck
+> tsc --noEmit
+
+
+> pi-read-map@1.0.0 lint
+> oxlint -c .oxlintrc.json src tests
+
+Found 0 warnings and 0 errors.
+Finished in 214ms on 61 files with 427 rules using 16 threads.
+
+> pi-read-map@1.0.0 format:check
+> oxfmt --config .oxfmtrc.jsonc src tests --check
+
+Checking formatting...
+
+All matched files use the correct format.
+Finished in 556ms on 73 files using 16 threads.
+
+> pi-read-map@1.0.0 dead-code
+> knip
+
+```
+
+## Full Test Suite
+
+All 197 tests pass (27 test files), including the 9 new recovery tests:
+
+```bash
+cd /home/will/projects/pi-read-map && npm run test 2>&1 | grep -E "(Test Files|Tests|✓ tests/integration)" 
+```
+
+```output
+ ✓ tests/integration/mapper-dispatch.test.ts (8 tests) 627ms
+ ✓ tests/integration/budget-enforcement.test.ts (8 tests) 693ms
+ ✓ tests/integration/directory-read.test.ts (4 tests) 14ms
+ ✓ tests/integration/cache-behavior.test.ts (4 tests) 262ms
+ ✓ tests/integration/skipped-read-recovery.test.ts (9 tests) 7ms
+ ✓ tests/integration/separate-map-message.test.ts (6 tests) 9ms
+ ✓ tests/integration/extension-load.test.ts (6 tests) 6ms
+ Test Files  27 passed (27)
+      Tests  197 passed (197)
+```
+
+## Implementation Detail
+
+The recovery handler in `src/index.ts` narrows the `AgentMessage` union to `AssistantMessage` (via `role === "assistant"` check) and then matches skipped `toolCallId`s against the `toolCall` entries in the assistant content to extract file paths. The recovery message is delivered as a `followUp`, which triggers a new agent turn without entering the steering queue.
+
+A custom `read-recovery` message renderer shows a compact summary in collapsed view (e.g., 'Recovery: 2 interrupted read(s) being re-issued') and the full path list when expanded.

package/knip.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/knip@latest/schema.json",
+  "entry": ["src/index.ts"],
+  "project": ["src/**/*.ts"],
+  "ignore": ["scripts/**", "tests/fixtures/**"],
+  "ignoreDependencies": [
+    "@factory/eslint-plugin",
+    "ultracite",
+    "@mariozechner/pi-tui"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-read-map",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Pi extension that adds structural file maps for large files",
   "type": "module",
   "pi": {
@@ -14,12 +14,15 @@
     "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",
+    "dead-code": "knip",
+    "duplicates": "jscpd src --min-tokens 50 --min-lines 5",
+    "validate": "npm run typecheck && npm run lint && npm run format:check && npm run dead-code",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:integration": "vitest run tests/integration/",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
-    "bench": "vitest bench"
+    "bench": "vitest bench",
+    "prepare": "husky"
   },
   "keywords": [
     "pi-package",
@@ -41,6 +44,7 @@
   "license": "MIT",
   "dependencies": {
     "tree-sitter": "0.22.4",
+    "tree-sitter-clojure": "github:ghoseb/tree-sitter-clojure#78928e6",
     "tree-sitter-cpp": "0.23.4",
     "tree-sitter-rust": "0.23.3",
     "ts-morph": "27.0.2"
@@ -50,7 +54,11 @@
     "@mariozechner/pi-coding-agent": "^0.52.9",
     "@sinclair/typebox": "^0.34.0",
     "@types/node": "^22.0.0",
+    "husky": "^9.1.7",
+    "jscpd": "^4.0.8",
+    "knip": "^5.83.1",
     "oxfmt": "^0.28.0",
+    "oxlint": "^1.46.0",
     "typescript": "^5.7.0",
     "ultracite": "^7.1.5",
     "vitest": "^3.0.0"

package/scripts/go_outline.go

@@ -18,6 +18,8 @@ type Symbol struct {
 	Signature string   `json:"signature,omitempty"`
 	Modifiers []string `json:"modifiers,omitempty"`
 	Children  []Symbol `json:"children,omitempty"`
+	Docstring string   `json:"docstring,omitempty"`
+	IsExported bool    `json:"isExported"`
 }
 
 type OutlineResult struct {
@@ -106,10 +108,16 @@ func extractSymbols(fset *token.FileSet, file *ast.File) []Symbol {
 			case token.TYPE:
 				for _, spec := range d.Specs {
 					ts := spec.(*ast.TypeSpec)
+					doc := ts.Doc
+					if doc == nil {
+						doc = d.Doc
+					}
 					sym := Symbol{
-						Name:      ts.Name.Name,
-						StartLine: fset.Position(d.Pos()).Line,
-						EndLine:   fset.Position(d.End()).Line,
+						Name:       ts.Name.Name,
+						StartLine:  fset.Position(d.Pos()).Line,
+						EndLine:    fset.Position(d.End()).Line,
+						Docstring:  getDocstringFirstLine(doc),
+						IsExported: isExportedName(ts.Name.Name),
 					}
 					switch t := ts.Type.(type) {
 					case *ast.StructType:
@@ -163,10 +171,12 @@ func extractSymbols(fset *token.FileSet, file *ast.File) []Symbol {
 							continue
 						}
 						sym := Symbol{
-							Name:      name.Name,
-							Kind:      kind,
-							StartLine: fset.Position(vs.Pos()).Line,
-							EndLine:   fset.Position(vs.End()).Line,
+							Name:       name.Name,
+							Kind:       kind,
+							StartLine:  fset.Position(vs.Pos()).Line,
+							EndLine:    fset.Position(vs.End()).Line,
+							Docstring:  getDocstringFirstLine(d.Doc),
+							IsExported: isExportedName(name.Name),
 						}
 						if vs.Type != nil {
 							sym.Signature = formatType(vs.Type)
@@ -177,10 +187,12 @@ func extractSymbols(fset *token.FileSet, file *ast.File) []Symbol {
 			}
 		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),
+				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),
+				Docstring:  getDocstringFirstLine(d.Doc),
+				IsExported: isExportedName(d.Name.Name),
 			}
 			if d.Recv != nil && len(d.Recv.List) > 0 {
 				sym.Kind = "method"
@@ -199,6 +211,26 @@ func extractSymbols(fset *token.FileSet, file *ast.File) []Symbol {
 	return symbols
 }
 
+func getDocstringFirstLine(doc *ast.CommentGroup) string {
+	if doc == nil {
+		return ""
+	}
+	text := doc.Text()
+	if text == "" {
+		return ""
+	}
+	lines := strings.SplitN(text, "\n", 2)
+	return strings.TrimSpace(lines[0])
+}
+
+func isExportedName(name string) bool {
+	if len(name) == 0 {
+		return false
+	}
+	r := []rune(name)
+	return r[0] >= 'A' && r[0] <= 'Z'
+}
+
 func extractImports(file *ast.File) []string {
 	var imports []string
 	for _, imp := range file.Imports {

package/scripts/python_outline.py

@@ -82,6 +82,18 @@ def get_end_line(node: ast.AST) -> int:
     return getattr(node, 'lineno', 0)
 
 
+def get_docstring_first_line(node: ast.AST) -> str | None:
+    """Extract the first line of a docstring from a class or function."""
+    try:
+        doc = ast.get_docstring(node)
+    except TypeError:
+        return None
+    if not doc:
+        return None
+    first_line = doc.split('\n')[0].strip()
+    return first_line if first_line else None
+
+
 def extract_symbols(node: ast.AST, parent_end: int | None = None) -> list[dict]:
     """Recursively extract symbols from AST."""
     symbols = []
@@ -113,6 +125,8 @@ def extract_symbols(node: ast.AST, parent_end: int | None = None) -> list[dict]:
             "endLine": end_line,
             "modifiers": modifiers,
             "children": children if children else None,
+            "docstring": get_docstring_first_line(node),
+            "is_exported": not node.name.startswith("_"),
         })
     
     elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
@@ -132,6 +146,8 @@ def extract_symbols(node: ast.AST, parent_end: int | None = None) -> list[dict]:
             "endLine": end_line,
             "signature": get_signature(node),
             "modifiers": modifiers if modifiers else None,
+            "docstring": get_docstring_first_line(node),
+            "is_exported": not node.name.startswith("_"),
         })
     
     elif isinstance(node, ast.Assign):

package/src/formatter.ts

@@ -43,14 +43,23 @@ function formatSymbol(
 
   let { name } = symbol;
 
-  // Add modifiers for full detail
-  if (level === DetailLevel.Full && symbol.modifiers?.length) {
-    name = `${symbol.modifiers.join(" ")} ${name}`;
-  }
-
-  // Add signature for full detail
-  if (level === DetailLevel.Full && symbol.signature) {
-    name = `${name}${symbol.signature}`;
+  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
@@ -79,6 +88,11 @@ function formatSymbol(
     }
   }
 
+  // Append docstring at Full detail level
+  if (level === DetailLevel.Full && symbol.docstring) {
+    formatted += ` — ${symbol.docstring}`;
+  }
+
   return formatted;
 }
 
@@ -155,7 +169,6 @@ export function formatFileMap(map: FileMap, level?: DetailLevel): string {
   if (
     effectiveLevel !== DetailLevel.Outline &&
     effectiveLevel !== DetailLevel.Truncated &&
-    map.imports?.length &&
     map.imports.length > 0
   ) {
     const importList =
@@ -245,7 +258,7 @@ export function reduceToLevel(map: FileMap, level: DetailLevel): FileMap {
     return {
       ...map,
       detailLevel: DetailLevel.Outline,
-      imports: undefined,
+      imports: [],
       symbols: map.symbols.map((s) => ({
         name: s.name,
         kind: s.kind,
@@ -256,7 +269,7 @@ export function reduceToLevel(map: FileMap, level: DetailLevel): FileMap {
   }
 
   if (level === DetailLevel.Minimal) {
-    // Remove signatures but keep children flattened
+    // Remove signatures and docstrings but keep children flattened
     return {
       ...map,
       detailLevel: DetailLevel.Minimal,
@@ -265,11 +278,13 @@ export function reduceToLevel(map: FileMap, level: DetailLevel): FileMap {
         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,
         })),
       })),
     };
@@ -294,6 +309,8 @@ function stripSignatures(symbol: FileSymbol): FileSymbol {
     startLine: symbol.startLine,
     endLine: symbol.endLine,
     modifiers: symbol.modifiers,
+    docstring: symbol.docstring,
+    isExported: symbol.isExported,
     children: symbol.children?.map(stripSignatures),
   };
 }
@@ -332,7 +349,7 @@ export function reduceToTruncated(
     ...map,
     symbols: [...firstSymbols, ...lastSymbols],
     detailLevel: DetailLevel.Truncated,
-    imports: undefined,
+    imports: [],
     truncatedInfo: {
       totalSymbols: total,
       shownSymbols: symbolsEach * 2,