@mrclrchtr/supi-tree-sitter 1.1.2 → 1.2.0

package/README.md

@@ -1,97 +1,65 @@
 # @mrclrchtr/supi-tree-sitter
 
-Tree-sitter structural analysis for the [pi coding agent](https://github.com/earendil-works/pi).
+Structural code analysis for PI — your agent parses code, not just text.
 
-This package registers a `tree_sitter` tool and also exports a small TypeScript service API for other SuPi extensions. It is designed as a standalone structural-analysis substrate: it does not depend on `supi-lsp` or semantic language-server tooling, and it remains correct and useful when installed by itself.
+Grep matches strings. Tree-sitter parses structure — functions, classes, imports, call chains. The agent stops pattern-matching and starts understanding your code.
 
-## Install
+## What you get
 
-```bash
-pi install npm:@mrclrchtr/supi-tree-sitter
-```
+### See code structure
 
-Standalone installs include the runtime grammar dependencies needed for the supported non-vendored languages. Kotlin and SQL use vendored WASM grammars bundled with this package.
+Extract functions, classes, interfaces, and methods from any file. The agent knows what lives where without reading every line.
 
-It is also bundled by the full SuPi meta-package:
+### Trace call chains
 
-```bash
-pi install npm:@mrclrchtr/supi
-```
+Find every function call from a given location. The agent follows the code's actual shape instead of guessing from text proximity.
 
-## Supported files
+### 14 languages
 
-The runtime can parse these file families:
+JavaScript, TypeScript, Python, Rust, Go, C, C++, Java, Kotlin, Ruby, Bash, HTML, R, SQL — get structural analysis for every project you touch.
 
-- **JavaScript / TypeScript** — `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, `.cjs`
-- **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`
+Works standalone or alongside LSP. Grammar files are vendored — no native toolchain required at install time.
+
+## Install
 
-Grammar `.wasm` files are resolved from installed package metadata for npm-shipped grammars, not from repository-relative paths.
+```bash
+pi install npm:@mrclrchtr/supi-tree-sitter
+```
 
-## `tree_sitter` tool
+## Quick look
 
-Actions:
+The agent gets a `tree_sitter` tool with these actions:
 
-- `outline` — list structural declarations such as functions, classes, interfaces, methods, and variables (**currently JavaScript / TypeScript only**)
-- `imports` — list import statements and module specifiers (**currently JavaScript / TypeScript only**)
-- `exports` — list exported declarations, re-exports, and TypeScript `export =` assignments (**currently JavaScript / TypeScript only**)
-- `node_at` — return the smallest syntax node at a 1-based `line`/`character` position, plus ancestry (all supported grammars)
-- `query` — run a custom Tree-sitter query and return captures (all supported grammars)
-- `callees` — find outgoing function/method calls from a position; supports all grammars with a callee query configured
+| 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 |
 
-Coordinates are 1-based and compatible with the `lsp` tool. `character` is a UTF-16 code-unit column. Relative file paths resolve from the pi session working directory.
+`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.
 
-Large result sets are capped at 100 emitted items per tool response. For outlines, nested children count toward the same cap so deeply nested classes do not bypass the limit.
+## For extension developers
 
-## Service API
+This package exports a reusable session-scoped parsing service:
 
 ```ts
 import { createTreeSitterSession } from "@mrclrchtr/supi-tree-sitter";
 
-const session = createTreeSitterSession(process.cwd());
-try {
-  const parseable = await session.canParse("src/index.ts");
-  if (parseable.kind === "success") {
-    console.log(parseable.data.file, parseable.data.language);
-  }
-
-  const outline = await session.outline("src/index.ts");
-  if (outline.kind === "success") {
-    console.log(outline.data);
-  }
-
-  const callees = await session.calleesAt("src/index.ts", 1, 10);
-  if (callees.kind === "success") {
-    console.log(callees.data.enclosingScope.name, callees.data.callees);
-  }
-} finally {
-  session.dispose();
-}
-```
-
-`canParse(file)` validates that a supported file can be read and parsed, then returns the resolved file path and grammar id. It does not expose the raw Tree-sitter tree; use `outline`, `query`, `imports`, `exports`, `nodeAt`, or `calleesAt` for structured results.
-
-`calleesAt(file, line, character)` extracts structural outgoing calls from the enclosing function/method scope at the given position. It returns the enclosing scope name and a deduplicated list of callees with their source ranges.
+const session = createTreeSitterSession("/project");
 
-Exported types include `TreeSitterResult`, `TreeSitterSession`, `OutlineItem`, `ImportRecord`, `ExportRecord`, `NodeAtResult`, `QueryCapture`, `CalleesAtResult`, `SourceRange`, `GrammarId`, and `SupportedExtension`.
+// Check if a file is parseable
+const result = await session.canParse("src/index.ts");
 
-Always call `dispose()` when the session is no longer needed. The runtime lazily initializes grammars, reuses parser instances within a session, deduplicates concurrent first-use grammar initialization, and retries after initialization failures.
+// Get structural outline
+const outline = await session.outline("src/index.ts");
 
-## Positioning
+// Trace outgoing calls from a position
+const callees = await session.calleesAt("src/index.ts", 42, 10);
 
-`supi-tree-sitter` is the structural-analysis substrate in SuPi's layered code-understanding stack:
-
-- `supi-tree-sitter` — parser-backed structural analysis (this package)
-- `supi-lsp` — live semantic analysis through language servers
-- `supi-code-intelligence` — higher-level agent-facing analysis built on top of both substrates
+// Always clean up
+session.dispose();
+```
 
-Each substrate can be installed and used independently. `supi-tree-sitter` does not require `supi-lsp` to be present, and its prompt guidance is written so it remains correct in standalone installs.
+Import from the package root. No internal imports needed. Call `dispose()` when done.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-tree-sitter",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "SuPi Tree-sitter extension — structural AST analysis for pi",
   "license": "MIT",
   "repository": {
@@ -30,6 +30,17 @@
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
   "pi": {
     "extensions": [
       "./src/tree-sitter.ts"