@mrclrchtr/supi-tree-sitter 1.6.0 → 1.8.0

package/src/tool/guidance.ts

@@ -1,31 +1,35 @@
-// Prompt guidance and tool description for the tree_sitter tool.
+// Guidance surfaces for the focused tree_sitter_* tool set.
 //
-// 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.
+// Derives from tool-specs.ts so prompt surfaces stay in sync with
+// the public tool metadata.
 
-import {
-  formatTreeSitterActionList,
-  getTreeSitterActionNamesByGuidanceGroup,
-} from "./action-specs.ts";
+import { TREE_SITTER_TOOL_SPECS, type TreeSitterToolName } from "./tool-specs.ts";
 
-const jsTsStructureActions = getTreeSitterActionNamesByGuidanceGroup("js-ts-structure")
-  .map((action) => `tree_sitter.${action}(file)`)
-  .join(", ");
+export interface TreeSitterToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
 
-export const toolDescription = `Tree-sitter tool — parser-level structure and syntax queries for supported files.
+export type TreeSitterToolPromptSurfaceMap = Record<
+  TreeSitterToolName,
+  TreeSitterToolPromptSurface
+>;
 
-Actions: ${formatTreeSitterActionList()}.
+const _DEFAULT_SURFACES = buildTreeSitterToolPromptSurfaces();
 
-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 ${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.",
-  "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";
+/**
+ * Build the full prompt-surface map for all 6 tree_sitter_* tools.
+ */
+export function buildTreeSitterToolPromptSurfaces(): TreeSitterToolPromptSurfaceMap {
+  return Object.fromEntries(
+    TREE_SITTER_TOOL_SPECS.map((spec) => [
+      spec.name,
+      {
+        description: spec.description,
+        promptSnippet: spec.promptSnippet,
+        promptGuidelines: [...spec.promptGuidelines],
+      } satisfies TreeSitterToolPromptSurface,
+    ]),
+  ) as TreeSitterToolPromptSurfaceMap;
+}

package/src/tool/handlers.ts

@@ -0,0 +1,196 @@
+// Per-action handler functions for the focused tree_sitter tool surface.
+//
+// Each handler receives only the parameters it needs (no action dispatch).
+// Handlers are shared between the extension factory (tree-sitter.ts) and the
+// tool registration layer (register-tools.ts).
+
+import { detectGrammar, isJsTsGrammar } from "../language.ts";
+import type { TreeSitterRuntime } from "../session/runtime.ts";
+import {
+  formatNonSuccess,
+  formatOutlineItemsCapped,
+  MAX_ITEMS,
+  truncate,
+  truncatedNotice,
+  truncateText,
+} from "./formatting.ts";
+import { collectOutline } from "./outline.ts";
+import { extractExports, extractImports, lookupCalleesAt, lookupNodeAt } from "./structure.ts";
+
+// ---------------------------------------------------------------------------
+// Outline — JS/TS only
+// ---------------------------------------------------------------------------
+
+export async function handleOutline(runtime: TreeSitterRuntime, file: string): Promise<string> {
+  const parseResult = await runtime.parseFile(file);
+  if (parseResult.kind !== "success") return formatNonSuccess(parseResult);
+  if (!isJsTsGrammar(parseResult.data.grammarId)) {
+    return "Unsupported language: outline is only supported for JavaScript and TypeScript files";
+  }
+
+  const { tree, source } = parseResult.data;
+  let items: ReturnType<typeof collectOutline>;
+  try {
+    items = collectOutline(tree.rootNode, source);
+  } finally {
+    tree.delete();
+  }
+
+  if (items.length === 0) return `No structural declarations found in ${file}`;
+
+  const lines = [`## Outline: ${file}`, ""];
+  const { omitted } = formatOutlineItemsCapped(items, lines, MAX_ITEMS);
+  if (omitted) lines.push("", truncatedNotice(omitted, "outline items"));
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Imports — JS/TS only
+// ---------------------------------------------------------------------------
+
+export async function handleImports(runtime: TreeSitterRuntime, file: string): Promise<string> {
+  const grammarId = detectGrammar(file);
+  if (grammarId && !isJsTsGrammar(grammarId)) {
+    return "Unsupported language: imports is only supported for JavaScript and TypeScript files";
+  }
+  const result = await extractImports(runtime, file);
+  if (result.kind !== "success") return formatNonSuccess(result);
+
+  const { data: imports } = result;
+  if (imports.length === 0) return `No imports found in ${file}`;
+
+  const { included, truncated } = truncate(imports, MAX_ITEMS);
+  const lines = [`## Imports: ${file}`, ""];
+  for (const imp of included) {
+    const r = imp.range;
+    lines.push(`- "${imp.moduleSpecifier}" (L${r.startLine}:${r.startCharacter})`);
+  }
+  if (truncated) lines.push("", truncatedNotice(truncated, "imports"));
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Exports — JS/TS only
+// ---------------------------------------------------------------------------
+
+export async function handleExports(runtime: TreeSitterRuntime, file: string): Promise<string> {
+  const grammarId = detectGrammar(file);
+  if (grammarId && !isJsTsGrammar(grammarId)) {
+    return "Unsupported language: exports is only supported for JavaScript and TypeScript files";
+  }
+  const result = await extractExports(runtime, file);
+  if (result.kind !== "success") return formatNonSuccess(result);
+
+  const { data: exports } = result;
+  if (exports.length === 0) return `No exports found in ${file}`;
+
+  const { included, truncated } = truncate(exports, MAX_ITEMS);
+  const lines = [`## Exports: ${file}`, ""];
+  for (const exp of included) {
+    const r = exp.range;
+    const from = exp.moduleSpecifier ? ` from "${exp.moduleSpecifier}"` : "";
+    lines.push(`- ${exp.kind}: ${exp.name}${from} (L${r.startLine}:${r.startCharacter})`);
+  }
+  if (truncated) lines.push("", truncatedNotice(truncated, "exports"));
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Node at position — all supported grammars
+// ---------------------------------------------------------------------------
+
+export 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;
+  const lines = [
+    `## Node at ${file}:${line}:${character}`,
+    "",
+    `**Type:** ${data.type}`,
+    `**Range:** L${data.range.startLine}:${data.range.startCharacter} — L${data.range.endLine}:${data.range.endCharacter}`,
+    `**Text:** ${truncateText(data.text, 200)}`,
+  ];
+
+  if (data.ancestry.length > 0) {
+    lines.push("", "**Ancestry:**");
+    const { included, truncated } = truncate(data.ancestry, MAX_ITEMS);
+    for (const ancestor of included) {
+      lines.push(
+        `- ${ancestor.type} (L${ancestor.range.startLine}:${ancestor.range.startCharacter}-L${ancestor.range.endLine}:${ancestor.range.endCharacter})`,
+      );
+    }
+    if (truncated) lines.push("", truncatedNotice(truncated, "ancestry entries"));
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Query — all supported grammars
+// ---------------------------------------------------------------------------
+
+export 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;
+  if (captures.length === 0) return `No matches for query in ${file}`;
+
+  const { included, truncated } = truncate(captures, MAX_ITEMS);
+  const lines = [`## Query results: ${file}`, ""];
+  for (const capture of included) {
+    const r = capture.range;
+    lines.push(
+      `- ${capture.name}: ${capture.nodeType} (L${r.startLine}:${r.startCharacter}-L${r.endLine}:${r.endCharacter})`,
+    );
+    lines.push(`  \`${truncateText(capture.text, 120)}\``);
+  }
+  if (truncated) lines.push("", truncatedNotice(truncated, "captures"));
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Callees — many supported grammars
+// ---------------------------------------------------------------------------
+
+export 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);
+
+  const { enclosingScope, callees } = result.data;
+  if (callees.length === 0) {
+    return `No outgoing calls found in \`${enclosingScope.name}\` at ${file}:${line}:${character}`;
+  }
+
+  const lines: string[] = [];
+  lines.push(`## Callees: ${file}:${line}:${character}`);
+  lines.push("");
+  lines.push(
+    `**${callees.length} outgoing call${callees.length > 1 ? "s" : ""}** from \`${enclosingScope.name}\` at L${enclosingScope.range.startLine}-L${enclosingScope.range.endLine}`,
+  );
+  lines.push("");
+
+  for (const c of callees.slice(0, MAX_ITEMS)) {
+    lines.push(`- \`${c.name}\` (L${c.range.startLine})`);
+  }
+  if (callees.length > MAX_ITEMS) {
+    lines.push("", truncatedNotice(callees.length - MAX_ITEMS, "callees"));
+  }
+
+  return lines.join("\n");
+}

package/src/tool/register-tools.ts

@@ -0,0 +1,107 @@
+// Focused tool registration for the tree_sitter extension.
+//
+// Derives tool metadata, schemas, and prompt surfaces from tool-specs.ts.
+// Handler functions from ./handlers.ts do the actual work.
+
+import type { AgentToolResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { TreeSitterRuntime } from "../session/runtime.ts";
+import {
+  handleCallees,
+  handleExports,
+  handleImports,
+  handleNodeAt,
+  handleOutline,
+  handleQuery,
+} from "./handlers.ts";
+import {
+  getTreeSitterToolSpec,
+  PARAM_SCHEMAS,
+  TREE_SITTER_TOOL_SPECS,
+  type TreeSitterToolName,
+} from "./tool-specs.ts";
+
+function notInitializedResult(): AgentToolResult<Record<string, unknown>> {
+  return {
+    content: [{ type: "text", text: "Tree-sitter not initialized. Start a new session first." }],
+    details: {},
+  };
+}
+
+function textResult(text: string): AgentToolResult<Record<string, unknown>> {
+  return { content: [{ type: "text", text }], details: {} };
+}
+
+/** Wraps a handler call into a pi-compatible execute function. */
+function createExecute(
+  fn: (runtime: TreeSitterRuntime, params: Record<string, unknown>) => Promise<string> | string,
+  getRuntime: () => TreeSitterRuntime | undefined,
+) {
+  // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
+  return async (
+    _toolCallId: string,
+    params: Record<string, unknown>,
+    _signal: AbortSignal | undefined,
+    _onUpdate: unknown,
+    _ctx: { cwd: string },
+  ): Promise<AgentToolResult<Record<string, unknown>>> => {
+    const runtime = getRuntime();
+    if (!runtime) return notInitializedResult();
+
+    // Guard against direct execute calls (tests, tool reuse) that bypass pi's schema validation
+    if (!params.file || typeof params.file !== "string") {
+      return textResult("Validation error: `file` is required.");
+    }
+
+    try {
+      const text = await fn(runtime, params);
+      return textResult(text);
+    } catch (error) {
+      return textResult(`Error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  };
+}
+
+// ── Handler dispatch map ───────────────────────────────────────────────
+
+type HandlerFn = (
+  runtime: TreeSitterRuntime,
+  params: Record<string, unknown>,
+) => Promise<string> | string;
+
+const HANDLER_MAP: Record<TreeSitterToolName, HandlerFn> = {
+  tree_sitter_outline: (runtime, params) => handleOutline(runtime, String(params.file)),
+  tree_sitter_imports: (runtime, params) => handleImports(runtime, String(params.file)),
+  tree_sitter_exports: (runtime, params) => handleExports(runtime, String(params.file)),
+  tree_sitter_node_at: (runtime, params) =>
+    handleNodeAt(runtime, String(params.file), Number(params.line), Number(params.character)),
+  tree_sitter_query: (runtime, params) =>
+    handleQuery(runtime, String(params.file), String(params.query)),
+  tree_sitter_callees: (runtime, params) =>
+    handleCallees(runtime, String(params.file), Number(params.line), Number(params.character)),
+};
+
+// ── Registration ───────────────────────────────────────────────────────
+
+/**
+ * Register 6 focused tree-sitter tools.
+ *
+ * @param pi — extension API
+ * @param getRuntime — thunk returning the current runtime (or undefined before session_start)
+ */
+export function registerFocusedTreeSitterTools(
+  pi: ExtensionAPI,
+  getRuntime: () => TreeSitterRuntime | undefined,
+): void {
+  for (const spec of TREE_SITTER_TOOL_SPECS) {
+    const spec2 = getTreeSitterToolSpec(spec.name);
+    pi.registerTool({
+      name: spec2.name,
+      label: spec2.label,
+      description: spec2.description,
+      promptSnippet: spec2.promptSnippet,
+      promptGuidelines: spec2.promptGuidelines,
+      parameters: PARAM_SCHEMAS[spec2.paramSchemaKey],
+      execute: createExecute(HANDLER_MAP[spec2.name], getRuntime),
+    });
+  }
+}

package/src/tool/tool-specs.ts

@@ -0,0 +1,117 @@
+/**
+ * Single source of truth for the split `tree_sitter_*` tool surface.
+ *
+ * Tool registration, guidance, and parameter validation should derive
+ * from these specs so the public surface does not drift from the
+ * metadata that drives it.
+ */
+
+import { Type } from "typebox";
+
+// ── Shared parameter fragments ─────────────────────────────────────────
+
+const FileParam = Type.String({ description: "File path" });
+const LineParam = Type.Number({ description: "1-based line", minimum: 1 });
+const CharacterParam = Type.Number({
+  description: "1-based UTF-16 column",
+  minimum: 1,
+});
+const QueryParam = Type.String({ description: "Tree-sitter query" });
+
+export const PARAM_SCHEMAS = {
+  fileOnly: Type.Object({ file: FileParam }, { additionalProperties: false }),
+  fileLineChar: Type.Object(
+    { file: FileParam, line: LineParam, character: CharacterParam },
+    { additionalProperties: false },
+  ),
+  fileQuery: Type.Object({ file: FileParam, query: QueryParam }, { additionalProperties: false }),
+} as const;
+
+export type ParamSchemaKey = keyof typeof PARAM_SCHEMAS;
+
+// ── Tool names ─────────────────────────────────────────────────────────
+
+export const TREE_SITTER_TOOL_NAMES = [
+  "tree_sitter_outline",
+  "tree_sitter_imports",
+  "tree_sitter_exports",
+  "tree_sitter_node_at",
+  "tree_sitter_query",
+  "tree_sitter_callees",
+] as const;
+
+export type TreeSitterToolName = (typeof TREE_SITTER_TOOL_NAMES)[number];
+
+// ── Per-tool metadata ──────────────────────────────────────────────────
+
+export interface TreeSitterToolSpec {
+  name: TreeSitterToolName;
+  label: string;
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+  paramSchemaKey: ParamSchemaKey;
+}
+
+export const TREE_SITTER_TOOL_SPECS: readonly TreeSitterToolSpec[] = [
+  {
+    name: "tree_sitter_outline",
+    label: "Tree-sitter Outline",
+    description: "Shallow JS/TS outline of top-level declarations and supported members.",
+    promptSnippet: "tree_sitter_outline — quick JS/TS outline",
+    promptGuidelines: ["Use tree_sitter_outline(file) for a quick JS/TS outline."],
+    paramSchemaKey: "fileOnly",
+  },
+  {
+    name: "tree_sitter_imports",
+    label: "Tree-sitter Imports",
+    description: "List imports in a JS/TS file.",
+    promptSnippet: "tree_sitter_imports — JS/TS imports",
+    promptGuidelines: ["Use tree_sitter_imports(file) to inspect JS/TS dependencies."],
+    paramSchemaKey: "fileOnly",
+  },
+  {
+    name: "tree_sitter_exports",
+    label: "Tree-sitter Exports",
+    description: "List exports in a JS/TS file.",
+    promptSnippet: "tree_sitter_exports — JS/TS exports",
+    promptGuidelines: ["Use tree_sitter_exports(file) to inspect JS/TS exports."],
+    paramSchemaKey: "fileOnly",
+  },
+  {
+    name: "tree_sitter_node_at",
+    label: "Tree-sitter Node At",
+    description: "Show the syntax node and ancestry at a file position.",
+    promptSnippet: "tree_sitter_node_at — syntax node at a position",
+    promptGuidelines: ["Use tree_sitter_node_at(file,line,character) for the exact syntax node."],
+    paramSchemaKey: "fileLineChar",
+  },
+  {
+    name: "tree_sitter_query",
+    label: "Tree-sitter Query",
+    description: "Run a custom Tree-sitter query against a file.",
+    promptSnippet: "tree_sitter_query — custom AST query",
+    promptGuidelines: ["Use tree_sitter_query(file,query) for custom AST matching."],
+    paramSchemaKey: "fileQuery",
+  },
+  {
+    name: "tree_sitter_callees",
+    label: "Tree-sitter Callees",
+    description: "List outgoing callees from the enclosing scope at a file position.",
+    promptSnippet: "tree_sitter_callees — outgoing callees",
+    promptGuidelines: ["Use tree_sitter_callees(file,line,character) for outgoing calls."],
+    paramSchemaKey: "fileLineChar",
+  },
+];
+
+// ── Lookup helpers ─────────────────────────────────────────────────────
+
+const TREE_SITTER_TOOL_SPEC_MAP = new Map<TreeSitterToolName, TreeSitterToolSpec>(
+  TREE_SITTER_TOOL_SPECS.map((spec) => [spec.name, spec]),
+);
+
+export function getTreeSitterToolSpec(toolName: TreeSitterToolName): TreeSitterToolSpec {
+  const spec = TREE_SITTER_TOOL_SPEC_MAP.get(toolName);
+  if (!spec) throw new Error(`Unknown tree_sitter tool: ${toolName}`);
+  return spec;
+}