@mrclrchtr/supi-tree-sitter 1.4.0 → 1.5.0

package/src/tool/action-specs.ts

@@ -0,0 +1,92 @@
+/**
+ * Single source of truth for the public `tree_sitter` action surface.
+ *
+ * Tool registration, validation, and prompt guidance should derive from these
+ * specs so the action list and per-action requirements do not drift apart.
+ */
+export const TREE_SITTER_ACTION_SPECS = [
+  {
+    name: "outline",
+    guidanceGroup: "js-ts-structure",
+    languageScope: "js-ts-only",
+    requiresPosition: false,
+    requiresQuery: false,
+  },
+  {
+    name: "imports",
+    guidanceGroup: "js-ts-structure",
+    languageScope: "js-ts-only",
+    requiresPosition: false,
+    requiresQuery: false,
+  },
+  {
+    name: "exports",
+    guidanceGroup: "js-ts-structure",
+    languageScope: "js-ts-only",
+    requiresPosition: false,
+    requiresQuery: false,
+  },
+  {
+    name: "node_at",
+    guidanceGroup: "node-at",
+    languageScope: "all-supported",
+    requiresPosition: true,
+    requiresQuery: false,
+  },
+  {
+    name: "query",
+    guidanceGroup: "query",
+    languageScope: "all-supported",
+    requiresPosition: false,
+    requiresQuery: true,
+  },
+  {
+    name: "callees",
+    guidanceGroup: "callees",
+    languageScope: "many-supported",
+    requiresPosition: true,
+    requiresQuery: false,
+  },
+] as const;
+
+export type TreeSitterAction = (typeof TREE_SITTER_ACTION_SPECS)[number]["name"];
+export type TreeSitterActionSpec = (typeof TREE_SITTER_ACTION_SPECS)[number];
+export type TreeSitterGuidanceGroup = TreeSitterActionSpec["guidanceGroup"];
+
+/** Ordered action names for schemas, validation messages, and docs. */
+export const TREE_SITTER_ACTION_NAMES = TREE_SITTER_ACTION_SPECS.map(
+  (spec) => spec.name,
+) as readonly TreeSitterAction[];
+
+const TREE_SITTER_ACTION_NAME_SET = new Set<string>(TREE_SITTER_ACTION_NAMES);
+const TREE_SITTER_ACTION_SPEC_MAP = new Map<TreeSitterAction, TreeSitterActionSpec>(
+  TREE_SITTER_ACTION_SPECS.map((spec) => [spec.name, spec]),
+);
+
+/** Check whether a runtime string is a supported `tree_sitter` action. */
+export function isTreeSitterAction(action: string): action is TreeSitterAction {
+  return TREE_SITTER_ACTION_NAME_SET.has(action);
+}
+
+/** Look up the spec for one supported `tree_sitter` action. */
+export function getTreeSitterActionSpec(action: TreeSitterAction): TreeSitterActionSpec {
+  const spec = TREE_SITTER_ACTION_SPEC_MAP.get(action);
+  if (!spec) {
+    throw new Error(`Unknown tree_sitter action: ${action}`);
+  }
+  return spec;
+}
+
+/** Get the ordered action names that belong to one prompt-guidance group. */
+export function getTreeSitterActionNamesByGuidanceGroup(
+  group: TreeSitterGuidanceGroup,
+): TreeSitterAction[] {
+  return TREE_SITTER_ACTION_SPECS.filter((spec) => spec.guidanceGroup === group).map(
+    (spec) => spec.name,
+  );
+}
+
+/** Format the public action list for validation messages and docs. */
+export function formatTreeSitterActionList(): string {
+  return TREE_SITTER_ACTION_NAMES.join(", ");
+}

package/src/tool/guidance.ts

@@ -3,14 +3,23 @@
 // 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.
 
