@mrclrchtr/supi-tree-sitter 0.1.0

package/src/outline.ts

@@ -0,0 +1,287 @@
+// Outline extraction for supported files.
+
+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([
+  "function_declaration",
+  "generator_function_declaration",
+  "class_declaration",
+  "abstract_class_declaration",
+  "class",
+  "interface_declaration",
+  "type_alias_declaration",
+  "enum_declaration",
+  "method_definition",
+  "public_field_definition",
+  "variable_declarator",
+  "ambient_declaration",
+  "internal_module",
+  "module",
+  "function_signature",
+]);
+
+/** Extract a structural outline from a parsed tree. */
+export function collectOutline(rootNode: SyntaxNodeLike, source: string): OutlineItem[] {
+  return collectItems(rootNode, source);
+}
+
+function collectItems(node: SyntaxNodeLike, source: string): OutlineItem[] {
+  const items: OutlineItem[] = [];
+
+  for (const child of node.children) {
+    const item = extractItem(child, source);
+    if (item) {
+      items.push(item);
+    } else {
+      items.push(...collectItems(child, source));
+    }
+  }
+
+  return items;
+}
+
+function extractItem(node: SyntaxNodeLike, source: string): OutlineItem | null {
+  switch (node.type) {
+    case "export_statement":
+      return extractExportStatement(node, source);
+    case "lexical_declaration":
+      return extractLexicalDeclaration(node, source);
+    case "function_declaration":
+    case "generator_function_declaration":
+    case "function_signature":
+      return extractNamedDeclaration(node, "function", source);
+    case "class_declaration":
+    case "abstract_class_declaration":
+    case "class":
+      return extractClassDeclaration(node, source);
+    case "interface_declaration":
+      return extractInterfaceDeclaration(node, source);
+    case "type_alias_declaration":
+      return extractNamedDeclaration(node, "type", source);
+    case "enum_declaration":
+      return extractEnumDeclaration(node, source);
+    case "method_definition":
+      return extractNamedDeclaration(node, "method", source);
+    case "public_field_definition":
+      return extractFieldDefinition(node, source);
+    case "variable_declarator":
+      return extractVariableDeclarator(node, source);
+    case "ambient_declaration":
+      return extractAmbientDeclaration(node, source);
+    case "internal_module":
+    case "module":
+      return extractModuleDeclaration(node, source);
+    default:
+      return null;
+  }
+}
+
+/** Extract an outline item from an export wrapper without exposing non-extractable syntax nodes. */
+function extractExportStatement(node: SyntaxNodeLike, source: string): OutlineItem | null {
+  const decl = node.children.find((child) => OUTLINE_DECLARATION_NODE_TYPES.has(child.type));
+  if (decl) {
+    const item = extractItem(decl, source);
+    if (item) return item;
+  }
+
+  if (hasDefaultKeyword(node)) {
+    return {
+      name: "default",
+      kind: "export",
+      range: nodeToRange(node, source),
+    };
+  }
+
+  const exportClause = node.children.find((child) => child.type === "export_clause");
+  if (exportClause) {
+    return {
+      name: node.text.replace(/^export\s+/, "").substring(0, 60),
+      kind: "export",
+      range: nodeToRange(node, source),
+    };
+  }
+
+  return null;
+}
+
+function extractLexicalDeclaration(node: SyntaxNodeLike, source: string): OutlineItem | null {
+  const declarators = node.children.filter((child) => child.type === "variable_declarator");
+  if (declarators.length !== 1) return null;
+  return extractVariableDeclarator(declarators[0] as SyntaxNodeLike, source);
+}
+
+function extractNamedDeclaration(
+  node: SyntaxNodeLike,
+  kind: string,
+  source: string,
+): OutlineItem | null {
+  const nameNode = findNameNode(node);
+  if (!nameNode) return null;
+
+  return {
+    name: nameNode.text,
+    kind,
+    range: nodeToRange(node, source),
+  };
+}
+
+function extractClassDeclaration(node: SyntaxNodeLike, source: string): OutlineItem {
+  const nameNode = findNameNode(node);
+  return {
+    name: nameNode ? nameNode.text : "<anonymous>",
+    kind: "class",
+    range: nodeToRange(node, source),
+    children: collectClassMembers(node, source),
+  };
+}
+
+function extractInterfaceDeclaration(node: SyntaxNodeLike, source: string): OutlineItem | null {
+  const item = extractNamedDeclaration(node, "interface", source);
+  if (!item) return null;
+  return { ...item, children: collectInterfaceMembers(node, source) };
+}
+
+function extractEnumDeclaration(node: SyntaxNodeLike, source: string): OutlineItem | null {
+  const item = extractNamedDeclaration(node, "enum", source);
+  if (!item) return null;
+  return { ...item, children: collectEnumMembers(node, source) };
+}
+
+function extractVariableDeclarator(node: SyntaxNodeLike, source: string): OutlineItem | null {
+  const nameNode = findNameNode(node);
+  if (!nameNode) return null;
+  return {
+    name: nameNode.text,
+    kind: detectKind(node),
+    range: nodeToRange(node, source),
+  };
+}
+
+function extractFieldDefinition(node: SyntaxNodeLike, source: string): OutlineItem | null {
+  const nameNode = findNameNode(node);
+  if (!nameNode) return null;
+  return {
+    name: nameNode.text,
+    kind: isFunctionLike(node.childForFieldName("value")) ? "field-function" : "field",
+    range: nodeToRange(node, source),
+  };
+}
+
+function extractAmbientDeclaration(node: SyntaxNodeLike, source: string): OutlineItem | null {
+  const declaration = node.children.find((child) => OUTLINE_DECLARATION_NODE_TYPES.has(child.type));
+  return declaration ? extractItem(declaration, source) : null;
+}
+
+function extractModuleDeclaration(node: SyntaxNodeLike, source: string): OutlineItem | null {
+  const name = getModuleName(node);
+  if (!name) return null;
+
+  return {
+    name,
+    kind: "namespace",
+    range: nodeToRange(node, source),
+  };
+}
+
+function detectKind(node: SyntaxNodeLike): string {
+  const valueNode = node.childForFieldName("value");
+  if (!valueNode) return "variable";
+  if (isFunctionLike(valueNode)) return "function";
+  if (valueNode.type === "class" || valueNode.type === "class_expression") return "class";
+  return "variable";
+}
+
+/** Collect supported class members without descending into method implementation bodies. */
+function collectClassMembers(node: SyntaxNodeLike, source: string): OutlineItem[] {
+  const body = node.childForFieldName("body");
+  if (!body) return [];
+
+  const items: OutlineItem[] = [];
+  for (const child of body.children) {
+    if (child.type !== "method_definition" && child.type !== "public_field_definition") continue;
+    const item = extractItem(child, source);
+    if (item) items.push(item);
+  }
+  return items;
+}
+
+/** Collect interface signatures as shallow member outline items. */
+function collectInterfaceMembers(node: SyntaxNodeLike, source: string): OutlineItem[] {
+  const body = node.childForFieldName("body");
+  if (!body) return [];
+
+  const items: OutlineItem[] = [];
+  for (const child of body.children) {
+    const item = extractInterfaceMember(child, source);
+    if (item) items.push(item);
+  }
+  return items;
+}
+
+function extractInterfaceMember(node: SyntaxNodeLike, source: string): OutlineItem | null {
+  if (node.type === "method_signature") return memberItem(node, "method", source);
+  if (node.type === "property_signature") return memberItem(node, "property", source);
+  return null;
+}
+
+/** Collect enum members from both bare identifiers and assigned members. */
+function collectEnumMembers(node: SyntaxNodeLike, source: string): OutlineItem[] {
+  const body = node.childForFieldName("body");
+  if (!body) return [];
+
+  const items: OutlineItem[] = [];
+  for (const child of body.children) {
+    if (child.type !== "property_identifier" && child.type !== "enum_assignment") continue;
+    const item = memberItem(child, "enum-member", source);
+    if (item) items.push(item);
+  }
+  return items;
+}
+
+function memberItem(node: SyntaxNodeLike, kind: string, source: string): OutlineItem | null {
+  const nameNode = findNameNode(node);
+  if (!nameNode) return null;
+  return {
+    name: nameNode.text,
+    kind,
+    range: nodeToRange(node, source),
+  };
+}
+
+function findNameNode(node: SyntaxNodeLike): SyntaxNodeLike | null {
+  return (
+    node.childForFieldName("name") ??
+    node.children.find((child) =>
+      [
+        "identifier",
+        "type_identifier",
+        "property_identifier",
+        "private_property_identifier",
+      ].includes(child.type),
+    ) ??
+    null
+  );
+}
+
+function hasDefaultKeyword(node: SyntaxNodeLike): boolean {
+  return node.children.some((child) => child.type === "default");
+}
+
+function getModuleName(node: SyntaxNodeLike): string | null {
+  const nameNode =
+    node.childForFieldName("name") ?? node.children.find((child) => child.type === "string");
+  if (!nameNode) return null;
+  return nameNode.type === "string" ? stripQuotes(nameNode.text) : nameNode.text;
+}
+
+function stripQuotes(text: string): string {
+  return text.replace(/^["']|["']$/g, "");
+}
+
+function isFunctionLike(node: SyntaxNodeLike | null): boolean {
+  if (!node) return false;
+  return ["arrow_function", "function_expression", "generator_function"].includes(node.type);
+}

package/src/runtime.ts

@@ -0,0 +1,237 @@
+// Tree-sitter runtime — parser management, parse, and query services.
+
+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";
+
+interface ParserEntry {
+  parser: Parser;
+  language: Language;
+}
+
+/**
+ * Session-scoped Tree-sitter runtime.
+ *
+ * A runtime owns the expensive `web-tree-sitter` initialization and parser
+ * instances for one pi working directory. Call `dispose()` when the session is
+ * torn down so WASM parser resources are released.
+ */
+export class TreeSitterRuntime {
+  private parserModule: typeof import("web-tree-sitter") | undefined;
+  private parsers = new Map<GrammarId, ParserEntry>();
+  private parserPromises = new Map<GrammarId, Promise<ParserEntry>>();
+  private initPromise: Promise<typeof import("web-tree-sitter")> | undefined;
+  private initializing = false;
+  private disposed = false;
+
+  /** Create a runtime that resolves relative file paths from `cwd`. */
+  constructor(private cwd: string) {}
+
+  /** Ensure web-tree-sitter Parser is initialized. */
+  private async ensureParserInit(): Promise<typeof import("web-tree-sitter")> {
+    this.assertActive();
+    if (this.parserModule) return this.parserModule;
+    if (this.initializing && this.initPromise) return this.initPromise;
+
+    this.initializing = true;
+    this.initPromise = (async () => {
+      const mod = await import("web-tree-sitter");
+      await mod.Parser.init();
+      this.assertActive();
+      this.parserModule = mod;
+      return mod;
+    })();
+
+    try {
+      return await this.initPromise;
+    } catch (err: unknown) {
+      // Allow retry on next call
+      this.initPromise = undefined;
+      this.initializing = false;
+      throw new Error("Failed to initialize web-tree-sitter", { cause: err });
+    }
+  }
+
+  /**
+   * Get or create a parser entry for a grammar.
+   *
+   * Concurrent first-use calls for the same grammar share one initialization
+   * promise. Failed initialization is not cached, so a later request can retry.
+   */
+  async ensureGrammarParser(grammarId: GrammarId): Promise<ParserEntry> {
+    this.assertActive();
+    const existing = this.parsers.get(grammarId);
+    if (existing) return existing;
+
+    const pending = this.parserPromises.get(grammarId);
+    if (pending) return pending;
+
+    const promise = this.createGrammarParser(grammarId);
+    this.parserPromises.set(grammarId, promise);
+
+    try {
+      return await promise;
+    } finally {
+      if (this.parserPromises.get(grammarId) === promise) {
+        this.parserPromises.delete(grammarId);
+      }
+    }
+  }
+
+  private async createGrammarParser(grammarId: GrammarId): Promise<ParserEntry> {
+    const mod = await this.ensureParserInit();
+    const wasmPath = resolveGrammarWasmPath(grammarId);
+
+    const language = await mod.Language.load(wasmPath);
+    const parser = new mod.Parser();
+    try {
+      parser.setLanguage(language);
+    } catch (err) {
+      parser.delete();
+      throw err;
+    }
+
+    if (this.disposed) {
+      parser.delete();
+      throw new Error("Tree-sitter runtime has been disposed");
+    }
+
+    const entry = { parser, language };
+    this.parsers.set(grammarId, entry);
+    return entry;
+  }
+
+  /** Read and parse a file. Returns structured result. */
+  async parseFile(filePath: string): Promise<
+    TreeSitterResult<{
+      tree: Tree;
+      source: string;
+      resolvedPath: string;
+      grammarId: GrammarId;
+    }>
+  > {
+    const resolvedPath = path.resolve(this.cwd, filePath);
+
+    // Check language support first
+    const grammarId = detectGrammar(filePath);
+    if (!grammarId) {
+      return {
+        kind: "unsupported-language",
+        file: filePath,
+        message: `No Tree-sitter grammar configured for ${path.extname(filePath) || "this file type"}`,
+      };
+    }
+
+    // Read the file
+    let source: string;
+    try {
+      source = fs.readFileSync(resolvedPath, "utf-8");
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : "File could not be read";
+      return {
+        kind: "file-access-error",
+        file: filePath,
+        message,
+      };
+    }
+
+    try {
+      const entry = await this.ensureGrammarParser(grammarId);
+      const tree = entry.parser.parse(source);
+      return {
+        kind: "success",
+        data: { tree: tree as Tree, source, resolvedPath, grammarId },
+      };
+    } catch (err: unknown) {
+      return { kind: "runtime-error", message: formatError(err, "Parser initialization failed") };
+    }
+  }
+
+  /** Execute a Tree-sitter query against a file. */
+  async queryFile(
+    filePath: string,
+    queryString: string,
+  ): Promise<TreeSitterResult<QueryCapture[]>> {
+    if (!queryString || queryString.trim().length === 0) {
+      return { kind: "validation-error", message: "query is required and must be non-empty" };
+    }
+
+    const parseResult = await this.parseFile(filePath);
+    if (parseResult.kind !== "success") return parseResult;
+
+    const { tree, source } = parseResult.data;
+
+    try {
+      const entry = await this.ensureGrammarParser(parseResult.data.grammarId);
+      const mod = await this.ensureParserInit();
+      let query: InstanceType<typeof mod.Query>;
+
+      try {
+        query = new mod.Query(entry.language, queryString);
+      } catch (err: unknown) {
+        return { kind: "validation-error", message: `Invalid query: ${formatError(err)}` };
+      }
+
+      try {
+        const matches = query.matches(tree.rootNode);
+        const captures: QueryCapture[] = [];
+        for (const match of matches) {
+          for (const { name, node } of match.captures) {
+            captures.push({
+              name,
+              nodeType: node.type,
+              range: nodeToRange(node, source),
+              text: node.text,
+            });
+          }
+        }
+        return { kind: "success", data: captures };
+      } finally {
+        query.delete();
+      }
+    } catch (err: unknown) {
+      return { kind: "runtime-error", message: formatError(err, "Query execution failed") };
+    } finally {
+      tree.delete();
+    }
+  }
+
+  /** Get the grammar ID for a file, or undefined if unsupported. */
+  getGrammarId(filePath: string): GrammarId | undefined {
+    return detectGrammar(filePath);
+  }
+
+  /** Resolve a file path from cwd. */
+  resolvePath(filePath: string): string {
+    return path.resolve(this.cwd, filePath);
+  }
+
+  /** Dispose all held parser resources. */
+  dispose(): void {
+    this.disposed = true;
+    for (const [, entry] of this.parsers) {
+      entry.parser.delete();
+    }
+    this.parsers.clear();
+    this.parserPromises.clear();
+    this.parserModule = undefined;
+    this.initPromise = undefined;
+    this.initializing = false;
+  }
+
+  private assertActive(): void {
+    if (this.disposed) {
+      throw new Error("Tree-sitter runtime has been disposed");
+    }
+  }
+}
+
+/** Format errors with their cause chain's first message for user-facing tool output. */
+function formatError(err: unknown, fallback = "Operation failed"): string {
+  if (!(err instanceof Error)) return String(err || fallback);
+  if (err.cause instanceof Error) return `${err.message}: ${err.cause.message}`;
+  return err.message || fallback;
+}

package/src/session.ts

@@ -0,0 +1,112 @@
+// Session factory — creates a TreeSitterSession bound to a working directory.
+
+import { detectGrammar, isJsTsGrammar } from "./language.ts";
+import { TreeSitterRuntime } from "./runtime.ts";
+import {
+  extractExports,
+  extractImports,
+  extractOutline,
+  lookupCalleesAt,
+  lookupNodeAt,
+} from "./structure.ts";
+import type {
+  CalleesAtResult,
+  ExportRecord,
+  ImportRecord,
+  NodeAtResult,
+  OutlineItem,
+  QueryCapture,
+  TreeSitterResult,
+  TreeSitterSession,
+} from "./types.ts";
+
+/**
+ * Create a new Tree-sitter session bound to the given working directory.
+ * The session owns parser/grammar reuse and must be disposed when done.
+ */
+export function createTreeSitterSession(cwd: string): TreeSitterSession {
+  const runtime = new TreeSitterRuntime(cwd);
+
+  return {
+    async canParse(file: string) {
+      const result = await runtime.parseFile(file);
+      if (result.kind !== "success") return result;
+      const { resolvedPath, grammarId, tree } = result.data;
+      try {
+        return {
+          kind: "success",
+          data: { file: resolvedPath, language: grammarId },
+        };
+      } finally {
+        tree.delete();
+      }
+    },
+
+    async query(file: string, queryString: string): Promise<TreeSitterResult<QueryCapture[]>> {
+      return runtime.queryFile(file, queryString);
+    },
+
+    async outline(file: string): Promise<TreeSitterResult<OutlineItem[]>> {
+      const parseResult = await runtime.parseFile(file);
+      if (parseResult.kind !== "success") return parseResult;
+      if (!isJsTsGrammar(parseResult.data.grammarId)) {
+        return {
+          kind: "unsupported-language",
+          file,
+          message: `outline is not supported for ${parseResult.data.grammarId} files`,
+        };
+      }
+      const { tree, source } = parseResult.data;
+      try {
+        const items = extractOutline(tree.rootNode, source);
+        return { kind: "success", data: items };
+      } finally {
+        tree.delete();
+      }
+    },
+
+    async imports(file: string): Promise<TreeSitterResult<ImportRecord[]>> {
+      const grammarId = detectGrammar(file);
+      if (grammarId && !isJsTsGrammar(grammarId)) {
+        return {
+          kind: "unsupported-language",
+          file,
+          message: `imports is not supported for ${grammarId} files`,
+        };
+      }
+      return extractImports(runtime, file);
+    },
+
+    async exports(file: string): Promise<TreeSitterResult<ExportRecord[]>> {
+      const grammarId = detectGrammar(file);
+      if (grammarId && !isJsTsGrammar(grammarId)) {
+        return {
+          kind: "unsupported-language",
+          file,
+          message: `exports is not supported for ${grammarId} files`,
+        };
+      }
+      return extractExports(runtime, file);
+    },
+
+    async nodeAt(
+      file: string,
+      line: number,
+      character: number,
+    ): Promise<TreeSitterResult<NodeAtResult>> {
+      return lookupNodeAt(runtime, file, line, character);
+    },
+
+    async calleesAt(
+      file: string,
+      line: number,
+      character: number,
+    ): Promise<TreeSitterResult<CalleesAtResult>> {
+      return lookupCalleesAt(runtime, file, line, character);
+    },
+
+    dispose() {
+      runtime.dispose();
+    },
+  };
+}

package/src/structure.ts

@@ -0,0 +1,7 @@
+// Structural extraction services — re-exports from sub-modules.
+
+export { lookupCalleesAt } from "./callees.ts";
+export { extractExports } from "./exports.ts";
+export { extractImports } from "./imports.ts";
+export { lookupNodeAt } from "./node-at.ts";
+export { collectOutline as extractOutline } from "./outline.ts";

package/src/syntax-node.ts

@@ -0,0 +1,13 @@
+// Shared type alias for tree-sitter syntax nodes used in structure extraction.
+// We use a minimal interface instead of importing from web-tree-sitter directly
+// to avoid coupling to the runtime module.
+
+export interface SyntaxNodeLike {
+  type: string;
+  text: string;
+  children: SyntaxNodeLike[];
+  parent: SyntaxNodeLike | null;
+  startPosition: { row: number; column: number };
+  endPosition: { row: number; column: number };
+  childForFieldName(name: string): SyntaxNodeLike | null;
+}