@mrclrchtr/supi-tree-sitter 1.16.1 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-tree-sitter",
-  "version": "1.16.1",
+  "version": "2.0.0",
   "description": "SuPi Tree-sitter extension — structural AST analysis for pi",
   "license": "MIT",
   "repository": {
@@ -16,7 +16,6 @@
     "access": "public"
   },
   "keywords": [
-    "pi-package",
     "pi",
     "pi-coding-agent",
     "pi-extension",
@@ -26,6 +25,7 @@
     "code-navigation",
     "structural-search"
   ],
+  "type": "module",
   "files": [
     "src/**/*.ts",
     "src/**/*.json",
@@ -35,12 +35,13 @@
   ],
   "dependencies": {
     "web-tree-sitter": "^0.26.8",
-    "@mrclrchtr/supi-core": "1.16.1",
-    "@mrclrchtr/supi-code-runtime": "1.16.1"
+    "@mrclrchtr/supi-code-runtime": "2.0.0",
+    "@mrclrchtr/supi-core": "2.0.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",
-    "@mrclrchtr/supi-core"
+    "@mrclrchtr/supi-core",
+    "web-tree-sitter"
   ],
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
@@ -58,16 +59,9 @@
       "optional": true
     }
   },
-  "pi": {
-    "extensions": [
-      "./src/extension.ts"
-    ],
-    "image": "https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-tree-sitter.png"
-  },
   "main": "src/api.ts",
   "exports": {
     "./api": "./src/api.ts",
-    "./extension": "./src/extension.ts",
     "./package.json": "./package.json",
     "./provider/tree-sitter-provider": "./src/provider/tree-sitter-provider.ts"
   },

package/src/api.ts

@@ -1,9 +1,38 @@
 // Public tree-sitter session factory, shared session service access, and shared types.
+//
+// This package is library-only — no pi extension surface.
+// Exports structured runtime/service APIs only.
+// Tool handler string-formatting lives in @mrclrchtr/supi-code-intelligence.
 
+// Language detection helpers
+export {
+  detectGrammar,
+  getSupportedExtension,
+  getSupportedExtensions,
+  isJsTsGrammar,
+  isSupportedFile,
+} from "./language.ts";
+export { TreeSitterRuntime } from "./session/runtime.ts";
+export type {
+  TsControllerState,
+  TsStartResult,
+} from "./session/runtime-controller.ts";
+export { TreeSitterRuntimeController } from "./session/runtime-controller.ts";
 export { getSessionTreeSitterService } from "./session/service-registry.ts";
 export { createTreeSitterSession } from "./session/session.ts";