+import {
+  formatTreeSitterActionList,
+  getTreeSitterActionNamesByGuidanceGroup,
+} from "./action-specs.ts";
+
+const jsTsStructureActions = getTreeSitterActionNamesByGuidanceGroup("js-ts-structure")
+  .map((action) => `tree_sitter.${action}(file)`)
+  .join(", ");
+
 export const toolDescription = `Tree-sitter tool — parser-level structure and syntax queries for supported files.
 
-Actions: outline, imports, exports, node_at, query, callees.
+Actions: ${formatTreeSitterActionList()}.
 
-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.`;
+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, and a leading @ on file paths is stripped.`;
 
 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 ${jsTsStructureActions} 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.",

package/src/tree-sitter.ts

@@ -5,6 +5,18 @@ 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 {
+  clearSessionTreeSitterService,
+  setSessionTreeSitterService,
+} from "./session/service-registry.ts";
+import { createTreeSitterService } from "./session/session.ts";
+import {
+  formatTreeSitterActionList,
+  getTreeSitterActionSpec,
+  isTreeSitterAction,
+  TREE_SITTER_ACTION_NAMES,
+  type TreeSitterAction,
+} from "./tool/action-specs.ts";
 import {
   formatNonSuccess,
   formatOutlineItemsCapped,
@@ -18,26 +30,30 @@ import { promptGuidelines, promptSnippet, toolDescription } from "./tool/guidanc
 import { collectOutline } from "./tool/outline.ts";
 import { extractExports, extractImports, lookupCalleesAt, lookupNodeAt } from "./tool/structure.ts";
 
-const TreeSitterActionEnum = StringEnum([
-  "outline",
-  "imports",
-  "exports",
-  "node_at",
-  "query",
-  "callees",
-] as const);
+const TreeSitterActionEnum = StringEnum(TREE_SITTER_ACTION_NAMES);
 
 export default function treeSitterExtension(pi: ExtensionAPI) {
   let runtime: TreeSitterRuntime | undefined;
+  let activeCwd: string | null = null;
 
   pi.on("session_start", (_event, ctx) => {
-    runtime?.dispose();
+    if (runtime && activeCwd) {
+      clearSessionTreeSitterService(activeCwd);
+      runtime.dispose();
+    }
+
+    activeCwd = ctx.cwd;
     runtime = new TreeSitterRuntime(ctx.cwd);
+    setSessionTreeSitterService(ctx.cwd, createTreeSitterService(runtime));
   });
 
   pi.on("session_shutdown", () => {
+    if (activeCwd) {
+      clearSessionTreeSitterService(activeCwd);
+    }
     runtime?.dispose();
     runtime = undefined;
+    activeCwd = null;
   });
 
   pi.registerTool({
@@ -73,8 +89,6 @@ export default function treeSitterExtension(pi: ExtensionAPI) {
   });
 }
 
-type TreeSitterAction = "outline" | "imports" | "exports" | "node_at" | "query" | "callees";
-
 type ToolParams = {
   action?: string;
   file?: string;
@@ -83,17 +97,47 @@ type ToolParams = {
   query?: string;
 };
 
+interface ValidatedToolParams {
+  action: TreeSitterAction;
+  file: string;
+  line?: number;
+  character?: number;
+  query?: string;
+}
+
+const SUPPORTED_ACTIONS_TEXT = formatTreeSitterActionList();
+
+const ACTION_HANDLERS: Record<
+  TreeSitterAction,
+  (runtime: TreeSitterRuntime, params: ValidatedToolParams) => Promise<string>
+> = {
+  outline: (runtime, params) => handleOutline(runtime, params.file),
+  imports: (runtime, params) => handleImports(runtime, params.file),
+  exports: (runtime, params) => handleExports(runtime, params.file),
+  node_at: (runtime, params) =>
+    handleNodeAt(runtime, params.file, params.line as number, params.character as number),
+  query: (runtime, params) => handleQuery(runtime, params.file, params.query as string),
+  callees: (runtime, params) =>
+    handleCallees(runtime, params.file, params.line as number, params.character as number),
+};
+
 async function executeToolAction(runtime: TreeSitterRuntime, params: ToolParams): Promise<string> {
+  const validated = validateToolParams(params);
+  if (typeof validated === "string") {
+    return validated;
+  }
+
+  return ACTION_HANDLERS[validated.action](runtime, validated);
+}
+
+function validateToolParams(params: ToolParams): ValidatedToolParams | string {
   if (!params.action) {
-    return validationError(
-      "`action` is required. Supported: outline, imports, exports, node_at, query, callees.",
-    );
+    return validationError(`\`action\` is required. Supported: ${SUPPORTED_ACTIONS_TEXT}.`);
   }
 
-  const action = toSupportedAction(params.action);
-  if (!action) {
+  if (!isTreeSitterAction(params.action)) {
     return validationError(
-      `Unknown action: ${params.action}. Supported: outline, imports, exports, node_at, query, callees`,
+      `Unknown action: ${params.action}. Supported: ${SUPPORTED_ACTIONS_TEXT}`,
     );
   }
 
@@ -101,12 +145,37 @@ async function executeToolAction(runtime: TreeSitterRuntime, params: ToolParams)
     return validationError("`file` is required for all actions.");
   }
 
