Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* Generic "breadth" extractor tier — one language-agnostic extractor over any
* tree-sitter grammar + its `tags.scm` (the standard tree-sitter tags convention). This is how
* graft covers the long tail of languages for ~one registry row each, instead of
* a hand-written extractor per language (the depth tier in extract.ts).
*
* Grammars are WASM (`tree-sitter-wasm` bundle) loaded via `web-tree-sitter`, so
* a new language needs no native node-gyp build. Loading is async (WASM init), so
* callers MUST `await warmGenericGrammars([...])` once before the synchronous
* `extractGeneric()` is used in a build/check loop. If a grammar isn't warmed,
* `extractGeneric` degrades to a file node only (never throws).
*
* What it emits (signature-only): a file node + one node per `@definition.<kind>`
* capture, and bare-name `calls` raw edges from `@reference.call` attributed to
* the innermost enclosing definition. resolve.ts then resolves those calls by
* name for free (same-file → extracted, unique-global → inferred). Member-call
* receiver typing (recvType) is NOT produced here — that needs a per-language
* binding pass; the opt-in LSP tier fills that gap for popular languages.
*/
import { readFileSync } from "node:fs";
import { fileURLToPath } from "node:url";
import { dirname, join } from "node:path";
import { createRequire } from "node:module";
import { contentHash } from "../util/id.js";
import type { Kind, NodeV1 } from "./types.js";
import type { ExtractResult, Language, RawEdge } from "./extract.js";
const HERE = dirname(fileURLToPath(import.meta.url));
const require = createRequire(import.meta.url);
// queries/ ships beside the compiled JS (copied by the build); fall back to src.
const QUERY_DIRS = [join(HERE, "queries"), join(HERE, "..", "..", "src", "graph", "queries")];
/** A breadth-tier language: graft name, file extensions, and the wasm basename
* in tree-sitter-wasm/<wasm>/tree-sitter-<wasm>.wasm. One row per language. */
export interface GenericLang {
name: string;
exts: string[];
wasm: string;
/** Bundle dirs whose `tags.scm` to use, concatenated, when there is no vendored
* queries/<name>.scm. Only the depth-tier stand-ins below set it. */
bundledTags?: string[];
}
/** The breadth registry. Add a row + a queries/<name>.scm to support a language.
* Extensions here must NOT collide with the depth tier's EXTENSIONS (extract.ts). */
export const GENERIC_LANGS: readonly GenericLang[] = [
{ name: "rust", exts: [".rs"], wasm: "rust" },
{ name: "java", exts: [".java"], wasm: "java" },
{ name: "c", exts: [".c", ".h"], wasm: "c" },
{ name: "cpp", exts: [".cpp", ".cc", ".cxx", ".hpp", ".hh"], wasm: "cpp" },
{ name: "ruby", exts: [".rb"], wasm: "ruby" },
{ name: "c_sharp", exts: [".cs"], wasm: "c_sharp" },
// These ship a tags.scm (calls + symbols); ocaml/zig have none and use the
// node-kind walker fallback (symbols only) — still one row, zero query.
{ name: "scala", exts: [".scala", ".sc"], wasm: "scala" },
{ name: "elixir", exts: [".ex", ".exs"], wasm: "elixir" },
{ name: "solidity", exts: [".sol"], wasm: "solidity" },
{ name: "ocaml", exts: [".ml", ".mli"], wasm: "ocaml" },
{ name: "zig", exts: [".zig"], wasm: "zig" },
{ name: "dart", exts: [".dart"], wasm: "dart" }, // surfaced by PR #38 (@muneebshere)
{ name: "clojure", exts: [".clj", ".cljs", ".cljc", ".bb"], wasm: "clojure" },
{ name: "nix", exts: [".nix"], wasm: "nix" },
{ name: "lua", exts: [".lua"], wasm: "lua" },
{ name: "gleam", exts: [".gleam"], wasm: "gleam" },
];
/**
* WASM stand-ins for the depth tier, used only for a language whose native grammar
* did not load (native.ts): npm 12 skips the install script that builds
* `tree-sitter-kotlin`, for one. They claim no extension, so `genericLangOf` never
* returns them; the build picks one by asking {@link fallbackLangOf}. Output is the
* breadth tier's: symbols and bare-name calls, no receiver types or bindings.
* Kotlin, Swift and PHP use their vendored queries/<name>.scm; the rest use the
* bundle's own tags.scm (typescript's builds on javascript's, as upstream does).
*/
const FALLBACK_LANGS: Record<Exclude<Language, "java">, GenericLang> = {
typescript: { name: "typescript", exts: [], wasm: "typescript", bundledTags: ["javascript", "typescript"] },
tsx: { name: "tsx", exts: [], wasm: "tsx", bundledTags: ["javascript", "tsx"] },
python: { name: "python", exts: [], wasm: "python", bundledTags: ["python"] },
go: { name: "go", exts: [], wasm: "go", bundledTags: ["go"] },
r: { name: "r", exts: [], wasm: "r", bundledTags: ["r"] },
kotlin: { name: "kotlin", exts: [], wasm: "kotlin" },
swift: { name: "swift", exts: [], wasm: "swift" },
php: { name: "php", exts: [], wasm: "php" },
};
/** The breadth-tier grammar that stands in for a depth-tier language whose native
* grammar can't load. Java already has a breadth row, so it is its own stand-in. */
export function fallbackLangOf(lang: Language): GenericLang {
return lang === "java" ? GENERIC_LANGS.find((l) => l.name === "java")! : FALLBACK_LANGS[lang];
}
function rowNamed(name: string): GenericLang | undefined {
return GENERIC_LANGS.find((l) => l.name === name) ?? Object.values(FALLBACK_LANGS).find((l) => l.name === name);
}
const byExt = new Map<string, GenericLang>();
for (const l of GENERIC_LANGS) for (const e of l.exts) byExt.set(e, l);
/** The generic language for a path, or null if no breadth grammar claims it. */
export function genericLangOf(path: string): GenericLang | null {
const lower = path.toLowerCase();
for (const [ext, l] of byExt) if (lower.endsWith(ext)) return l;
return null;
}
/** Every file extension a breadth-tier (generic tree-sitter) grammar claims. */
export function genericExtensions(): string[] {
return GENERIC_LANGS.flatMap((l) => l.exts);
}
// tags.scm @definition.<X> → graft Kind (types.ts). Unmapped → "function".
const KIND: Record<string, Kind> = {
function: "function", method: "method", class: "class", interface: "interface",
type: "type", struct: "struct", enum: "enum", module: "module",
constant: "constant", variable: "variable", field: "variable",
object: "class", property: "variable", // Scala object; Swift/Scala property
};
// Loaded grammars + compiled tags queries, keyed by graft lang name. Populated by
// warmGenericGrammars; read synchronously by extractGeneric.
export interface Loaded { language: unknown; query: unknown | null }
const loaded = new Map<string, Loaded>();
let tsMod: typeof import("web-tree-sitter") | null = null;
let initPromise: Promise<void> | null = null;
function requireWasm(wasm: string): Buffer | null {
// Resolve the grammar wasm from the tree-sitter-wasm bundle (its package.json
// `exports` maps the bare "<lang>/…" subpath to the actual "out/<lang>/…" file).
try {
const p = require.resolve(`tree-sitter-wasm/${wasm}/tree-sitter-${wasm}.wasm`);
return readFileSync(p);
} catch {
return null;
}
}
// Sanitize editor-specific query predicates the tree-sitter Query compiler rejects.
function sanitizeQuery(raw: string): string {
return raw.replace(/\(#(?:strip!|set!|set-adjacent!|select-adjacent!|make-range!|offset!|gsub!)[^()]*\)/g, "");
}
function loadQuery(row: GenericLang): string | null {
for (const dir of QUERY_DIRS) {
try {
return sanitizeQuery(readFileSync(join(dir, `${row.name}.scm`), "utf8"));
} catch {
/* try next dir */
}
}
if (!row.bundledTags) return null;
const parts: string[] = [];
for (const dir of row.bundledTags) {
try {
parts.push(readFileSync(require.resolve(`tree-sitter-wasm/${dir}/tags.scm`), "utf8"));
} catch {
/* no tags.scm for this one */
}
}
return parts.length > 0 ? sanitizeQuery(parts.join("\n")) : null;
}
/** Warm the WASM grammars for the given graft lang names. Idempotent; must be
* awaited once before extractGeneric is used in a sync loop. Unknown/unavailable
* grammars are silently skipped (their files then extract as file-only). */
export async function warmGenericGrammars(langNames: Iterable<string>): Promise<void> {
const want = new Set(langNames);
const need = [...want].filter((n) => !loaded.has(n) && rowNamed(n) !== undefined);
if (need.length === 0) return;
if (!tsMod) {
tsMod = await import("web-tree-sitter");
initPromise = initPromise ?? tsMod.Parser.init();
}
await initPromise;
const { Language, Query } = tsMod;
for (const name of need) {
const row = rowNamed(name)!;
const bytes = requireWasm(row.wasm);
if (!bytes) continue;
try {
const language = await Language.load(bytes);
const scm = loadQuery(row);
let query: unknown | null = null;
if (scm) {
try { query = new Query(language, scm); } catch { query = null; }
}
loaded.set(name, { language, query });
} catch {
/* grammar failed to instantiate — skip; files extract as file-only */
}
}
}
/** True if a grammar has been warmed for this lang (else extractGeneric is file-only). */
export function isWarm(langName: string): boolean {
return loaded.has(langName);
}
/** Test seam: swap in (or, with null, remove) a grammar entry, returning the
* previous one so the caller can restore it. The parse-failure path in
* extractGeneric needs a grammar that throws deterministically; the real crash
* that motivated it (tree-sitter-wasm PHP on heredocs, #139) is heap-state
* dependent, so tests inject a fake here instead of depending on it. */
export function swapGrammarForTest(name: string, entry: Loaded | null): Loaded | null {
const prev = loaded.get(name) ?? null;
if (entry) loaded.set(name, entry);
else loaded.delete(name);
return prev;
}
/** Load one grammar from the tree-sitter-wasms bundle, initialising
* web-tree-sitter on first call. Null when the wasm is missing or won't
* instantiate — never throws, so a caller degrades instead of failing the build.
*
* Shared with the container tier (container.ts), which needs a grammar to find
* where an embedded language starts but none of the tags.scm machinery above.
* Kept here so web-tree-sitter is initialised exactly once per process. */
export async function loadWasmLanguage(wasm: string): Promise<unknown | null> {
if (!tsMod) {
tsMod = await import("web-tree-sitter");
initPromise = initPromise ?? tsMod.Parser.init();
}
await initPromise;
const bytes = requireWasm(wasm);
if (!bytes) return null;
try {
return await tsMod.Language.load(bytes);
} catch {
return null;
}
}
const PARSE_CHUNK = 16384; // <32KB slices — same tree-sitter limit workaround as extract.ts
/** Parse with an already-loaded grammar. Returns the root node, or null if the
* grammar was never warmed or the parse blew up. Companion to
* `loadWasmLanguage` for callers outside this module. */
export function parseWasm(language: unknown, source: string): TsNode | null {
if (!tsMod) return null;
try {
const parser = new tsMod.Parser();
parser.setLanguage(language as never);
const tree = parser.parse((i: number) => source.slice(i, i + PARSE_CHUNK));
return (tree?.rootNode as TsNode) ?? null;
} catch {
return null;
}
}
function fileNode(rel: string, source: string): NodeV1 {
return {
id: rel, name: rel.split("/").pop() ?? rel, kind: "file", path: rel,
span: `L1-L${Math.max(1, source.split("\n").length)}`, signature: null,
exported: true, origin: "generic", body_hash: contentHash(source),
chars: Buffer.byteLength(source), summary_state: "pending", summary: null, crux: null,
};
}
interface Def { id: string; startIndex: number; endIndex: number }
/** The innermost definition whose span covers the token at byte offset `at` —
* the caller a reference found there belongs to. Shared by the tags.scm path and
* the per-language passes below so both attribute edges the same way. */
function enclosingDef(defs: Def[], at: number): Def | undefined {
return defs
.filter((d) => d.startIndex <= at && at < d.endIndex)
.sort((a, b) => (a.endIndex - a.startIndex) - (b.endIndex - b.startIndex))[0];
}
/** Extract a single generic-tier file. Synchronous; needs the grammar pre-warmed.
* Uses the grammar's compiled tags.scm when present (symbols + call edges);
* otherwise falls back to a node-kind tree walker (symbols only) so ANY warmed
* grammar yields a graph even with no vendored query. */
export function extractGeneric(rel: string, source: string, langName: string): ExtractResult {
const nodes: NodeV1[] = [fileNode(rel, source)];
const rawEdges: RawEdge[] = [];
const entry = loaded.get(langName);
if (!entry || !tsMod) return { nodes, rawEdges };
let tree;
try {
const parser = new tsMod.Parser();
parser.setLanguage(entry.language as never);
tree = parser.parse((i: number) => source.slice(i, i + PARSE_CHUNK));
} catch (err) {
// A grammar that throws (e.g. a WASM "memory access out of bounds" from an
// external scanner) is not a per-file syntax problem: swallowing it here left
// the file with only its file node and the build reporting success. Rethrow so
// build.ts records it in `errors`, the CLI prints it, and the extract cache
// remembers the failure instead of caching an empty result as clean.
throw new Error(`${langName} grammar threw: ${err instanceof Error ? err.message : String(err)}`);
}
if (!tree) return { nodes, rawEdges };
const minted = new Set<string>([rel]);
const lines = source.split("\n");
const defs: Def[] = [];
// One definition per source span: a grammar's tags.scm can capture the same node
// under two @definition kinds (Swift `func` is method AND function), and the
// walker can revisit a nested match — both would emit near-duplicate nodes.
const spanSeen = new Set<number>();
// Mint one definition node from a whole-definition tree node. Shared by both
// the tags.scm path and the walker fallback so id/span/signature/body_text are
// built identically.
const mkDef = (name: string, kind: Kind, whole: TsNode): void => {
if (spanSeen.has(whole.startIndex)) return;
spanSeen.add(whole.startIndex);
const idBase = `${rel}#${name}`;
let id = idBase, n = 2;
while (minted.has(id)) id = `${idBase}~${n++}`;
minted.add(id);
const startRow = whole.startPosition.row, endRow = whole.endPosition.row;
const sigLine = (lines[startRow] ?? "").trim().replace(/\s*\{?\s*$/, "");
nodes.push({
id, name, kind, path: rel,
span: `L${startRow + 1}-L${endRow + 1}`,
signature: sigLine || null, exported: true, origin: "generic",
body_hash: contentHash(source.slice(whole.startIndex, whole.endIndex)),
body_text: source.slice(whole.startIndex, whole.endIndex).replace(/\s+/g, " ").slice(0, 5000),
summary_state: "pending", summary: null, crux: null,
});
defs.push({ id, startIndex: whole.startIndex, endIndex: whole.endIndex });
};
if (entry.query) {
tagsExtract(entry.query, tree.rootNode as TsNode, rel, mkDef, defs, rawEdges, langName);
} else {
walkExtract(tree.rootNode as TsNode, mkDef); // no tags.scm → symbols only
}
// The preprocessor is invisible to tags.scm, but in C/C++ a local `#include "x.h"`
// IS the dependency graph — capture it as a file→file import. Likewise a Rust
// `use crate::…` is an in-crate module dependency.
if (langName === "c" || langName === "cpp") extractIncludes(tree.rootNode as TsNode, rel, rawEdges);
else if (langName === "rust") extractUses(tree.rootNode as TsNode, rel, rawEdges);
else if (langName === "php") extractPhpUses(tree.rootNode as TsNode, rel, rawEdges);
else if (langName === "gleam") extractGleamModules(tree.rootNode as TsNode, rel, defs, rawEdges);
return { nodes, rawEdges };
}
/** PHP `use App\Models\User;` → a file→class-file `imports` raw edge, one per imported
* name (a `{ … }` group expands to several). `use function`/`use const` are skipped —
* those name a symbol, not a PSR-4 class file. resolve.ts settles the fully-qualified
* name to the in-repo file by namespace suffix, and drops it when it can't. */
function extractPhpUses(root: TsNode, rel: string, rawEdges: RawEdge[]): void {
const visit = (n: TsNode): void => {
if (n.type === "namespace_use_declaration") {
for (const fqn of phpUseNames(n.text)) rawEdges.push({ source: rel, relation: "imports", specifier: fqn, file: rel });
}
for (let i = 0; i < (n.namedChildCount ?? 0); i++) {
const c = n.namedChild?.(i);
if (c) visit(c);
}
};
visit(root);
}
/** The fully-qualified class names a PHP `use` declaration imports. Handles a plain
* `use A\B\C;`, a comma list `use A\B, C\D;`, a group `use A\B\{C, D};`, and `as` aliases;
* returns [] for `use function`/`use const` (symbol imports, not class files). */
function phpUseNames(text: string): string[] {
let s = text.replace(/^\s*use\s+/, "").replace(/;\s*$/, "").trim();
if (/^(function|const)\b/.test(s)) return [];
const brace = s.indexOf("{");
if (brace >= 0) {
const prefix = s.slice(0, brace).replace(/\\\s*$/, "");
const inner = s.slice(brace + 1, s.lastIndexOf("}"));
return inner.split(",").map((m) => m.trim().replace(/\s+as\s+\w+$/i, "").trim()).filter(Boolean)
.map((m) => `${prefix}\\${m}`);
}
return s.split(",").map((c) => c.trim().replace(/\s+as\s+\w+$/i, "").trim()).filter(Boolean);
}
/** Rust `use crate::a::b::Item` → a file→module `imports` raw edge whose specifier is the
* crate-relative module path (`a/b`). Only in-crate imports are captured; `std::`,
* `super::`, `self::`, external crates, and globs are skipped — resolve.ts settles the
* path against the file's crate root, and drops it when it can't. */
function extractUses(root: TsNode, rel: string, rawEdges: RawEdge[]): void {
const visit = (n: TsNode): void => {
if (n.type === "use_declaration") {
const spec = rustUseModule(n.text);
if (spec !== null) rawEdges.push({ source: rel, relation: "imports", specifier: spec ? `crate/${spec}` : "crate", file: rel });
}
for (let i = 0; i < (n.namedChildCount ?? 0); i++) {
const c = n.namedChild?.(i);
if (c) visit(c);
}
};
visit(root);
}
/** The crate-relative path a Rust `use crate::…` names (`::`→`/`), or null when it is not
* an in-crate import. The FULL path is returned — including any trailing item segment —
* because a single `crate::lexical` can be either a module OR a crate-root item; the
* resolver settles that by finding the longest prefix that is a real module file. A
* `{ … }` group has no single item, so its prefix (before `{`) is the path. */
function rustUseModule(text: string): string | null {
let s = text.replace(/^\s*use\s+/, "").replace(/;\s*$/, "").trim();
const brace = s.indexOf("{");
if (brace >= 0) s = s.slice(0, brace).replace(/::\s*$/, "");
else s = s.replace(/\s+as\s+\w+$/, "");
s = s.trim();
if (s !== "crate" && !s.startsWith("crate::")) return null; // only in-crate absolute imports
if (s.includes("*")) return null; // glob — no single module target
return s.replace(/^crate::?/, "").replace(/\s+/g, "").replace(/::/g, "/"); // "" = crate root
}
/** C/C++ `#include "header.h"` → a file→file `imports` raw edge. Only LOCAL includes
* (quoted) are captured; system includes (`<stdio.h>`) are skipped — high volume, and
* there is no in-repo target to navigate to. resolve.ts settles the quoted path to an
* in-repo header (relative to the including file, else a unique path-suffix match), and
* keeps it as an external string when it cannot — never a guessed edge. */
function extractIncludes(root: TsNode, rel: string, rawEdges: RawEdge[]): void {
const visit = (n: TsNode): void => {
if (n.type === "preproc_include") {
const raw = n.childForFieldName?.("path")?.text ?? "";
if (raw.startsWith('"')) {
const spec = raw.replace(/^"|"$/g, "").trim();
if (spec) rawEdges.push({ source: rel, relation: "imports", specifier: spec, file: rel });
}
}
for (let i = 0; i < (n.namedChildCount ?? 0); i++) {
const c = n.namedChild?.(i);
if (c) visit(c);
}
};
visit(root);
}
/**
* Gleam's module system IS its dependency graph, and it is unusually exact: an
* `import app/thing` names one module file, every reference to another module
* goes through a qualifier that import binds (`thing.helper()`), and there is no
* ambient global scope for a name to arrive from. This pass reads that table and
* uses it for two things.
*
* First, a file→file `imports` raw edge per import, which resolve.ts settles
* against the repo's `.gleam` files (`app/thing` → `…/src/app/thing.gleam`).
*
* Second, precision on calls. tags.scm sees `list.map(…)` as the bare label
* `map`, and because EVERY stdlib call in Gleam is spelled that way, resolving
* those by name alone is a false-edge machine — `map`, `filter`, `try`, `new`
* and `to_string` all collide with in-repo functions. So qualified calls are
* emitted here instead, stamped with the module the qualifier names: resolve.ts
* then looks the label up in that one file, or drops the call when the module is
* out of repo (the stdlib, a hex dependency). Unqualified imports
* (`import app/thing.{helper}`, then a bare `helper()`) give the same two halves,
* so the bare edge tags.scm already emitted is upgraded in place.
*
* A function is as often piped into or handed over as it is called outright
* (`xs |> thing.helper`, `list.map(xs, thing.helper)`), and neither is a
* `function_call` node, so both are read here too: a pipe's right side is a
* call, a name passed as a value is a `references` edge.
*/
function extractGleamModules(root: TsNode, rel: string, defs: Def[], rawEdges: RawEdge[]): void {
// `list` in `list.map(…)` → the module path it was bound to. The qualifier is
// the `as` alias when there is one, else the module path's last segment.
const byQualifier = new Map<string, string>();
// `helper` from `import app/thing.{helper}` (or its `as` alias) → that module.
const byName = new Map<string, string>();
for (let i = 0; i < (root.namedChildCount ?? 0); i++) {
const imp = root.namedChild?.(i);
if (imp?.type !== "import") continue;
const mod = imp.childForFieldName?.("module")?.text;
if (!mod) continue;
rawEdges.push({ source: rel, relation: "imports", specifier: mod, file: rel });
byQualifier.set(imp.childForFieldName?.("alias")?.text || mod.slice(mod.lastIndexOf("/") + 1), mod);
const unqualified = imp.childForFieldName?.("imports");
for (let j = 0; j < (unqualified?.namedChildCount ?? 0); j++) {
const u = unqualified?.namedChild?.(j);
if (u?.type !== "unqualified_import") continue;
// `{ other as o }` binds `o`; `{ type Handler }` binds a type, harmless here.
const local = u.childForFieldName?.("alias")?.text ?? u.childForFieldName?.("name")?.text;
if (local) byName.set(local, mod);
}
}
// This file's own functions, and the module path that names this file, so a
// name that can only be local resolves in this file alone.
const ownFns = new Set<string>();
for (let i = 0; i < (root.namedChildCount ?? 0); i++) {
const fn = root.namedChild?.(i);
const name = fn?.type === "function" ? fn.childForFieldName?.("name")?.text : undefined;
if (name) ownFns.add(name);
}
const ownModule = rel.replace(/\.gleam$/, "");
const ownNames = new Set(defs.map((d) => d.id.slice(rel.length + 1).replace(/~\d+$/, "")));
// A bare name in Gleam is this file's own definition, an unqualified import, or
// a local — there is nowhere else for it to come from. So every bare edge
// tags.scm emitted is pinned to the one module it can mean, and one that means
// neither (a parameter being called, a prelude `Ok` or `Int`) is dropped rather
// than left to match a same-named definition somewhere else in the repo.
for (let i = rawEdges.length - 1; i >= 0; i--) {
const e = rawEdges[i];
if ((e.relation !== "calls" && e.relation !== "references") || e.specifier || !e.name) continue;
const mod = byName.get(e.name) ?? (ownNames.has(e.name) ? ownModule : undefined);
if (mod) e.specifier = mod;
else rawEdges.splice(i, 1);
}
// Every name a function binds — parameters, `let`, `use` and `case` patterns,
// at any depth. There is no scope analysis here, so a name bound ANYWHERE in
// the function is treated as a local throughout it. Coarser than real scoping,
// and only ever in the direction of dropping an edge.
const boundIn = (fn: TsNode): Set<string> => {
const bound = new Set<string>();
const names = (n: TsNode | null | undefined): void => {
// `thing.Busy(x)` and `x: thing.State` spell a module, not a binding.
if (!n || n.type === "remote_constructor_name" || n.type === "remote_type_identifier") return;
if (n.type === "identifier") bound.add(n.text);
// `Busy(since:)` is shorthand for `Busy(since: since)` — the label binds.
if (n.type === "record_pattern_argument" && n.namedChildCount === 1 && n.namedChild?.(0)?.type === "label")
bound.add(n.namedChild(0)!.text);
for (let i = 0; i < (n.namedChildCount ?? 0); i++) names(n.namedChild?.(i));
};
const walk = (n: TsNode): void => {
if (n.type === "function_parameters" || n.type === "use_assignments" || n.type === "case_clause_patterns") names(n);
else if (n.type === "let" || n.type === "let_assert") names(n.childForFieldName?.("pattern"));
for (let i = 0; i < (n.namedChildCount ?? 0); i++) {
const c = n.namedChild?.(i);
if (c) walk(c);
}
};
walk(fn);
return bound;
};
const same = (a: TsNode | null | undefined, b: TsNode): boolean =>
!!a && a.startIndex === b.startIndex && a.endIndex === b.endIndex;
// `xs |> thing.helper` — the right of a pipe is applied, with or without `()`.
const piped = (n: TsNode, parent: TsNode | null): boolean =>
parent?.type === "binary_expression" &&
parent.childForFieldName?.("operator")?.type === "|>" &&
same(parent.childForFieldName?.("right"), n);
// Where a bare name is a value being handed on rather than a binding or a call.
const passed = (n: TsNode, parent: TsNode | null): boolean =>
parent?.type === "argument" || parent?.type === "list" || parent?.type === "tuple" ||
((parent?.type === "let" || parent?.type === "let_assert") && same(parent.childForFieldName?.("value"), n));
const NONE = new Set<string>();
// The ways a Gleam file names something in another module. All carry the
// qualifier, so all get scoped to one file rather than guessed by name.
const emit = (
qualifier: TsNode | null,
name: TsNode | null,
relation: "calls" | "references",
locals: Set<string> = NONE,
): void => {
// Only a bare identifier can be a module qualifier. `field_access` is also how
// the grammar spells record access, so `cfg.handler.run()` is a field chain,
// and a qualifier no import bound is a record field holding a function.
// Neither names a module, and neither gets a guessed edge.
const mod =
qualifier?.type === "identifier" && name && !locals.has(qualifier.text) ? byQualifier.get(qualifier.text) : undefined;
if (!mod || !name) return;
const enc = enclosingDef(defs, name.startIndex);
if (relation === "references" && !enc) return; // no sound source to hang it on
rawEdges.push({ source: enc ? enc.id : rel, relation, file: rel, name: name.text, specifier: mod });
};
const visit = (n: TsNode, parent: TsNode | null, bound: Set<string>): void => {
if (n.type === "function") bound = boundIn(n);
if (n.type === "function_call") {
// `list.map(…)` — a remote function call.
const fn = n.childForFieldName?.("function");
if (fn?.type === "field_access")
emit(fn.childForFieldName?.("record") ?? null, fn.childForFieldName?.("field") ?? null, "calls");
} else if (n.type === "field_access") {
// `thing.helper` with no call around it: applied when it sits on the right
// of a pipe, otherwise named as a value — a callback (`list.map(xs,
// thing.helper)`) or a constant (`thing.limit`). Either way the module's
// symbol is in use, and without the edge it reads as dead code.
//
// A local may share the module's name (`fn show(user: User)` under `import
// app/user`), and Gleam then reads `user.x` as the record's field first and
// the module's `x` only if there is no such field. Applied, that is nearly
// always the module (`user.to_string(user)`), so calls keep their edge; read
// as a value it is nearly always the field (`user.name`), so that is dropped.
if (!(parent?.type === "function_call" && same(parent.childForFieldName?.("function"), n))) {
const record = n.childForFieldName?.("record") ?? null;
const field = n.childForFieldName?.("field") ?? null;
if (piped(n, parent)) emit(record, field, "calls");
else emit(record, field, "references", bound);
}
} else if (n.type === "identifier" && !bound.has(n.text)) {
// The same two shapes for a bare name, which is only ever this file's own
// function or an unqualified import — anything a local could be is dropped.
const enc = enclosingDef(defs, n.startIndex);
const mod = byName.get(n.text) ?? (ownFns.has(n.text) ? ownModule : undefined);
if (!mod || !enc || enc.id === `${rel}#${n.text}`) {
// not a function this file can name, or the function naming itself
} else if (piped(n, parent)) {
rawEdges.push({ source: enc.id, relation: "calls", file: rel, name: n.text, specifier: mod });
} else if (passed(n, parent)) {
rawEdges.push({ source: enc.id, relation: "references", file: rel, name: n.text, specifier: mod });
}
} else if (n.type === "remote_constructor_name") {
// `thing.Busy(since: 1)`, a record update, or a `case` pattern — all apply
// or take apart the same callable, the way the local forms do in tags.scm.
emit(n.childForFieldName?.("module") ?? null, n.childForFieldName?.("name") ?? null, "calls");
} else if (n.type === "remote_type_identifier") {
// `thing.State` in an annotation — names the type without calling it.
emit(n.childForFieldName?.("module") ?? null, n.childForFieldName?.("name") ?? null, "references");
}
for (let i = 0; i < (n.namedChildCount ?? 0); i++) {
const c = n.namedChild?.(i);
if (c) visit(c, n, bound);
}
};
visit(root, null, NONE);
}
/** tags.scm path: @definition.<kind> → nodes, @reference.call/@reference.send →
* bare-name call edges attributed to the innermost enclosing definition. */
function tagsExtract(
query: unknown,
root: TsNode,
rel: string,
mkDef: (name: string, kind: Kind, whole: TsNode) => void,
defs: Def[],
rawEdges: RawEdge[],
langName: string,
): void {
const q = query as { matches(n: unknown): Array<{ captures: Array<{ name: string; node: TsNode }> }> };
const matches = q.matches(root);
// Some grammars' tags.scm capture a definition's own NAME token as a
// @reference.call too (Ruby tags `def foo`'s `foo` as both @name and a call),
// producing bogus self-loops (foo→foo). Skip any call at a definition's name token.
const defNameAt = new Set<number>();
const calls: Array<{ name: string; at: number }> = [];
const refs: Array<{ name: string; at: number }> = [];
for (const m of matches) {
const cap: Record<string, TsNode> = {};
for (const c of m.captures) cap[c.name] = c.node;
const defKey = Object.keys(cap).find((k) => k.startsWith("definition."));
if (defKey && cap.name) {
defNameAt.add(cap.name.startIndex);
mkDef(cap.name.text, KIND[defKey.slice("definition.".length)] ?? "function", defScope(cap[defKey], langName));
}
if (("reference.call" in cap || "reference.send" in cap) && cap.name)
calls.push({ name: cap.name.text, at: cap.name.startIndex });
// Structural references the grammar already marks: a supertype (extends), an
// implemented interface, an object creation (`new Foo`), a module alias. Grammars
// label these @reference.class/.interface/.implementation/.module — heterogeneous
// syntactically but all "names this symbol without calling it". They become
// `references` edges the same precision-first resolver settles to a type-like def
// (same-file certain, unique cross-file inferred, ambiguous dropped), so a data
// class that's only ever extended or instantiated stops being an orphan.
if (("reference.class" in cap || "reference.interface" in cap ||
"reference.implementation" in cap || "reference.module" in cap) && cap.name)
refs.push({ name: cap.name.text, at: cap.name.startIndex });
}
for (const c of calls) {
if (defNameAt.has(c.at)) continue;
const enc = enclosingDef(defs, c.at);
rawEdges.push({ source: enc ? enc.id : rel, relation: "calls", file: rel, name: c.name });
}
for (const r of refs) {
if (defNameAt.has(r.at)) continue;
const enc = enclosingDef(defs, r.at);
if (!enc) continue; // a reference with no enclosing definition has no sound source
rawEdges.push({ source: enc.id, relation: "references", file: rel, name: r.name });
}
}
// Node-type → Kind for the walker fallback. A node is a definition when its type
// ends with a declaration-ish suffix AND names a construct — matched most-specific
// first (method before function). Covers the common tree-sitter grammar vocab
// without any per-language query.
const DEF_SUFFIX = /(declaration|definition|_item|_specifier|_decl|_def|_binding)$/;
function classifyKind(type: string): Kind | null {
const t = type.toLowerCase();
if (!DEF_SUFFIX.test(t) && !/^(class|struct|enum|interface|trait|module|namespace)/.test(t)) return null;
if (/method|constructor/.test(t)) return "method";
if (/func|function|def\b|subroutine|procedure/.test(t)) return "function";
if (/class/.test(t)) return "class";
if (/struct|record/.test(t)) return "struct";
if (/interface|trait|protocol/.test(t)) return "interface";
if (/enum/.test(t)) return "enum";
if (/module|namespace|package|mod_/.test(t)) return "module";
if (/const/.test(t)) return "constant";
if (/typedef|type_alias|type_def|alias/.test(t)) return "type";
if (/type/.test(t)) return "type";
if (/(^|_)(val|var|let|field|property)/.test(t)) return "variable";
return null;
}
/** The declared name of a node: its `name` field, else the first identifier-ish
* descendant within a couple of levels. */
function nodeName(node: TsNode): string | null {
const byField = node.childForFieldName?.("name");
if (byField?.text) return byField.text;
const stack: Array<{ n: TsNode; d: number }> = [{ n: node, d: 0 }];
while (stack.length) {
const { n, d } = stack.shift()!;
if (d > 0 && /identifier|name/.test(n.type) && n.text && !n.text.includes("\n")) return n.text;
if (d < 3) for (let i = 0; i < (n.namedChildCount ?? 0); i++) {
const c = n.namedChild?.(i);
if (c) stack.push({ n: c, d: d + 1 });
}
}
return null;
}
/** Walker fallback: DFS every named node, emit a def for each classified one
* (symbols only — no call resolution without a query). */
function walkExtract(root: TsNode, mkDef: (name: string, kind: Kind, whole: TsNode) => void): void {
const visit = (n: TsNode): void => {
const kind = classifyKind(n.type);
if (kind) {
const name = nodeName(n);
if (name) mkDef(name, kind, n);
}
for (let i = 0; i < (n.namedChildCount ?? 0); i++) {
const c = n.namedChild?.(i);
if (c) visit(c);
}
};
visit(root);
}
/** Minimal structural view of a web-tree-sitter node — shared with container.ts. */
export interface TsNode {
type: string;
text: string;
startIndex: number;
endIndex: number;
startPosition: { row: number; column: number };
endPosition: { row: number; column: number };
parent: TsNode | null;
namedChildCount?: number;
namedChild?(i: number): TsNode | null;
childForFieldName?(field: string): TsNode | null;
}
// Some grammars' tags.scm put @definition.<X> on a narrow node (C tags the
// `function_declarator`, not the whole `function_definition` with its body), so
// the capture's span stops before the body and calls inside it can't be
// attributed to the function. Expand up to the outermost enclosing
// declaration/definition node so a def's span covers its body.
const DEF_CONTAINER = /(definition|declaration|specifier|_item)$/;
function nextNamedSibling(n: TsNode): TsNode | null {
const tagged = n as TsNode & { nextNamedSibling?: TsNode | null };
if ("nextNamedSibling" in tagged) return tagged.nextNamedSibling ?? null;
const p = n.parent;
if (!p?.namedChild) return null;
const count = p.namedChildCount ?? 0;
for (let i = 0; i < count - 1; i++) {
const c = p.namedChild(i);
if (c && c.startIndex === n.startIndex && c.endIndex === n.endIndex) return p.namedChild(i + 1);
}
return null;
}
function defScope(node: TsNode, langName?: string): TsNode {
let n = node;
while (n.parent && DEF_CONTAINER.test(n.parent.type)) n = n.parent;
// Dart's grammar leaves `function_signature` / `method_signature` as a sibling
// of `function_body` (no wrapping function_definition). Expand so a def's span
// covers its body and calls inside it attribute to the function, not the file
// or enclosing class. Gated on Dart so other breadth-tier languages are untouched.
if (langName === "dart") {
const body = nextNamedSibling(n);
if (body?.type === "function_body") {
return {
type: n.type,
text: n.text,
startIndex: n.startIndex,
endIndex: body.endIndex,
startPosition: n.startPosition,
endPosition: body.endPosition,
parent: n.parent,
};
}
}
return n;
}