@tduyng/pi-outline 0.0.2 → 0.0.4

package/README.md

@@ -1,23 +1,48 @@
 # @tduyng/pi-outline
 
-Declarations of a source file with the line span of each, so a read fetches one body by offset and limit instead of the whole file.
+A map of a source file instead of the file. One call lists every declaration with its line span, so the read that follows fetches one body.
 
-## The tool
+A 1,213-line TypeScript file puts 51 KB into the transcript, and every later turn of the session re-reads it. The depth-1 outline of that file is 47 rows, about 3 KB, and it names the lines worth reading.
 
-`outline` takes a `path` and an optional `depth` (0 to 5, default 1). It prints one row per declaration: the span, then the declaration line. Members sit under their class or impl, one indent per level. A row whose declaration has children beyond `depth` ends in `[N nested]`.
+## How it works
 
-Covered: TypeScript and JavaScript (functions, classes, interfaces, type aliases, enums, and class methods), Python (`def` and `class`), Go (`func` and `type`), Rust (`fn`, `struct`, `enum`, `trait`, `impl`, `mod`), and Markdown headings. Headings inside code fences are ignored.
+```text
+outline(path: "src/goal.ts", depth: 1)
+```
 
-## Why it is cheap
+Depth runs from 0 to 5 and defaults to 1. Depth 0 lists top-level declarations, each extra level adds members, and a row with children past the depth ends in `[N nested]`.
 
-A big read is blocked by pi-subagent's bulk-read guard, and the block message now names `outline` first. On pi-goal's `goal.ts` (1,213 lines, 51KB) the depth-1 outline is 47 rows, 3.4KB. A whole read would put all 51KB into context and re-bill it on every later turn.
+| Language | Declarations |
+| --- | --- |
+| TypeScript, JavaScript | functions, classes, interfaces, type aliases, enums, class methods |
+| Python | `def`, `class` |
+| Go | `func`, `type` |
+| Rust | `fn`, `struct`, `enum`, `trait`, `impl`, `mod` |
+| Markdown | headings |
 
-## Limits
+Headings inside code fences are ignored.
+
+There is no parser. A parser means a dependency, a language server, and a version of both that disagrees with the repository. The outline is built from single-line rules over the text, and spans come from indentation: a declaration runs until the next line at the same or a lower indent, and includes the closing brace that follows its body.
+
+That covers the languages people actually outline, and a miss is visible. A file the rules do not cover gets a line saying so, with grep and a ranged read as the fallback.
+
+## With the read guard
 
-No parser is used, so the rules are regular expressions over single lines. Spans come from indentation: a span runs to the next line at the same or a lower indent, and includes the closing brace that follows the body. Expect an occasional missed declaration on unusual formatting, and an object-literal method may show as a member. A file the rules do not cover gets a line saying so, with grep or a ranged read as the fallback.
+pi-subagent's bulk-read guard blocks a read of a file over 350 lines, and its block message names `outline` first. The intended path is outline, then a ranged read of the one body needed.
 
-Files over 2MB are refused.
+Without the guard the tool still works, it just stops being the thing that catches an oversized read.
 
 ## Install
 
-Local checkout, as part of this dotfiles package: the root `package.json` lists `./extensions/pi-outline/src/outline.ts`.
+```bash
+pi install npm:@tduyng/pi-outline
+```
+
+Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-outline`
+
+## Limits
+
+- Files over 2 MB are refused, since the map would be bigger than the useful part.
+- At most 200 rows, and a row is cut at 120 characters.
+- Spans come from indentation, so unusual formatting can miss a declaration, and an object-literal method can show up as a member.
+- No types, no imports, no call graph.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tduyng/pi-outline",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Declarations of a source file with line spans, so a read fetches one body instead of the whole file.",
   "keywords": [
     "pi",