@mrclrchtr/supi-tree-sitter 10.0.0 → 11.0.0

package/src/syntax-errors.ts

@@ -0,0 +1,73 @@
+import { nodeToRange } from "./coordinates.ts";
+import type { SyntaxNodeLike } from "./syntax-node.ts";
+import type { GrammarId, SourceRange } from "./types.ts";
+
+/** Return whether a parsed tree contains an explicit or recovered syntax error. */
+export function hasSyntaxErrors(root: SyntaxNodeLike): boolean {
+  if (root.hasError === true) return true;
+  if (root.type === "ERROR" || root.isMissing === true) return true;
+  return (root.children ?? []).some(hasSyntaxErrors);
+}
+
+/** Collect explicit ERROR and inserted-node ranges from one parser tree. */
+export function collectSyntaxErrorRanges(root: SyntaxNodeLike, source: string): SourceRange[] {
+  const ranges: SourceRange[] = [];
+  const seen = new Set<string>();
+  const visit = (node: SyntaxNodeLike): void => {
+    if (node.type === "ERROR" || node.isMissing === true) {
+      const range = nodeToRange(node, source);
+      const key = `${range.startLine}:${range.startCharacter}:${range.endLine}:${range.endCharacter}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        ranges.push(range);
+      }
+      return;
+    }
+    for (const child of node.children ?? []) visit(child);
+  };
+  visit(root);
+  return ranges;
+}
+
+interface SyntaxCompletenessInput<T> {
+  readonly data: T;
+  readonly file: string;
+  readonly root: SyntaxNodeLike;
+  readonly source: string;
+  readonly grammarId: GrammarId;
+}
+
+/** Attach explicit recovery metadata when a parsed tree contains syntax errors. */
+export function withSyntaxCompleteness<T>(input: SyntaxCompletenessInput<T>):
+  | { kind: "success"; data: T }
+  | {
+      kind: "partial";
+      data: T;
+      file: string;
+      reason: string;
+      errorRanges: SourceRange[];
+    } {
+  const { data, file, root, source, grammarId } = input;
+  if (!PARTIAL_EVIDENCE_GRAMMARS.has(grammarId) || !hasSyntaxErrors(root)) {
+    return { kind: "success", data };
+  }
+  return {
+    kind: "partial",
+    data,
+    file,
+    reason: "Tree-sitter recovered syntax; structural evidence may be incomplete.",
+    errorRanges: collectSyntaxErrorRanges(root, source),
+  };
+}
+
+const PARTIAL_EVIDENCE_GRAMMARS: ReadonlySet<GrammarId> = new Set([
+  "javascript",
+  "typescript",
+  "tsx",
+  "python",
+  "java",
+  "go",
+  "rust",
+  "c",
+  "cpp",
+]);

package/src/syntax-node.ts

@@ -7,6 +7,10 @@ export interface SyntaxNodeLike {
   text: string;
   children: SyntaxNodeLike[];
   parent: SyntaxNodeLike | null;
+  /** True when this syntax node is an inserted recovery node. */
+  isMissing?: boolean;
+  /** True when this node contains a syntax error or inserted node. */
+  hasError?: boolean;
   startPosition: { row: number; column: number };
   endPosition: { row: number; column: number };
   childForFieldName(name: string): SyntaxNodeLike | null;

package/src/tool/call-sites.ts

@@ -1,7 +1,6 @@
 /** File-wide call-site extraction using per-grammar tree-sitter queries. */
 
 import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
-import { detectGrammar } from "../language.ts";
 import type { CallSiteMatch, GrammarId, TreeSitterResult } from "../types.ts";
 import type { TreeSitterRuntime } from "../worker/runtime.ts";
 import { normalizeCallName } from "./call-name.ts";
@@ -42,15 +41,14 @@ export function supportsCallSitesGrammar(grammarId: GrammarId): boolean {
 /**
  * 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.
+ * Returns each written call-site expression once, keyed by its exact source range.
  */
 export async function extractCallSites(
   runtime: TreeSitterRuntime,
   filePath: string,
   control?: CodeRequestControl,
 ): Promise<TreeSitterResult<CallSiteMatch[]>> {
-  const grammarId = detectGrammar(filePath);
+  const grammarId = runtime.getGrammarForFile(filePath);
   if (!grammarId) {
     return {
       kind: "unsupported-language",
@@ -69,7 +67,7 @@ export async function extractCallSites(
   }
 
   const queryResult = await runtime.queryFile(filePath, queryStr, control);
-  if (queryResult.kind !== "success") return queryResult;
+  if (queryResult.kind !== "success" && queryResult.kind !== "partial") return queryResult;
 
   const captures = queryResult.data;
   const seen = new Set<string>();
@@ -80,13 +78,21 @@ export async function extractCallSites(
     const name = normalizeCallName(capture.text, grammarId, capture.nodeType);
     if (name.length === 0) continue;
 
-    // Deduplicate by name + line
-    const key = `${name}:${capture.range.startLine}`;
+    // Collapse duplicate captures only when they identify the same source range.
+    const key = `${capture.range.startLine}:${capture.range.startCharacter}:${capture.range.endLine}:${capture.range.endCharacter}`;
     if (seen.has(key)) continue;
     seen.add(key);
 
-    matches.push({ name, startLine: capture.range.startLine });
+    matches.push({
+      name,
+      startLine: capture.range.startLine,
+      startCharacter: capture.range.startCharacter,
+      endLine: capture.range.endLine,
+      endCharacter: capture.range.endCharacter,
+    });
   }
 
-  return { kind: "success", data: matches };
+  return queryResult.kind === "partial"
+    ? { ...queryResult, data: matches }
+    : { kind: "success", data: matches };
 }

package/src/tool/callees.ts

@@ -3,7 +3,7 @@
 
 import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import { validatePublicPositionBounds } from "../coordinates.ts";
-import { detectGrammar } from "../language.ts";
+import { withSyntaxCompleteness } from "../syntax-errors.ts";
 import type { SyntaxNodeLike } from "../syntax-node.ts";
 import type { GrammarId, SourceRange, TreeSitterResult } from "../types.ts";
 import { queryParsedFile, type TreeSitterRuntime } from "../worker/runtime.ts";
@@ -82,11 +82,13 @@ const ENCLOSING_SCOPE_TYPES: Record<GrammarId, ReadonlySet<string>> = {
 // ── Main entrypoint ──────────────────────────────────────────────────
 
 /** Validate that coordinates are usable and grammar is supported. */
-function validateCalleeInput(
-  filePath: string,
-  line: number,
-  character: number,
-): { kind: "ok"; grammarId: GrammarId } | TreeSitterResult<CalleesAtResult> {
+function validateCalleeInput(input: {
+  filePath: string;
+  line: number;
+  character: number;
+  grammarId: GrammarId | undefined;
+}): { kind: "ok" } | TreeSitterResult<CalleesAtResult> {
+  const { filePath, line, character, grammarId } = input;
   if (!Number.isInteger(line) || line < 1) {
     return {
       kind: "validation-error" as const,
@@ -100,7 +102,6 @@ function validateCalleeInput(
     };
   }
 
-  const grammarId = detectGrammar(filePath);
   if (!grammarId) {
     return {
       kind: "unsupported-language" as const,
@@ -117,7 +118,7 @@ function validateCalleeInput(
     };
   }
 
-  return { kind: "ok", grammarId };
+  return { kind: "ok" };
 }
 
 /** Find the enclosing function/method node at a position in the tree. */
@@ -155,15 +156,19 @@ export async function lookupCalleesAt(
   control?: CodeRequestControl,
 ): Promise<TreeSitterResult<CalleesAtResult>> {
   // Validate coordinates and grammar
-  const validation = validateCalleeInput(filePath, line, character);
+  const validation = validateCalleeInput({
+    filePath,
+    line,
+    character,
+    grammarId: runtime.getGrammarForFile(filePath),
+  });
   if (validation.kind !== "ok") return validation;
-  const { grammarId } = validation;
 
   // Parse the file
   const parseResult = await runtime.parseFile(filePath, control);
   if (parseResult.kind !== "success") return parseResult;
 
-  const { tree, source } = parseResult.data;
+  const { tree, source, grammarId } = parseResult.data;
 
   try {
     const boundsError = validatePublicPositionBounds(line, character, source);
@@ -197,13 +202,14 @@ export async function lookupCalleesAt(
     }
 
     const queryResult = await queryParsedFile(runtime, {
+      file: filePath,
       grammarId,
       tree,
       source,
       queryString: queryStr,
       control,
     });
-    if (queryResult.kind !== "success") {
+    if (queryResult.kind !== "success" && queryResult.kind !== "partial") {
       return {
         kind: "runtime-error",
         message: "Callee query failed",
@@ -223,8 +229,7 @@ export async function lookupCalleesAt(
     const enclosingRange = nodeToSourceRange(enclosingNode);
     const scopeName = extractScopeName(enclosingNode);
 
-    return {
-      kind: "success",
+    return withSyntaxCompleteness({
       data: {
         enclosingScope: {
           name: scopeName,
@@ -233,7 +238,11 @@ export async function lookupCalleesAt(
         callees,
         depth,
       },
-    };
+      file: filePath,
+      root: tree.rootNode,
+      source,
+      grammarId,
+    });
   } finally {
     tree.delete();
   }

package/src/tool/exports.ts

@@ -2,6 +2,7 @@
 
 import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import { nodeToRange } from "../coordinates.ts";
+import { withSyntaxCompleteness } from "../syntax-errors.ts";
 import type { SyntaxNodeLike } from "../syntax-node.ts";
 import type { ExportRecord, TreeSitterResult } from "../types.ts";
 import type { TreeSitterRuntime } from "../worker/runtime.ts";
@@ -21,7 +22,13 @@ export async function extractExports(
 
   try {
     collectTopLevelExports(tree.rootNode, source, exports);
-    return { kind: "success", data: exports };
+    return withSyntaxCompleteness({
+      data: exports,
+      file: filePath,
+      root: tree.rootNode,
+      source,
+      grammarId: parseResult.data.grammarId,
+    });
   } finally {
     tree.delete();
   }

package/src/tool/imports.ts

@@ -2,6 +2,7 @@
 
 import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import { nodeToRange } from "../coordinates.ts";
+import { withSyntaxCompleteness } from "../syntax-errors.ts";
 import type { SyntaxNodeLike } from "../syntax-node.ts";
 import type { ImportRecord, TreeSitterResult } from "../types.ts";
 import type { TreeSitterRuntime } from "../worker/runtime.ts";
@@ -19,12 +20,36 @@ export async function extractImports(
   const imports: ImportRecord[] = [];
 
   try {
-    if (parseResult.data.grammarId === "latex") {
-      walkForLatexImports(tree.rootNode, source, imports);
-    } else {
-      walkForImports(tree.rootNode, source, imports);
+    switch (parseResult.data.grammarId) {
+      case "latex":
+        walkForLatexImports(tree.rootNode, source, imports);
+        break;
+      case "python":
+        walkForPythonImports(tree.rootNode, source, imports);
+        break;
+      case "java":
+        walkForJavaImports(tree.rootNode, source, imports);
+        break;
+      case "go":
+        walkForGoImports(tree.rootNode, source, imports);
+        break;
+      case "rust":
+        walkForRustImports(tree.rootNode, source, imports);
+        break;
+      case "c":
+      case "cpp":
+        walkForCIncludes(tree.rootNode, source, imports);
+        break;
+      default:
+        walkForImports(tree.rootNode, source, imports);
     }
-    return { kind: "success", data: imports };
+    return withSyntaxCompleteness({
+      data: imports,
+      file: filePath,
+      root: tree.rootNode,
+      source,
+      grammarId: parseResult.data.grammarId,
+    });
   } finally {
     tree.delete();
   }
@@ -35,18 +60,219 @@ function walkForImports(node: SyntaxNodeLike, source: string, imports: ImportRec
     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);
+}
+
+function walkForPythonImports(node: SyntaxNodeLike, source: string, imports: ImportRecord[]): void {
+  if (node.type === "import_statement") {
+    for (const child of node.children) {
+      const path = pythonImportPath(child);
+      if (path) imports.push({ moduleSpecifier: path, range: nodeToRange(node, source) });
+    }
+    return;
+  }
+  if (node.type === "import_from_statement") {
+    const module = node.children.find(
+      (child) => child.type === "relative_import" || child.type === "dotted_name",
+    );
+    if (module) imports.push({ moduleSpecifier: module.text, range: nodeToRange(node, source) });
+    return;
+  }
+  for (const child of node.children) walkForPythonImports(child, source, imports);
+}
+
+function pythonImportPath(node: SyntaxNodeLike): string | null {
+  if (node.type === "aliased_import") {
+    const path = node.children.find(
+      (child) => child.type === "dotted_name" || child.type === "identifier",
+    );
+    return path?.text ?? null;
+  }
+  return node.type === "dotted_name" || node.type === "identifier" ? node.text : null;
+}
+
+function walkForJavaImports(node: SyntaxNodeLike, source: string, imports: ImportRecord[]): void {
+  if (node.type === "import_declaration") {
+    const path = node.children.find(
+      (child) => child.type === "scoped_identifier" || child.type === "identifier",
+    );
+    if (path) {
+      const wildcard = node.children.some(
+        (child) => child.type === "*" || child.type === "asterisk",
+      );
       imports.push({
-        moduleSpecifier: specifier,
+        moduleSpecifier: `${path.text}${wildcard ? ".*" : ""}`,
         range: nodeToRange(node, source),
       });
     }
     return;
   }
+  for (const child of node.children) walkForJavaImports(child, source, imports);
+}
+
+function walkForGoImports(node: SyntaxNodeLike, source: string, imports: ImportRecord[]): void {
+  if (node.type === "import_spec") {
+    const literal = node.children.find(
+      (child) => child.type === "interpreted_string_literal" || child.type === "raw_string_literal",
+    );
+    if (literal) {
+      imports.push({
+        moduleSpecifier: literalContent(literal.text),
+        range: nodeToRange(node, source),
+      });
+    }
+    return;
+  }
+  for (const child of node.children) walkForGoImports(child, source, imports);
+}
+
+function walkForRustImports(node: SyntaxNodeLike, source: string, imports: ImportRecord[]): void {
+  if (node.type === "use_declaration") {
+    const argument = node.childForFieldName("argument");
+    if (argument) flattenRustUseTree(argument, "", source, imports);
+    return;
+  }
+  if (node.type === "extern_crate_declaration") {
+    const crate = node.children.find((child) => child.type === "identifier");
+    if (crate) imports.push({ moduleSpecifier: crate.text, range: nodeToRange(node, source) });
+    return;
+  }
+  if (node.type === "mod_item") {
+    const body = node.childForFieldName("body");
+    if (body) {
+      walkForRustImports(body, source, imports);
+    } else {
+      const name = node.childForFieldName("name");
+      if (name) imports.push({ moduleSpecifier: name.text, range: nodeToRange(node, source) });
+    }
+    return;
+  }
+  for (const child of node.children) walkForRustImports(child, source, imports);
+}
+
+function flattenRustUseTree(
+  node: SyntaxNodeLike,
+  prefix: string,
+  source: string,
+  imports: ImportRecord[],
+): void {
+  switch (node.type) {
+    case "scoped_use_list":
+      flattenRustScopedUseList(node, prefix, source, imports);
+      return;
+    case "use_list":
+      flattenRustUseList(node, prefix, source, imports);
+      return;
+    case "use_as_clause":
+      flattenRustUseAlias(node, prefix, source, imports);
+      return;
+    case "use_wildcard":
+      flattenRustUseWildcard(node, prefix, source, imports);
+      return;
+    case "self":
+      imports.push({ moduleSpecifier: prefix, range: nodeToRange(node, source) });
+      return;
+    default:
+      if (RUST_USE_PATH_TYPES.has(node.type)) {
+        imports.push({
+          moduleSpecifier: appendRustPath(prefix, node.text),
+          range: nodeToRange(node, source),
+        });
+        return;
+      }
+      for (const child of node.children) flattenRustUseTree(child, prefix, source, imports);
+  }
+}
+
+function flattenRustScopedUseList(
+  node: SyntaxNodeLike,
+  prefix: string,
+  source: string,
+  imports: ImportRecord[],
+): void {
+  const group = node.children.find((child) => child.type === "use_list");
+  const base = node.children.find((child) => child !== group && child.type !== "::");
+  if (group) flattenRustUseTree(group, appendRustPath(prefix, base?.text ?? ""), source, imports);
+}
+
+function flattenRustUseList(
+  node: SyntaxNodeLike,
+  prefix: string,
+  source: string,
+  imports: ImportRecord[],
+): void {
   for (const child of node.children) {
-    walkForImports(child, source, imports);
+    if (["{", "}", ","].includes(child.type)) continue;
+    if (child.type === "self") {
+      imports.push({ moduleSpecifier: prefix, range: nodeToRange(child, source) });
+    } else {
+      flattenRustUseTree(child, prefix, source, imports);
+    }
+  }
+}
+
+function flattenRustUseAlias(
+  node: SyntaxNodeLike,
+  prefix: string,
+  source: string,
+  imports: ImportRecord[],
+): void {
+  const aliasIndex = node.children.findIndex((child) => child.type === "as");
+  const pathChildren = aliasIndex < 0 ? node.children : node.children.slice(0, aliasIndex);
+  const path = pathChildren.find((child) => child.type !== "::");
+  if (path) flattenRustUseTree(path, prefix, source, imports);
+}
+
+function flattenRustUseWildcard(
+  node: SyntaxNodeLike,
+  prefix: string,
+  source: string,
+  imports: ImportRecord[],
+): void {
+  const path = node.children.find((child) => child.type !== "::" && child.type !== "*");
+  const target = appendRustPath(prefix, path?.text ?? "");
+  imports.push({ moduleSpecifier: `${target}::*`, range: nodeToRange(node, source) });
+}
+
+function appendRustPath(prefix: string, suffix: string): string {
+  if (!prefix) return suffix;
+  if (!suffix) return prefix;
+  return `${prefix}::${suffix}`;
+}
+
+function walkForCIncludes(node: SyntaxNodeLike, source: string, imports: ImportRecord[]): void {
+  if (node.type === "preproc_include") {
+    const literal = node.children.find(
+      (child) => child.type === "system_lib_string" || child.type === "string_literal",
+    );
+    if (literal) {
+      imports.push({
+        moduleSpecifier: literalContent(literal.text),
+        range: nodeToRange(node, source),
+      });
+    }
+    return;
   }
+  for (const child of node.children) walkForCIncludes(child, source, imports);
 }
 
+function literalContent(value: string): string {
+  return value.length >= 2 ? value.slice(1, -1) : "";
+}
+
+const RUST_USE_PATH_TYPES = new Set([
+  "identifier",
+  "crate",
+  "self",
+  "super",
+  "scoped_identifier",
+  "scoped_type_identifier",
+]);
+
 const LATEX_IMPORT_FIELDS: Readonly<Record<string, string>> = {
   package_include: "paths",
   class_include: "path",

package/src/tool/node-at.ts

@@ -2,6 +2,7 @@
 
 import type { CodeRequestControl } from "@mrclrchtr/supi-code-runtime/api";
 import { nodeToRange, publicToTreeSitter, validatePublicPositionBounds } from "../coordinates.ts";
+import { withSyntaxCompleteness } from "../syntax-errors.ts";
 import type { NodeAtResult, SourceRange, TreeSitterResult } from "../types.ts";
 import type { TreeSitterRuntime } from "../worker/runtime.ts";
 
@@ -38,15 +39,18 @@ export async function lookupNodeAt(
       return { kind: "runtime-error", message: "No node found at the given position" };
     }
 
-    return {
-      kind: "success",
+    return withSyntaxCompleteness({
       data: {
         type: node.type,
         range: nodeToRange(node, source),
         text: node.text,
         ancestry: collectAncestry(node, source),
       },
-    };
+      file: filePath,
+      root: tree.rootNode,
+      source,
+      grammarId: parseResult.data.grammarId,
+    });
   } finally {
     tree.delete();
   }

package/src/tool/outline-expansion.ts

@@ -0,0 +1,78 @@
+// Declaration wrapper handling for nested outline expansion.
+
+import { nodeToRange } from "../coordinates.ts";
+import type { SyntaxNodeLike } from "../syntax-node.ts";
+import type { GrammarId, OutlineItem } from "../types.ts";
+import { expandNestedItems } from "./outline-nested.ts";
+
+/** Node types that can be extracted directly as outline items. */
+export 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",
+  "lexical_declaration",
+  "ambient_declaration",
+  "internal_module",
+  "module",
+  "function_signature",
+]);
+
+/** Expand extracted declarations using the syntax node that owns their scope. */
+export function expandExtractedItems(options: {
+  readonly items: OutlineItem[];
+  readonly node: SyntaxNodeLike;
+  readonly source: string;
+  readonly lineStarts: readonly number[];
+  readonly grammarId?: GrammarId;
+  readonly extractItemsForNode: (node: SyntaxNodeLike) => OutlineItem[] | null;
+}): OutlineItem[] {
+  const { items, node, source } = options;
+  if (node.type === "export_statement" || node.type === "ambient_declaration") {
+    const declaration = node.children.find((child) =>
+      OUTLINE_DECLARATION_NODE_TYPES.has(child.type),
+    );
+    if (declaration) return expandExtractedItems({ ...options, node: declaration });
+
+    if (node.type === "export_statement") {
+      const expression = node.children.find((child) =>
+        [
+          "arrow_function",
+          "function_expression",
+          "generator_function",
+          "class_expression",
+        ].includes(child.type),
+      );
+      if (expression) return expandExtractedItems({ ...options, node: expression });
+    }
+  }
+
+  if (node.type === "lexical_declaration") {
+    const declarators = node.children.filter((child) => child.type === "variable_declarator");
+    if (declarators.length > 0) {
+      return declarators.flatMap((declarator) => {
+        const range = nodeToRange(declarator, source);
+        const declarationItems = items.filter((item) => sameRange(item.range, range));
+        return expandExtractedItems({ ...options, items: declarationItems, node: declarator });
+      });
+    }
+  }
+
+  return expandNestedItems(options);
+}
+
+function sameRange(left: OutlineItem["range"], right: OutlineItem["range"]): boolean {
+  return (
+    left.startLine === right.startLine &&
+    left.startCharacter === right.startCharacter &&
+    left.endLine === right.endLine &&
+    left.endCharacter === right.endCharacter
+  );
+}