SDK Reference

// Count imports in a file
return typescriptImports().length;

// Check if this is a test file
return filename().includes(".test.") || filename().includes(".spec.");

// Follow an import to another file
const resolved = resolveTypescriptImport("./utils");
const handle = at(resolved.resolvedPath);
return handle.typescriptExports().length;

// Get type info from the language server
const info = await at(filepath()).getType({ line: 10, pos: 0 });
return info.detail;

column("Language");
// → "TypeScript"

// Use it to branch logic based on another column's value
const lang = column("Language");
if (lang === "Python") return pythonImports().length;
if (lang === "TypeScript") return typescriptImports().length;
return null;

filepath(); // → "/project/src/components/Button.tsx"
directory(); // → "/project/src/components"
filename(); // → "Button.tsx"
extension(); // → ".tsx"

codeowners();
// → ["@frontend-platform", "@design-systems"]

gitLastModified();
// → Date("2025-12-23T17:29:50.000Z")

// Days since last modified:
const d = gitLastModified();
return d ? Math.floor((Date.now() - d.getTime()) / 86400000) : null;

typescriptImports();
// → [
//   {source: "react", specifiers: [{name: "useState"}], default: "React", line: 1},
//   {source: "./utils", specifiers: [{name: "formatDate", alias: "format"}], line: 2}
// ]

typescriptSymbols();
// → [
//   {name: "Button", kind: "function", line: 14, endLine: 45, exported: true},
//   {name: "ButtonProps", kind: "interface", line: 5, endLine: 12, exported: true}
// ]

typescriptExports();
// → [
//   {name: "Button", kind: "function", line: 14},
//   {name: "default", kind: "default", line: 100, originalName: "App"}
// ]

// Resolve where an import points to
resolveTypescriptImport("./utils");
// → {source: "./utils", resolvedPath: "/project/src/utils.ts", isExternal: false, isNotFound: false}

// Resolve all imports at once
resolveTypescriptImports();
// → [{source: "react", resolvedPath: null, isExternal: true, isNotFound: false}, ...]

// Given this code structure:
// 1: export function BenefitsList() {
// 2:   const formatIcon = (item) => {
// 3:     return items.map((x) => {
// 4:       // lineStart = 4
// 5:     });
// 6:   };
// 7: }

enclosingScope();
// → [
//   {name: "BenefitsList", kind: "function", line: 1, endLine: 7, exported: true},
//   {name: "formatIcon", kind: "arrow_function", line: 2, endLine: 6, exported: false},
//   {name: null, kind: "arrow_function", line: 3, endLine: 5, exported: false}
// ]

enclosingComponent();
// → "BenefitsList"

enclosingNamedFunction();
// → "formatIcon" (skips the anonymous .map callback)

scopeDepth();
// → 3

namedScopeAt(0);
// → "BenefitsList" (outermost named scope)

namedScopeAt(1);
// → "formatIcon" (next level)

pythonImports();
// → [
//   {module: "os", names: [], isFrom: false, line: 1},
//   {module: "typing", names: [{name: "List"}, {name: "Dict"}], isFrom: true, line: 2}
// ]

pythonSymbols();
// → [
//   {name: "MyClass", kind: "class", line: 5, endLine: 18, private: false},
//   {name: "process_data", kind: "function", line: 20, endLine: 32, private: false, decorators: ["staticmethod"]}
// ]

resolvePythonImport("django.http");
// → {module: "django.http", resolvedPath: null, isExternal: true, isPackage: false, isNotFound: false}

goImports();
// → [
//   {path: "fmt", line: 3},
//   {path: "github.com/pkg/errors", alias: "errors", line: 4}
// ]

goSymbols();
// → [
//   {name: "MyStruct", kind: "struct", line: 10, endLine: 15, exported: true},
//   {name: "ProcessData", kind: "function", line: 20, endLine: 30, exported: true},
//   {name: "String", kind: "method", line: 40, endLine: 45, exported: true, receiver: "*MyStruct"}
// ]

goCalls({ method: "Println" });
// → [
//   {callee: "fmt.Println", object: "fmt", method: "Println", line: 25, args: [...]}
// ]

resolveGoImport("github.com/pkg/errors");
// → {importPath: "github.com/pkg/errors", resolvedDir: null, isStdlib: false, isExternal: true, isNotFound: false}

// Get all functions called (directly or transitively) from the current function
typescriptCallGraph();
// → [
//   {file: "/project/src/utils.ts", func: "formatDate", count: 2},
//   {file: "/project/src/api.ts", func: "fetchUser", count: 1}
// ]

// Start from a specific function
typescriptCallGraph({ func: "handleSubmit" });

// Limit traversal depth (1-3, default 2)
typescriptCallGraph({ func: "main", depth: 3 });

// Count functions in a specific directory
typescriptCallGraph({ file: "src/utils" });
// → 5