-  if (action === "outline") return handleOutline(runtime, params.file);
-  if (action === "imports") return handleImports(runtime, params.file);
-  if (action === "exports") return handleExports(runtime, params.file);
-  if (action === "node_at") return handleNodeAt(runtime, params);
-  if (action === "callees") return handleCallees(runtime, params);
-  return handleQuery(runtime, params);
+  const spec = getTreeSitterActionSpec(params.action);
+  if (spec.requiresPosition) {
+    const lineError = validatePositiveInteger("line", params.line, params.action);
+    if (lineError) return lineError;
+
+    const characterError = validatePositiveInteger("character", params.character, params.action);
+    if (characterError) return characterError;
+  }
+
+  if (spec.requiresQuery && (!params.query || params.query.trim().length === 0)) {
+    return validationError("`query` is required and must be non-empty.");
+  }
+
+  return {
+    action: params.action,
+    file: params.file,
+    line: params.line,
+    character: params.character,
+    query: params.query,
+  };
+}
+
+function validatePositiveInteger(
+  field: "line" | "character",
+  value: number | undefined,
+  action: TreeSitterAction,
+): string | null {
+  if (value === undefined || !Number.isInteger(value) || value < 1) {
+    return validationError(`\`${field}\` must be a positive 1-based integer for ${action} action.`);
+  }
+  return null;
 }
 
 async function handleOutline(runtime: TreeSitterRuntime, file: string): Promise<string> {
@@ -175,18 +244,13 @@ async function handleExports(runtime: TreeSitterRuntime, file: string): Promise<
   return lines.join("\n");
 }
 
-async function handleNodeAt(runtime: TreeSitterRuntime, params: ToolParams): Promise<string> {
-  if (!Number.isInteger(params.line) || (params.line as number) < 1) {
-    return validationError("`line` must be a positive 1-based integer for node_at action.");
-  }
-  if (!Number.isInteger(params.character) || (params.character as number) < 1) {
-    return validationError("`character` must be a positive 1-based integer for node_at action.");
-  }
-
-  const file = params.file;
-  const line = params.line as number;
-  const character = params.character as number;
-  const result = await lookupNodeAt(runtime, file as string, line, character);
+async function handleNodeAt(
+  runtime: TreeSitterRuntime,
+  file: string,
+  line: number,
+  character: number,
+): Promise<string> {
+  const result = await lookupNodeAt(runtime, file, line, character);
   if (result.kind !== "success") return formatNonSuccess(result);
 
   const { data } = result;
@@ -212,13 +276,12 @@ async function handleNodeAt(runtime: TreeSitterRuntime, params: ToolParams): Pro
   return lines.join("\n");
 }
 
-async function handleQuery(runtime: TreeSitterRuntime, params: ToolParams): Promise<string> {
-  if (!params.query || params.query.trim().length === 0) {
-    return validationError("`query` is required and must be non-empty.");
-  }
-
-  const file = params.file as string;
-  const result = await runtime.queryFile(file, params.query);
+async function handleQuery(
+  runtime: TreeSitterRuntime,
+  file: string,
+  query: string,
+): Promise<string> {
+  const result = await runtime.queryFile(file, query);
   if (result.kind !== "success") return formatNonSuccess(result);
 
   const { data: captures } = result;
@@ -237,25 +300,12 @@ async function handleQuery(runtime: TreeSitterRuntime, params: ToolParams): Prom
   return lines.join("\n");
 }
 
-function toSupportedAction(action: string): TreeSitterAction | undefined {
-  if (["outline", "imports", "exports", "node_at", "query", "callees"].includes(action)) {
-    return action as TreeSitterAction;
-  }
-  return undefined;
-}
-
-async function handleCallees(runtime: TreeSitterRuntime, params: ToolParams): Promise<string> {
-  if (!Number.isInteger(params.line) || (params.line as number) < 1) {
-    return validationError("`line` must be a positive 1-based integer for callees action.");
-  }
-  if (!Number.isInteger(params.character) || (params.character as number) < 1) {
-    return validationError("`character` must be a positive 1-based integer for callees action.");
-  }
-
-  const file = params.file as string;
-  const line = params.line as number;
-  const character = params.character as number;
-
+async function handleCallees(
+  runtime: TreeSitterRuntime,
+  file: string,
+  line: number,
+  character: number,
+): Promise<string> {
   const result = await lookupCalleesAt(runtime, file, line, character);
   if (result.kind !== "success") return formatNonSuccess(result);
 

package/src/types.ts

@@ -66,8 +66,8 @@ export interface QueryCapture {
   text: string;
 }
 
-/** Session-level Tree-sitter service. */
-export interface TreeSitterSession {
+/** 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. */
   canParse(file: string): Promise<TreeSitterResult<{ file: string; language: string }>>;
   /** Run a Tree-sitter query and return all captures. */
@@ -86,10 +86,21 @@ export interface TreeSitterSession {
     line: number,
     character: number,
   ): Promise<TreeSitterResult<CalleesAtResult>>;
+}
+
+/** Owned Tree-sitter session that must release its runtime resources. */
+export interface TreeSitterSession extends TreeSitterService {
   /** Release parser and grammar resources owned by this session. */
   dispose(): void;
 }
 
+/** Session-scoped shared structural service published by the extension runtime. */
+export type SessionTreeSitterService = TreeSitterService;
+
+export type SessionTreeSitterServiceState =
+  | { kind: "ready"; service: SessionTreeSitterService }
+  | { kind: "unavailable"; reason: string };
+
 /** Supported grammar identifiers. */
 export type GrammarId =
   | "javascript"