trail-code 0.0.0-stage → 0.28.0-semantic.3

package/dist/graph/generic.js

@@ -0,0 +1,773 @@
+/**
+ * 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 { webTreeSitter } from "./wasm-runtime.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")];
+/** 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 = [
+    { 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" },
+];
+/**
+ * Stand-ins for the depth tier, used only for a language whose own grammar did not
+ * load (depth-parser.ts), as after a broken install. 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 = {
+    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) {
+    return lang === "java" ? GENERIC_LANGS.find((l) => l.name === "java") : FALLBACK_LANGS[lang];
+}
+function rowNamed(name) {
+    return GENERIC_LANGS.find((l) => l.name === name) ?? Object.values(FALLBACK_LANGS).find((l) => l.name === name);
+}
+const byExt = new Map();
+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) {
+    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() {
+    return GENERIC_LANGS.flatMap((l) => l.exts);
+}
+// tags.scm @definition.<X>  →  graft Kind (types.ts). Unmapped → "function".
+const 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
+};
+const loaded = new Map();
+let tsMod = null;
+function requireWasm(wasm) {
+    // 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) {
+    return raw.replace(/\(#(?:strip!|set!|set-adjacent!|select-adjacent!|make-range!|offset!|gsub!)[^()]*\)/g, "");
+}
+function loadQuery(row) {
+    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 = [];
+    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) {
+    const want = new Set(langNames);
+    const need = [...want].filter((n) => !loaded.has(n) && rowNamed(n) !== undefined);
+    if (need.length === 0)
+        return;
+    tsMod = await webTreeSitter();
+    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 = 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) {
+    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, entry) {
+    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.
+ * The runtime itself is shared with every WASM tier (wasm-runtime.ts). */
+export async function loadWasmLanguage(wasm) {
+    tsMod = await webTreeSitter();
+    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, source) {
+    if (!tsMod)
+        return null;
+    try {
+        const parser = new tsMod.Parser();
+        parser.setLanguage(language);
+        const tree = parser.parse((i) => source.slice(i, i + PARSE_CHUNK));
+        return tree?.rootNode ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function fileNode(rel, source) {
+    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,
+    };
+}
+/** 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, at) {
+    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, source, langName) {
+    const nodes = [fileNode(rel, source)];
+    const rawEdges = [];
+    const entry = loaded.get(langName);
+    if (!entry || !tsMod)
+        return { nodes, rawEdges };
+    let tree;
+    try {
+        const parser = new tsMod.Parser();
+        parser.setLanguage(entry.language);
+        tree = parser.parse((i) => 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([rel]);
+    const lines = source.split("\n");
+    const defs = [];
+    // 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();
+    // 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, kind, whole) => {
+        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, rel, mkDef, defs, rawEdges, langName);
+    }
+    else {
+        walkExtract(tree.rootNode, 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, rel, rawEdges);
+    else if (langName === "rust")
+        extractUses(tree.rootNode, rel, rawEdges);
+    else if (langName === "php")
+        extractPhpUses(tree.rootNode, rel, rawEdges);
+    else if (langName === "gleam")
+        extractGleamModules(tree.rootNode, 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, rel, rawEdges) {
+    const visit = (n) => {
+        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) {
+    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, rel, rawEdges) {
+    const visit = (n) => {
+        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) {
+    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, rel, rawEdges) {
+    const visit = (n) => {
+        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, rel, defs, rawEdges) {
+    // `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();
+    // `helper` from `import app/thing.{helper}` (or its `as` alias) → that module.
+    const byName = new Map();
+    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();
+    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) => {
+        const bound = new Set();
+        const names = (n) => {
+            // `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) => {
+            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, b) => !!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, parent) => 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, parent) => 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();
+    // 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, name, relation, locals = NONE) => {
+        // 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, parent, bound) => {
+        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, root, rel, mkDef, defs, rawEdges, langName) {
+    const q = query;
+    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();
+    const calls = [];
+    const refs = [];
+    for (const m of matches) {
+        const cap = {};
+        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) {
+    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) {
+    const byField = node.childForFieldName?.("name");
+    if (byField?.text)
+        return byField.text;
+    const stack = [{ 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, mkDef) {
+    const visit = (n) => {
+        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);
+}
+// 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) {
+    const tagged = n;
+    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, langName) {
+    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;
+}
+//# sourceMappingURL=generic.js.map