@mrclrchtr/supi-code-intelligence 0.1.0

package/node_modules/@mrclrchtr/supi-tree-sitter/src/exports.ts

@@ -0,0 +1,315 @@
+// Export extraction for supported files.
+
+import { nodeToRange } from "./coordinates.ts";
+import type { TreeSitterRuntime } from "./runtime.ts";
+import type { SyntaxNodeLike } from "./syntax-node.ts";
+import type { ExportRecord, TreeSitterResult } from "./types.ts";
+
+/** Extract export records from a supported file. */
+export async function extractExports(
+  runtime: TreeSitterRuntime,
+  filePath: string,
+): Promise<TreeSitterResult<ExportRecord[]>> {
+  const parseResult = await runtime.parseFile(filePath);
+  if (parseResult.kind !== "success") return parseResult;
+
+  const { tree, source } = parseResult.data;
+  const exports: ExportRecord[] = [];
+
+  try {
+    collectTopLevelExports(tree.rootNode, source, exports);
+    return { kind: "success", data: exports };
+  } finally {
+    tree.delete();
+  }
+}
+
+/** Only collect file-level exports; nested namespace/module exports are not module exports. */
+function collectTopLevelExports(
+  rootNode: SyntaxNodeLike,
+  source: string,
+  exports: ExportRecord[],
+): void {
+  for (const child of rootNode.children) {
+    if (child.type !== "export_statement") continue;
+    handleExportStatement(child, source, exports);
+  }
+}
+
+/** Dispatch a single export statement into declaration, re-export, default, or named export records. */
+function handleExportStatement(
+  node: SyntaxNodeLike,
+  source: string,
+  exports: ExportRecord[],
+): void {
+  const decl = findDeclarationChild(node);
+
+  if (decl) {
+    extractDeclarationExport(decl, source, exports);
+    return;
+  }
+
+  const sourceNode = findStringChild(node);
+  if (sourceNode) {
+    extractReExport(node, sourceNode, source, exports);
+    return;
+  }
+
+  if (hasExportAssignment(node)) {
+    extractExportAssignment(node, source, exports);
+    return;
+  }
+
+  if (hasDefaultKeyword(node)) {
+    extractDefaultExport(node, source, exports);
+    return;
+  }
+
+  extractNamedExportClause(node, source, exports);
+}
+
+function findDeclarationChild(node: SyntaxNodeLike): SyntaxNodeLike | undefined {
+  return node.children.find((child) => DECLARATION_EXPORT_NODE_TYPES.has(child.type));
+}
+
+const DECLARATION_EXPORT_NODE_TYPES = new Set([
+  "function_declaration",
+  "generator_function_declaration",
+  "class_declaration",
+  "abstract_class_declaration",
+  "interface_declaration",
+  "type_alias_declaration",
+  "enum_declaration",
+  "lexical_declaration",
+  "ambient_declaration",
+  "internal_module",
+  "module",
+]);
+
+function extractDeclarationExport(
+  decl: SyntaxNodeLike,
+  source: string,
+  exports: ExportRecord[],
+): void {
+  if (decl.type === "lexical_declaration") {
+    extractLexicalDeclarationExports(decl, source, exports);
+    return;
+  }
+
+  if (decl.type === "ambient_declaration") {
+    extractAmbientDeclarationExport(decl, source, exports);
+    return;
+  }
+
+  const name = getDeclarationName(decl);
+  if (!name) return;
+
+  exports.push({
+    name,
+    kind: exportKindForDeclaration(decl.type),
+    range: nodeToRange(decl, source),
+  });
+}
+
+function extractLexicalDeclarationExports(
+  decl: SyntaxNodeLike,
+  source: string,
+  exports: ExportRecord[],
+): void {
+  for (const child of decl.children) {
+    if (child.type !== "variable_declarator") continue;
+    const nameNode = findNameNode(child);
+    if (!nameNode) continue;
+    exports.push({
+      name: nameNode.text,
+      kind: "variable",
+      range: nodeToRange(child, source),
+    });
+  }
+}
+
+/** Extract the declared symbol from `export declare ...` statements. */
+function extractAmbientDeclarationExport(
+  decl: SyntaxNodeLike,
+  source: string,
+  exports: ExportRecord[],
+): void {
+  const nested = decl.children.find((child) => child.type !== "declare" && child.type !== ";");
+  if (!nested) return;
+
+  const name = getDeclarationName(nested);
+  if (!name) return;
+
+  exports.push({
+    name,
+    kind: exportKindForDeclaration(nested.type),
+    range: nodeToRange(decl, source),
+  });
+}
+
+/** Map Tree-sitter declaration node types to stable public export kinds. */
+function exportKindForDeclaration(type: string): string {
+  switch (type) {
+    case "function_declaration":
+    case "generator_function_declaration":
+    case "function_signature":
+      return "function";
+    case "class_declaration":
+    case "abstract_class_declaration":
+      return "class";
+    case "interface_declaration":
+      return "interface";
+    case "type_alias_declaration":
+      return "type";
+    case "enum_declaration":
+      return "enum";
+    case "internal_module":
+    case "module":
+      return "namespace";
+    default:
+      return type.replace(/_declaration$/, "");
+  }
+}
+
+function hasDefaultKeyword(node: SyntaxNodeLike): boolean {
+  return node.children.some((child) => child.type === "default");
+}
+
+function hasExportAssignment(node: SyntaxNodeLike): boolean {
+  return node.children.some((child) => child.type === "=");
+}
+
+function extractExportAssignment(
+  node: SyntaxNodeLike,
+  source: string,
+  exports: ExportRecord[],
+): void {
+  const expr = node.children.find(
+    (child) => child.type !== "export" && child.type !== "=" && child.type !== ";",
+  );
+
+  exports.push({
+    name: expr ? expr.text.substring(0, 60) : "=",
+    kind: "export assignment",
+    range: nodeToRange(node, source),
+  });
+}
+
+function extractDefaultExport(node: SyntaxNodeLike, source: string, exports: ExportRecord[]): void {
+  const expr = node.children.find(
+    (child) => child.type !== "export" && child.type !== "default" && child.type !== ";",
+  );
+  exports.push({
+    name: expr ? expr.text.substring(0, 60) : "default",
+    kind: "default export",
+    range: nodeToRange(node, source),
+  });
+}
+
+function findStringChild(node: SyntaxNodeLike): SyntaxNodeLike | undefined {
+  return node.children.find((child) => child.type === "string");
+}
+
+function extractReExport(
+  node: SyntaxNodeLike,
+  sourceNode: SyntaxNodeLike,
+  source: string,
+  exports: ExportRecord[],
+): void {
+  const specifier = sourceNode.text.replace(/^["']|["']$/g, "");
+  const namespaceExport = node.children.find((child) => child.type === "namespace_export");
+  if (namespaceExport) {
+    extractNamespaceReExport(namespaceExport, specifier, source, exports);
+    return;
+  }
+
+  const exportClause = node.children.find((child) => child.type === "export_clause");
+  if (exportClause) {
+    extractExportSpecifiers(exportClause, source, exports, {
+      kind: "re-export",
+      moduleSpecifier: specifier,
+    });
+    return;
+  }
+
+  exports.push({
+    name: "*",
+    kind: "re-export",
+    range: nodeToRange(node, source),
+    moduleSpecifier: specifier,
+  });
+}
+
+/** Extract `export * as name from "module"` namespace re-export records. */
+function extractNamespaceReExport(
+  node: SyntaxNodeLike,
+  moduleSpecifier: string,
+  source: string,
+  exports: ExportRecord[],
+): void {
+  const nameNode = findNameNode(node);
+  if (!nameNode) return;
+
+  exports.push({
+    name: nameNode.text,
+    kind: "re-export",
+    range: nodeToRange(node, source),
+    moduleSpecifier,
+  });
+}
+
+function extractNamedExportClause(
+  node: SyntaxNodeLike,
+  source: string,
+  exports: ExportRecord[],
+): void {
+  const exportClause = node.children.find((child) => child.type === "export_clause");
+  if (!exportClause) return;
+
+  extractExportSpecifiers(exportClause, source, exports, { kind: "export" });
+}
+
+function extractExportSpecifiers(
+  exportClause: SyntaxNodeLike,
+  source: string,
+  exports: ExportRecord[],
+  options: { kind: "export" | "re-export"; moduleSpecifier?: string },
+): void {
+  for (const child of exportClause.children) {
+    if (child.type !== "export_specifier") continue;
+    const exportedName = child.childForFieldName("alias") ?? child.childForFieldName("name");
+    if (!exportedName) continue;
+    exports.push({
+      name: exportedName.text,
+      kind: options.kind,
+      range: nodeToRange(child, source),
+      ...(options.moduleSpecifier ? { moduleSpecifier: options.moduleSpecifier } : {}),
+    });
+  }
+}
+
+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 getDeclarationName(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, "");
+}

package/node_modules/@mrclrchtr/supi-tree-sitter/src/formatting.ts

@@ -0,0 +1,104 @@
+// Formatting helpers for tree_sitter tool output.
+
+import type { OutlineItem, TreeSitterResult } from "./types.ts";
+
+export const MAX_ITEMS = 100;
+
+export function validationError(message: string): string {
+  return `**Validation error:** ${message}`;
+}
+
+export function formatNonSuccess(
+  result: Exclude<TreeSitterResult<unknown>, { kind: "success" }>,
+): string {
+  switch (result.kind) {
+    case "unsupported-language":
+      return `**Unsupported language:** ${result.message}`;
+    case "file-access-error":
+      return `**File access error:** ${result.message}`;
+    case "validation-error":
+      return `**Validation error:** ${result.message}`;
+    case "runtime-error":
+      return `**Runtime error:** ${result.message}`;
+  }
+}
+
+export function truncateText(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text;
+  return `${text.substring(0, maxLen)}…`;
+}
+
+export function truncate<T>(items: T[], max: number): { included: T[]; truncated: number } {
+  if (items.length <= max) return { included: items, truncated: 0 };
+  return { included: items.slice(0, max), truncated: items.length - max };
+}
+
+export function truncatedNotice(count: number, kind: string, max = MAX_ITEMS): string {
+  return `⚠ ${count} additional ${kind} omitted (result capped at ${max}).`;
+}
+
+interface OutlineFormatContext {
+  lines: string[];
+  max: number;
+  emitted: number;
+  omitted: number;
+}
+
+/**
+ * Append outline items to `lines` while enforcing a recursive item cap.
+ *
+ * The cap counts every printed declaration, including nested methods and other
+ * children. This keeps generated or deeply nested files from bypassing the
+ * `tree_sitter` tool's agent-facing result limit.
+ */
+export function formatOutlineItemsCapped(
+  items: OutlineItem[],
+  lines: string[],
+  max = MAX_ITEMS,
+): { emitted: number; omitted: number } {
+  const context: OutlineFormatContext = { lines, max, emitted: 0, omitted: 0 };
+  appendOutlineItems(items, context, 0);
+  return { emitted: context.emitted, omitted: context.omitted };
+}
+
+/** Append outline items without a cap. Prefer `formatOutlineItemsCapped` for tool output. */
+export function formatOutlineItems(items: OutlineItem[], lines: string[], depth: number): void {
+  appendOutlineItems(
+    items,
+    { lines, max: Number.POSITIVE_INFINITY, emitted: 0, omitted: 0 },
+    depth,
+  );
+}
+
+function appendOutlineItems(
+  items: OutlineItem[],
+  context: OutlineFormatContext,
+  depth: number,
+): void {
+  for (const item of items) {
+    if (context.emitted >= context.max) {
+      context.omitted += countOutlineItems(item);
+      continue;
+    }
+
+    appendOutlineItem(item, context, depth);
+    context.emitted++;
+
+    if (item.children?.length) {
+      appendOutlineItems(item.children, context, depth + 1);
+    }
+  }
+}
+
+function appendOutlineItem(item: OutlineItem, context: OutlineFormatContext, depth: number): void {
+  const indent = "  ".repeat(depth);
+  const range = item.range;
+  context.lines.push(
+    `${indent}- ${item.kind}: ${item.name} (L${range.startLine}:${range.startCharacter}-L${range.endLine}:${range.endCharacter})`,
+  );
+}
+
+function countOutlineItems(item: OutlineItem): number {
+  const childCount = item.children?.reduce((sum, child) => sum + countOutlineItems(child), 0) ?? 0;
+  return 1 + childCount;
+}

package/node_modules/@mrclrchtr/supi-tree-sitter/src/imports.ts

@@ -0,0 +1,42 @@
+// Import extraction for supported files.
+
+import { nodeToRange } from "./coordinates.ts";
+import type { TreeSitterRuntime } from "./runtime.ts";
+import type { SyntaxNodeLike } from "./syntax-node.ts";
+import type { ImportRecord, TreeSitterResult } from "./types.ts";
+
+/** Extract import records from a supported file. */
+export async function extractImports(
+  runtime: TreeSitterRuntime,
+  filePath: string,
+): Promise<TreeSitterResult<ImportRecord[]>> {
+  const parseResult = await runtime.parseFile(filePath);
+  if (parseResult.kind !== "success") return parseResult;
+
+  const { tree, source } = parseResult.data;
+  const imports: ImportRecord[] = [];
+
+  try {
+    walkForImports(tree.rootNode, source, imports);
+    return { kind: "success", data: imports };
+  } finally {
+    tree.delete();
+  }
+}
+
+function walkForImports(node: SyntaxNodeLike, source: string, imports: ImportRecord[]): void {
+  if (node.type === "import_statement") {
+    const sourceNode = node.childForFieldName("source");
+    if (sourceNode) {
+      const specifier = sourceNode.text.replace(/^["']|["']$/g, "");
+      imports.push({
+        moduleSpecifier: specifier,
+        range: nodeToRange(node, source),
+      });
+    }
+    return;
+  }
+  for (const child of node.children) {
+    walkForImports(child, source, imports);
+  }
+}

package/node_modules/@mrclrchtr/supi-tree-sitter/src/index.ts

@@ -0,0 +1,16 @@
+// Public session factory and re-exports for @mrclrchtr/supi-tree-sitter.
+
+export { createTreeSitterSession } from "./session.ts";
+export type {
+  CalleesAtResult,
+  ExportRecord,
+  GrammarId,
+  ImportRecord,
+  NodeAtResult,
+  OutlineItem,
+  QueryCapture,
+  SourceRange,
+  SupportedExtension,
+  TreeSitterResult,
+  TreeSitterSession,
+} from "./types.ts";

package/node_modules/@mrclrchtr/supi-tree-sitter/src/language.ts

@@ -0,0 +1,116 @@
+// Language detection and grammar resolution for Tree-sitter.
+//
+// All grammar WASM files are vendored in resources/grammars/<id>/ and
+// shipped with the package. No runtime require.resolve() to third-party
+// npm packages is needed.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { GrammarId, SupportedExtension } from "./types.ts";
+
+const sourceDir = path.dirname(fileURLToPath(import.meta.url));
+
+/** Mapping from file extension to grammar identifier. */
+const EXTENSION_GRAMMAR: Record<string, GrammarId> = {
+  ".js": "javascript",
+  ".jsx": "javascript",
+  ".mjs": "javascript",
+  ".cjs": "javascript",
+  ".ts": "typescript",
+  ".mts": "typescript",
+  ".cts": "typescript",
+  ".tsx": "tsx",
+  ".py": "python",
+  ".pyi": "python",
+  ".rs": "rust",
+  ".go": "go",
+  ".mod": "go",
+  ".c": "c",
+  ".h": "c",
+  ".cpp": "cpp",
+  ".hpp": "cpp",
+  ".cc": "cpp",
+  ".cxx": "cpp",
+  ".hxx": "cpp",
+  ".c++": "cpp",
+  ".h++": "cpp",
+  ".java": "java",
+  ".kt": "kotlin",
+  ".kts": "kotlin",
+  ".rb": "ruby",
+  ".sh": "bash",
+  ".bash": "bash",
+  ".zsh": "bash",
+  ".html": "html",
+  ".htm": "html",
+  ".xhtml": "html",
+  ".r": "r",
+  ".sql": "sql",
+};
+
+const SUPPORTED_EXTENSIONS = new Set<string>(Object.keys(EXTENSION_GRAMMAR));
+
+/** Check if a file extension is supported. */
+export function isSupportedFile(filePath: string): boolean {
+  return detectGrammar(filePath) !== undefined;
+}
+
+/** Get the file extension if it's supported, otherwise undefined. */
+export function getSupportedExtension(filePath: string): SupportedExtension | undefined {
+  const ext = path.extname(filePath).toLowerCase();
+  return SUPPORTED_EXTENSIONS.has(ext) ? (ext as SupportedExtension) : undefined;
+}
+
+/** Detect the grammar for a file. Returns undefined if unsupported. */
+export function detectGrammar(filePath: string): GrammarId | undefined {
+  const ext = path.extname(filePath).toLowerCase();
+  return EXTENSION_GRAMMAR[ext];
+}
+
+const JS_TS_GRAMMARS: ReadonlySet<GrammarId> = new Set(["javascript", "typescript", "tsx"]);
+
+/** Returns true if the grammar is one the JS/TS extractors understand. */
+export function isJsTsGrammar(grammarId: GrammarId): boolean {
+  return JS_TS_GRAMMARS.has(grammarId);
+}
+
+/** Grammar WASM file names within the vendored resources directory. */
+const GRAMMAR_WASM: Record<GrammarId, string> = {
+  javascript: "tree-sitter-javascript.wasm",
+  typescript: "tree-sitter-typescript.wasm",
+  tsx: "tree-sitter-tsx.wasm",
+  python: "tree-sitter-python.wasm",
+  rust: "tree-sitter-rust.wasm",
+  go: "tree-sitter-go.wasm",
+  c: "tree-sitter-c.wasm",
+  cpp: "tree-sitter-cpp.wasm",
+  java: "tree-sitter-java.wasm",
+  kotlin: "tree-sitter-kotlin.wasm",
+  ruby: "tree-sitter-ruby.wasm",
+  bash: "tree-sitter-bash.wasm",
+  html: "tree-sitter-html.wasm",
+  r: "tree-sitter-r.wasm",
+  sql: "tree-sitter-sql.wasm",
+};
+
+const resourcesDir = path.resolve(sourceDir, "../resources/grammars");
+
+/**
+ * Resolve the WASM grammar file path for a given grammar ID.
+ * All grammars use vendored WASM files under `resources/grammars/<id>/`.
+ */
+export function resolveGrammarWasmPath(grammarId: GrammarId): string {
+  const wasmFile = GRAMMAR_WASM[grammarId];
+  const vendoredPath = path.join(resourcesDir, grammarId, wasmFile);
+
+  // Verify the vendored file exists at init time — fail fast if missing
+  if (!fs.existsSync(vendoredPath)) {
+    throw new Error(
+      `Vendored WASM grammar not found for "${grammarId}": expected at ${vendoredPath}. ` +
+        "Run `node scripts/vendor-wasm.mjs` or reinstall the package.",
+    );
+  }
+
+  return vendoredPath;
+}

package/node_modules/@mrclrchtr/supi-tree-sitter/src/node-at.ts

@@ -0,0 +1,96 @@
+// Node-at-position lookup.
+
+import { nodeToRange, publicToTreeSitter, splitSourceLines } from "./coordinates.ts";
+import type { TreeSitterRuntime } from "./runtime.ts";
+import type { NodeAtResult, SourceRange, TreeSitterResult } from "./types.ts";
+
+const MAX_ANCESTRY = 10;
+
+/** Find the smallest relevant node at a given 1-based position. */
+export async function lookupNodeAt(
+  runtime: TreeSitterRuntime,
+  filePath: string,
+  line: number,
+  character: number,
+): Promise<TreeSitterResult<NodeAtResult>> {
+  if (!Number.isInteger(line) || line < 1) {
+    return { kind: "validation-error", message: "line must be a positive 1-based integer" };
+  }
+  if (!Number.isInteger(character) || character < 1) {
+    return { kind: "validation-error", message: "character must be a positive 1-based integer" };
+  }
+
+  const parseResult = await runtime.parseFile(filePath);
+  if (parseResult.kind !== "success") return parseResult;
+
+  const { tree, source } = parseResult.data;
+
+  try {
+    const boundsError = validateBounds(line, character, source);
+    if (boundsError) return boundsError;
+
+    const tsPoint = publicToTreeSitter(line, character, source);
+    const node = tree.rootNode.descendantForPosition(tsPoint);
+
+    if (!node) {
+      return { kind: "runtime-error", message: "No node found at the given position" };
+    }
+
+    return {
+      kind: "success",
+      data: {
+        type: node.type,
+        range: nodeToRange(node, source),
+        text: node.text,
+        ancestry: collectAncestry(node, source),
+      },
+    };
+  } finally {
+    tree.delete();
+  }
+}
+
+/** Validate that a requested public position exists in the source text. */
+function validateBounds(
+  line: number,
+  character: number,
+  source: string,
+): TreeSitterResult<NodeAtResult> | null {
+  const lines = splitSourceLines(source);
+  if (line > lines.length) {
+    return { kind: "validation-error", message: "line is beyond end of file" };
+  }
+
+  const lineText = lines[line - 1] ?? "";
+  if (character > lineText.length + 1) {
+    return { kind: "validation-error", message: "character is beyond end of line" };
+  }
+
+  return null;
+}
+
+function collectAncestry(
+  node: {
+    type: string;
+    parent: {
+      type: string;
+      startPosition: { row: number; column: number };
+      endPosition: { row: number; column: number };
+      parent: unknown;
+    } | null;
+  },
+  source: string,
+): Array<{ type: string; range: SourceRange }> {
+  const ancestry: Array<{ type: string; range: SourceRange }> = [];
+  let parent = node.parent;
+  let count = 0;
+  while (parent && count < MAX_ANCESTRY) {
+    ancestry.push({
+      type: parent.type,
+      range: nodeToRange(parent, source),
+    });
+    parent = parent.parent as typeof parent | null;
+    count++;
+  }
+  return ancestry;
+}