// Count with a predicate
typescriptCallGraph((entry) => entry.func.startsWith("use"));
// → 3

typescriptFindCallChains(
  [{ file: "/project/src/api.ts", func: "handleRequest" }],
  {
    endCondition: (entry) => entry.func.includes("database"),
    maxExplorations: 100,
  },
);
// → [{file: "/project/src/db.ts", func: "queryDatabase"}]

import { at, typescriptImports, resolveTypescriptImport } from "tern-sdk";

export default async () => {
  // Analyze another file with tree-sitter
  const other = at("src/utils.ts");
  other.typescriptSymbols();
  other.fileContent();

  // Follow an import to its source
  const imp = typescriptImports().find((i) => i.source === "./Button");
  if (!imp) return null;
  const resolved = resolveTypescriptImport(imp.source);
  if (!resolved.resolvedPath) return null;

  const source = at(resolved.resolvedPath);
  return source.typescriptExports().length;
};

// String path (absolute or repo-relative)
at("src/utils.ts");

// Call graph entry
const entries = typescriptCallGraph();
const handle = at(entries[0]);

// Reference (from definition(), references(), etc.)
const def = await at("src/api.ts").definition({ line: 10, pos: 5 });
const target = at(def);

import { at, typescriptSymbols } from "tern-sdk";

export default async () => {
  // Get type info for an exported symbol
  const sym = typescriptSymbols().find(
    (s) => s.exported && s.kind === "function",
  );
  if (!sym) return null;

  const handle = at(filepath());
  const info = await handle.getType({ line: sym.line - 1, pos: 0 });
  return info.detail;
  // → "function Button(props: ButtonProps): JSX.Element"
};

// Find all references to a function across the codebase
const handle = at("src/utils.ts");
const refs = await handle.references({ line: 5, pos: 10 });
return refs.references.length;
// → 12

// Who calls this function?
const handle = at("src/api.ts");
const callers = await handle.inboundCalls({ line: 20, pos: 0 });
return callers.source.map((c) => c.name);
// → ["handleSubmit", "processQueue", "runMigration"]

import { log, filepath } from "tern-sdk";

export default () => {
  log("processing", filepath());
  return codeowners();
};

interface TypeScriptImport {
  source: string; // Module specifier
  specifiers: Array<{ name: string; alias?: string }>; // Named imports
  default?: string; // Default import name
  namespace?: string; // Namespace import (import * as X)
  line: number; // Line number (1-indexed)
}

interface TypeScriptSymbol {
  name: string;
  kind:
    | "function"
    | "class"
    | "variable"
    | "interface"
    | "type"
    | "enum"
    | "const";
  line: number;
  endLine: number;
  exported: boolean;
}

interface TypeScriptExport {
  name: string;
  kind:
    | "function"
    | "class"
    | "variable"
    | "interface"
    | "type"
    | "enum"
    | "const"
    | "default"
    | "re-export";
  line: number;
  originalName?: string; // Original name if aliased or default export
  source?: string; // Source module if re-export
}

interface PythonImport {
  module: string; // Module being imported
  names: Array<{ name: string; alias?: string }>; // Specific names imported
  isFrom: boolean; // "from X import Y" style
  alias?: string; // Module alias (import X as Y)
  line: number;
}

interface PythonSymbol {
  name: string;
  kind: "function" | "class" | "variable" | "async_function";
  line: number;
  endLine: number;
  private: boolean; // Starts with _
  decorators?: string[]; // Applied decorators
}

interface GoImport {
  path: string; // Import path
  alias?: string; // Alias if any
  line: number;
}

interface GoSymbol {
  name: string;
  kind:
    | "function"
    | "type"
    | "const"
    | "var"
    | "method"
    | "interface"
    | "struct";
  line: number;
  endLine: number;
  exported: boolean; // Starts with uppercase
  receiver?: string; // Receiver type for methods
}

interface ScopeEntry {
  name: string | null; // Symbol name, or null if anonymous
  kind:
    | "function"
    | "arrow_function"
    | "class"
    | "method"
    | "interface"
    | "object_method";
  line: number;
  endLine: number;
  exported: boolean;
}

interface BlameInfo {
  commit: string; // Commit hash
  author: string; // Author name
  email: string; // Author email
  date: Date; // Commit timestamp
  line: string; // Line content
}

interface TypeScriptCall {
  callee: string; // e.g., "console.log", "useState"
  calleeType: "identifier" | "member_expression" | "call_expression";
  object?: string; // For method calls: "console", "this"
  method?: string; // For method calls: "log", "map"
  line: number;
  endLine: number;
  args: Array<{ value: string; line: number }>;
}

interface PythonCall {
  callee: string; // e.g., "ti.xcom_pull", "print"
  calleeType: "identifier" | "attribute" | "call" | "subscript";
  object?: string; // For method calls: "ti", "foo.bar"
  method?: string; // For method calls: "xcom_pull"
  line: number;
  endLine: number;
  args: Array<{
    type: "positional" | "keyword";
    name?: string;
    value: string;
    line: number;
  }>;
}

