@mrclrchtr/supi-tree-sitter 1.3.0 → 1.4.0

package/README.md

@@ -1,72 +1,79 @@
 # @mrclrchtr/supi-tree-sitter
 
-Structural code analysis for PI — your agent parses code, not just text.
+Adds a `tree_sitter` tool to the [pi coding agent](https://github.com/earendil-works/pi) for parser-based structural code analysis.
 
-Grep matches strings. Tree-sitter parses structure — functions, classes, imports, call chains. The agent stops pattern-matching and starts understanding your code.
-
-## What you get
+## Install
 
-### See code structure
+```bash
+pi install npm:@mrclrchtr/supi-tree-sitter
+```
 
-Extract functions, classes, interfaces, and methods from any file. The agent knows what lives where without reading every line.
+For local development:
 
-### Trace call chains
+```bash
+pi install ./packages/supi-tree-sitter
+```
 
-Find every function call from a given location. The agent follows the code's actual shape instead of guessing from text proximity.
+After editing the source, run `/reload`.
 
-### 14 languages
+## What you get
 
-JavaScript, TypeScript, Python, Rust, Go, C, C++, Java, Kotlin, Ruby, Bash, HTML, R, SQL — get structural analysis for every project you touch.
+After install, pi gets one tool:
 
-Works standalone or alongside LSP. Grammar files are vendored — no native toolchain required at install time.
+- `tree_sitter` — inspect code structure through Tree-sitter parsers instead of plain text search
 
-## Install
+## `tree_sitter` actions
 
-```bash
-pi install npm:@mrclrchtr/supi-tree-sitter
-```
+| Action | What it is for | Current language coverage |
+| --- | --- | --- |
+| `outline` | List structural declarations such as functions, classes, interfaces, and methods | JavaScript / TypeScript only |
+| `imports` | List import statements | JavaScript / TypeScript only |
+| `exports` | List export declarations, re-exports, and export assignments | JavaScript / TypeScript only |
+| `node_at` | Show the syntax node at a position, including ancestry | Any supported grammar |
+| `query` | Run a custom Tree-sitter query against a file | Any supported grammar |
+| `callees` | Find outgoing calls from the enclosing function or method at a position | Supported for most grammars, but not all |
 
-## Quick look
+Coordinates use **1-based** line and character columns. Character positions use UTF-16 code units.
 
-The agent gets a `tree_sitter` tool with these actions:
+## Supported file families
 
-| Action | What it does |
-|--------|-------------|
-| `outline` | List functions, classes, interfaces in a file |
-| `callees` | Find all function calls from a position |
-| `imports` / `exports` | See what a file imports and exports |
-| `node_at` | Inspect the AST node at any line/column |
-| `query` | Run a custom Tree-sitter query |
+The current tool description covers:
 
-`outline`, `imports`, and `exports` are currently JavaScript/TypeScript only. `node_at`, `query`, and `callees` work across all 14 supported languages. Coordinates are 1-based, matching the `lsp` tool convention.
+- JavaScript / TypeScript (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`, `.mts`, `.cts`)
+- Python (`.py`, `.pyi`)
+- Rust (`.rs`)
+- Go (`.go`, `.mod`)
+- C / C++ (`.c`, `.h`, `.cpp`, `.hpp`, `.cc`, `.cxx`, `.hxx`, `.c++`, `.h++`)
+- Java (`.java`)
+- Kotlin (`.kt`, `.kts`)
+- Ruby (`.rb`)
+- Bash / shell (`.sh`, `.bash`, `.zsh`)
+- HTML (`.html`, `.htm`, `.xhtml`)
+- R (`.r`)
+- SQL (`.sql`)
 
 ## Package surfaces
 
-- `@mrclrchtr/supi-tree-sitter/api` — reusable parsing/session API
+- `@mrclrchtr/supi-tree-sitter/api` — reusable parsing session factory and shared result types
 - `@mrclrchtr/supi-tree-sitter/extension` — pi extension entrypoint
 
-`pi.extensions` still points at the real file path `./src/extension.ts` inside the package. The `/api` and `/extension` paths are consumer-facing package exports, not manifest aliases.
-
-## For extension developers
-
-This package exports a reusable session-scoped parsing service:
+Example:
 
 ```ts
 import { createTreeSitterSession } from "@mrclrchtr/supi-tree-sitter/api";
 
 const session = createTreeSitterSession("/project");
 
-// Check if a file is parseable
-const result = await session.canParse("src/index.ts");
-
-// Get structural outline
+const parseable = await session.canParse("src/index.ts");
 const outline = await session.outline("src/index.ts");
-
-// Trace outgoing calls from a position
 const callees = await session.calleesAt("src/index.ts", 42, 10);
 
-// Always clean up
 session.dispose();
 ```
 
-Call `dispose()` when done.
+## Source
+
+- `src/tree-sitter.ts` — tool registration and action handling
+- `src/runtime.ts` — parser and query runtime
+- `src/session.ts` — reusable session API
+- `src/outline.ts`, `src/imports.ts`, `src/exports.ts`, `src/node-at.ts`, `src/callees.ts` — structural analyses

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-tree-sitter",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "SuPi Tree-sitter extension — structural AST analysis for pi",
   "license": "MIT",
   "repository": {

package/src/api.ts

@@ -1,6 +1,6 @@
 // Public tree-sitter session factory and shared types.
 
-export { createTreeSitterSession } from "./session.ts";
+export { createTreeSitterSession } from "./session/session.ts";
 export type {
   CalleesAtResult,
   ExportRecord,

package/src/index.ts

@@ -1,6 +1,6 @@
 // Public session factory and re-exports for @mrclrchtr/supi-tree-sitter.
 
-export { createTreeSitterSession } from "./session.ts";
+export { createTreeSitterSession } from "./session/session.ts";
 export type {
   CalleesAtResult,
   ExportRecord,

package/src/{runtime.ts → session/runtime.ts}

@@ -3,9 +3,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { Language, Parser, Tree } from "web-tree-sitter";
-import { nodeToRange } from "./coordinates.ts";
-import { detectGrammar, resolveGrammarWasmPath } from "./language.ts";
-import type { GrammarId, QueryCapture, TreeSitterResult } from "./types.ts";
+import { nodeToRange } from "../coordinates.ts";
+import { detectGrammar, resolveGrammarWasmPath } from "../language.ts";
+import type { GrammarId, QueryCapture, TreeSitterResult } from "../types.ts";
 
 interface ParserEntry {
   parser: Parser;

package/src/{session.ts → session/session.ts}

@@ -1,14 +1,13 @@
 // Session factory — creates a TreeSitterSession bound to a working directory.
 
-import { detectGrammar, isJsTsGrammar } from "./language.ts";
-import { TreeSitterRuntime } from "./runtime.ts";
+import { detectGrammar, isJsTsGrammar } from "../language.ts";
 import {
   extractExports,
   extractImports,
   extractOutline,
   lookupCalleesAt,
   lookupNodeAt,
-} from "./structure.ts";
+} from "../tool/structure.ts";
 import type {
   CalleesAtResult,
   ExportRecord,
@@ -18,7 +17,8 @@ import type {
   QueryCapture,
   TreeSitterResult,
   TreeSitterSession,
-} from "./types.ts";
+} from "../types.ts";
+import { TreeSitterRuntime } from "./runtime.ts";
 
 /**
  * Create a new Tree-sitter session bound to the given working directory.

package/src/{callees.ts → tool/callees.ts}

@@ -1,8 +1,8 @@
 // Structural callee extraction — enclosing-scope lookup with per-language queries.
 
-import { detectGrammar } from "./language.ts";
-import type { TreeSitterRuntime } from "./runtime.ts";
-import type { GrammarId, SourceRange, TreeSitterResult } from "./types.ts";
+import { detectGrammar } from "../language.ts";
+import type { TreeSitterRuntime } from "../session/runtime.ts";
+import type { GrammarId, SourceRange, TreeSitterResult } from "../types.ts";
 
 /** Result shape returned by lookupCalleesAt. */
 export interface CalleesAtResult {

package/src/{exports.ts → tool/exports.ts}

@@ -1,9 +1,9 @@
 // Export extraction for supported files.
 
-import { nodeToRange } from "./coordinates.ts";
-import type { TreeSitterRuntime } from "./runtime.ts";
-import type { SyntaxNodeLike } from "./syntax-node.ts";
-import type { ExportRecord, TreeSitterResult } from "./types.ts";
+import { nodeToRange } from "../coordinates.ts";
+import type { TreeSitterRuntime } from "../session/runtime.ts";
+import type { SyntaxNodeLike } from "../syntax-node.ts";
+import type { ExportRecord, TreeSitterResult } from "../types.ts";
 
 /** Extract export records from a supported file. */
 export async function extractExports(

package/src/{formatting.ts → tool/formatting.ts}

@@ -1,6 +1,6 @@
 // Formatting helpers for tree_sitter tool output.
 
-import type { OutlineItem, TreeSitterResult } from "./types.ts";
+import type { OutlineItem, TreeSitterResult } from "../types.ts";
 
 export const MAX_ITEMS = 100;
 

package/src/tool/guidance.ts

@@ -0,0 +1,22 @@
+// Prompt guidance and tool description for the tree_sitter tool.
+//
+// Note: We intentionally do NOT include cross-tool routing (e.g., "use lsp for
+// type info") because this package can be installed standalone without supi-lsp.
+
+export const toolDescription = `Tree-sitter tool — parser-level structure and syntax queries for supported files.
+
+Actions: outline, imports, exports, node_at, query, callees.
+
+Use tree_sitter for exact syntax nodes, shallow structure, parsed imports/exports, outgoing calls, or custom AST queries within one file. file is required for all actions. line and character are 1-based UTF-16 coordinates for node_at and callees. query is required for query. outline, imports, and exports are JavaScript/TypeScript-only; node_at and query work across supported grammars; callees works for many grammars. Relative paths resolve from the session working directory.`;
+
+export const promptGuidelines = [
+  "Use tree_sitter.outline(file), tree_sitter.imports(file), or tree_sitter.exports(file) for shallow JavaScript or TypeScript structure without reading the whole file.",
+  "Use tree_sitter.node_at(file, line, character) for the exact syntax node and ancestry at a known position.",
+  "Use tree_sitter.callees(file, line, character) for outgoing calls from the enclosing function or method at a known position.",
+  "Use tree_sitter.query(file, query) for custom Tree-sitter patterns when the built-in actions are not specific enough.",
+  "Use tree_sitter for syntax, node types, source ranges, and other parser-backed structure within one supported file.",
+  "Do not use tree_sitter for type information, cross-file references, semantic renames, or codebase-wide orientation.",
+];
+
+export const promptSnippet =
+  "tree_sitter — parser-backed single-file structure, node lookup, callees, and AST queries";

package/src/{imports.ts → tool/imports.ts}

@@ -1,9 +1,9 @@
 // Import extraction for supported files.
 
-import { nodeToRange } from "./coordinates.ts";
-import type { TreeSitterRuntime } from "./runtime.ts";
-import type { SyntaxNodeLike } from "./syntax-node.ts";
-import type { ImportRecord, TreeSitterResult } from "./types.ts";
+import { nodeToRange } from "../coordinates.ts";
+import type { TreeSitterRuntime } from "../session/runtime.ts";
+import type { SyntaxNodeLike } from "../syntax-node.ts";
+import type { ImportRecord, TreeSitterResult } from "../types.ts";
 
 /** Extract import records from a supported file. */
 export async function extractImports(

package/src/{node-at.ts → tool/node-at.ts}

@@ -1,8 +1,8 @@
 // Node-at-position lookup.
 
-import { nodeToRange, publicToTreeSitter, splitSourceLines } from "./coordinates.ts";
-import type { TreeSitterRuntime } from "./runtime.ts";
-import type { NodeAtResult, SourceRange, TreeSitterResult } from "./types.ts";
+import { nodeToRange, publicToTreeSitter, splitSourceLines } from "../coordinates.ts";
+import type { TreeSitterRuntime } from "../session/runtime.ts";
+import type { NodeAtResult, SourceRange, TreeSitterResult } from "../types.ts";
 
 const MAX_ANCESTRY = 10;
 

package/src/{outline.ts → tool/outline.ts}

@@ -1,8 +1,8 @@
 // Outline extraction for supported files.
 
-import { nodeToRange } from "./coordinates.ts";
-import type { SyntaxNodeLike } from "./syntax-node.ts";
-import type { OutlineItem } from "./types.ts";
+import { nodeToRange } from "../coordinates.ts";
+import type { SyntaxNodeLike } from "../syntax-node.ts";
+import type { OutlineItem } from "../types.ts";
 
 /** Node types that can be extracted directly as outline items. */
 const OUTLINE_DECLARATION_NODE_TYPES = new Set([

package/src/tree-sitter.ts

@@ -3,6 +3,8 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { detectGrammar, isJsTsGrammar } from "./language.ts";
+import { TreeSitterRuntime } from "./session/runtime.ts";
 import {
   formatNonSuccess,
   formatOutlineItemsCapped,
@@ -11,11 +13,10 @@ import {
   truncatedNotice,
   truncateText,
   validationError,
-} from "./formatting.ts";
-import { detectGrammar, isJsTsGrammar } from "./language.ts";
-import { collectOutline } from "./outline.ts";
-import { TreeSitterRuntime } from "./runtime.ts";
-import { extractExports, extractImports, lookupCalleesAt, lookupNodeAt } from "./structure.ts";
+} from "./tool/formatting.ts";
+import { promptGuidelines, promptSnippet, toolDescription } from "./tool/guidance.ts";
+import { collectOutline } from "./tool/outline.ts";
+import { extractExports, extractImports, lookupCalleesAt, lookupNodeAt } from "./tool/structure.ts";
 
 const TreeSitterActionEnum = StringEnum([
   "outline",
@@ -26,30 +27,6 @@ const TreeSitterActionEnum = StringEnum([
   "callees",
 ] as const);
 
-const toolDescription = `Tree-sitter tool — provides structural AST analysis for supported files.
-
-Actions:
-- outline: Extract structural declarations (functions, classes, interfaces, etc.). JavaScript/TypeScript only.
-- imports: List import statements with module specifiers. JavaScript/TypeScript only.
-- exports: List export declarations, re-exports, and export assignments with names and kinds. JavaScript/TypeScript only.
-- node_at: Find the syntax node at a position. Params: file, line, character
-- query: Run a Tree-sitter query. Params: file, query
-- callees: Find outgoing function/method calls from a position. Params: file, line, character. Supported for most grammars.
-
-Coordinates are 1-based (line, character), compatible with the lsp tool convention.
-Character is a UTF-16 code-unit column.
-Relative file paths resolve from the session working directory.
-
-Supported extensions: .ts, .tsx, .js, .jsx, .mts, .cts, .mjs, .cjs, .py, .pyi, .rs, .go, .mod, .c, .h, .cpp, .hpp, .cc, .cxx, .hxx, .c++, .h++, .java, .kt, .kts, .rb, .sh, .bash, .zsh, .html, .htm, .xhtml, .r, .sql`;
-
-const promptGuidelines = [
-  "Use tree_sitter for structural syntax-tree analysis: extracting declarations, imports, exports, node-at-position lookup, and custom queries.",
-  "Prefer tree_sitter when you need AST node types, exact source ranges, or parser-level structure that semantic language-server tooling does not expose.",
-  "tree_sitter is a standalone structural analysis tool; use semantic language-server features separately when they are available for hover, definitions, references, or diagnostics.",
-];
-
-const promptSnippet = `Use the tree_sitter tool for structural code analysis — outline, imports, exports, node-at-position lookup, and custom queries.`;
-
 export default function treeSitterExtension(pi: ExtensionAPI) {
   let runtime: TreeSitterRuntime | undefined;