@tduyng/pi-outline 0.0.1 → 0.0.3

package/README.md

@@ -1,23 +1,49 @@
 # @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 `outline` call lists every declaration with its line span, so the read that follows fetches one body rather than a thousand lines.
+
+## What it costs
+
+`outline` is 161 tokens a request, and that is the whole bill.
+
+What it saves is larger and grows with the file. On a 1,213-line, 51 KB TypeScript file the depth-1 outline is 47 rows, 3.4 KB. The whole read would put 51 KB in the transcript and re-bill it on every later turn of the session, which is the cheapest mistake to make in pi and the most expensive to keep.
 
 ## The tool
 
-`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]`.
+`outline` takes a `path` and an optional `depth` from 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]`.
+
+```text
+outline(path: "src/goal.ts", depth: 1)
+```
 
-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.
+Covered:
 
-## Why it is cheap
+| 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 |
 
-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.
+Headings inside code fences are ignored.
+
+## Where it fits
+
+A read of a file over 350 lines is blocked by pi-subagent's bulk-read guard, and the block message names `outline` first. The pair is the intended path: outline, pick the span, then a ranged read of the one body you need.
+
+With no guard installed the tool still works, it just stops being the thing that catches you.
 
 ## Limits
 
-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.
+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.
 
-Files over 2MB are refused.
+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. Files over 2 MB are refused.
 
 ## 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`

package/package.json

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

package/src/declarations.ts

@@ -63,6 +63,7 @@ interface Mark {
 
 function markLines(lines: string[], language: Language): Mark[] {
     let inFence = false
+    let inTemplate = false
     return lines.map((line) => {
         const blank = line.trim() === ''
         if (language === 'markdown') {
@@ -74,9 +75,16 @@ function markLines(lines: string[], language: Language): Mark[] {
             const level = heading ? heading[1]!.length : 0
             return { blank, measure: level, declares: heading !== null, boundary: heading !== null }
         }
+        const startedInsideTemplate = inTemplate
+        if ((line.match(/(?<!\\)`/g) ?? []).length % 2 === 1) inTemplate = !inTemplate
         const measure = /^[ \t]*/.exec(line)![0].length
-        const declares = PATTERNS[language].some((pattern) => pattern.test(line))
-        return { blank, measure, declares, boundary: !blank && !CLOSER.test(line) }
+        const declares = !startedInsideTemplate && PATTERNS[language].some((pattern) => pattern.test(line))
+        return {
+            blank,
+            measure,
+            declares,
+            boundary: !startedInsideTemplate && !blank && !CLOSER.test(line)
+        }
     })
 }
 

package/src/outline.ts

@@ -33,15 +33,23 @@ export const outlineTool = {
             const text = `No outline for ${params.path}: no declaration rules for this file type. Use grep, or read with offset and limit.`
             return { content: [{ type: 'text', text }], details: undefined }
         }
-        if (statSync(absolute).size > MAX_BYTES) {
-            const text = `${params.path} is over 2MB. Use grep for a name, or read with offset and limit.`
+        try {
+            if (statSync(absolute).size > MAX_BYTES) {
+                const text = `${params.path} is over 2MB. Use grep for a name, or read with offset and limit.`
+                return { content: [{ type: 'text', text }], details: undefined }
+            }
+            const content = readFileSync(absolute, 'utf8')
+            const declarations = findDeclarations(content, language)
+            const lineCount = content.split('\n').length
+            const text = renderOutline(params.path, language, lineCount, declarations, params.depth ?? 1)
             return { content: [{ type: 'text', text }], details: undefined }
+        } catch (error) {
+            const reason = error instanceof Error ? error.message : String(error)
+            return {
+                content: [{ type: 'text', text: `Could not outline ${params.path}: ${reason}` }],
+                details: undefined
+            }
         }
-        const content = readFileSync(absolute, 'utf8')
-        const declarations = findDeclarations(content, language)
-        const lineCount = content.split('\n').length
-        const text = renderOutline(params.path, language, lineCount, declarations, params.depth ?? 1)
-        return { content: [{ type: 'text', text }], details: undefined }
     }
 } satisfies ToolDefinition<typeof parameters>