@tduyng/pi-outline

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.

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.

How it works

outline(path: "src/goal.ts", depth: 1)

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].

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

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.

Without the guard the tool still works, it just stops being the thing that catches an oversized read.

Install

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.