+
+// Structural extraction services (consumed by supi-code-intelligence tool execution)
+export { extractCallSites } from "./tool/call-sites.ts";
+export { lookupCalleesAt } from "./tool/callees.ts";
+export { extractExports } from "./tool/exports.ts";
+export { extractImports } from "./tool/imports.ts";
+export { lookupNodeAt } from "./tool/node-at.ts";
+export { collectOutline } from "./tool/outline.ts";
+
+// Shared types
 export type {
   CalleesAtResult,
+  CallSiteMatch,
   ExportRecord,
   GrammarId,
   ImportRecord,

package/src/index.ts

@@ -1,9 +1,37 @@
 // Public session factory, shared session service access, and re-exports for @mrclrchtr/supi-tree-sitter.
+//
+// This package is library-only — no pi extension surface.
+// Tool handler string-formatting lives in @mrclrchtr/supi-code-intelligence.
 
+// Language detection helpers
+export {
+  detectGrammar,
+  getSupportedExtension,
+  getSupportedExtensions,
+  isJsTsGrammar,
+  isSupportedFile,
+} from "./language.ts";
+// Provider implementation
+export { createTreeSitterProvider } from "./provider/tree-sitter-provider.ts";
+export { TreeSitterRuntime } from "./session/runtime.ts";
+export type {
+  TsControllerState,
+  TsStartResult,
+} from "./session/runtime-controller.ts";
+export { TreeSitterRuntimeController } from "./session/runtime-controller.ts";
 export { getSessionTreeSitterService } from "./session/service-registry.ts";
 export { createTreeSitterSession } from "./session/session.ts";
+// Structural extraction services (consumed by supi-code-intelligence tool execution)
+export { extractCallSites } from "./tool/call-sites.ts";
+export { lookupCalleesAt } from "./tool/callees.ts";
+export { extractExports } from "./tool/exports.ts";
+export { extractImports } from "./tool/imports.ts";
+export { lookupNodeAt } from "./tool/node-at.ts";
+export { collectOutline } from "./tool/outline.ts";
+// Shared types
 export type {
   CalleesAtResult,
+  CallSiteMatch,
   ExportRecord,
   GrammarId,
   ImportRecord,

package/src/language.ts

@@ -56,6 +56,11 @@ export function isSupportedFile(filePath: string): boolean {
   return detectGrammar(filePath) !== undefined;
 }
 
+/** Return all supported file extensions (with leading dot). */
+export function getSupportedExtensions(): string[] {
+  return [...SUPPORTED_EXTENSIONS];
+}
+
 /** Get the file extension if it's supported, otherwise undefined. */
 export function getSupportedExtension(filePath: string): SupportedExtension | undefined {
   const ext = path.extname(filePath).toLowerCase();

package/src/provider/tree-sitter-provider.ts

@@ -3,6 +3,7 @@
 
 import type {
   CalleesData,
+  CallSite,
   CodeResult,
   ExportData,
   ImportData,
@@ -12,6 +13,7 @@ import type {
 } from "@mrclrchtr/supi-code-runtime/api";
 import type {
   CalleesAtResult,
+  CallSiteMatch,
   ExportRecord,
   ImportRecord,
   NodeAtResult,
@@ -27,8 +29,8 @@ import type {
  */
 export function createTreeSitterProvider(service: TreeSitterService): StructuralProvider {
   return {
-    async calleesAt(file, line, character) {
-      const result = await service.calleesAt(file, line, character);
+    async calleesAt(file, line, character, depth?) {
+      const result = await service.calleesAt(file, line, character, depth);
       return mapTreeSitterResult(result, mapCalleesAtResult);
     },
 
@@ -51,6 +53,11 @@ export function createTreeSitterProvider(service: TreeSitterService): Structural
       const result = await service.nodeAt(file, line, character);
       return mapTreeSitterResult(result, mapNodeAtResult);
     },
+
+    async callSites(file) {
+      const result = await service.callSites(file);
+      return mapTreeSitterResult(result, mapCallSites);
+    },
   };
 }
 
@@ -140,5 +147,10 @@ function mapCalleesAtResult(result: CalleesAtResult): CalleesData {
       name: c.name,
       startLine: c.range.startLine,
     })),
+    depth: result.depth,
   };
 }
+
+function mapCallSites(matches: CallSiteMatch[]): CallSite[] {
+  return matches.map((m) => ({ name: m.name, startLine: m.startLine }));
+}

package/src/session/runtime-controller.ts

@@ -0,0 +1,157 @@
+// Tree-sitter session runtime controller — pi-independent lifecycle for structural analysis.
+//
+// This controller owns runtime creation/disposal for one cwd:
+//   - Creates and disposes the TreeSitterRuntime
+//   - Creates TreeSitterService from the runtime
+//   - Publishes SessionTreeSitterService state through the existing registry
+//   - Exposes ready/unavailable lifecycle for umbrella adapter consumption
+
+import type { WorkspaceRuntime } from "@mrclrchtr/supi-code-runtime/api";
+import type { SessionTreeSitterService, TreeSitterService } from "../types.ts";
+import { TreeSitterRuntime } from "./runtime.ts";
+import {
+  registerTreeSitterCapabilities,
+  unregisterTreeSitterCapabilities,
+} from "./runtime-registration.ts";
+import { clearSessionTreeSitterService, setSessionTreeSitterService } from "./service-registry.ts";
+import { createTreeSitterService } from "./session.ts";
+
+// ── Types ─────────────────────────────────────────────────────────────
+
+/** Starting state before or after shutdown. */
+export type TsControllerState = TsControllerInitial | TsControllerReady | TsControllerUnavailable;
+
+interface TsControllerInitial {
+  kind: "initial";
+}
+
+interface TsControllerReady {
+  kind: "ready";
+  runtime: TreeSitterRuntime;
+  service: TreeSitterService;
+}
+
+interface TsControllerUnavailable {
+  kind: "unavailable";
+  reason: string;
+}
+
+/** Result type from {@link TreeSitterRuntimeController.start}. */
+export type TsStartResult = { kind: "ready" } | { kind: "unavailable"; reason: string };
+
+// ── Controller ────────────────────────────────────────────────────────
+
+/**
+ * Pi-independent Tree-sitter session lifecycle controller.
+ *
+ * Use this in the umbrella extension (supi-code-intelligence) instead of
+ * reaching into substrate extension internals.
+ *
+ * @example
+ * ```ts
+ * const controller = new TreeSitterRuntimeController(cwd);
+ * const result = await controller.start();
+ * if (result.kind === "ready") {
+ *   // use controller.service, controller.runtime
+ * }
+ * // later
+ * await controller.shutdown();
+ * ```
+ */
+export class TreeSitterRuntimeController {
+  readonly #cwd: string;
+  #state: TsControllerState;
+  #runtime: WorkspaceRuntime | null;
+
+  constructor(cwd: string, runtime?: WorkspaceRuntime) {
+    this.#cwd = cwd;
+    this.#state = { kind: "initial" };
+    this.#runtime = runtime ?? null;
+  }
+
+  /** The workspace cwd this controller was created for. */
+  get cwd(): string {
+    return this.#cwd;
+  }
+
+  /** Current controller state. */
+  get kind(): TsControllerState["kind"] {
+    return this.#state.kind;
+  }
+
+  /** The TreeSitterService (structural operations), available when state is "ready". */
+  get service(): SessionTreeSitterService | null {
+    return this.#state.kind === "ready" ? this.#state.service : null;
+  }
+
+  /** The TreeSitterRuntime, available when state is "ready". */
+  get runtime(): TreeSitterRuntime | null {
+    return this.#state.kind === "ready" ? this.#state.runtime : null;
+  }
+
+  /** Attach a WorkspaceRuntime for capability registration. */
+  setRuntime(runtime: WorkspaceRuntime): void {
+    this.#runtime = runtime;
+  }
+
+  /**
+   * Start the Tree-sitter session.
+   *
+   * Creates the runtime, wires the service, and publishes state
+   * into the shared registries. Validates that WASM initialization
+   * succeeds, returning `unavailable` if it fails.
+   */
+  async start(): Promise<TsStartResult> {
+    // Restart safety: dispose any existing runtime
+    if (this.#state.kind === "ready") {
+      this.#state.runtime.dispose();
+      if (this.#runtime) unregisterTreeSitterCapabilities(this.#runtime, this.#cwd);
+      clearSessionTreeSitterService(this.#cwd);
+    }
+
+    this.#state = { kind: "unavailable", reason: "Initializing Tree-sitter" };
+
+    try {
+      const treeSitterRuntime = new TreeSitterRuntime(this.#cwd);
+
+      // Probe WASM initialization by loading the JavaScript grammar
+      // (always vendored). This catches missing web-tree-sitter or
+      // corrupted WASM early rather than deferring to first tool use.
+      await treeSitterRuntime.ensureGrammarParser("javascript");
+
+      const service = createTreeSitterService(treeSitterRuntime);
+      setSessionTreeSitterService(this.#cwd, service);
+
+      if (this.#runtime) {
+        registerTreeSitterCapabilities(this.#runtime, this.#cwd, service);
+      }
+
+      this.#state = { kind: "ready", runtime: treeSitterRuntime, service };
+      return { kind: "ready" };
+    } catch (error: unknown) {
+      const reason = error instanceof Error ? error.message : String(error);
+      this.#state = { kind: "unavailable", reason };
+      clearSessionTreeSitterService(this.#cwd);
+      return { kind: "unavailable", reason };
+    }
+  }
+
+  /**
+   * Shut down the Tree-sitter session.
+   *
+   * Disposes the runtime and clears all published state.
+   */
+  async shutdown(): Promise<void> {
+    if (this.#runtime && this.#cwd) {
+      unregisterTreeSitterCapabilities(this.#runtime, this.#cwd);
+    }
+
+    clearSessionTreeSitterService(this.#cwd);
+
+    if (this.#state.kind === "ready") {
+      this.#state.runtime.dispose();
+    }
+
+    this.#state = { kind: "initial" };
+  }
+}

package/src/session/session.ts

@@ -2,6 +2,7 @@
 
 import { detectGrammar, isJsTsGrammar } from "../language.ts";
 import {
+  extractCallSites,
   extractExports,
   extractImports,
   extractOutline,
@@ -10,6 +11,7 @@ import {
 } from "../tool/structure.ts";
 import type {
   CalleesAtResult,
+  CallSiteMatch,
   ExportRecord,
   ImportRecord,
   NodeAtResult,
@@ -97,8 +99,13 @@ export function createTreeSitterService(runtime: TreeSitterRuntime): TreeSitterS
       file: string,
       line: number,
       character: number,
+      depth?: "direct" | "deep",
     ): Promise<TreeSitterResult<CalleesAtResult>> {
-      return lookupCalleesAt(runtime, file, line, character);
+      return lookupCalleesAt(runtime, file, line, character, depth);
+    },
+
+    async callSites(file: string): Promise<TreeSitterResult<CallSiteMatch[]>> {
+      return extractCallSites(runtime, file);
     },
   };
 }

package/src/tool/call-sites.ts

@@ -0,0 +1,86 @@
+/** File-wide call-site extraction using per-grammar tree-sitter queries. */
+
+import { detectGrammar } from "../language.ts";
+import type { TreeSitterRuntime } from "../session/runtime.ts";
+import type { CallSiteMatch, GrammarId, TreeSitterResult } from "../types.ts";
+
+// ── Per-grammar call-site queries ─────────────────────────────────────
+
+// JS/TS/TSX queries that capture the full callee expression, not just the leaf name.
+// `(_)` matches any expression node, giving us the full callee including member chains
+// and nested call expressions (e.g. `factory()()` captures `factory()` for the outer call).
+const JS_TS_CALL_SITE_QUERY = [
+  // Regular calls: capture the whole callee expression
+  "(call_expression function: (_) @call)",
+  // New expressions: capture the constructor expression
+  "(new_expression constructor: (_) @call)",
+].join("\n");
+
+const CALL_SITE_QUERIES: Partial<Record<GrammarId, string>> = {
+  javascript: JS_TS_CALL_SITE_QUERY,
+  typescript: JS_TS_CALL_SITE_QUERY,
+  tsx: JS_TS_CALL_SITE_QUERY,
+  python:
+    "(call function: (identifier) @call) (call function: (attribute attribute: (identifier) @call))",
+  rust: "(call_expression function: (identifier) @call) (call_expression function: (field_expression field: (field_identifier) @call)) (macro_invocation macro: (identifier) @call)",
+  go: "(call_expression function: (identifier) @call) (call_expression function: (selector_expression field: (field_identifier) @call))",
+  c: "(call_expression function: (identifier) @call)",
+  cpp: "(call_expression function: (identifier) @call) (call_expression function: (field_expression field: (field_identifier) @call))",
+  java: "(method_invocation name: (identifier) @call) (object_creation_expression type: (type_identifier) @call)",
+  kotlin:
+    "(call_expression . (simple_identifier) @call) (call_expression . (navigation_expression . (simple_identifier) @call))",
+  ruby: "(call method: (identifier) @call)",
+  bash: "(command name: (word) @call)",
+  r: "(call function: (identifier) @call)",
+};
+
+/**
+ * Extract all call-site callee expressions from a file.
+ *
+ * Returns a deduplicated list of { name, startLine } for every call-site
+ * captured by the grammar-specific query.
+ */
+export async function extractCallSites(
+  runtime: TreeSitterRuntime,
+  filePath: string,
+): Promise<TreeSitterResult<CallSiteMatch[]>> {
+  const grammarId = detectGrammar(filePath);
+  if (!grammarId) {
+    return {
+      kind: "unsupported-language",
+      file: filePath,
+      message: `Unsupported file: ${filePath}`,
+    };
+  }
+
+  const queryStr = CALL_SITE_QUERIES[grammarId];
+  if (!queryStr) {
+    return {
+      kind: "unsupported-language",
+      file: filePath,
+      message: `callSites is not supported for ${grammarId} files`,
+    };
+  }
+
+  const queryResult = await runtime.queryFile(filePath, queryStr);
+  if (queryResult.kind !== "success") return queryResult;
+
+  const captures = queryResult.data;
+  const seen = new Set<string>();
+  const matches: CallSiteMatch[] = [];
+
+  for (const capture of captures) {
+    // Normalize: trim whitespace and collapse internal whitespace to single space
+    const name = capture.text.trim().replace(/\s+/g, " ");
+    if (name.length === 0) continue;
+
+    // Deduplicate by name + line
+    const key = `${name}:${capture.range.startLine}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    matches.push({ name, startLine: capture.range.startLine });
+  }
+
+  return { kind: "success", data: matches };
+}

package/src/tool/callees.ts

@@ -14,6 +14,7 @@ export interface CalleesAtResult {
     name: string;
     range: SourceRange;
   }>;
+  depth: "direct" | "deep";
 }
 
 // ── Per-grammar callee queries ────────────────────────────────────────
@@ -103,13 +104,14 @@ function extractScopeName(_type: string, text: string): string {
 // ── Main entrypoint ──────────────────────────────────────────────────
 
 /**
- * Extract structural callee calls for a file at the given position.
+ * Extract direct structural callee calls for a file at the given position.
  *
  * 1. Parses the file with the Tree-sitter runtime.
- * 2. Finds the enclosing function/method scope at the position.
+ * 2. Finds the enclosing function/method/callback scope at the position.
  * 3. Runs a grammar-specific callee query.
- * 4. Filters to captures within the enclosing scope.
- * 5. Deduplicates by name.
+ * 4. Filters to captures within that enclosing scope.
+ * 5. Excludes nested function/method/callback scopes that do not contain the anchor.
+ * 6. Deduplicates by name.
  */
 /** Validate that coordinates are usable and grammar is supported. */
 function validateCalleeInput(
@@ -165,11 +167,13 @@ function findEnclosingScope(
   return null;
 }
 
+// biome-ignore lint/complexity/useMaxParams: provider function needs runtime + coordinates + depth
 export async function lookupCalleesAt(
   runtime: TreeSitterRuntime,
   filePath: string,
   line: number,
   character: number,
+  depth: "direct" | "deep" = "direct",
 ): Promise<TreeSitterResult<CalleesAtResult>> {
   // Validate coordinates and grammar
   const validation = validateCalleeInput(filePath, line, character);
@@ -218,7 +222,13 @@ export async function lookupCalleesAt(
       };
     }
 
-    const callees = filterCalleeCaptures(queryResult.data, enclosingNode, scopes, tsPoint.row);
+    const callees = filterCalleeCaptures(
+      queryResult.data,
+      enclosingNode,
+      scopes,
+      tsPoint.row,
+      depth,
+    );
 
     const enclosingRange = nodeToSourceRange(enclosingNode);
     const scopeName = extractScopeName(enclosingNode.type, enclosingNode.text);
@@ -231,6 +241,7 @@ export async function lookupCalleesAt(
           range: enclosingRange,
         },
         callees,
+        depth,
       },
     };
   } finally {
@@ -239,9 +250,9 @@ export async function lookupCalleesAt(
 }
 
 /**
- * Recursively collect line ranges of inner function/method scopes that do not
- * contain the anchor row. Captures from these ranges are excluded so that
- * nested function calls are not attributed to the parent scope.
+ * Recursively collect line ranges of inner function/method/callback scopes that
+ * do not contain the anchor row. Captures from these ranges are excluded so
+ * nested calls are not attributed to the parent scope.
  */
 function collectInnerScopes(
   node: {
@@ -281,18 +292,24 @@ function collectInnerScopes(
 }
 
 /**
- * Filter query captures to only those within the enclosing scope,
- * excluding any that fall within inner nested function scopes.
+ * Filter query captures to only those within the enclosing scope.
+ * In `direct` depth, excludes captures that fall within inner nested
+ * function/callback scopes. In `deep` depth, all captures within the
+ * enclosing scope are included regardless of nesting.
  */
+// biome-ignore lint/complexity/useMaxParams: filtering needs captures + node context + depth
 function filterCalleeCaptures(
   captures: Array<{ range: SourceRange; text: string }>,
   // biome-ignore lint/suspicious/noExplicitAny: tree-sitter SyntaxNode is complex
   enclosingNode: any,
   scopeTypes: ReadonlySet<string>,
   anchorRow: number,
+  depth: "direct" | "deep" = "direct",
 ): Array<{ name: string; range: SourceRange }> {
   const excludeRanges: Array<{ startRow: number; endRow: number }> = [];
-  collectInnerScopes(enclosingNode, scopeTypes, anchorRow, excludeRanges);
+  if (depth === "direct") {
+    collectInnerScopes(enclosingNode, scopeTypes, anchorRow, excludeRanges);
+  }
 
   const seen = new Set<string>();
   const callees: Array<{ name: string; range: SourceRange }> = [];
@@ -306,11 +323,13 @@ function filterCalleeCaptures(
       continue;
     }
 
-    // Exclude captures that fall within inner nested function scopes
-    const isInInner = excludeRanges.some(
-      (exc) => capture.range.startLine >= exc.startRow && capture.range.endLine <= exc.endRow,
-    );
-    if (isInInner) continue;
+    // In direct depth, exclude captures that fall within inner nested function scopes
+    if (depth === "direct") {
+      const isInInner = excludeRanges.some(
+        (exc) => capture.range.startLine >= exc.startRow && capture.range.endLine <= exc.endRow,
+      );
+      if (isInInner) continue;
+    }
 
     const name = capture.text.replace(/\s+/g, "").slice(0, 60);
     if (name.length === 0 || seen.has(name)) continue;

package/src/tool/structure.ts

@@ -1,5 +1,6 @@
 // Structural extraction services — re-exports from sub-modules.
 
+export { extractCallSites } from "./call-sites.ts";
 export { lookupCalleesAt } from "./callees.ts";
 export { extractExports } from "./exports.ts";
 export { extractImports } from "./imports.ts";

package/src/types.ts

@@ -56,6 +56,7 @@ export interface CalleesAtResult {
     name: string;
     range: SourceRange;
   }>;
+  depth: "direct" | "deep";
 }
 
 /** Query capture result. */
@@ -66,6 +67,12 @@ export interface QueryCapture {
   text: string;
 }
 
+/** A single call-site match from tree-sitter analysis. */
+export interface CallSiteMatch {
+  name: string;
+  startLine: number;
+}
+
 /** Shared Tree-sitter service surface, independent of lifecycle ownership. */
 export interface TreeSitterService {
   /** Validate that a supported file can be read and parsed; does not expose the raw tree. */
@@ -85,7 +92,10 @@ export interface TreeSitterService {
     file: string,
     line: number,
     character: number,
+    depth?: "direct" | "deep",
   ): Promise<TreeSitterResult<CalleesAtResult>>;
+  /** Extract all call-site identifiers in a file. */
+  callSites(file: string): Promise<TreeSitterResult<CallSiteMatch[]>>;
 }
 
 /** Owned Tree-sitter session that must release its runtime resources. */

package/src/extension.ts

@@ -1 +0,0 @@
-export { default } from "./tree-sitter.ts";