interface GoCall {
  callee: string; // e.g., "fmt.Println", "myFunc"
  calleeType: "identifier" | "selector_expression" | "call_expression";
  object?: string; // For selectors: "fmt", "obj"
  method?: string; // For selectors: "Println", "Method"
  line: number;
  endLine: number;
  args: Array<{ value: string; line: number }>;
}

interface ResolvedTypeScriptImport {
  source: string; // Original import source
  resolvedPath: string | null; // Absolute file path, or null
  isExternal: boolean; // node_modules package
  isNotFound: boolean; // Resolution failed
}

interface ResolvedPythonImport {
  module: string; // Original module path
  resolvedPath: string | null; // Absolute file path, or null
  isExternal: boolean; // stdlib or installed package
  isPackage: boolean; // Directory with __init__.py
  isNotFound: boolean; // Resolution failed
}

interface ResolvedGoImport {
  importPath: string; // Original import path
  resolvedDir: string | null; // Absolute directory path, or null
  isStdlib: boolean; // Standard library package
  isExternal: boolean; // Not in current module
  isNotFound: boolean; // Resolution failed
}

interface CallGraphEntry {
  file: string; // Absolute file path
  func: string; // Function name
  count: number; // Number of call edges in traversal
}

interface CallChainEntry {
  file: string; // Absolute file path
  func: string; // Function name
}

// Cursor position (0-indexed)
interface Location {
  line: number;
  pos: number;
}

// A reference to a code location
interface Reference {
  file: string; // Path relative to project root
  source: Location;
  expanse?: Range;
}

// Symbol information from the language server
interface SymbolInfo {
  name: string;
  kind: string; // "function", "method", "class", etc.
  detail: string; // Signature or type annotation
  docs?: string;
  container?: string; // Enclosing symbol name
  definition?: Reference;
}

// A caller or callee in the call hierarchy
interface CallEntry {
  name: string;
  kind: string;
  detail: string;
  call_site: Reference;
}

interface RefList {
  references: Reference[];
}

interface InboundCalls {
  source: CallEntry[]; // Functions that call this one
}

interface OutboundCalls {
  target: CallEntry[]; // Functions called by this one
}

return filename().includes(".test.") || filename().includes(".spec.");

const d = gitLastModified();
return d ? Math.floor((Date.now() - d.getTime()) / 86400000) : null;

return typescriptImports().filter((i) => !i.source.startsWith(".")).length;

return typescriptExports().filter(
  (e) => e.kind === "function" && /^[A-Z]/.test(e.name),
);

const owners = codeowners();
return owners.length > 0 ? owners[0] : null;

return typescriptImports().some(
  (i) => i.specifiers.length === 0 && !i.default && !i.namespace,
);

return enclosingComponent() ?? filename();

return enclosingNamedFunction();

return enclosingClass() !== null;

return typescriptCallGraph().length;

return typescriptCallGraph({ file: "src/db" }) > 0;

const sym = typescriptSymbols().find(
  (s) => s.exported && s.kind === "function",
);
if (!sym) return null;
const info = await at(filepath()).getType({ line: sym.line - 1, pos: 0 });
return info.detail;

const refs = await at(filepath()).references({ line: 0, pos: 0 });
return new Set(refs.references.map((r) => r.file)).size;

return column("Owner") ?? "unowned";

import * as fs from "fs";
import { filepath } from "tern-sdk";

// Runs ONCE when module loads
const graph = JSON.parse(fs.readFileSync("/path/to/graph.json", "utf-8"));

// Runs PER ROW
export default () => {
  return graph.targets[filepath()]?.deps.length ?? 0;
};

import * as fs from "fs";
import { filepath } from "tern-sdk";

// Load and index once
const data = JSON.parse(fs.readFileSync("/repo/deps.json", "utf-8"));
const reverseDeps = new Map<string, string[]>();
for (const [target, info] of Object.entries(data.targets)) {
  for (const dep of (info as any).deps || []) {
    if (!reverseDeps.has(dep)) reverseDeps.set(dep, []);
    reverseDeps.get(dep)!.push(target);
  }
}

// Query per row
export default () => reverseDeps.get(filepath())?.length ?? 0;

import * as fs from "fs";
import * as os from "os";
import * as path from "path";
import { filepath } from "tern-sdk";

// Accumulate results across rows
const tmpFile = path.join(os.tmpdir(), `sdk-summary-${Date.now()}.json`);
const results: Record<string, number> = {};

// Runs once after all rows complete
export const teardown = () => {
  fs.writeFileSync(tmpFile, JSON.stringify(results, null, 2));
};

export default () => {
  const lines = fs.readFileSync(filepath(), "utf-8").split("\n").length;
  results[filepath()] = lines;
  return lines;
};