Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

263 KB
Raw Blame
// Copyright 2026 Ix Infrastructure Inc.

import * as nodePath from 'node:path';
import * as crypto from 'node:crypto';
import { createRequire } from 'node:module';
// @ts-ignore — tree-sitter has no bundled types
import Parser from 'tree-sitter';
// A grammar is imported by the explicit path to its binding ONLY when Node
// would otherwise emit DEP0151 for it. That is a narrower set than it looks.
//
// DEP0151 fires when an **ESM** resolution lands on a `"main"` with no filename
// or extension. It is gated on the resolved format: a CommonJS package with
// `"main": "bindings/node"` never warns, however it is imported. Almost every
// grammar here is CJS, so almost none of them warn — measured per package in a
// fresh process on Node 26:
//
//   tree-sitter-c-sharp                     required  type=module    -> 1
//   tree-sitter-powershell                  required  type=module    -> 1  (*)
//   @tree-sitter-grammars/tree-sitter-lua   optional  type=module    -> 1
//   tree-sitter-css                         optional  type=module    -> 1
//   every remaining required grammar        required  type=commonjs  -> 0
//   every remaining optional grammar        optional  type=commonjs  -> 0
//   tree-sitter-sas                         optional  type=module    -> 0
//                                             (full-filename main + "exports")
//
// (*) INFERRED, not measured: nobody has run Node against the BARE specifier
// `tree-sitter-powershell` and watched for the warning. Its row comes from the
// import comment below, which describes the package's shape. That is the
// durable reason, and it does not expire when the package is installed -- CI
// installs it and proves the subpath `bindings/node/index.js` resolves, which
// is a different thing from proving the bare specifier warns. (It was also
// missing from the working copy this was written in, which is how the gap was
// noticed, but do not read the marker as being about that: a clean `npm ci`
// has it, since it is a plain `dependencies` entry in `package-lock.json`.)
// Re-measure before relying on it, and do not clear the marker just because
// the package is present. An unverifiable row in this table is what went
// stale in #595 and cost Ix#650 sixteen review rounds.
//
// The rows above are deliberately not counted. What decides a warning is the
// per-package shape, which is what this table is for; the required/optional
// totals are arithmetic over `package.json` and belong to
// `docs/parse-pool-teardown.md`. Restating them here is how the previous
// version went stale -- #595 added a required grammar and the count under it
// silently stopped being true.
//
// So the rule is `"type": "module"` + a directory `"main"` + no `"exports"`,
// which today means c-sharp (static, below) plus powershell, css and lua
// (dynamic, through tryImportGrammar further down). The parse pool loads this
// module once per worker and every worker shares the parent's stderr, so each
// warning arrives once per worker and shreds the `ix map` progress bar.
//
// powershell was added in Ix#595 and this table was not updated: it said "12
// required grammars" and named the shape as "exactly c-sharp, plus css and
// lua", while the comment on the powershell import ~90 lines below has always
// said it is "the same shape". The table was wrong on both counts, and Ix#650
// -- a change about these files disagreeing on counts -- is where it showed.
//
// Do NOT pre-emptively convert the CJS grammars "for consistency". A subpath
// import is a dependency on a package's internal layout, and it fails *hard* —
// a static import that cannot resolve takes down this whole module, every
// language with it. tree-sitter-sas is already the counterexample: it ships
// `"exports": { ".": "./bindings/node/index.js" }`, so its bare specifier is
// fine and `tree-sitter-sas/bindings/node/index.js` throws
// ERR_PACKAGE_PATH_NOT_EXPORTED. That is the direction these packages are
// migrating, so the explicit form is the exception to justify, not the default.
//
// `tree-sitter` itself needs nothing — its main is a real filename.
// @ts-ignore
import JavaScript from 'tree-sitter-javascript';
// @ts-ignore
import TypeScript from 'tree-sitter-typescript';
// @ts-ignore
import Python from 'tree-sitter-python';
// @ts-ignore
import Java from 'tree-sitter-java';
// @ts-ignore
import C from 'tree-sitter-c';
// @ts-ignore
import CPP from 'tree-sitter-cpp';
// tree-sitter-c-sharp is `"type": "module"` with a directory `"main"` and no
// `"exports"`, so it needs the explicit file path. NOT the only required
// grammar in that shape — tree-sitter-powershell is too, further down; the
// table at the top of this file lists them. Saying "the only one" here is what
// went stale when #595 added powershell.
// @ts-ignore
import CSharp from 'tree-sitter-c-sharp/bindings/node/index.js';
// @ts-ignore
import Go from 'tree-sitter-go';
// @ts-ignore
import Rust from 'tree-sitter-rust';
// @ts-ignore
import Ruby from 'tree-sitter-ruby';
// @ts-ignore
import PHP from 'tree-sitter-php';
// @ts-ignore
import Scala from 'tree-sitter-scala';
const _require = createRequire(import.meta.url);
function tryLoadGrammar(pkg: string): any {
  try { return _require(pkg); } catch { return null; }
}
// Async sibling of tryLoadGrammar for grammars that publish ESM bindings with
// top-level await (they can't go through CJS require). Returns null silently
// when the optional grammar can't load on this platform — same contract as
// tryLoadGrammar. An unavailable optional grammar (e.g. no native prebuild for
// this OS/arch) is expected and must not be logged per parse worker.
async function tryImportGrammar(pkg: string): Promise<any> {
  try {
    const mod: any = await import(pkg);
    return mod?.default ?? mod;
  } catch {
    return null;
  }
}
const Kotlin = tryLoadGrammar('tree-sitter-kotlin');
const Swift  = tryLoadGrammar('tree-sitter-swift');
const R = tryLoadGrammar('@davisvaughan/tree-sitter-r');
const Elixir = tryLoadGrammar('tree-sitter-elixir');
const Make = tryLoadGrammar('tree-sitter-make');
const Bash = tryLoadGrammar('tree-sitter-bash');
const Haskell = tryLoadGrammar('tree-sitter-haskell');
const Zig = tryLoadGrammar('@tree-sitter-grammars/tree-sitter-zig');
const Html = tryLoadGrammar('tree-sitter-html');
// tree-sitter-xml exports { xml, dtd }; we use the xml sub-grammar.
const XmlPkg = tryLoadGrammar('@tree-sitter-grammars/tree-sitter-xml');
const Xml = XmlPkg?.xml ?? null;
const HclPkg = tryLoadGrammar('@tree-sitter-grammars/tree-sitter-hcl');
const Hcl = HclPkg?.default ?? HclPkg;
// SAS / Lua / CSS publish ESM bindings with top-level await, so they load via
// import() through the quiet helper above. A grammar that can't load on this
// platform (e.g. tree-sitter-sas has no win32 prebuild) is simply absent; its
// files go unparsed, exactly as with any unavailable CJS grammar.
//
// These three are genuine ESM imports, so the DEP0151 rule described at the top
// of this file applies to them exactly as it does to the static ones — being
// optional and going through a helper does not exempt them.
//
// tree-sitter-sas stays bare: its `main` is already a full filename and it
// declares `"exports"`, so it never warns and a subpath import of it throws
// ERR_PACKAGE_PATH_NOT_EXPORTED.
const SAS = await tryImportGrammar('tree-sitter-sas');
// Lua and CSS are both `"type": "module"` with a directory `"main"` and no
// `"exports"`, so the bare specifier makes Node fall back to directory-index
// lookup and warn — once per parse worker, onto the same stderr the `ix map`
// progress bar draws on. Pointing straight at the file skips that resolution.
const Lua = await tryImportGrammar('@tree-sitter-grammars/tree-sitter-lua/bindings/node/index.js');
const Css = await tryImportGrammar('tree-sitter-css/bindings/node/index.js');
// tree-sitter-powershell is the same shape: ESM bindings with top-level await,
// a directory `main` and no `"exports"`, so it needs the async helper and the
// explicit file path for the same two reasons Lua and CSS do.
const PowerShell = await tryImportGrammar('tree-sitter-powershell/bindings/node/index.js');

import { SupportedLanguages, languageFromPath } from './languages.js';
import { LANGUAGE_QUERIES } from './queries.js';
import { classifyFileRole } from './role-classifier.js';
import type { RoleClassification } from './role-classifier.js';
import { callReceiver, collectReceiverFacts } from './receiver-types.js';
import { summarySignature, type FileSummary } from './symbol-index.js';
export type { FileSummary } from './symbol-index.js';

// ---------------------------------------------------------------------------
// Public types
// ---------------------------------------------------------------------------

export interface ParsedEntity {
  name: string;
  kind: string;       // NodeKind string: "class", "function", "method", etc.
  lineStart: number;
  lineEnd: number;
  language: string;
  /** Direct enclosing class/interface/trait, if any (undefined for file-level entities). */
  container?: string;
  /**
   * Package or namespace name for languages that group entities. Used by
   * downstream resolution to distinguish identically named declarations and
   * index entities under their fully-qualified path.
   */
  packageScope?: string;
}

/** A semantic code span extracted from the AST. The primary LLM retrieval unit. */
export interface ParsedChunk {
  /** Semantic name of the chunk (function/class/trait name), or null for file_body. */
  name: string | null;
  /** Chunk kind: "function" | "method" | "class" | "interface" | "trait" | "module_block" | "file_body" */
  chunkKind: string;
  lineStart: number;
  lineEnd: number;
  startByte: number;
  endByte: number;
  /** SHA-256 of the chunk source text for change detection and stable identity. */
  contentHash: string;
  language: string;
  /** Name of the directly enclosing class/trait/interface, if any. */
  container?: string;
}

export interface ParsedRelationship {
  srcName: string;
  dstName: string;
  predicate: string;  // "CONTAINS" | "CALLS" | "IMPORTS" | "EXTENDS"
  // For path-based IMPORTS only: the unwrapped raw import specifier exactly as
  // written (e.g. "./core", "../util/x", "@nestjs/core", "alpha"), BEFORE it is
  // flattened to a bare stem. The multi-repo dependency gate needs this to tell a
  // relative intra-repo import (./core) apart from a package import (@nestjs/core)
  // that happens to flatten to the same stem ("core"). Absent on non-import rels
  // and on dotted/symbol imports where dstName is already the full identifier.
  importRaw?: string;
  /** PHP namespace import category. Absent for all other languages. */
  importKind?: 'type' | 'function' | 'const';
  /** PHP aliases need binding metadata before exact FQCN resolution is safe. */
  importAliased?: boolean;
  /** PHP call shape used to distinguish constructors from same-named functions. */
  phpCallKind?: 'constructor' | 'function' | 'member' | 'static';
  /**
   * JS/TS only: whether this identifier use is lexically bound to its matching
   * import. False means a parameter or local declaration shadows that import.
   * Undefined preserves compatibility with hand-built/older parse results.
   */
  importBinding?: boolean;
  /**
   * CALLS only (JS/TS, Python, Rust, PHP): true when every call site folded
   * into this relationship calls a plain identifier (`foo()`, `new Foo()` in
   * JS/TS), never a member (`obj.foo()`, `self.foo()`, `$this->foo()`). In
   * these languages a plain identifier is resolved by lexical scope, so it can
   * only denote a module-scope declaration — never a class member in another
   * file. (Not set for Java, C#, Kotlin, Scala, C++, Ruby..., where a bare call
   * can be an implicit-`this` method.) Absent means "at least one
   * member-shaped use, or unknown".
   */
  bareCall?: true;
  /**
   * JS/TS IMPORTS only: `'helper'` marks a module path that was not written in
   * an import statement but passed as a string literal to an import helper
   * (`importModule(resolveModule("../../pkg/dist/x.js"))`). It is inferred, so
   * it becomes an edge only when it resolves to exactly one tracked file.
   */
  importVia?: 'helper';
  /**
   * Lexically inferred receiver. An exact member resolves at tier `type`;
   * otherwise the relationship resolves by its name, as without inference.
   */
  receiverType?: string;
  receiverFactory?: string;
  /**
   * Java: methods called in turn on `receiverType` before this call
   * (`a.getB().m()`); each one's declared return type is the next receiver.
   */
  receiverChain?: string[];
  /**
   * Set on a typed relationship that only exists for its receiver (the call
   * also has its own, unchanged relationship). Without an exact member it
   * resolves to nothing: no edge, no claim, no unresolved-call entry.
   */
  receiverOnly?: true;
}

/**
 * A single named/default import binding: the in-file local name
 * mapped to the PUBLIC symbol it refers to in the source package. `imported` is
 * the public export name ("default" for a default import). Lets a consumer's
 * call to the LOCAL name (e.g. `fmt()` from `import { format as fmt }`) be
 * resolved back to the provider's public symbol for cross-repo stitching.
 */
export interface ImportBinding {
  pkg: string;       // raw import specifier, e.g. "libcore", "@scope/pkg", "./local"
  local: string;     // in-file binding name (the call site uses this)
  imported: string;  // public symbol in the source package ("default" for default import)
}

/**
 * A provider-side public export whose public name differs from the local entity
 * name: `export default function debug` → { local: "debug", public: "default" };
 * `export { impl as format }` → { local: "impl", public: "format" }. Lets the
 * provider advertise the symbol by the name consumers actually import.
 */
export interface ExportPublicName {
  local: string;   // local entity name in the provider file
  public: string;  // name consumers import it by ("default" for default export)
}

export interface FileParseResult {
  filePath: string;
  language: SupportedLanguages;
  entities: ParsedEntity[];
  chunks: ParsedChunk[];
  relationships: ParsedRelationship[];
  importAliases?: Record<string, string>;
  /** Named/default import bindings (local → public symbol). */
  importBindings?: ImportBinding[];
  /** JS/TS provider-side aliased/default public export names. */
  exportPublicNames?: ExportPublicName[];
  /**
   * PHP only: how many namespaces the file declares, braced or not. Consumers
   * that key an index per FILE need this to detect the multi-namespace files
   * where a per-file index would be wrong (a `use` is scoped to its block).
   * Absent for non-PHP files and for PHP files in the global namespace.
   */
  phpNamespaceBlocks?: number;
  /**
   * The tree has ERROR or MISSING nodes: tree-sitter recovered, and whatever
   * sat in the broken region may be missing from `entities`. Absent when the
   * file parsed cleanly.
   */
  hasParseErrors?: true;
  receiverFactories?: Array<[string, string]>;
  receiverHeritage?: Array<[string, string]>;
  receiverPackage?: string;
  /**
   * Java: `${srcName}\0${dstName}` of each CALLS relationship whose every call
   * site also has a typed receiver relationship. When those all resolve to
   * another file, a same-named method in this file is not the target.
   */
  receiverTypedCalls?: string[];
  fileRole: RoleClassification;
}

// ---------------------------------------------------------------------------
// Language → grammar map
// ---------------------------------------------------------------------------

const GRAMMAR_MAP: Partial<Record<SupportedLanguages, any>> = {
  [SupportedLanguages.JavaScript]: JavaScript,
  [SupportedLanguages.TypeScript]: TypeScript.typescript,
  [SupportedLanguages.Python]: Python,
  [SupportedLanguages.Java]: Java,
  [SupportedLanguages.C]: C,
  [SupportedLanguages.CPlusPlus]: CPP,
  [SupportedLanguages.CSharp]: CSharp,
  [SupportedLanguages.Go]: Go,
  [SupportedLanguages.Rust]: Rust,
  [SupportedLanguages.Ruby]: Ruby,
  [SupportedLanguages.PHP]: PHP.php_only,
  [SupportedLanguages.Scala]: Scala,
  ...(Kotlin ? { [SupportedLanguages.Kotlin]: Kotlin } : {}),
  ...(Swift ? { [SupportedLanguages.Swift]: Swift } : {}),
  ...(R ? { [SupportedLanguages.R]: R } : {}),
  ...(SAS ? { [SupportedLanguages.SAS]: SAS } : {}),
  ...(Elixir ? { [SupportedLanguages.Elixir]: Elixir } : {}),
  ...(Make ? { [SupportedLanguages.Makefile]: Make } : {}),
  ...(Lua ? { [SupportedLanguages.Lua]: Lua } : {}),
  ...(Bash ? { [SupportedLanguages.Bash]: Bash } : {}),
  ...(Haskell ? { [SupportedLanguages.Haskell]: Haskell } : {}),
  ...(Zig ? { [SupportedLanguages.Zig]: Zig } : {}),
  ...(Html ? { [SupportedLanguages.HTML]: Html } : {}),
  ...(Xml ? { [SupportedLanguages.XML]: Xml } : {}),
  ...(PowerShell ? { [SupportedLanguages.PowerShell]: PowerShell } : {}),
  ...(Hcl ? { [SupportedLanguages.HCL]: Hcl } : {}),
  ...(Css ? { [SupportedLanguages.CSS]: Css } : {}),
};

// Capture key prefix → NodeKind string
const DEFINITION_KIND_MAP: Record<string, string> = {
  'definition.class':     'class',
  'definition.interface': 'interface',
  'definition.function':  'function',
  'definition.method':    'method',
  'definition.struct':    'class',
  'definition.enum':      'class',
  'definition.trait':     'trait',
  'definition.module':    'module',
  'definition.namespace': 'module',
  'definition.impl':      'class',
  'definition.type':      'class',
  'definition.property':  'function',
  // Its own kind, not 'function' (Ix#679 / decision D10). Rust const_item,
  // Scala val/var_definition, Java, C#, Swift and CSS keyframes all already
  // routed through here, so every one of them has been arriving as a function:
  // `ix search --kind function`, `ix inventory --kind function` and
  // `ix rank --kind function` have been counting constants as callable code.
  'definition.const':     'constant',
  'definition.static':    'function',
  'definition.macro':     'macro',
  'definition.union':     'class',
  'definition.typedef':   'class',
  'definition.template':  'class',
  'definition.record':    'class',
  'definition.delegate':  'class',
  'definition.annotation':'class',
  'definition.constructor':'method',
};

// Primitive / built-in types to exclude from REFERENCES edges
const TYPE_BUILTINS = new Set([
  // TypeScript / JavaScript
  'string', 'number', 'boolean', 'void', 'null', 'undefined', 'any', 'never',
  'unknown', 'object', 'bigint', 'symbol',
  // TypeScript utility types, now that generic arguments, arrays and unions
  // are referenced too. Only names no other language uses for its own types:
  // this set is shared, and `Buffer` or `Error` are real types elsewhere.
  'Record', 'Partial', 'Required', 'Readonly', 'ReadonlyArray', 'Pick', 'Omit',
  'Exclude', 'Extract', 'NonNullable', 'ReturnType', 'Parameters', 'InstanceType',
  'Awaited', 'PromiseLike', 'WeakMap', 'WeakSet',
  // Java / Kotlin / Scala
  'String', 'Integer', 'Long', 'Double', 'Float', 'Boolean', 'Byte', 'Short',
  'Character', 'Object', 'Void', 'Int', 'Unit', 'Any', 'AnyVal', 'AnyRef',
  'Nothing', 'Null', 'Char', 'Number',
  // C#
  'decimal',
  // Python
  'int', 'str', 'float', 'bool', 'bytes', 'Optional', 'Union', 'List', 'Dict',
  'Set', 'Tuple', 'Type',
  // Rust
  'i8', 'i16', 'i32', 'i64', 'i128', 'u8', 'u16', 'u32', 'u64', 'u128',
  'f32', 'f64', 'usize', 'isize',
  // Go
  'int8', 'int16', 'int32', 'int64', 'uint8', 'uint16', 'uint32', 'uint64',
  'float32', 'float64', 'byte', 'rune', 'error',
  // Common stdlib collections / wrappers
  'Array', 'Map', 'Seq', 'Vector', 'Option', 'Future', 'Promise', 'Result',
  'Either', 'Try', 'IO', 'Observable', 'Iterator', 'Iterable',
  // C / C++
  'size_t', 'uint8_t', 'uint16_t', 'uint32_t', 'uint64_t', 'int8_t',
  'int16_t', 'int32_t', 'int64_t',
]);

// Builtins to exclude from CALLS edges — split by language family to avoid
// suppressing valid method names in other languages (e.g. `filter` is a Python
// builtin but also a common ORM method; `warn`/`error` are JS console methods
// but also valid Python logging method names).

// Keywords and pseudo-variables that are never valid call targets in any language.
const SHARED_BUILTINS = new Set([
  'if', 'for', 'while', 'return', 'new', 'this', 'self',
  'undefined', 'null', 'true', 'false',
  'println',  // Scala/Java/Kotlin/Rust standard-output builtin — noise in any language
]);

// Python-specific builtins (bare function calls like `len(x)`, `range(n)`, etc.)
const PYTHON_BUILTINS = new Set([
  ...SHARED_BUILTINS,
  'print', 'len', 'range', 'int', 'str', 'float', 'list', 'dict',
  'set', 'tuple', 'type', 'isinstance', 'super', 'property', 'enumerate',
  'zip', 'map', 'filter', 'sorted', 'any', 'all', 'min', 'max', 'sum',
  'open', 'repr', 'abs', 'round', 'hash', 'id', 'callable', 'iter', 'next',
  'vars', 'dir', 'getattr', 'setattr', 'hasattr', 'delattr',
]);

// JavaScript/TypeScript-specific builtins
const JS_BUILTINS = new Set([
  ...SHARED_BUILTINS,
  'console', 'log', 'warn', 'error', 'debug', 'info',
  'module', 'exports',
  'Promise', 'Array', 'Object', 'String', 'Number', 'Boolean', 'JSON',
  'Math', 'Date', 'Error', 'Map', 'Set', 'Symbol',
  'setTimeout', 'setInterval', 'clearTimeout', 'clearInterval',
  'process', 'Buffer', 'global', 'window', 'document',
  'require', 'fetch', 'parseInt', 'parseFloat', 'isNaN', 'isFinite',
]);

const R_BUILTINS = new Set([
  ...SHARED_BUILTINS,
  'library', 'require', 'source',
  'print', 'cat', 'message', 'warning', 'stop', 'sprintf', 'paste', 'paste0',
  'c', 'list', 'vector', 'matrix', 'array', 'data.frame',
  'length', 'nrow', 'ncol', 'dim', 'names', 'colnames', 'rownames',
  'head', 'tail', 'subset', 'merge', 'rbind', 'cbind', 'order', 'sort',
  'apply', 'lapply', 'sapply', 'vapply', 'tapply', 'mapply',
  'sum', 'mean', 'median', 'sd', 'var', 'min', 'max', 'abs',
  'round', 'floor', 'ceiling', 'sqrt', 'exp', 'log', 'log10',
  'as.character', 'as.numeric', 'as.integer', 'as.logical', 'as.factor',
  'is.character', 'is.numeric', 'is.integer', 'is.logical', 'is.null', 'is.na',
  'seq', 'seq_len', 'seq_along', 'rep', 'which', 'match', 'any', 'all', 'ifelse',
  'read.csv', 'write.csv', 'readRDS', 'saveRDS', 'load', 'save',
  'attr', 'attributes', 'class', 'inherits', 'structure',
  'nzchar', 'nchar', 'trimws', 'toupper', 'tolower', 'chartr', 'strsplit',
  'grep', 'grepl', 'regexpr', 'regmatches', 'sub', 'gsub',
  'isFALSE', 'isTRUE', 'missing', 'exists', 'get', 'assign', 'rm',
  'srcfile', 'srcref', 'getSrcref', 'getSrcFilename',
  'tryCatch', 'withCallingHandlers', 'try', 'simpleError', 'simpleCondition',
  'environment', 'parent.env', 'new.env', 'ls', 'rm',
  'Recall', 'do.call', 'match.arg', 'match.call', 'sys.call',
  'identical', 'stopifnot', 'switch', 'invisible', 'force',
  'numeric', 'character', 'logical', 'integer', 'complex', 'raw',
  'unlist', 'setdiff', 'union', 'intersect', 'unique', 'duplicated', 'table',
  'format', 'formatC', 'strtoi', 'chartr', 'startsWith', 'endsWith',
  'Reduce', 'Filter', 'Find', 'Map', 'Position',
  // base R functions whose names contain dots (not package::function calls)
  'on.exit', 'sys.call', 'sys.function', 'sys.frame', 'sys.nframe', 'sys.source',
  'proc.time', 'date.time',
  'file.path', 'file.exists', 'file.copy', 'file.remove', 'file.rename',
  'file.create', 'file.info', 'file.size', 'file.show',
  'dir.create', 'dir.exists',
  'Sys.time', 'Sys.sleep', 'Sys.getenv', 'Sys.setenv', 'Sys.getpid',
  'Sys.info', 'Sys.chmod', 'Sys.umask',
]);

// SAS-specific builtins: common PROC names and macro keywords that generate
// noise as CALLS edges (user-defined macros are what we want to track).
const SAS_BUILTINS = new Set([
  ...SHARED_BUILTINS,
  'print', 'means', 'freq', 'sort', 'import', 'export', 'contents', 'datasets',
  'sql', 'reg', 'logistic', 'glm', 'anova', 'ttest', 'format', 'report',
  'univariate', 'corr', 'mixed', 'phreg', 'lifetest', 'transpose', 'append',
  'put', 'let', 'do', 'end', 'goto', 'abort',
]);

// Per-language BUILTINS lookup — falls back to shared for languages without a
// specific set (e.g. Java, Go, Rust) so they only skip obvious non-calls.
function builtinsForLanguage(lang: SupportedLanguages): Set<string> {
  switch (lang) {
    case SupportedLanguages.Python:
      return PYTHON_BUILTINS;
    case SupportedLanguages.JavaScript:
    case SupportedLanguages.TypeScript:
      return JS_BUILTINS;
    case SupportedLanguages.R:
      return R_BUILTINS;
    case SupportedLanguages.SAS:
      return SAS_BUILTINS;
    default:
      return SHARED_BUILTINS;
  }
}

/** Returns true if a grammar is installed for the given file's language. */
export function isGrammarSupported(filePath: string): boolean {
  const language = languageFromPath(filePath);
  if (!language) return false;
  if (language === SupportedLanguages.YAML || language === SupportedLanguages.Dockerfile || language === SupportedLanguages.SQL || language === SupportedLanguages.JSON || language === SupportedLanguages.TOML || language === SupportedLanguages.Markdown || language === SupportedLanguages.LaTeX) return true;
  if (filePath.endsWith('.tsx')) return true; // TSX uses TypeScript.tsx, always available
  return GRAMMAR_MAP[language] !== undefined;
}

// ---------------------------------------------------------------------------
// Parser instance (reused across calls)
// ---------------------------------------------------------------------------

let _parser: Parser | null = null;
let _currentGrammar: any = null;
const _queryCache = new Map<SupportedLanguages | 'tsx', { grammar: any; query: any }>();

function getParser(): Parser {
  if (!_parser) _parser = new Parser();
  return _parser;
}

function getCachedQuery(
  language: SupportedLanguages | 'tsx',
  grammar: any,
  querySource: string,
): any {
  const cached = _queryCache.get(language);
  if (cached && cached.grammar === grammar) return cached.query;
  const query = new Parser.Query(grammar, querySource);
  _queryCache.set(language, { grammar, query });
  return query;
}

function normalizeCapturedImport(rawValue: string, language: SupportedLanguages): string {
  const trimmed = rawValue.trim().replace(/\\\\/g, '/');
  const unwrapped = trimmed
    .replace(/^["'`<]/, '')
    .replace(/[>"'`]$/, '');

  if (language === SupportedLanguages.C || language === SupportedLanguages.CPlusPlus) {
    return unwrapped.replace(/^\.\/+/, '');
  }

  if (language === SupportedLanguages.Go) {
    return unwrapped.replace(/^\.+/, '');
  }

  if (language === SupportedLanguages.PHP) {
    const slashed = unwrapped.replace(/\\/g, '/');
    return slashed.split('/').filter(Boolean).pop() ?? slashed;
  }

  if (language === SupportedLanguages.SAS) {
    // Real SAS uses single backslashes in Windows paths (libname "&P.\SASData").
    // The general pre-normalization only collapses double backslashes, so do it
    // here before any path inspection.
    const slashed = unwrapped.replace(/\\/g, '/');
    // Unexpanded macro-var targets (&OUTFILE, &P.\dir) have no stable identity
    // until macro expansion — drop them so they create no bogus node/edge.
    if (slashed.includes('&')) return '';
    if (!slashed.includes('/')) {
      // fileref_source text: FILEREF or FILEREF(member.sas) — no path separators.
      const memberMatch = slashed.match(/^[A-Za-z_][A-Za-z0-9_]*\(([^)]+)\)$/);
      if (memberMatch) return memberMatch[1];
      return slashed;
    }
    // String-literal %include and LIBNAME paths → basename.
    const base = slashed.split('/').filter((s: string) => s !== '*').pop() ?? slashed;
    return base.replace(/^\.+/, '');
  }

  const rawMod = unwrapped.split('/').filter((s: string) => s !== '*').pop() ?? unwrapped;
  return rawMod.replace(/^\.+/, '');
}

/** Unwrap an import specifier's surrounding quotes/brackets WITHOUT reducing it to
 *  a stem — preserving the leading "./", "../", and "@scope/" so the multi-repo
 *  dependency gate can distinguish relative (intra-repo) from package imports.
 *  Mirrors the pre-normalization in normalizeCapturedImport, minus the stem split. */
function unwrapImportSpecifier(rawValue: string): string {
  return rawValue
    .trim()
    .replace(/\\\\/g, '/')
    .replace(/^["'`<]/, '')
    .replace(/[>"'`]$/, '');
}

// Callee text that marks a call as an import helper: `importModule(...)`,
// `resolveIngestionModule(...)`, `require.resolve(...)`, `lazyImport(...)`.
const JS_IMPORT_HELPER_CALLEE = /import|require|module/i;
// Module paths a JS/TS runtime can load: the source and build extensions.
const JS_MODULE_PATH_EXTENSION = /\.(?:[cm]?[jt]s|[jt]sx)$/;

/**
 * The module path a JS/TS call passes to an import helper, or null.
 *
 * A dynamic `import("./x.js")` is already an IMPORTS edge (see the query), but
 * loaders often route the specifier through a helper first, e.g.
 * `importModule(resolveIngestionModule("../../../../core-ingestion/dist/languages.js"))`.
 * Deliberately conservative, because this infers an import from a string:
 *   - the callee's text must name importing (`JS_IMPORT_HELPER_CALLEE`),
 *   - the FIRST argument must be a plain string literal (no substitutions),
 *   - relative (`./`, `../`) and ending in a JS/TS module extension.
 * `readFileSync("./x.ts")` and `path.join(dir, "x.js")` are never matched. The
 * resolver then keeps the edge only when the path names exactly one tracked
 * file (mapping a build path such as `dist/x.js` back to `src/x.ts`).
 */
function jsTsHelperImportSpecifier(callNode: any): string | null {
  if (callNode?.type !== 'call_expression') return null;
  const fn = callNode.childForFieldName?.('function');
  if (!fn || (fn.type !== 'identifier' && fn.type !== 'member_expression')) return null;
  // The argument is checked before the callee: this runs for every call, and a
  // member callee's text spans its whole receiver chain -- in a long builder
  // chain (`b.step(x).step(y)...`) reading it per call is quadratic in the chain.
  const firstArg = callNode.childForFieldName?.('arguments')?.firstNamedChild;
  if (!firstArg) return null;
  if (firstArg.type !== 'string' &&
      !(firstArg.type === 'template_string' && !firstArg.namedChildren.some((c: any) => c.type === 'template_substitution'))) {
    return null;
  }
  const spec = unwrapImportSpecifier(firstArg.text);
  if (!spec.startsWith('./') && !spec.startsWith('../')) return null;
  if (!JS_MODULE_PATH_EXTENSION.test(spec)) return null;
  return JS_IMPORT_HELPER_CALLEE.test(fn.text) ? spec : null;
}

/**
 * Walk a JS/TS `import_statement` node and return its named/default bindings.
 * Namespace imports (`* as ns`) are intentionally skipped: a call like `ns.foo()`
 * already resolves to "foo" through the member_expression call query, so it needs
 * no rewrite. Purely additive — does not alter any emitted relationship.
 */
function extractJsImportBindings(stmtNode: any, rawSpec: string): ImportBinding[] {
  const out: ImportBinding[] = [];
  if (!stmtNode || stmtNode.type !== 'import_statement') return out;
  let clause: any = null;
  for (let i = 0; i < stmtNode.namedChildCount; i++) {
    const c = stmtNode.namedChild(i);
    if (c.type === 'import_clause') { clause = c; break; }
  }
  if (!clause) return out;
  for (let i = 0; i < clause.namedChildCount; i++) {
    const child = clause.namedChild(i);
    if (child.type === 'identifier') {
      // `import dbg from "pkg"` — default import.
      if (child.text) out.push({ pkg: rawSpec, local: child.text, imported: 'default' });
    } else if (child.type === 'named_imports') {
      for (let j = 0; j < child.namedChildCount; j++) {
        const spec = child.namedChild(j);
        if (spec.type !== 'import_specifier') continue;
        const nameNode = spec.namedChild(0);
        const aliasNode = spec.namedChildCount > 1 ? spec.namedChild(1) : null;
        if (!nameNode || !nameNode.text) continue;
        const imported = nameNode.text;
        const local = aliasNode && aliasNode.text ? aliasNode.text : imported;
        out.push({ pkg: rawSpec, local, imported });
      }
    }
  }
  return out;
}

const JS_TS_FUNCTION_NODES = new Set([
  'function_declaration',
  'generator_function_declaration',
  'function_expression',
  'generator_function',
  'arrow_function',
  'method_definition',
]);

function jsTsBindingPatternContains(node: any, name: string): boolean {
  if (!node) return false;
  if ((node.type === 'identifier' || node.type === 'shorthand_property_identifier_pattern') && node.text === name) {
    return true;
  }
  if (node.type === 'required_parameter' || node.type === 'optional_parameter') {
    return jsTsBindingPatternContains(node.childForFieldName?.('pattern'), name);
  }
  if (node.type === 'assignment_pattern') {
    return jsTsBindingPatternContains(node.childForFieldName?.('left'), name);
  }
  if (node.type === 'object_assignment_pattern') {
    return jsTsBindingPatternContains(node.childForFieldName?.('left'), name);
  }
  if (node.type === 'pair_pattern') {
    return jsTsBindingPatternContains(node.childForFieldName?.('value'), name);
  }
  if (node.type === 'rest_pattern') {
    return jsTsBindingPatternContains(node.childForFieldName?.('argument') ?? node.namedChild(0), name);
  }
  for (let i = 0; i < node.namedChildCount; i++) {
    if (jsTsBindingPatternContains(node.namedChild(i), name)) return true;
  }
  return false;
}

function jsTsTypeParametersContain(node: any, name: string): boolean {
  if (!node) return false;
  for (let i = 0; i < node.namedChildCount; i++) {
    const parameter = node.namedChild(i);
    if (parameter.type !== 'type_parameter') continue;
    const nameNode = parameter.childForFieldName?.('name') ?? parameter.namedChild(0);
    if (nameNode?.text === name) return true;
  }
  return false;
}

function jsTsDeclarationBinds(node: any, name: string, namespace: 'value' | 'type'): boolean {
  if (!node) return false;
  if (node.type === 'export_statement') {
    for (let i = 0; i < node.namedChildCount; i++) {
      if (jsTsDeclarationBinds(node.namedChild(i), name, namespace)) return true;
    }
    return false;
  }
  if (namespace === 'value' && (node.type === 'lexical_declaration' || node.type === 'variable_declaration')) {
    for (let i = 0; i < node.namedChildCount; i++) {
      const declarator = node.namedChild(i);
      if (declarator.type !== 'variable_declarator') continue;
      if (jsTsBindingPatternContains(declarator.childForFieldName?.('name') ?? declarator.namedChild(0), name)) return true;
    }
    return false;
  }
  const bindsValue = node.type === 'function_declaration' || node.type === 'generator_function_declaration' ||
    node.type === 'class_declaration' || node.type === 'enum_declaration';
  const bindsType = node.type === 'class_declaration' || node.type === 'type_alias_declaration' ||
    node.type === 'interface_declaration' || node.type === 'enum_declaration';
  if ((namespace === 'value' && bindsValue) || (namespace === 'type' && bindsType)) {
    return node.childForFieldName?.('name')?.text === name;
  }
  return false;
}

// `namedChildren` once rather than `namedChild(i)` per index: each indexed
// call walks the children from the start, so the loop was quadratic in the
// scope's size before it did any work.
function jsTsScopeDirectlyBinds(scope: any, name: string, namespace: 'value' | 'type'): boolean {
  for (const child of scope.namedChildren) {
    if (jsTsDeclarationBinds(child, name, namespace)) return true;
  }
  return false;
}

function jsTsFunctionHasVarBinding(node: any, name: string, isRoot = true): boolean {
  if (!node) return false;
  if (!isRoot && JS_TS_FUNCTION_NODES.has(node.type)) return false;
  if (node.type === 'variable_declaration' && jsTsDeclarationBinds(node, name, 'value')) return true;
  for (const child of node.namedChildren) {
    if (jsTsFunctionHasVarBinding(child, name, false)) return true;
  }
  return false;
}

/**
 * Answers of the two whole-scope scans behind `isJsTsImportShadowed`, for one
 * parse: node id -> `${kind}\0${namespace}\0${name}` -> result. Without it each
 * USE of an imported name rescanned every enclosing scope, so a file with 4,000
 * `it(...)` calls scanned its 4,000 top-level statements 4,000 times. Node ids
 * are unique only within one tree, hence one memo per parse.
 */
type JsTsShadowMemo = Map<number, Map<string, boolean>>;

function memoisedScan(memo: JsTsShadowMemo | undefined, node: any, key: string, scan: () => boolean): boolean {
  if (!memo) return scan();
  let forNode = memo.get(node.id);
  if (!forNode) {
    forNode = new Map();
    memo.set(node.id, forNode);
  }
  let result = forNode.get(key);
  if (result === undefined) {
    result = scan();
    forNode.set(key, result);
  }
  return result;
}

/** True when a declaration shadows an imported JS/TS name at this use. */
function isJsTsImportShadowed(
  identifierNode: any,
  name: string,
  namespace: 'value' | 'type',
  memo?: JsTsShadowMemo,
): boolean {
  let child = identifierNode;
  let scope = identifierNode?.parent;
  while (scope) {
    if (scope.type === 'statement_block' || scope.type === 'program') {
      if (memoisedScan(memo, scope, `scope\0${namespace}\0${name}`, () => jsTsScopeDirectlyBinds(scope, name, namespace))) {
        return true;
      }
    }
    if (namespace === 'value' && scope.type === 'catch_clause') {
      if (jsTsBindingPatternContains(scope.childForFieldName?.('parameter'), name)) return true;
    }
    if (namespace === 'value' && (scope.type === 'for_statement' || scope.type === 'for_in_statement')) {
      const initializer = scope.childForFieldName?.('initializer') ?? scope.childForFieldName?.('left');
      if (jsTsDeclarationBinds(initializer, name, 'value')) return true;
    }
    if (JS_TS_FUNCTION_NODES.has(scope.type)) {
      if (namespace === 'value') {
        if (scope.childForFieldName?.('name')?.text === name) return true;
        if (jsTsBindingPatternContains(scope.childForFieldName?.('parameters'), name)) return true;
        const body = scope.childForFieldName?.('body');
        if (body && memoisedScan(memo, body, `var\0${name}`, () => jsTsFunctionHasVarBinding(body, name))) return true;
      } else if (jsTsTypeParametersContain(scope.childForFieldName?.('type_parameters'), name)) {
        return true;
      }
    }
    if (scope.type === 'class_declaration' || scope.type === 'class') {
      if (scope.childForFieldName?.('name')?.text === name) return true;
      if (namespace === 'type' && jsTsTypeParametersContain(scope.childForFieldName?.('type_parameters'), name)) return true;
    }
    child = scope;
    scope = child.parent;
  }
  return false;
}

/**
 * Walk a JS/TS tree for provider-side public export names that differ from the
 * local entity name: `export { impl as format }` (no source) → {impl, format};
 * `export default function debug` → {debug, "default"}. Lets a provider advertise
 * a symbol by the name a consumer imports it as. Purely additive.
 */
function extractJsExportPublicNames(rootNode: any): ExportPublicName[] {
  const out: ExportPublicName[] = [];
  const seen = new Set<string>();
  const visit = (node: any): void => {
    if (node.type === 'export_statement') {
      let hasSource = false;
      let isDefault = false;
      for (let i = 0; i < node.childCount; i++) {
        const c = node.child(i);
        if (c.type === 'default') isDefault = true;
        if (c.type === 'string') hasSource = true;
      }
      let clause: any = null;
      let decl: any = null;
      let defaultIdentifier: any = null;
      for (let i = 0; i < node.namedChildCount; i++) {
        const c = node.namedChild(i);
        if (c.type === 'export_clause') clause = c;
        else if (c.type === 'function_declaration' || c.type === 'class_declaration'
          || c.type === 'lexical_declaration' || c.type === 'generator_function_declaration') decl = c;
        else if (c.type === 'identifier') defaultIdentifier = c;
      }
      // Local re-export `export { a as b }` (NOT `... from './x'`): a is public as b.
      if (clause && !hasSource) {
        for (let j = 0; j < clause.namedChildCount; j++) {
          const spec = clause.namedChild(j);
          if (spec.type !== 'export_specifier') continue;
          const localN = spec.namedChild(0);
          const pubN = spec.namedChildCount > 1 ? spec.namedChild(1) : null;
          if (!localN || !localN.text) continue;
          const local = localN.text;
          const pub = pubN && pubN.text ? pubN.text : local;
          if (pub !== local) {
            const k = `${local}\x00${pub}`;
            if (!seen.has(k)) { seen.add(k); out.push({ local, public: pub }); }
          }
        }
      }
      // Named default declarations and `export default localName` advertise the
      // local entity under the public name "default".
      if (isDefault && (decl || defaultIdentifier)) {
        const nameNode = decl
          ? (decl.childForFieldName && decl.childForFieldName('name')) || decl.namedChild(0)
          : defaultIdentifier;
        const nm = nameNode?.text;
        if (nm) {
          const k = `${nm}\x00default`;
          if (!seen.has(k)) { seen.add(k); out.push({ local: nm, public: 'default' }); }
        }
      }
    }
    for (let i = 0; i < node.namedChildCount; i++) visit(node.namedChild(i));
  };
  visit(rootNode);
  return out;
}

function fileEntityName(filePath: string): string {
  return nodePath.basename(filePath);
}

function looksLikeCppHeader(source: string): boolean {
  return /\bclass\s+[A-Za-z_]\w*\b/.test(source)
    || /\bnamespace\s+[A-Za-z_]\w*\b/.test(source)
    || /\btemplate\s*</.test(source)
    || /\busing\s+namespace\b/.test(source)
    || /\b(public|private|protected)\s*:/.test(source)
    || /\b(virtual|constexpr|typename|friend|operator)\b/.test(source)
    || /\b[A-Za-z_]\w*::[A-Za-z_]\w*/.test(source);
}

function detectLanguageForSource(filePath: string, source: string): SupportedLanguages | null {
  const language = languageFromPath(filePath);
  if (language === SupportedLanguages.C && filePath.toLowerCase().endsWith('.h') && looksLikeCppHeader(source)) {
    return SupportedLanguages.CPlusPlus;
  }
  return language;
}

function countSourceLines(source: string): number {
  let lineCount = 1;
  for (let i = 0; i < source.length; i++) {
    if (source.charCodeAt(i) === 10) lineCount++;
  }
  return lineCount;
}

function computeLineStarts(source: string): number[] {
  const lineStarts = [0];
  for (let i = 0; i < source.length; i++) {
    if (source.charCodeAt(i) === 10) lineStarts.push(i + 1);
  }
  return lineStarts;
}

function parseYamlFile(filePath: string, source: string): FileParseResult {
  const language = SupportedLanguages.YAML;
  const fileName = nodePath.basename(filePath);
  const sourceLineCount = countSourceLines(source);
  const fileRole = classifyFileRole(filePath);
  const entities: ParsedEntity[] = [
    { name: fileName, kind: 'file', lineStart: 1, lineEnd: sourceLineCount, language },
  ];
  const chunks: ParsedChunk[] = [];
  const relationships: ParsedRelationship[] = [];
  const lineStarts = computeLineStarts(source);
  const lines = source.split(/\r?\n/);
  const stack: Array<{ indent: number; key: string }> = [];
  const keyLinePattern = /^(\s*)(?:-\s+)?([A-Za-z0-9_.-]+)\s*:.*$/;

  for (let index = 0; index < lines.length; index++) {
    const line = lines[index];
    const match = keyLinePattern.exec(line);
    if (!match) continue;

    const indent = match[1].replace(/\t/g, '  ').length;
    const listPrefixWidth = line.trimStart().startsWith('- ') ? 2 : 0;
    const effectiveIndent = indent + listPrefixWidth;
    const key = match[2];
    while (stack.length > 0 && effectiveIndent <= stack[stack.length - 1].indent) {
      stack.pop();
    }

    const parent = stack[stack.length - 1];
    const lineNumber = index + 1;
    const lineStartOffset = lineStarts[index] ?? 0;
    const startByte = lineStartOffset + match[1].length + listPrefixWidth;
    const endByte = Math.max(startByte + key.length, lineStartOffset + line.length);

    entities.push({
      name: key,
      kind: 'config_entry',
      lineStart: lineNumber,
      lineEnd: lineNumber,
      language,
      container: parent?.key,
    });

    chunks.push({
      name: key,
      chunkKind: 'config_key',
      lineStart: lineNumber,
      lineEnd: lineNumber,
      startByte,
      endByte,
      contentHash: crypto.createHash('sha256').update(line).digest('hex'),
      language,
      container: parent?.key,
    });

    relationships.push({
      srcName: parent?.key ?? fileName,
      dstName: key,
      predicate: 'CONTAINS',
    });

    if (listPrefixWidth === 0) {
      stack.push({ indent: effectiveIndent, key });
    }
  }

  if (chunks.length === 0) {
    chunks.push({
      name: null,
      chunkKind: 'file_body',
      lineStart: 1,
      lineEnd: Math.max(sourceLineCount, 1),
      startByte: 0,
      endByte: source.length,
      contentHash: crypto.createHash('sha256').update(source).digest('hex'),
      language,
    });
  }

  return {
    filePath,
    language,
    entities,
    chunks,
    relationships,
    fileRole,
  };
}

function parseTomlFile(filePath: string, source: string): FileParseResult {
  const language = SupportedLanguages.TOML;
  const fileName = nodePath.basename(filePath);
  const sourceLineCount = countSourceLines(source);
  const fileRole = classifyFileRole(filePath);
  const entities: ParsedEntity[] = [
    { name: fileName, kind: 'file', lineStart: 1, lineEnd: sourceLineCount, language },
  ];
  const chunks: ParsedChunk[] = [];
  const relationships: ParsedRelationship[] = [];
  const lineStarts = computeLineStarts(source);
  const lines = source.split(/\r?\n/);

  // [table] or [[array-of-tables]] headers set the current section context.
  const tableHeaderPattern = /^\s*\[{1,2}([^\[\]]+)\]{1,2}\s*(?:#.*)?$/;
  // key = value lines (bare keys, quoted keys, dotted keys).
  // Quoted keys handled separately to avoid ReDoS from spaces overlapping with \s*.
  const keyPattern = /^\s*("[^"]*"|'[^']*'|[A-Za-z0-9_-][A-Za-z0-9_.-]*)\s*=/;

  let currentTable: string | null = null;
  const seenTablePaths = new Set<string>();

  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    const trimmed = line.trimStart();
    if (!trimmed || trimmed.startsWith('#')) continue;

    const tableMatch = tableHeaderPattern.exec(line);
    if (tableMatch) {
      const tablePath = tableMatch[1].trim();
      currentTable = tablePath;
      const parts = tablePath.split('.');
      const lineNumber = i + 1;
      const startByte = lineStarts[i] ?? 0;

      // Emit intermediate nodes for each prefix segment (e.g. [a.b.c] → emit a, a.b)
      for (let p = 1; p < parts.length; p++) {
        const prefixPath = parts.slice(0, p).join('.');
        if (!seenTablePaths.has(prefixPath)) {
          seenTablePaths.add(prefixPath);
          const prefixKey = parts[p - 1];
          const prefixParent = p > 1 ? parts.slice(0, p - 1).join('.') : null;
          entities.push({
            name: prefixKey,
            kind: 'config_entry',
            lineStart: lineNumber,
            lineEnd: lineNumber,
            language,
            container: prefixParent ?? undefined,
          });
          relationships.push({
            srcName: prefixParent ?? fileName,
            dstName: prefixKey,
            predicate: 'CONTAINS',
          });
        }
      }

      const key = parts[parts.length - 1];
      const parent = parts.length > 1 ? parts.slice(0, -1).join('.') : null;

      seenTablePaths.add(tablePath);
      entities.push({
        name: key,
        kind: 'config_entry',
        lineStart: lineNumber,
        lineEnd: lineNumber,
        language,
        container: parent ?? undefined,
      });
      chunks.push({
        name: key,
        chunkKind: 'config_key',
        lineStart: lineNumber,
        lineEnd: lineNumber,
        startByte,
        endByte: startByte + line.length,
        contentHash: crypto.createHash('sha256').update(line).digest('hex'),
        language,
        container: parent ?? undefined,
      });
      relationships.push({
        srcName: parent ?? fileName,
        dstName: key,
        predicate: 'CONTAINS',
      });
      continue;
    }

    const keyMatch = keyPattern.exec(line);
    if (keyMatch) {
      const key = keyMatch[1].trim().replace(/^["']|["']$/g, '');
      const lineNumber = i + 1;
      const startByte = lineStarts[i] ?? 0;

      entities.push({
        name: key,
        kind: 'config_entry',
        lineStart: lineNumber,
        lineEnd: lineNumber,
        language,
        container: currentTable ?? undefined,
      });
      chunks.push({
        name: key,
        chunkKind: 'config_key',
        lineStart: lineNumber,
        lineEnd: lineNumber,
        startByte,
        endByte: startByte + line.length,
        contentHash: crypto.createHash('sha256').update(line).digest('hex'),
        language,
        container: currentTable ?? undefined,
      });
      relationships.push({
        srcName: currentTable ?? fileName,
        dstName: key,
        predicate: 'CONTAINS',
      });
    }
  }

  if (chunks.length === 0) {
    chunks.push({
      name: null,
      chunkKind: 'file_body',
      lineStart: 1,
      lineEnd: Math.max(sourceLineCount, 1),
      startByte: 0,
      endByte: source.length,
      contentHash: crypto.createHash('sha256').update(source).digest('hex'),
      language,
    });
  }

  return { filePath, language, entities, chunks, relationships, fileRole };
}

function cleanHeadingName(raw: string): string {
  // 1. Strip VitePress anchor ID suffix {#...}
  // Use string methods to avoid ReDoS from overlapping \s* / [^}]+ quantifiers.
  let s = raw;
  const anchorStart = raw.lastIndexOf('{#');
  if (anchorStart !== -1) {
    const closeIdx = raw.indexOf('}', anchorStart + 2);
    if (closeIdx !== -1 && raw.slice(closeIdx + 1).trim() === '') {
      s = raw.slice(0, anchorStart).trimEnd();
    }
  }
  // 2. Unescape backslash-escaped angle brackets before HTML stripping
  s = s.replace(/\\</g, '\x01LT\x01').replace(/\\>/g, '\x01GT\x01');
  // 3. Protect inline code spans from HTML stripping
  const spans: string[] = [];
  s = s.replace(/`[^`]+`/g, (m) => { spans.push(m); return `\x00${spans.length - 1}\x00`; });
  // 4. Strip HTML tags (iteratively to handle split tags like <scr<x>ipt>).
  let prev: string;
  do {
    prev = s;
    s = s.replace(/<[^>]+>/g, '');
  } while (s !== prev);
  // 5. Restore inline code spans and strip their backtick delimiters
  s = s.replace(/\x00(\d+)\x00/g, (_, i) => spans[Number(i)].replace(/`/g, ''));
  // 6. Restore escaped angle brackets
  s = s.replace(/\x01LT\x01/g, '<').replace(/\x01GT\x01/g, '>');
  // 7. Strip VitePress stability markers (\* \*\* \*\*\*)
  s = s.replace(/\\\*+/g, '');
  // 8. Normalize whitespace
  s = s.replace(/\s{2,}/g, ' ').trim();
  return s;
}

function parseMarkdownFile(filePath: string, source: string): FileParseResult {
  const language = SupportedLanguages.Markdown;
  const fileName = nodePath.basename(filePath);
  const sourceLineCount = countSourceLines(source);
  const fileRole = classifyFileRole(filePath);
  const entities: ParsedEntity[] = [
    { name: fileName, kind: 'file', lineStart: 1, lineEnd: sourceLineCount, language },
  ];
  const chunks: ParsedChunk[] = [];
  const relationships: ParsedRelationship[] = [];
  const lineStarts = computeLineStarts(source);
  const lines = source.split(/\r?\n/);

  let startLine = 0;

  // Parse YAML frontmatter delimited by --- ... ---
  if (lines[0]?.trim() === '---') {
    let fmEnd = -1;
    for (let j = 1; j < lines.length; j++) {
      if (lines[j].trim() === '---' || lines[j].trim() === '...') {
        fmEnd = j;
        break;
      }
    }
    if (fmEnd > 0) {
      startLine = fmEnd + 1;
      const endByte = (lineStarts[fmEnd] ?? 0) + lines[fmEnd].length;
      const fmContent = lines.slice(0, fmEnd + 1).join('\n');
      entities.push({ name: 'frontmatter', kind: 'frontmatter', lineStart: 1, lineEnd: fmEnd + 1, language });
      chunks.push({
        name: 'frontmatter',
        chunkKind: 'frontmatter',
        lineStart: 1,
        lineEnd: fmEnd + 1,
        startByte: 0,
        endByte,
        contentHash: crypto.createHash('sha256').update(fmContent).digest('hex'),
        language,
      });
      relationships.push({ srcName: fileName, dstName: 'frontmatter', predicate: 'CONTAINS' });
    }
  }

  // headingStack[level] = heading name currently active at that depth (1–6)
  const headingStack: (string | null)[] = [null, null, null, null, null, null, null];
  // \S[^\r\n]* requires content to start with non-whitespace, eliminating the
  // \s+/(.*\S) overlap that caused polynomial backtracking. Trailing whitespace
  // and closing ## markers are stripped in code below.
  const headingPattern = /^(#{1,6})[ \t]+(\S[^\r\n]*)$/;
  // Greedy .* with specific closing tag as anchor avoids (.*?)\s*$ overlap (ReDoS).
  const htmlHeadingPattern = /^<h([1-6])\b[^>]*>(.*)<\/h\1>/i;
  const headingLines: { level: number; name: string; lineNum: number; container: string | null }[] = [];

  // Bug 3 fix: track opening fence char+length so only matching delimiter closes the block
  let fenceState: { char: string; len: number } | null = null;
  for (let i = startLine; i < lines.length; i++) {
    const line = lines[i];

    // Toggle fenced code block — only close with same character and >= opening length
    const fenceMatch = /^(`{3,}|~{3,})/.exec(line.trimStart());
    if (fenceMatch) {
      const matchChar = fenceMatch[1][0];
      const matchLen = fenceMatch[1].length;
      if (fenceState === null) {
        fenceState = { char: matchChar, len: matchLen };
      } else if (matchChar === fenceState.char && matchLen >= fenceState.len) {
        fenceState = null;
      }
      continue;
    }
    if (fenceState !== null) continue;

    const headingMatch = headingPattern.exec(line);
    const htmlHeadingMatch = headingMatch ? null : htmlHeadingPattern.exec(line.trim());

    // Bug 2 fix: detect setext-style headings (text line followed by === or --- underline)
    let setextLevel: number | null = null;
    if (!headingMatch && !htmlHeadingMatch && line.trim() !== '') {
      const nextLine = lines[i + 1];
      if (nextLine !== undefined) {
        if (/^=+\s*$/.test(nextLine)) setextLevel = 1;
        else if (/^-+\s*$/.test(nextLine)) setextLevel = 2;
      }
    }

    if (!headingMatch && !htmlHeadingMatch && setextLevel === null) continue;

    const level = headingMatch ? headingMatch[1].length : (htmlHeadingMatch ? Number(htmlHeadingMatch![1]) : setextLevel!);
    // Strip optional ATX closing markers (e.g. "Title ##") that (.*\S) now includes.
    // Use string walk instead of regex to avoid ReDoS on +#+$ backtracking.
    let atxRaw = headingMatch ? headingMatch[2].trimEnd() : null;
    if (atxRaw !== null && atxRaw[atxRaw.length - 1] === '#') {
      let i = atxRaw.length - 1;
      while (i >= 0 && atxRaw[i] === '#') i--;
      if (i >= 0 && (atxRaw[i] === ' ' || atxRaw[i] === '\t')) atxRaw = atxRaw.slice(0, i);
    }
    const rawName = atxRaw !== null ? atxRaw : (htmlHeadingMatch ? htmlHeadingMatch![2] : line.trim());
    const name = cleanHeadingName(rawName);
    if (!name) continue;
    const lineNum = i + 1;

    if (setextLevel !== null) i++; // skip the underline line

    // Find nearest ancestor at a shallower level
    let container: string | null = null;
    for (let l = level - 1; l >= 1; l--) {
      if (headingStack[l] !== null) {
        container = headingStack[l];
        break;
      }
    }

    // Reset all deeper levels when a heading resets scope
    for (let l = level; l <= 6; l++) headingStack[l] = null;
    headingStack[level] = name;

    entities.push({ name, kind: 'heading', lineStart: lineNum, lineEnd: lineNum, language, container: container ?? undefined });
    relationships.push({ srcName: container ?? fileName, dstName: name, predicate: 'CONTAINS' });
    headingLines.push({ level, name, lineNum, container });
  }

  // Build one section chunk per heading spanning to the line before the next heading at the same or
  // shallower level. This ensures parent sections contain their nested sub-sections' content.
  for (let h = 0; h < headingLines.length; h++) {
    const { level: currentLevel, name, lineNum, container } = headingLines[h];
    let nextLineNum = sourceLineCount;
    for (let k = h + 1; k < headingLines.length; k++) {
      if (headingLines[k].level <= currentLevel) {
        nextLineNum = headingLines[k].lineNum - 1;
        break;
      }
    }
    const startByte = lineStarts[lineNum - 1] ?? 0;
    const endByte = nextLineNum < lines.length ? (lineStarts[nextLineNum] ?? source.length) : source.length;
    const sectionContent = lines.slice(lineNum - 1, nextLineNum).join('\n');
    chunks.push({
      name,
      chunkKind: 'section',
      lineStart: lineNum,
      lineEnd: nextLineNum,
      startByte,
      endByte,
      contentHash: crypto.createHash('sha256').update(sectionContent).digest('hex'),
      language,
      container: container ?? undefined,
    });
  }

  // Bug 1 fix: emit file_body when no section chunks exist, regardless of frontmatter chunk
  if (headingLines.length === 0) {
    const bodyLineStart = startLine + 1;
    const bodyStartByte = lineStarts[startLine] ?? 0;
    const bodyContent = source.slice(bodyStartByte);
    chunks.push({
      name: null,
      chunkKind: 'file_body',
      lineStart: bodyLineStart,
      lineEnd: Math.max(sourceLineCount, 1),
      startByte: bodyStartByte,
      endByte: source.length,
      contentHash: crypto.createHash('sha256').update(bodyContent).digest('hex'),
      language,
    });
  }

  return { filePath, language, entities, chunks, relationships, fileRole };
}

// ---------------------------------------------------------------------------
// LaTeX / TeX (.tex, .sty, .cls, .ltx, .latex)
//
// Hand-rolled scanner rather than tree-sitter: there is no maintained Node
// tree-sitter-latex binding for this ABI, and TeX is a macro-expansion language
// whose custom-macro arities a static grammar cannot know — real grammars emit
// ERROR nodes on ordinary documents. A targeted single-pass scanner extracts the
// constructs Ix models (sectioning hierarchy, macro/environment/theorem defs,
// labels, package/file dependencies, ref/cite cross-references) and degrades
// gracefully on malformed input. O(n), deterministic.
// ---------------------------------------------------------------------------

const LATEX_SECTION_LEVELS: Record<string, number> = {
  part: 0, chapter: 1, section: 2, subsection: 3,
  subsubsection: 4, paragraph: 5, subparagraph: 6,
};
const LATEX_MACRO_DEFS = new Set([
  'newcommand', 'renewcommand', 'providecommand', 'DeclareRobustCommand',
  'DeclareMathOperator', 'newcommandx', 'renewcommandx', 'providecommandx',
]);
const LATEX_CS_DEFS = new Set(['def', 'gdef', 'edef', 'xdef', 'let']);
// When a definition's target is one of these primitives the real name is built
// at expansion time (e.g. \def\csname foo\endcsname{...} defines "foo", not
// "csname"), so it is not statically knowable — skip rather than emit noise.
const LATEX_DYNAMIC_CS = new Set(['csname', 'endcsname']);
const LATEX_ENV_DEFS = new Set(['newenvironment', 'renewenvironment', 'newenvironmentx']);
const LATEX_THEOREM_DEFS = new Set(['newtheorem']);
const LATEX_PACKAGE_IMPORTS = new Set([
  'usepackage', 'RequirePackage', 'RequirePackageWithOptions',
  'documentclass', 'LoadClass', 'LoadClassWithOptions', 'documentstyle',
]);
const LATEX_FILE_INCLUDES = new Set([
  'input', 'include', 'subfile', 'subfileinclude', 'includeonly',
]);
const LATEX_BIB_INCLUDES = new Set(['bibliography', 'addbibresource']);
const LATEX_REF_CMDS = new Set([
  'ref', 'eqref', 'pageref', 'cref', 'Cref', 'autoref', 'nameref',
  'vref', 'vpageref', 'labelcref', 'cpageref', 'Autoref', 'fref', 'thref',
]);
const LATEX_CITE_CMDS = new Set([
  'cite', 'citep', 'citet', 'citealt', 'citealp', 'citeauthor', 'citeyear',
  'citeyearpar', 'Citep', 'Citet', 'Cite', 'textcite', 'parencite', 'footcite',
  'autocite', 'smartcite', 'citenum', 'fullcite', 'nocite', 'citealp',
]);
// Inside these environments backslashes are literal text, not commands; skip
// scanning their body so listings/verbatim content never produces spurious nodes.
const LATEX_VERBATIM_ENVS = new Set([
  'verbatim', 'verbatim*', 'Verbatim', 'BVerbatim', 'LVerbatim',
  'lstlisting', 'minted', 'comment', 'alltt', 'filecontents', 'filecontents*',
]);

function parseLatexFile(filePath: string, source: string): FileParseResult {
  const language = SupportedLanguages.LaTeX;
  const fileName = nodePath.basename(filePath);
  const sourceLineCount = countSourceLines(source);
  const fileRole = classifyFileRole(filePath);
  const entities: ParsedEntity[] = [
    { name: fileName, kind: 'file', lineStart: 1, lineEnd: sourceLineCount, language },
  ];
  const chunks: ParsedChunk[] = [];
  const relationships: ParsedRelationship[] = [];
  const lineStarts = computeLineStarts(source);
  const n = source.length;

  const lineAt = (idx: number): number => {
    let lo = 0, hi = lineStarts.length - 1, ans = 0;
    while (lo <= hi) {
      const mid = (lo + hi) >> 1;
      if (lineStarts[mid] <= idx) { ans = mid; lo = mid + 1; } else hi = mid - 1;
    }
    return ans + 1;
  };

  // Read a balanced { ... } group starting at `open` (source[open] === '{').
  // Honors \{ and \} escapes. On imbalance, returns the rest of the source.
  const readBraceGroup = (open: number): { text: string; end: number } => {
    let depth = 0;
    for (let q = open; q < n; q++) {
      const cc = source[q];
      if (cc === '\\') { q++; continue; }
      if (cc === '{') depth++;
      else if (cc === '}') { depth--; if (depth === 0) return { text: source.slice(open + 1, q), end: q + 1 }; }
    }
    return { text: source.slice(open + 1, n), end: n };
  };

  // Read an optional [ ... ] group; stops at the first unescaped ] not nested in {}.
  const readOptGroup = (open: number): { text: string; end: number } => {
    let braceDepth = 0;
    for (let q = open + 1; q < n; q++) {
      const cc = source[q];
      if (cc === '\\') { q++; continue; }
      if (cc === '{') braceDepth++;
      else if (cc === '}') { if (braceDepth > 0) braceDepth--; }
      else if (cc === ']' && braceDepth === 0) return { text: source.slice(open + 1, q), end: q + 1 };
    }
    return { text: source.slice(open + 1, n), end: n };
  };

  // From `start`, greedily collect immediately-following { } (required) and [ ]
  // (optional) argument groups. Only spaces/tabs may separate them — never a
  // newline — so an unrelated brace group on a later line is not misattributed.
  const collectArgs = (start: number): { args: string[]; opts: string[]; end: number } => {
    const args: string[] = [];
    const opts: string[] = [];
    let p = start;
    for (;;) {
      let q = p;
      while (q < n && (source[q] === ' ' || source[q] === '\t')) q++;
      if (source[q] === '{') { const g = readBraceGroup(q); args.push(g.text); p = g.end; }
      else if (source[q] === '[') { const g = readOptGroup(q); opts.push(g.text); p = g.end; }
      else break;
    }
    return { args, opts, end: p };
  };

  // Strip nested commands/braces from a sectioning/environment title for a clean name.
  const cleanTitle = (raw: string): string =>
    raw.replace(/\\[a-zA-Z@]+\*?/g, '').replace(/[{}$]/g, '').replace(/\s+/g, ' ').trim();
  const csName = (raw: string): string => {
    const m = /\\([a-zA-Z@]+)/.exec(raw);
    return (m ? m[1] : raw.trim().replace(/^\\/, '')).trim();
  };
  const splitList = (raw: string): string[] =>
    raw.split(',').map(s => s.trim()).filter(Boolean);
  const ensureExt = (raw: string, ext: string): string =>
    /\.[a-zA-Z0-9]+$/.test(raw) ? raw : `${raw}${ext}`;

  // Sectioning hierarchy (levels 0..6); deepest active section is the live container.
  const sectionStack: (string | null)[] = [null, null, null, null, null, null, null];
  const sectionMarks: { name: string; level: number; line: number }[] = [];
  const envStack: { name: string }[] = [];
  const seenEnv = new Set<string>();
  const currentSection = (): string | null => {
    for (let l = 6; l >= 0; l--) if (sectionStack[l]) return sectionStack[l];
    return null;
  };
  // The containment parent for definitions, labels, environments and references
  // is the nearest enclosing SECTION (or the file). It deliberately does NOT use
  // the open-environment name: environment type names ("figure", "table") are not
  // unique within a file, and patch-builder resolves a CONTAINS edge's *source*
  // by bare name with no container hint — so an environment used as a parent would
  // be ambiguous and its children's edges would dangle. Sections (unique titles)
  // are safe parents. Environments are still recorded as section members.
  const container = (): string => currentSection() ?? fileName;

  const addImport = (rawSpec: string, dst: string, line: number): void => {
    if (!dst) return;
    entities.push({ name: dst, kind: 'module', lineStart: line, lineEnd: line, language });
    relationships.push({ srcName: fileName, dstName: dst, predicate: 'IMPORTS', importRaw: rawSpec });
  };
  const addDef = (name: string, kind: string, line: number): void => {
    if (!name) return;
    const cont = container();
    entities.push({ name, kind, lineStart: line, lineEnd: line, language, container: cont === fileName ? undefined : cont });
    relationships.push({ srcName: cont, dstName: name, predicate: 'CONTAINS' });
  };

  let i = 0;
  while (i < n) {
    const ch = source[i];
    if (ch === '%') { while (i < n && source[i] !== '\n') i++; continue; }
    if (ch !== '\\') { i++; continue; }

    // Read the control-sequence name. A single non-letter after '\' (\\, \%, \{,
    // \,, \$) is an escape/control symbol — consume and skip.
    let j = i + 1;
    if (j >= n) { i = j; continue; }
    const c0 = source[j];
    if (!/[a-zA-Z@]/.test(c0)) { i = j + 1; continue; }
    let k = j;
    while (k < n && /[a-zA-Z@]/.test(source[k])) k++;
    const name = source.slice(j, k);
    let after = k;
    if (source[after] === '*') after++; // starred form (\section*, \newtheorem*)
    const line = lineAt(i);

    if (LATEX_SECTION_LEVELS[name] !== undefined) {
      const { args, opts, end } = collectArgs(after);
      const title = cleanTitle(args[0] ?? opts[0] ?? '');
      if (title) {
        const level = LATEX_SECTION_LEVELS[name];
        let cont: string = fileName;
        for (let l = level - 1; l >= 0; l--) if (sectionStack[l]) { cont = sectionStack[l]!; break; }
        for (let l = level; l <= 6; l++) sectionStack[l] = null;
        sectionStack[level] = title;
        entities.push({ name: title, kind: 'section', lineStart: line, lineEnd: line, language, container: cont === fileName ? undefined : cont });
        relationships.push({ srcName: cont, dstName: title, predicate: 'CONTAINS' });
        sectionMarks.push({ name: title, level, line });
      }
      i = end; continue;
    }

    if (name === 'begin') {
      const { args, end } = collectArgs(after);
      const envName = (args[0] ?? '').trim();
      if (envName) {
        const cont = container();
        const key = `${cont}\x00${envName}`;
        if (!seenEnv.has(key)) {
          seenEnv.add(key);
          entities.push({ name: envName, kind: 'environment', lineStart: line, lineEnd: line, language, container: cont === fileName ? undefined : cont });
          relationships.push({ srcName: cont, dstName: envName, predicate: 'CONTAINS' });
        }
        envStack.push({ name: envName });
        if (LATEX_VERBATIM_ENVS.has(envName)) {
          // Jump to the matching \end so it pops normally. Tolerate whitespace
          // (\end {verbatim}, \end{ verbatim }) — all legal TeX.
          const esc = envName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
          const m = new RegExp(`\\\\end\\s*\\{\\s*${esc}\\s*\\}`).exec(source.slice(end));
          i = m ? end + m.index : n;
          continue;
        }
      }
      i = end; continue;
    }

    if (name === 'end') {
      const { args, end } = collectArgs(after);
      const envName = (args[0] ?? '').trim();
      // Pop to the nearest matching open environment; ignore stray \end gracefully.
      for (let s = envStack.length - 1; s >= 0; s--) {
        if (envStack[s].name === envName) { envStack.length = s; break; }
      }
      i = end; continue;
    }

    if (LATEX_MACRO_DEFS.has(name)) {
      let p = after;
      while (p < n && (source[p] === ' ' || source[p] === '\t')) p++;
      let macro: string | null = null;
      if (source[p] === '\\') { const m = /^\\([a-zA-Z@]+)/.exec(source.slice(p, p + 80)); if (m) { macro = m[1]; p += m[0].length; } }
      else if (source[p] === '{') { const g = readBraceGroup(p); macro = csName(g.text); p = g.end; }
      if (macro && !LATEX_DYNAMIC_CS.has(macro)) addDef(macro, 'function', line);
      i = p; continue;
    }

    if (LATEX_CS_DEFS.has(name)) {
      let p = after;
      while (p < n && (source[p] === ' ' || source[p] === '\t')) p++;
      if (source[p] === '\\') { const m = /^\\([a-zA-Z@]+)/.exec(source.slice(p, p + 80)); if (m) { if (!LATEX_DYNAMIC_CS.has(m[1])) addDef(m[1], 'function', line); p += m[0].length; } }
      i = p; continue;
    }

    if (LATEX_ENV_DEFS.has(name)) {
      const { args, end } = collectArgs(after);
      addDef((args[0] ?? '').trim(), 'class', line);
      i = end; continue;
    }
    if (LATEX_THEOREM_DEFS.has(name)) {
      const { args, end } = collectArgs(after);
      addDef((args[0] ?? '').trim(), 'class', line);
      i = end; continue;
    }

    if (LATEX_PACKAGE_IMPORTS.has(name)) {
      const { args, end } = collectArgs(after);
      for (const pkg of splitList(args[0] ?? '')) addImport(pkg, pkg, line);
      i = end; continue;
    }

    if (LATEX_FILE_INCLUDES.has(name)) {
      const { args, end } = collectArgs(after);
      for (const raw of splitList(args[0] ?? '')) addImport(raw, ensureExt(raw, '.tex'), line);
      i = end; continue;
    }
    // \import{dir}{file} / \subimport{dir}{file}: path is dir + file
    if (name === 'import' || name === 'subimport' || name === 'inputfrom' || name === 'subinputfrom') {
      const { args, end } = collectArgs(after);
      if (args.length >= 2 && args[1].trim()) {
        const dir = args[0].trim().replace(/\/?$/, '/');
        const raw = `${dir}${args[1].trim()}`;
        addImport(raw, ensureExt(raw, '.tex'), line);
      }
      i = end; continue;
    }
    if (LATEX_BIB_INCLUDES.has(name)) {
      const { args, end } = collectArgs(after);
      for (const raw of splitList(args[0] ?? '')) addImport(raw, ensureExt(raw, '.bib'), line);
      i = end; continue;
    }

    if (name === 'label') {
      const { args, end } = collectArgs(after);
      addDef((args[0] ?? '').trim(), 'label', line);
      i = end; continue;
    }
    if (name === 'bibitem') {
      const { args, end } = collectArgs(after);
      addDef((args[0] ?? '').trim(), 'label', line);
      i = end; continue;
    }

    if (LATEX_REF_CMDS.has(name) || LATEX_CITE_CMDS.has(name)) {
      const { args, end } = collectArgs(after);
      const src = container();
      for (const target of splitList(args[0] ?? '')) {
        relationships.push({ srcName: src, dstName: target, predicate: 'REFERENCES' });
      }
      i = end; continue;
    }

    // Unknown command: advance past the name only, so any cross-references nested
    // in its argument groups (e.g. \caption{... \ref{x}}, \footnote{\cite{y}}) are
    // still scanned as ordinary content on the next iterations.
    i = after;
  }

  // Section chunks: each spans to the line before the next section at the same or
  // shallower level, so a parent section's chunk includes its sub-sections.
  for (let h = 0; h < sectionMarks.length; h++) {
    const { name, level, line } = sectionMarks[h];
    let endLine = sourceLineCount;
    for (let m = h + 1; m < sectionMarks.length; m++) {
      if (sectionMarks[m].level <= level) { endLine = sectionMarks[m].line - 1; break; }
    }
    const startByte = lineStarts[line - 1] ?? 0;
    const endByte = endLine < lineStarts.length ? (lineStarts[endLine] ?? source.length) : source.length;
    const content = source.slice(startByte, endByte);
    chunks.push({
      name,
      chunkKind: 'section',
      lineStart: line,
      lineEnd: endLine,
      startByte,
      endByte,
      contentHash: crypto.createHash('sha256').update(content).digest('hex'),
      language,
    });
  }
  if (sectionMarks.length === 0) {
    chunks.push({
      name: null,
      chunkKind: 'file_body',
      lineStart: 1,
      lineEnd: Math.max(sourceLineCount, 1),
      startByte: 0,
      endByte: source.length,
      contentHash: crypto.createHash('sha256').update(source).digest('hex'),
      language,
    });
  }

  return { filePath, language, entities, chunks, relationships, fileRole };
}

function parseDockerfileFile(filePath: string, source: string): FileParseResult {
  const language = SupportedLanguages.Dockerfile;
  const fileName = nodePath.basename(filePath);
  const sourceLineCount = countSourceLines(source);
  const fileRole = classifyFileRole(filePath);
  const entities: ParsedEntity[] = [
    { name: fileName, kind: 'file', lineStart: 1, lineEnd: sourceLineCount, language },
  ];
  const chunks: ParsedChunk[] = [];
  const relationships: ParsedRelationship[] = [];
  const lines = source.split(/\r?\n/);
  const lineStarts = computeLineStarts(source);
  const stageNames: string[] = [];
  let pending = '';
  let logicalStartLine = 1;

  const pushChunk = (
    name: string | null,
    chunkKind: string,
    lineStart: number,
    lineEnd: number,
    startByte: number,
    endByte: number,
    content: string,
    container?: string,
  ) => {
    chunks.push({
      name,
      chunkKind,
      lineStart,
      lineEnd,
      startByte,
      endByte,
      contentHash: crypto.createHash('sha256').update(content).digest('hex'),
      language,
      container,
    });
  };

  const addInstruction = (instructionLine: string, lineStart: number, lineEnd: number) => {
    const trimmed = instructionLine.trim();
    if (!trimmed || trimmed.startsWith('#')) return;

    const instructionMatch = /^([A-Z]+)\b(?:\s+([\s\S]*))?$/i.exec(trimmed);
    if (!instructionMatch) return;

    const keyword = instructionMatch[1].toUpperCase();
    const argument = (instructionMatch[2] ?? '').trim();
    const startByte = lineStarts[lineStart - 1] ?? 0;
    const endByte = lineEnd < lines.length
      ? (lineStarts[lineEnd] ?? source.length) - 1
      : source.length;

    if (keyword === 'FROM') {
      const fromMatch = /^([^\s]+)(?:\s+AS\s+([A-Za-z0-9._-]+))?/i.exec(argument);
      const baseImage = fromMatch?.[1] ?? argument;
      const stageName = fromMatch?.[2] ?? `stage-${stageNames.length}`;
      stageNames.push(stageName);

      entities.push({
        name: stageName,
        kind: 'config',
        lineStart,
        lineEnd,
        language,
      });
      relationships.push({
        srcName: fileName,
        dstName: stageName,
        predicate: 'CONTAINS',
      });
      pushChunk(stageName, 'build_stage', lineStart, lineEnd, startByte, endByte, instructionLine);

      if (baseImage) {
        entities.push({
          name: baseImage,
          kind: 'module',
          lineStart,
          lineEnd,
          language,
          container: stageName,
        });
        relationships.push({
          srcName: stageName,
          dstName: baseImage,
          predicate: 'IMPORTS',
        });
      }
      return;
    }

    const scope = stageNames[stageNames.length - 1];
    const entityName =
      keyword === 'COPY' || keyword === 'ADD'
        ? `${keyword.toLowerCase()}:${argument.split(/\s+/).find(token => token.length > 0) ?? keyword.toLowerCase()}`
        : keyword.toLowerCase();

    entities.push({
      name: entityName,
      kind: 'config_entry',
      lineStart,
      lineEnd,
      language,
      container: scope,
    });
    relationships.push({
      srcName: scope ?? fileName,
      dstName: entityName,
      predicate: 'CONTAINS',
    });
    pushChunk(entityName, 'docker_instruction', lineStart, lineEnd, startByte, endByte, instructionLine, scope);

    if (keyword === 'COPY') {
      const fromFlag = /--from=([^\s]+)/i.exec(argument)?.[1];
      if (fromFlag) {
        relationships.push({
          srcName: scope ?? fileName,
          dstName: fromFlag,
          predicate: 'IMPORTS',
        });
      }
    }
  };

  for (let index = 0; index < lines.length; index++) {
    const line = lines[index];
    const trimmedEnd = line.trimEnd();
    const lineContent = pending ? `${pending}\n${line}` : line;
    if (!pending) logicalStartLine = index + 1;

    if (trimmedEnd.endsWith('\\')) {
      pending = lineContent.slice(0, lineContent.lastIndexOf('\\')).trimEnd();
      continue;
    }

    addInstruction(lineContent, logicalStartLine, index + 1);
    pending = '';
  }

  if (pending) {
    addInstruction(pending, logicalStartLine, lines.length);
  }

  if (chunks.length === 0) {
    pushChunk(null, 'file_body', 1, Math.max(sourceLineCount, 1), 0, source.length, source);
  }

  return {
    filePath,
    language,
    entities,
    chunks,
    relationships,
    fileRole,
  };
}

// ---------------------------------------------------------------------------
// SQL
// ---------------------------------------------------------------------------

/** Strip -- line comments and /* block comments *\/ from SQL source. */
function stripSqlComments(source: string): string {
  // Block comments: use indexOf to avoid ReDoS from regex backtracking
  let result = '';
  let i = 0;
  while (i < source.length) {
    const start = source.indexOf('/*', i);
    if (start === -1) { result += source.slice(i); break; }
    result += source.slice(i, start);
    const end = source.indexOf('*/', start + 2);
    if (end === -1) { result += source.slice(start).replace(/[^\n]/g, ' '); break; }
    result += source.slice(start, end + 2).replace(/[^\n]/g, ' ');
    i = end + 2;
  }
  // Line comments: [^\n]* is always linear (no backtracking possible)
  return result.replace(/--[^\n]*/g, match => ' '.repeat(match.length));
}

/** Extract unquoted table/view names following FROM, JOIN variants, INTO, UPDATE, REFERENCES. */
function extractSqlTableRefs(sql: string): string[] {
  const refs = new Set<string>();
  // FROM tbl, JOIN tbl, INTO tbl, UPDATE tbl, REFERENCES tbl
  const refPattern =
    /\b(?:FROM|JOIN|INNER\s+JOIN|LEFT\s+JOIN|RIGHT\s+JOIN|FULL\s+JOIN|CROSS\s+JOIN|INTO|UPDATE|REFERENCES)\s+([A-Za-z0-9_.`"[\]]+)/gi;
  let m: RegExpExecArray | null;
  while ((m = refPattern.exec(sql)) !== null) {
    refs.add(m[1].replace(/[`"[\]]/g, ''));
  }
  return [...refs];
}

function parseJsonFile(filePath: string, source: string): FileParseResult {
  const language = SupportedLanguages.JSON;
  const fileName = nodePath.basename(filePath);
  const sourceLineCount = countSourceLines(source);
  const fileRole = classifyFileRole(filePath);
  const entities: ParsedEntity[] = [
    { name: fileName, kind: 'file', lineStart: 1, lineEnd: sourceLineCount, language },
  ];
  const chunks: ParsedChunk[] = [];
  const relationships: ParsedRelationship[] = [];

  // Walk the parsed JSON value, emitting one entity+chunk per object key.
  // `path` is the fully qualified key ancestry for the current object.
  const walk = (
    value: unknown,
    path: string,
    lineHint: number,
  ): void => {
    if (value === null || typeof value !== 'object') return;

    if (Array.isArray(value)) {
      for (const item of value) {
        walk(item, path, lineHint);
      }
      return;
    }

    for (const key of Object.keys(value as Record<string, unknown>)) {
      const fullPath = path ? `${path}.${key}` : key;
      entities.push({
        name: key,
        kind: 'config_entry',
        lineStart: lineHint,
        lineEnd: lineHint,
        language,
        container: path || undefined,
      });
      chunks.push({
        name: key,
        chunkKind: 'config_key',
        lineStart: lineHint,
        lineEnd: lineHint,
        startByte: 0,
        endByte: 0,
        contentHash: crypto
          .createHash('sha256')
          .update(`${fullPath}=${JSON.stringify((value as Record<string, unknown>)[key])}`)
          .digest('hex'),
        language,
        container: path || undefined,
      });
      relationships.push({
        srcName: path || fileName,
        dstName: key,
        predicate: 'CONTAINS',
      });
      walk((value as Record<string, unknown>)[key], fullPath, lineHint);
    }
  };

  try {
    const parsed: unknown = JSON.parse(source);
    walk(parsed, '', 1);
  } catch {
    // Unparseable JSON: fall through to file_body chunk below
  }

  if (chunks.length === 0) {
    chunks.push({
      name: null,
      chunkKind: 'file_body',
      lineStart: 1,
      lineEnd: Math.max(sourceLineCount, 1),
      startByte: 0,
      endByte: source.length,
      contentHash: crypto.createHash('sha256').update(source).digest('hex'),
      language,
    });
  }

  return { filePath, language, entities, chunks, relationships, fileRole };
}

function parseSqlFile(filePath: string, source: string): FileParseResult {
  const language = SupportedLanguages.SQL;
  const fileName = nodePath.basename(filePath);
  const sourceLineCount = countSourceLines(source);
  const fileRole = classifyFileRole(filePath);
  const entities: ParsedEntity[] = [
    { name: fileName, kind: 'file', lineStart: 1, lineEnd: sourceLineCount, language },
  ];
  const chunks: ParsedChunk[] = [];
  const relationships: ParsedRelationship[] = [];
  const lineStarts = computeLineStarts(source);
  const lines = source.split(/\r?\n/);
  const stripped = stripSqlComments(source);
  const strippedLines = stripped.split(/\r?\n/);

  // Matches: CREATE [OR REPLACE] [TEMP[ORARY]] [UNIQUE] <TYPE> [IF NOT EXISTS] <name>
  const createRe =
    /^\s*CREATE\s+(?:OR\s+REPLACE\s+)?(?:TEMP(?:ORARY)?\s+)?(?:UNIQUE\s+)?(TABLE|VIEW|FUNCTION|PROCEDURE|PROC|TRIGGER|INDEX)\s+(?:IF\s+NOT\s+EXISTS\s+)?([A-Za-z0-9_.`"[\]]+)/i;

  // For INDEX ... ON tableName
  const indexOnRe = /\bON\s+([A-Za-z0-9_.`"[\]]+)/i;

  let statementLines: number[] = [];  // line indices (0-based) belonging to current statement
  let currentCreate: { kind: string; name: string; lineStart: number } | null = null;

  const flushStatement = (endLineIdx: number) => {
    if (!currentCreate) return;
    const lineEnd = endLineIdx + 1;
    const startByte = lineStarts[currentCreate.lineStart - 1] ?? 0;
    const endByte =
      lineEnd < lines.length ? (lineStarts[lineEnd] ?? source.length) - 1 : source.length;
    const statementText = strippedLines
      .slice(currentCreate.lineStart - 1, lineEnd)
      .join('\n');
    const rawContent = lines.slice(currentCreate.lineStart - 1, lineEnd).join('\n');

    const objType = currentCreate.kind.toUpperCase();
    const entityKind =
      objType === 'TABLE' ? 'table'
      : objType === 'VIEW' ? 'view'
      : objType === 'INDEX' ? 'config_entry'
      : 'function'; // FUNCTION, PROCEDURE, PROC, TRIGGER
    const chunkKind =
      objType === 'TABLE' ? 'create_table'
      : objType === 'VIEW' ? 'create_view'
      : objType === 'INDEX' ? 'create_index'
      : objType === 'TRIGGER' ? 'create_trigger'
      : 'create_function';

    entities.push({
      name: currentCreate.name,
      kind: entityKind,
      lineStart: currentCreate.lineStart,
      lineEnd,
      language,
    });
    chunks.push({
      name: currentCreate.name,
      chunkKind,
      lineStart: currentCreate.lineStart,
      lineEnd,
      startByte,
      endByte,
      contentHash: crypto.createHash('sha256').update(rawContent).digest('hex'),
      language,
    });
    relationships.push({ srcName: fileName, dstName: currentCreate.name, predicate: 'CONTAINS' });

    if (objType === 'INDEX') {
      // REFERENCES the table the index is ON
      const onMatch = indexOnRe.exec(statementText);
      if (onMatch) {
        relationships.push({
          srcName: currentCreate.name,
          dstName: onMatch[1].replace(/[`"[\]]/g, ''),
          predicate: 'REFERENCES',
        });
      }
    } else if (objType !== 'TABLE') {
      // Views, functions, procedures, triggers: extract table refs from body
      for (const ref of extractSqlTableRefs(statementText)) {
        if (ref !== currentCreate.name) {
          relationships.push({ srcName: currentCreate.name, dstName: ref, predicate: 'REFERENCES' });
        }
      }
    }

    currentCreate = null;
  };

  for (let i = 0; i < strippedLines.length; i++) {
    const line = strippedLines[i];

    if (!currentCreate) {
      const m = createRe.exec(line);
      if (m) {
        currentCreate = {
          kind: m[1],
          name: m[2].replace(/[`"[\]]/g, ''),
          lineStart: i + 1,
        };
      }
    }

    if (currentCreate && /;/.test(line)) {
      flushStatement(i);
    }
  }

  if (chunks.length === 0) {
    chunks.push({
      name: null,
      chunkKind: 'file_body',
      lineStart: 1,
      lineEnd: Math.max(sourceLineCount, 1),
      startByte: 0,
      endByte: source.length,
      contentHash: crypto.createHash('sha256').update(source).digest('hex'),
      language,
    });
  }

  return { filePath, language, entities, chunks, relationships, fileRole };
}

// ---------------------------------------------------------------------------
// Protocol Buffers
// ---------------------------------------------------------------------------

// proto3 scalar types, plus proto2 spellings. Field types outside this set name
// another message or enum, which is the edge worth recording.
const PROTO_SCALARS = new Set([
  'double', 'float', 'int32', 'int64', 'uint32', 'uint64', 'sint32', 'sint64',
  'fixed32', 'fixed64', 'sfixed32', 'sfixed64', 'bool', 'string', 'bytes',
  'group',
]);

/** Blank comments and string bodies so braces and keywords inside them cannot
 *  be mistaken for structure. Length and newlines are preserved so line numbers
 *  and byte offsets stay accurate. */
function stripProtoNoise(source: string): string {
  let out = '';
  let i = 0;
  while (i < source.length) {
    const two = source.slice(i, i + 2);
    if (two === '//') {
      const nl = source.indexOf('\n', i);
      const end = nl === -1 ? source.length : nl;
      out += ' '.repeat(end - i);
      i = end;
    } else if (two === '/*') {
      const close = source.indexOf('*/', i + 2);
      const end = close === -1 ? source.length : close + 2;
      out += source.slice(i, end).replace(_blankNonNewline, ' ');
      i = end;
    } else if (source[i] === '"' || source[i] === "'") {
      const quote = source[i];
      let j = i + 1;
      while (j < source.length && source[j] !== quote) {
        if (source[j] === '\\') j += 1;
        j += 1;
      }
      const end = Math.min(j + 1, source.length);
      // Keep the quotes so `import "x.proto"` is still recognisable; blank the body.
      out += quote + source.slice(i + 1, end - 1).replace(_blankNonNewline, ' ') + (end > i + 1 ? quote : '');
      i = end;
    } else {
      out += source[i];
      i += 1;
    }
  }
  return out;
}

// Statement keywords that can begin a line shaped like a field declaration.
// `option deprecated = 1;` in particular matches PROTO_FIELD_RE exactly, and
// without this would emit a REFERENCES edge to a node called "option".
const PROTO_STATEMENT_KEYWORDS = new Set([
  'option', 'reserved', 'extensions', 'extend', 'import', 'package', 'syntax',
  'oneof', 'rpc', 'returns', 'message', 'enum', 'service', 'group', 'public',
  'weak', 'stream',
]);

const PROTO_DEF_RE = /^\s*(message|enum|service)\s+([A-Za-z_]\w*)/;
const PROTO_RPC_RE =
  /^\s*rpc\s+([A-Za-z_]\w*)\s*\(\s*(?:stream\s+)?([\w.]+)\s*\)\s*returns\s*\(\s*(?:stream\s+)?([\w.]+)\s*\)/;
const PROTO_IMPORT_RE = /^\s*import\s+(?:public\s+|weak\s+)?"([^"]*)"/;
const PROTO_PACKAGE_RE = /^\s*package\s+([\w.]+)\s*;/;
const PROTO_FIELD_RE =
  /^\s*(?:repeated\s+|optional\s+|required\s+)?(map\s*<\s*[\w.]+\s*,\s*([\w.]+)\s*>|[\w.]+)\s+[A-Za-z_]\w*\s*=\s*\d+/;

function parseProtoFile(filePath: string, source: string): FileParseResult {
  const language = SupportedLanguages.Proto;
  const fileName = nodePath.basename(filePath);
  const sourceLineCount = countSourceLines(source);
  const fileRole = classifyFileRole(filePath);
  const entities: ParsedEntity[] = [
    { name: fileName, kind: 'file', lineStart: 1, lineEnd: sourceLineCount, language },
  ];
  const chunks: ParsedChunk[] = [];
  const relationships: ParsedRelationship[] = [];
  const lineStarts = computeLineStarts(source);
  const stripped = stripProtoNoise(source);
  const lines = stripped.split(/\r?\n/);
  const rawLines = source.split(/\r?\n/);

  interface OpenDef {
    name: string;
    kind: 'message' | 'enum' | 'service';
    lineStart: number;
    depth: number;
    container?: string;
  }
  const open: OpenDef[] = [];
  let depth = 0;

  const close = (def: OpenDef, lineEnd: number) => {
    const entityKind =
      def.kind === 'service' ? 'interface' : 'class';
    const chunkKind = def.kind === 'service' ? 'interface' : 'class';
    entities.push({ name: def.name, kind: entityKind, lineStart: def.lineStart, lineEnd, language });
    const startByte = lineStarts[def.lineStart - 1] ?? 0;
    const endByte =
      lineEnd < rawLines.length ? (lineStarts[lineEnd] ?? source.length) - 1 : source.length;
    chunks.push({
      name: def.name,
      chunkKind,
      lineStart: def.lineStart,
      lineEnd,
      startByte,
      endByte,
      contentHash: crypto
        .createHash('sha256')
        .update(rawLines.slice(def.lineStart - 1, lineEnd).join('\n'))
        .digest('hex'),
      language,
      ...(def.container ? { container: def.container } : {}),
    });
    relationships.push({
      srcName: def.container ?? fileName,
      dstName: def.name,
      predicate: 'CONTAINS',
    });
  };

  const addReference = (from: string | undefined, typeName: string) => {
    if (!from) return;
    const bare = typeName.replace(/^\./, '');
    const simple = bare.includes('.') ? bare.slice(bare.lastIndexOf('.') + 1) : bare;
    if (!simple || PROTO_SCALARS.has(bare) || simple === from) return;
    relationships.push({ srcName: from, dstName: simple, predicate: 'REFERENCES' });
  };

  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    const enclosing = open.length ? open[open.length - 1] : undefined;

    const pkg = PROTO_PACKAGE_RE.exec(line);
    if (pkg) {
      entities.push({ name: pkg[1], kind: 'module', lineStart: i + 1, lineEnd: i + 1, language });
      relationships.push({ srcName: fileName, dstName: pkg[1], predicate: 'CONTAINS' });
    }

    const imp = PROTO_IMPORT_RE.exec(rawLines[i] ?? '');
    if (imp && imp[1]) {
      relationships.push({
        srcName: fileName,
        dstName: nodePath.basename(imp[1]),
        predicate: 'IMPORTS',
        importRaw: imp[1],
      });
    }

    const rpc = PROTO_RPC_RE.exec(line);
    if (rpc && enclosing) {
      entities.push({ name: rpc[1], kind: 'method', lineStart: i + 1, lineEnd: i + 1, language });
      relationships.push({ srcName: enclosing.name, dstName: rpc[1], predicate: 'CONTAINS' });
      addReference(rpc[1], rpc[2]);
      addReference(rpc[1], rpc[3]);
    } else if (enclosing && enclosing.kind === 'message' && !PROTO_DEF_RE.test(line)) {
      const field = PROTO_FIELD_RE.exec(line);
      if (field && !PROTO_STATEMENT_KEYWORDS.has(field[1])) {
        addReference(enclosing.name, field[2] ?? field[1]);
      }
    }

    const def = PROTO_DEF_RE.exec(line);
    if (def) {
      open.push({
        name: def[2],
        kind: def[1] as OpenDef['kind'],
        lineStart: i + 1,
        depth,
        container: enclosing?.name,
      });
    }

    for (const ch of line) {
      if (ch === '{') depth += 1;
      else if (ch === '}') {
        depth = Math.max(0, depth - 1);
        // A definition opened at this depth is now complete. Single-line forms
        // (`message Empty {}`) open and close on the same line, which this
        // handles because the push happens before the brace scan.
        while (open.length && open[open.length - 1].depth >= depth) {
          close(open.pop() as OpenDef, i + 1);
        }
      }
    }
  }

  // Unterminated definitions (truncated or malformed file): close at EOF rather
  // than dropping the symbols.
  while (open.length) close(open.pop() as OpenDef, sourceLineCount);

  if (chunks.length === 0) {
    chunks.push({
      name: null,
      chunkKind: 'file_body',
      lineStart: 1,
      lineEnd: Math.max(sourceLineCount, 1),
      startByte: 0,
      endByte: source.length,
      contentHash: crypto.createHash('sha256').update(source).digest('hex'),
      language,
    });
  }

  return { filePath, language, entities, chunks, relationships, fileRole };
}

// ---------------------------------------------------------------------------
// Rust: cfg macro unwrapping
// ---------------------------------------------------------------------------

/**
 * Blanks out feature-gating macro wrappers in Rust source so that the items
 * inside become visible to tree-sitter as top-level declarations.
 *
 * Replaces `cfg_rt! { ... }` (and similar) with the body contents in-place,
 * preserving every character position and line number so that entity line
 * numbers remain accurate.
 */
// Pre-compiled for blanking macro headers (preserves newlines, replaces all else with space)
const _blankNonNewline = /[^\n]/g;

function unwrapRustCfgMacros(source: string): string {
  const re = /\bcfg_(?:rt_multi_thread|not_rt|rt|io|time|sync|net|fs|process|signal)!\s*\{/g;
  // Collect edit regions before mutating anything
  const edits: Array<[number, number, number]> = []; // [macroStart, openBrace, closeBrace]
  let m: RegExpExecArray | null;
  while ((m = re.exec(source)) !== null) {
    const openBrace = m.index + m[0].length - 1;
    let depth = 0;
    let closeBrace = -1;
    for (let i = openBrace; i < source.length; i++) {
      if (source[i] === '{') depth++;
      else if (source[i] === '}') {
        if (--depth === 0) { closeBrace = i; break; }
      }
    }
    if (closeBrace !== -1) edits.push([m.index, openBrace, closeBrace]);
  }
  if (edits.length === 0) return source;

  // Build result from slices — avoids O(n) split('') allocation of N small string objects
  const parts: string[] = [];
  let pos = 0;
  for (const [macroStart, openBrace, closeBrace] of edits) {
    if (macroStart > pos) parts.push(source.slice(pos, macroStart));
    // Blank macro name + opening brace (preserve newlines)
    parts.push(source.slice(macroStart, openBrace + 1).replace(_blankNonNewline, ' '));
    pos = openBrace + 1;
    // Keep everything inside the braces unchanged
    if (closeBrace > pos) parts.push(source.slice(pos, closeBrace));
    // Blank closing brace
    parts.push(' ');
    pos = closeBrace + 1;
  }
  if (pos < source.length) parts.push(source.slice(pos));
  return parts.join('');
}

/**
 * Blanks out CUDA kernel-launch configurations (`<<<grid, block>>>`) so that
 * tree-sitter-cpp sees an ordinary call expression.
 *
 * The launch syntax is not valid C++: the grammar fails on it and, worse,
 * recovers by dropping the whole call — so the edge from host code to the
 * kernel it launches is lost, which is the one edge worth having in a CUDA
 * file. Blanking the config in-place (preserving every character position and
 * newline, as with the Rust macro unwrapper above) turns `k<<<a,b>>>(x)` into
 * `k        (x)`, which parses cleanly and yields the call.
 *
 * Hand-scanned rather than pattern-matched. The natural regex
 * (`/<<<[^;]*?>>>(?=\s*\()/g`) is quadratic on `<`-heavy input — a file of
 * 16k `<` took 67ms and grew 4x per doubling — and ingest input is an
 * arbitrary repository, so that is a denial-of-service vector, not a
 * micro-optimisation. This scanner never revisits a character: each failed
 * search advances the cursor past the region it just rejected.
 *
 * A launch config is always followed immediately by the argument list, so
 * requiring `(` after the closing `>>>` is what keeps this off ordinary C++ —
 * nested templates (`vector<vector<vector<int>>>`), shift operators and
 * `"<<<HEAD>>>"` in a string literal are all left alone. Stopping the search
 * at `;` keeps a stray `<<<` in a comment from reaching a later `>>>`.
 */
const _isSpace = (ch: string) => ch === ' ' || ch === '\n' || ch === '\t' || ch === '\r';

function blankCudaLaunchConfigs(source: string): string {
  if (!source.includes('<<<')) return source;

  const out: string[] = [];
  let copiedTo = 0;
  let cursor = 0;

  while (cursor < source.length) {
    const open = source.indexOf('<<<', cursor);
    if (open === -1) break;

    // Find the closing `>>>`, giving up at `;` — a launch config never spans a
    // statement boundary.
    let scan = open + 3;
    while (scan < source.length && source[scan] !== ';' && !source.startsWith('>>>', scan)) {
      scan += 1;
    }

    if (!source.startsWith('>>>', scan)) {
      // Hit `;` or end of file. No `<<<` inside the region just scanned can
      // reach a closing `>>>` either, so skip the whole thing.
      cursor = scan + 1;
      continue;
    }

    const close = scan + 3;
    let afterConfig = close;
    while (afterConfig < source.length && _isSpace(source[afterConfig])) afterConfig += 1;

    if (source[afterConfig] !== '(') {
      // A `>>>` that is not a launch — e.g. closing nested templates. Resume
      // after it; the region behind us cannot match.
      cursor = close;
      continue;
    }

    out.push(source.slice(copiedTo, open));
    out.push(source.slice(open, close).replace(_blankNonNewline, ' '));
    copiedTo = close;
    cursor = close;
  }

  if (copiedTo === 0) return source;
  out.push(source.slice(copiedTo));
  return out.join('');
}

// ---------------------------------------------------------------------------
// Main parse function
// ---------------------------------------------------------------------------

interface PhpNamespaceSpan {
  startIndex: number;
  namespace: string;
}

interface PhpNamespaces {
  /** Unbraced `namespace X;` declarations, ascending by start offset. */
  spans: PhpNamespaceSpan[];
  /** Every top-level `namespace` declaration, braced or not. */
  blocks: number;
}

/**
 * The file's namespace structure: start offsets of every unbraced
 * `namespace X;` at top level (ascending), plus how many namespaces the file
 * declares in total.
 *
 * Built once per parse. Doing the span scan per definition instead made the
 * file cost O(definitions x top-level nodes): a valid 890 KB PSR-12 file with
 * ~16k functions took ~197s, against ~355ms without it. Both results come off
 * that single walk on purpose — reading `namedChildren` a second time pays the
 * whole node-wrapper materialization cost again, which is the dominant term.
 *
 * A braced `namespace X { ... }` scopes by containment rather than position, so
 * it is handled by the ancestor walk in {@link phpNamespaceForNode} and is
 * excluded from `spans` — but it still counts towards `blocks`.
 */
function collectPhpNamespaces(rootNode: any): PhpNamespaces {
  const spans: PhpNamespaceSpan[] = [];
  let blocks = 0;
  // `namedChildren` materializes the list in a single walk; indexing
  // `namedChild(i)` in a loop is what made the original scan expensive.
  for (const child of rootNode.namedChildren ?? []) {
    if (!child || child.type !== 'namespace_definition') continue;
    blocks++;
    if (child.childForFieldName?.('body')) continue;
    spans.push({
      startIndex: child.startIndex,
      namespace: child.childForFieldName?.('name')?.text?.replace(/\s+/g, '') ?? '',
    });
  }
  return { spans, blocks };
}

function phpNamespaceForNode(node: any, spans: PhpNamespaceSpan[]): string | undefined {
  for (let current = node.parent; current; current = current.parent) {
    if (current.type === 'namespace_definition') {
      return current.childForFieldName?.('name')?.text?.replace(/\s+/g, '') ?? '';
    }
  }

  // The last unbraced declaration starting before this node wins.
  let low = 0;
  let high = spans.length - 1;
  let active: string | undefined;
  while (low <= high) {
    const mid = (low + high) >> 1;
    if (spans[mid].startIndex < node.startIndex) {
      active = spans[mid].namespace;
      low = mid + 1;
    } else {
      high = mid - 1;
    }
  }
  return active;
}

/** Default per-file parse budget in ms, overridable with IX_PARSE_BUDGET_MS. */
export const DEFAULT_PARSE_BUDGET_MS = 10_000;

/** The per-file budget: IX_PARSE_BUDGET_MS if it is a non-negative number, else the default. 0 = none. */
export function parseBudgetMs(): number {
  const raw = process.env.IX_PARSE_BUDGET_MS;
  const n = raw === undefined || raw.trim() === '' ? Number.NaN : Number(raw);
  return Number.isFinite(n) && n >= 0 ? n : DEFAULT_PARSE_BUDGET_MS;
}

/** Thrown inside `parseFile` when a file runs past its budget; never escapes it. */
class ParseBudgetExceeded extends Error {}

export interface ParseFileOptions {
  /** Give up on the file after this many ms. Defaults to `parseBudgetMs()`; 0 turns the budget off. */
  budgetMs?: number;
  /**
   * Called when a supported file does not parse, before `parseFile` returns
   * null: `timeout` when it ran past the budget, `error` for anything else.
   * Not called for a file no grammar handles.
   */
  onFailure?: (failure: { reason: 'timeout' | 'error'; message: string }) => void;
}

export function parseFile(filePath: string, source: string, opts: ParseFileOptions = {}): FileParseResult | null {
  const language = detectLanguageForSource(filePath, source);
  if (!language) return null;
  if (language === SupportedLanguages.YAML) return parseYamlFile(filePath, source);
  if (language === SupportedLanguages.Dockerfile) return parseDockerfileFile(filePath, source);
  if (language === SupportedLanguages.SQL) return parseSqlFile(filePath, source);
  if (language === SupportedLanguages.JSON) return parseJsonFile(filePath, source);
  if (language === SupportedLanguages.TOML) return parseTomlFile(filePath, source);
  if (language === SupportedLanguages.Markdown) return parseMarkdownFile(filePath, source);
  if (language === SupportedLanguages.LaTeX) return parseLatexFile(filePath, source);
  if (language === SupportedLanguages.Proto) return parseProtoFile(filePath, source);

  // TypeScript TSX uses a separate grammar
  const isTsx = filePath.endsWith('.tsx');
  const grammar = isTsx ? TypeScript.tsx : GRAMMAR_MAP[language];
  if (!grammar) return null;

  const queries = LANGUAGE_QUERIES[language];
  if (!queries) return null;

  const budgetMs = opts.budgetMs ?? parseBudgetMs();
  const deadline = budgetMs > 0 ? performance.now() + budgetMs : Number.POSITIVE_INFINITY;
  let budgetTicks = 0;
  /**
   * Called once per match in both passes. The tree-sitter parse and query run
   * in native code and cannot be interrupted, but the passes over the matches
   * are where a file can go quadratic, and a file that does must not hold a
   * parse worker for minutes. The worker pool has a backstop for the rest.
   */
  const checkBudget = (): void => {
    if ((++budgetTicks & 63) === 0 && performance.now() > deadline) {
      throw new ParseBudgetExceeded(`parse budget of ${budgetMs} ms exceeded`);
    }
  };

  try {
    const parser = getParser();
    if (grammar !== _currentGrammar) {
      parser.setLanguage(grammar);
      _currentGrammar = grammar;
    }
    // tree-sitter-java cannot parse array-type annotations on varargs params
    // (e.g. `@Nullable Object @Nullable ... args`). The second annotation causes
    // error recovery to truncate the enclosing class_declaration, orphaning all
    // subsequent methods. Strip any @Annotation immediately before `...` in-memory
    // so the class body parses correctly. Blanked with spaces, not deleted, so
    // every later byte offset and column still matches the file on disk.
    let parseSource = language === SupportedLanguages.Java
      ? source.replace(/@\w+\s*(?=\.\.\.)/g, m => ' '.repeat(m.length))
      : source;

    // Rust: unwrap feature-gating macros (cfg_rt! { ... }, cfg_io! { ... }, etc.)
    // These macros are transparent pass-throughs — their bodies contain normal items
    // that tree-sitter cannot see because they are parsed as raw token_tree nodes.
    // We blank out the macro call and matching closing brace in-place (preserving
    // character positions and line numbers) so the inner items become top-level.
    if (language === SupportedLanguages.Rust) {
      parseSource = unwrapRustCfgMacros(parseSource);
    }

    // CUDA: neutralise kernel-launch configs so the host -> kernel call survives.
    // Gated on the extension rather than the language so .cpp/.hpp parsing stays
    // byte-identical.
    if (filePath.endsWith('.cu') || filePath.endsWith('.cuh')) {
      parseSource = blankCudaLaunchConfigs(parseSource);
    }
    const tree = parser.parse(parseSource, undefined, { bufferSize: parseSource.length + 1 });
    const cacheKey = isTsx ? 'tsx' as const : language;
    const query = getCachedQuery(cacheKey, grammar, queries);
    const matches = query.matches(tree.rootNode);

    // Pre-partition matches so each pass only iterates its relevant subset.
    // Pass 1: definitions, heritage, and language-specific type hints.
    // Pass 2: imports, calls, type references.
    // Without this, every definition match does 5 useless find() calls in pass 2,
    // and every call match does 4 useless find() calls in pass 1.
    const pass1Matches: any[] = [];
    const pass2Matches: any[] = [];
    for (const m of matches) {
      let isPass1 = false;
      for (const c of m.captures) {
        const n = c.name;
        if (n.startsWith('definition.') || n.startsWith('heritage.') ||
            n === '_typed_param_scope' || n === '_assign_scope' || n === '_typed_var_scope' ||
            n === '_go_param_scope') {
          isPass1 = true;
          break;
        }
      }
      (isPass1 ? pass1Matches : pass2Matches).push(m);
    }

    const fileName = nodePath.basename(filePath);
    const sourceLineCount = countSourceLines(source);

    const entities: ParsedEntity[] = [
      { name: fileName, kind: 'file', lineStart: 1, lineEnd: sourceLineCount, language },
    ];
    const chunks: ParsedChunk[] = [];
    const relationships: ParsedRelationship[] = [];
    const pendingChunks: Array<{
      name: string;
      chunkKind: string;
      lineStart: number;
      lineEnd: number;
      startByte: number;
      endByte: number;
      language: SupportedLanguages;
      container?: string;
    }> = [];

    // Track class ranges for containment: [name, startLine, endLine]
    const classRanges: Array<{ name: string; start: number; end: number }> = [];
    // Track seen calls per enclosing scope to avoid duplicate CALLS edges
    const seenCalls = new Map<string, Set<string>>();
    // Track seen type references per enclosing class/file to avoid duplicate REFERENCES edges
    const seenRefs = new Map<string, Set<string>>();
    // Map function name → (param name → declared type) for typed-parameter qualifier substitution
    const paramTypeMap = new Map<string, Map<string, string>>();
    // Python: map function name → (variable name → assigned type) for untyped-param qualifier substitution
    const assignTypeMap = new Map<string, Map<string, string>>();
    // Map enclosing scope → (variable/member name → declared type)
    const declaredTypeMap = new Map<string, Map<string, string>>();
    // Import aliases keyed by the in-file alias name (Go explicit aliases, etc.).
    const importAliases: Record<string, string> = {};
    // JS/TS named/default import bindings (local → public symbol) for cross-repo
    // alias resolution. Additive: never alters emitted relationships.
    const isJsTs = language === SupportedLanguages.JavaScript || language === SupportedLanguages.TypeScript;
    const importBindings: ImportBinding[] = [];
    const jsTsImportedLocalNames = new Set<string>();
    const jsTsImportUseHasUnshadowed = new Map<string, boolean>();
    // Per `${scope}\x00${callKey}`, whether every call site folded into that
    // CALLS relationship is a plain identifier call (see ParsedRelationship.bareCall).
    // Only for languages where such a call can never reach a class member.
    const tracksBareCalls = isJsTs || language === SupportedLanguages.Python ||
      language === SupportedLanguages.Rust || language === SupportedLanguages.PHP;
    const jsTsCallBareOnly = new Map<string, boolean>();
    const jsTsCallRelationship = new Map<string, ParsedRelationship>();
    // Every CALLS relationship by `${scope}\0${callKey}`, so a typed relationship
    // can join the call relationship of the same name.
    const callRelationships = new Map<string, ParsedRelationship>();
    // Java: per `${scope}\0${callKey}`, whether every call site has a typed receiver.
    const javaTypedSites = new Map<string, boolean>();
    // JS/TS: helper-literal module paths already emitted (see importVia).
    const jsTsHelperImports = new Set<string>();
    if (isJsTs) {
      for (const match of pass2Matches) {
        const importSource = match.captures.find((c: any) => c.name === 'import.source');
        const stmtNode = match.captures.find((c: any) => c.name === 'import')?.node;
        if (!importSource || !stmtNode) continue;
        const rawSpec = unwrapImportSpecifier(importSource.node.text);
        for (const binding of extractJsImportBindings(stmtNode, rawSpec)) {
          jsTsImportedLocalNames.add(binding.local);
        }
      }
    }
    const jsTsShadowMemo: JsTsShadowMemo = new Map();
    const recordJsTsImportUse = (
      predicate: string,
      srcName: string,
      dstName: string,
      identifierNode: any,
      localName: string,
      namespace: 'value' | 'type' = 'value',
    ): void => {
      if (!isJsTs || !jsTsImportedLocalNames.has(localName)) return;
      const key = `${predicate}\x00${srcName}\x00${dstName}`;
      // Every use is still evaluated: the edge is kept when ANY use is
      // unshadowed, so the check cannot move behind the de-dup. The memo makes
      // each use cost its scope depth rather than the size of its scopes.
      const unshadowed = !isJsTsImportShadowed(identifierNode, localName, namespace, jsTsShadowMemo);
      jsTsImportUseHasUnshadowed.set(key, (jsTsImportUseHasUnshadowed.get(key) ?? false) || unshadowed);
    };

    // Detect the Go package name once (one package_clause per file). Used to
    // package-prefix Go entity qualifiedNames + bare-call dstNames so
    // resolution is deterministic across same-named entities in different
    // packages.
    let goPackage: string | undefined;
    if (language === SupportedLanguages.Go) {
      for (const m of [...pass1Matches, ...pass2Matches]) {
        const cap = m.captures.find((c: any) => c.name === 'package.name');
        if (cap) { goPackage = cap.node.text; break; }
      }
    }

    // Same idea for PHP: collect the file's namespace boundaries once rather
    // than rescanning the top level for every definition.
    const phpNamespaces: PhpNamespaces = language === SupportedLanguages.PHP
      ? collectPhpNamespaces(tree.rootNode)
      : { spans: [], blocks: 0 };

    // TypeScript overloads: `function f(a: string): string;` lines above the
    // implementation are signatures of the same function. They become one
    // entity, spanning the implementation -- or the first signature where there
    // is none (`declare function`, a .d.ts) -- not one entity per line, which
    // gave the function node the span of its first signature.
    const overloadKey = (defNode: any, name: string): string => {
      let scope = defNode.parent;
      while (scope && (scope.type === 'export_statement' || scope.type === 'ambient_declaration')) scope = scope.parent;
      return `${scope?.startIndex ?? -1}:${name}`;
    };
    const implementedOverloads = new Set<string>();
    if (language === SupportedLanguages.TypeScript) {
      for (const match of pass1Matches) {
        const def = match.captures.find((c: any) => c.name === 'definition.function')?.node;
        const name = match.captures.find((c: any) => c.name === 'name')?.node.text;
        if (def && name && (def.type === 'function_declaration' || def.type === 'generator_function_declaration')) {
          implementedOverloads.add(overloadKey(def, name));
        }
      }
    }
    const seenSignatures = new Set<string>();

    // --- First pass: collect definitions ---
    for (const match of pass1Matches) {
      checkBudget();
      // Definition captures: name + definition.*
      const defCapture = match.captures.find((c: any) =>
        c.name.startsWith('definition.')
      );
      const nameCapture = match.captures.find((c: any) => c.name === 'name');

      if (defCapture) {
        const kind = DEFINITION_KIND_MAP[defCapture.name] ?? 'function';

        // A module-level `const` bound to a function is already captured by the
        // TS/JS function rules, which run ahead of the const rule. Without this
        // the one declaration arrives twice — once as `function`, once as
        // `constant` — with the same name, file and line range. Only the JS/TS
        // const rules emit `const.value`; every other language's
        // `definition.const` has no such capture and falls straight through.
        if (defCapture.name === 'definition.const') {
          const valueType = match.captures.find((c: any) => c.name === 'const.value')?.node.type;
          if (valueType === 'arrow_function' || valueType === 'function_expression') continue;
        }
        const rawName = nameCapture?.node.text
          ?? (defCapture.name === 'definition.constructor' ? 'init' : '');
        // Strip surrounding quotes only for string-keyed definitions (R S3 method
        // names like "print.myClass"). Leave backtick identifiers intact (Scala
        // `type`, R `my fn`): the call/heritage paths don't strip, so stripping
        // here would desync the def name from its call captures.
        let name = nameCapture?.node.type === 'string'
          ? rawName.replace(/^(['"])(.*)\1$/, '$2')
          : rawName;
        if (!name || name.length === 0) continue;

        if (defCapture.node.type === 'function_signature') {
          const key = overloadKey(defCapture.node, name);
          if (implementedOverloads.has(key) || seenSignatures.has(key)) continue;
          seenSignatures.add(key);
        }

        // SAS module entities (DATA/PROC steps, PROC SQL CREATE) need extra
        // shaping so they reflect real data artifacts rather than parser noise.
        if (language === SupportedLanguages.SAS && kind === 'module') {
          if (defCapture.node.type === 'proc_step') {
            // The procedure name (means/sort/freq…) is too generic to be a node.
            // Re-key on the PROC's out= output dataset; drop the step entirely
            // when it produces none (e.g. proc print, proc means with no out=).
            // out= may sit on the header (proc sort out=) OR in a body statement
            // (proc means; output out=x; / proc freq; tables a / out=y;), so fall
            // back to scanning the full step text when the header has none.
            const header = defCapture.node.namedChild(0);
            const headerText = header?.type === 'proc_step_header' ? header.text : defCapture.node.text;
            const outRe = /\bout\s*=\s*([A-Za-z_][\w.]*)/i;
            const outMatch = headerText.match(outRe) ?? defCapture.node.text.match(outRe);
            if (!outMatch) continue;
            name = outMatch[1];
          }
          // Drop side-effect-only sentinels (_null_/_data_/_last_) and unexpanded
          // macro-var names (&ds) — neither denotes a stable dataset identity.
          if (/^_(null|data|last)_$/i.test(name) || name.includes('&')) continue;
        }

        const defNode = defCapture.node;
        const lineStart = defNode.startPosition.row + 1;
        const lineEnd = defNode.endPosition.row + 1;
        const startByte = defNode.startIndex;
        const endByte = defNode.endIndex;

        // Containment: file CONTAINS or class CONTAINS.
        // For Go methods the receiver type IS the container — methods are defined
        // outside the struct body so findEnclosing() always returns null for them.
        // The receiver.type capture (emitted by the Go method queries) overrides this.
        const enclosing = findEnclosing(classRanges, lineStart, name);
        const receiverCapture = match.captures.find((c: any) => c.name === 'receiver.type');
        // heritageClassCapture is set by the Go interface method query, where @heritage.class
        // captures the interface name and serves as the container (like receiver.type for structs).
        const heritageClassCapture = match.captures.find((c: any) => c.name === 'heritage.class');
        const effectiveContainer = (receiverCapture && kind === 'method')
          ? receiverCapture.node.text
          : (heritageClassCapture && kind === 'method')
          ? heritageClassCapture.node.text
          : (enclosing ?? undefined);

        entities.push({
          name,
          kind,
          lineStart,
          lineEnd,
          language,
          container: effectiveContainer,
          packageScope: goPackage ?? (
            language === SupportedLanguages.PHP
              ? phpNamespaceForNode(defNode, phpNamespaces.spans)
              : undefined
          ),
        });

        pendingChunks.push({
          name,
          chunkKind: kind,
          lineStart,
          lineEnd,
          startByte,
          endByte,
          language,
          container: enclosing ?? undefined,
        });

        if (kind === 'class' || kind === 'interface' || kind === 'trait') {
          classRanges.push({ name, start: lineStart, end: lineEnd });
        }

        if (effectiveContainer) {
          relationships.push({ srcName: effectiveContainer, dstName: name, predicate: 'CONTAINS' });
        } else {
          relationships.push({ srcName: fileName, dstName: name, predicate: 'CONTAINS' });
        }
        continue;
      }

      // Heritage: EXTENDS
      const heritageClass = match.captures.find((c: any) =>
        c.name === 'heritage.class'
      );
      const heritageExtends = match.captures.find((c: any) =>
        c.name === 'heritage.extends' || c.name === 'heritage.trait'
      );
      if (heritageClass && heritageExtends) {
        recordJsTsImportUse(
          'EXTENDS',
          heritageClass.node.text,
          heritageExtends.node.text,
          heritageExtends.node,
          heritageExtends.node.text,
        );
        relationships.push({
          srcName: heritageClass.node.text,
          dstName: heritageExtends.node.text,
          predicate: 'EXTENDS',
        });
        continue;
      }

      // Heritage: IMPLEMENTS (separate edge type, use EXTENDS for simplicity)
      const heritageImpl = match.captures.find((c: any) =>
        c.name === 'heritage.implements'
      );
      if (heritageClass && heritageImpl) {
        recordJsTsImportUse(
          'EXTENDS',
          heritageClass.node.text,
          heritageImpl.node.text,
          heritageImpl.node,
          heritageImpl.node.text,
          'type',
        );
        relationships.push({
          srcName: heritageClass.node.text,
          dstName: heritageImpl.node.text,
          predicate: 'EXTENDS',
        });
        continue;
      }

      // Python typed parameters: build paramTypeMap for qualifier substitution in the second pass.
      // Maps function name → (param name → declared type) so that e.g. `query: Query` lets us
      // rewrite `query.filter(...)` → `Query.filter` when building effectiveCallee.
      if (language === SupportedLanguages.Python) {
        const typedParamScope = match.captures.find((c: any) => c.name === '_typed_param_scope');
        const typedParamName = match.captures.find((c: any) => c.name === '_typed_param_name');
        const typedParamType = match.captures.find((c: any) => c.name === '_typed_param_type');
        if (typedParamScope && typedParamName && typedParamType) {
          const funcName = typedParamScope.node.childForFieldName?.('name')?.text as string | undefined;
          if (funcName) {
            if (!paramTypeMap.has(funcName)) paramTypeMap.set(funcName, new Map());
            paramTypeMap.get(funcName)!.set(typedParamName.node.text, typedParamType.node.text);
          }
          continue;
        }

        // Assignment tracking: x = SomeClass() or x = Model.objects.method()
        const assignScope = match.captures.find((c: any) => c.name === '_assign_scope');
        const assignLhs = match.captures.find((c: any) => c.name === '_assign_lhs');
        const assignRhsType = match.captures.find((c: any) => c.name === '_assign_rhs_type');
        if (assignScope && assignLhs && assignRhsType) {
          // Only track PascalCase RHS names (constructors by convention).
          // Lowercase function calls like `select(...)` or `create_engine(...)` are skipped
          // to avoid cross-module false edges (e.g. orm.query → select.where in SQLAlchemy).
          const rhsName = assignRhsType.node.text;
          if (/^[A-Z]/.test(rhsName)) {
            const funcName = assignScope.node.childForFieldName?.('name')?.text as string | undefined;
            if (funcName) {
              if (!assignTypeMap.has(funcName)) assignTypeMap.set(funcName, new Map());
              assignTypeMap.get(funcName)!.set(assignLhs.node.text, rhsName);
            }
          }
          continue;
        }
      }

      // PHP typed parameters: map the receiver variable to its declared class or
      // interface so member calls can target Class.method instead of a bare method.
      if (language === SupportedLanguages.PHP) {
        const typedParamScope = match.captures.find((c: any) => c.name === '_typed_param_scope');
        const typedParamName = match.captures.find((c: any) => c.name === '_typed_param_name');
        const typedParamType = match.captures.find((c: any) => c.name === '_typed_param_type');
        if (typedParamScope && typedParamName && typedParamType) {
          const line = typedParamScope.node.startPosition.row + 1;
          const methodName = typedParamScope.node.childForFieldName?.('name')?.text as string | undefined;
          const className = findEnclosing(classRanges, line, '');
          const scope = methodName ? (className ? `${className}.${methodName}` : methodName) : null;
          if (scope) {
            if (!paramTypeMap.has(scope)) paramTypeMap.set(scope, new Map());
            paramTypeMap.get(scope)!.set(typedParamName.node.text, typedParamType.node.text);
          }
          continue;
        }
      }

      // Go typed parameters: build paramTypeMap so method calls on
      // parameters (incl. receivers) resolve to the parameter's declared
      // type. e.g. `func (s *Scheme) F(opts *Options) { opts.Run() }`
      // records s → Scheme, opts → Options so `opts.Run()` becomes
      // `Options.Run` instead of bare `Run` (which is ambiguous across
      // 100+ same-named methods in a large monorepo).
      //
      // For method_declarations, the paramTypeMap key MUST include the
      // receiver type (i.e. `Container.method`) because that's what
      // findEnclosingDefinition returns at call-resolution time. Without
      // this, lookups for callers inside methods miss.
      if (language === SupportedLanguages.Go) {
        const goParamScope = match.captures.find((c: any) => c.name === '_go_param_scope');
        const goParamName = match.captures.find((c: any) => c.name === '_go_param_name');
        const goParamType = match.captures.find((c: any) => c.name === '_go_param_type');
        if (goParamScope && goParamName && goParamType) {
          const scopeNode = goParamScope.node;
          const baseName = scopeNode.childForFieldName?.('name')?.text as string | undefined;
          if (baseName) {
            let key = baseName;
            if (scopeNode.type === 'method_declaration') {
              const recvList = scopeNode.childForFieldName('receiver');
              const recvDecl = recvList?.firstNamedChild;
              const recvType = recvDecl?.childForFieldName('type');
              let container: string | undefined;
              if (recvType?.type === 'type_identifier') {
                container = recvType.text;
              } else if (recvType?.type === 'pointer_type') {
                const inner = recvType.firstNamedChild;
                if (inner?.type === 'type_identifier') container = inner.text;
              }
              if (container) key = `${container}.${baseName}`;
            }
            if (!paramTypeMap.has(key)) paramTypeMap.set(key, new Map());
            paramTypeMap.get(key)!.set(goParamName.node.text, goParamType.node.text);
          }
          continue;
        }
      }

      // Typed declarations: capture local vars, parameters, and fields so that
      // member calls like current->Get(...) can be rewritten to Version.Get.
      if (
        language === SupportedLanguages.C ||
        language === SupportedLanguages.CPlusPlus ||
        language === SupportedLanguages.PHP
      ) {
        const typedVarScope = match.captures.find((c: any) => c.name === '_typed_var_scope');
        const typedVarName = match.captures.find((c: any) => c.name === '_typed_var_name');
        const typedVarType = match.captures.find((c: any) => c.name === '_typed_var_type');
        if (typedVarScope && typedVarName && typedVarType) {
          const line = typedVarScope.node.startPosition.row + 1;
          const scope = language === SupportedLanguages.PHP
            ? findEnclosing(classRanges, line, '') ?? fileName
            : findEnclosingDefinition(entities, line)
              ?? findEnclosing(classRanges, line, '')
              ?? fileName;
          if (!declaredTypeMap.has(scope)) declaredTypeMap.set(scope, new Map());
          declaredTypeMap.get(scope)!.set(typedVarName.node.text, typedVarType.node.text);
          continue;
        }
      }
    }

    const receiverFacts = [SupportedLanguages.Scala, SupportedLanguages.TypeScript, SupportedLanguages.Go, SupportedLanguages.Java].includes(language)
      ? collectReceiverFacts(tree.rootNode, language, checkBudget) : undefined;

    // --- Second pass: calls and imports ---
    for (const match of pass2Matches) {
      checkBudget();
      // Full import statement captures (Scala: reconstructs dotted package paths)
      const importStmt = match.captures.find((c: any) => c.name === 'import.stmt');
      if (importStmt) {
        const raw = importStmt.node.text.replace(/^import\s+/, '').trim();
        const line = importStmt.node.startPosition.row + 1;
        if (raw.endsWith('._')) {
          // Wildcard: "ix.memory.model._" → package path "ix.memory.model"
          const pkgPath = raw.slice(0, -2);
          entities.push({ name: pkgPath, kind: 'module', lineStart: line, lineEnd: line, language });
          relationships.push({ srcName: fileName, dstName: pkgPath, predicate: 'IMPORTS' });
        } else {
          const braceIdx = raw.lastIndexOf('.{');
          if (braceIdx !== -1) {
            // Selective: "ix.memory.model.{NodeKind, GraphNode}"
            const prefix = raw.slice(0, braceIdx);
            const names = raw.slice(braceIdx + 2, -1).split(',').map((s: string) => s.trim()).filter(Boolean);
            for (const name of names) {
              const dstName = `${prefix}.${name}`;
              entities.push({ name: dstName, kind: 'module', lineStart: line, lineEnd: line, language });
              relationships.push({ srcName: fileName, dstName, predicate: 'IMPORTS' });
            }
          } else {
            // Simple: "ix.memory.model.NodeKind"
            entities.push({ name: raw, kind: 'module', lineStart: line, lineEnd: line, language });
            relationships.push({ srcName: fileName, dstName: raw, predicate: 'IMPORTS' });
          }
        }
        continue;
      }

      // PHP grouped use: `use Vendor\Package\{A, B};` (also `use function` /
      // `use const`). Each member is its own namespace_use_clause under the
      // group; the shared prefix arrives via @import.prefix. The clause's FIRST
      // name child is the imported symbol (a second one is an `as` alias and
      // must never become an import), so rebuild the FQCN from prefix + first
      // name, matching the single-clause form's modName/importRaw shape.
      const phpGroupPrefix = match.captures.find((c: any) => c.name === 'import.prefix')?.node.text;
      const phpGroupClauses = match.captures.filter((c: any) => c.name === 'import.clause');
      if (language === SupportedLanguages.PHP && phpGroupClauses.length > 0) {
        for (const clause of phpGroupClauses) {
          const firstName = clause.node.namedChildren.find((c: any) => c.type === 'name');
          if (!firstName) continue;
          const fqcn = phpGroupPrefix ? `${phpGroupPrefix}\\${firstName.text}` : firstName.text;
          const modName = normalizeCapturedImport(fqcn, language);
          const importRaw = unwrapImportSpecifier(fqcn);
          entities.push({ name: modName, kind: 'module', lineStart: firstName.startPosition.row + 1, lineEnd: firstName.startPosition.row + 1, language });
          relationships.push({ srcName: fileName, dstName: modName, predicate: 'IMPORTS', importRaw });
        }
        continue;
      }

      // Import captures (JS/TS/Python path-based)
      const importSource = match.captures.find((c: any) => c.name === 'import.source');
      if (importSource) {
        // JS/TS: pull per-specifier bindings off the whole import_statement node
        // (@import). Additive — leaves the IMPORTS/CALLS relationships untouched.
        if (isJsTs) {
          const stmtNode = match.captures.find((c: any) => c.name === 'import')?.node;
          if (stmtNode) {
            const rawSpec = unwrapImportSpecifier(importSource.node.text);
            for (const b of extractJsImportBindings(stmtNode, rawSpec)) importBindings.push(b);
          }
        }
        // Grouped alias `alias MyApp.{User, Repo}`: each member alias is captured bare
        // ("User"); the prefix alias ("MyApp") comes through @import.prefix so we can
        // rebuild the full module name "MyApp.User", matching the single-alias form.
        const importPrefix = match.captures.find((c: any) => c.name === 'import.prefix')?.node.text;
        let modName = normalizeCapturedImport(importSource.node.text, language);
        if (importPrefix) modName = `${importPrefix}.${modName}`;
        const importAlias = match.captures.find((c: any) => c.name === 'import.alias')?.node.text;
        if (importAlias && modName && importAlias !== '.' && importAlias !== '_') {
          importAliases[importAlias] = modName;
        }
        // Elixir: `alias MyApp.Repo` (and grouped `alias MyApp.{Repo, ...}`) implicitly
        // bind the last segment as a short name. No @import.alias capture exists, so
        // derive it here — this is what lets Tier-1b resolution translate e.g.
        // 'Repo.insert' → 'MyApp.Repo.insert', including through grouped aliases.
        if (!importAlias && language === SupportedLanguages.Elixir && modName.includes('.')) {
          const directive = match.captures.find((c: any) =>
            c.name === '_directive' || c.name === '_alias_group')?.node.text;
          if (directive === 'alias') {
            importAliases[modName.split('.').pop()!] = modName;
          }
        }
        if (modName.length > 0 && modName !== '*') {
          // Preserve the raw specifier (./core vs @nestjs/core) for the multi-repo
          // dependency gate; modName remains the flattened stem used everywhere else.
          const importRaw = unwrapImportSpecifier(importSource.node.text);
          const importNode = match.captures.find((c: any) => c.name === 'import')?.node;
          const phpImportText = language === SupportedLanguages.PHP ? importNode?.text ?? '' : '';
          const importKind = language === SupportedLanguages.PHP
            ? /^use\s+function\b/i.test(phpImportText)
              ? 'function' as const
              : /^use\s+const\b/i.test(phpImportText)
                ? 'const' as const
                : undefined
            : undefined;
          // Alias detection is per *clause*, not per statement. `use A\B, C\D as E;`
          // is one declaration with two clauses, so testing the statement text
          // flagged the un-aliased clause too and silently disabled FQCN
          // resolution for it. Reading the node also drops an unanchored
          // /\s+as\s+/ over repo-controlled text, which backtracks quadratically.
          const phpUseClause = importSource.node.parent;
          const phpImportAliased = language === SupportedLanguages.PHP
            && phpUseClause?.type === 'namespace_use_clause'
            && phpUseClause.namedChildCount > 1;
          entities.push({ name: modName, kind: 'module', lineStart: importSource.node.startPosition.row + 1, lineEnd: importSource.node.startPosition.row + 1, language });
          relationships.push({
            srcName: fileName,
            dstName: modName,
            predicate: 'IMPORTS',
            importRaw,
            ...(importKind ? { importKind } : {}),
            ...(phpImportAliased ? { importAliased: true } : {}),
          });
        }
        continue;
      }

      // Import name captures (e.g. from . import utils — the symbol name, not the module path)
      const importName = match.captures.find((c: any) => c.name === 'import.name');
      if (importName) {
        const name = importName.node.text;
        if (name && name !== '*' && name.length > 1) {
          const rawModule = match.captures.find((c: any) => c.name === 'import.module')?.node.text;
          if (language === SupportedLanguages.Python && rawModule) {
            const local = match.captures.find((c: any) => c.name === 'import.local')?.node.text ?? name;
            const dotsOnly = /^\.+$/.test(rawModule);
            const pkg = dotsOnly ? `${rawModule}${name}` : rawModule;
            importBindings.push({ pkg, local, imported: name });
            if (dotsOnly) {
              entities.push({ name, kind: 'module', lineStart: importName.node.startPosition.row + 1, lineEnd: importName.node.startPosition.row + 1, language });
              relationships.push({ srcName: fileName, dstName: name, predicate: 'IMPORTS', importRaw: pkg });
              continue;
            }
          }
          entities.push({ name, kind: 'module', lineStart: importName.node.startPosition.row + 1, lineEnd: importName.node.startPosition.row + 1, language });
          relationships.push({ srcName: fileName, dstName: name, predicate: 'IMPORTS' });
        }
        continue;
      }

      // Call captures
      const callName = match.captures.find((c: any) => c.name === 'call.name');
      if (callName) {
        const callee = callName.node.text;
        // JavaScript `require("./x")` is already an IMPORTS edge via its own query.
        if (isJsTs && !(language === SupportedLanguages.JavaScript && callee === 'require')) {
          const helperImport = jsTsHelperImportSpecifier(match.captures.find((c: any) => c.name === 'call')?.node);
          if (helperImport && !jsTsHelperImports.has(helperImport)) {
            jsTsHelperImports.add(helperImport);
            relationships.push({
              srcName: fileName,
              dstName: normalizeCapturedImport(helperImport, language),
              predicate: 'IMPORTS',
              importRaw: helperImport,
              importVia: 'helper',
            });
          }
        }
        if (!callee || callee.length <= 1) continue;
        const phpCallKind = language === SupportedLanguages.PHP
          ? callName.node.parent?.type === 'object_creation_expression'
            ? 'constructor' as const
            : callName.node.parent?.type === 'member_call_expression' ||
                callName.node.parent?.type === 'nullsafe_member_call_expression'
              ? 'member' as const
              : callName.node.parent?.type === 'scoped_call_expression'
                ? 'static' as const
                : 'function' as const
          : undefined;

        // If a _qualifier capture is present (field_expression / stable_identifier
        // patterns like NodeKind.Decision, or Python attribute calls like
        // Session.execute), emit the fully qualified name so that resolution can use
        // the qualifier to break ties between same-named symbols in different files.
        // BUILTINS filtering is skipped for attribute calls: method names like
        // `filter` or `map` are Python builtins when called bare, but are valid
        // user-defined method calls when invoked as `query.filter(...)`.
        const qualifierCapture = match.captures.find((c: any) => c.name === '_qualifier');
        // R package-qualified calls (pkg::func) carry a distinct @_namespace
        // capture so the dstName can keep the :: separator (vs a plain dotted name).
        const namespaceCapture = match.captures.find((c: any) => c.name === '_namespace');
        // A member call whose receiver has a lexically inferred type or factory
        // also gets a typed relationship (below). The call's own relationship is
        // unchanged, so inference only ever adds edges.
        const callCapture = receiverFacts ? match.captures.find((c: any) => c.name === 'call') : undefined;
        const typedReceiver = callCapture ? callReceiver(callName.node, receiverFacts!, callCapture.node) : undefined;
        // A builtin-named call is still dropped; only its typed relationship stays.
        const builtinCall = builtinsForLanguage(language).has(callee) && !qualifierCapture && !namespaceCapture;
        if (builtinCall && !typedReceiver) continue;

        // For Python: skip calls that are decorator applications.
        // When a method is decorated (e.g. @util.deprecated(...)), the call sits at the
        // class-body line before the def, so findEnclosingDefinition misses the method and
        // the caller falls back to the enclosing class — producing false edges like
        // Table → deprecated.  Decorator application is not an architectural CALLS edge.
        if (language === SupportedLanguages.Python) {
          let isDecoratorCall = false;
          let anc = callName.node.parent;
          while (anc) {
            if (anc.type === 'decorator') { isDecoratorCall = true; break; }
            if (anc.type === 'module' || anc.type === 'function_definition' || anc.type === 'class_definition') break;
            anc = anc.parent;
          }
          if (isDecoratorCall) continue;
        }

        // Elixir: skip the function-name node inside def/defp/defmacro(p) argument lists.
        // `def foo(args)` parses as call{target:def, args:[call{target:foo, args:[...]}]}.
        // callName.node is the identifier `foo`; its parent is the inner call node,
        // whose parent is `arguments`, whose parent is the outer def* call.
        // Without this, the inner call{target:foo} would emit a `foo CALLS foo` self-edge.
        if (language === SupportedLanguages.Elixir) {
          const innerCall = callName.node.parent;
          let argsNode = innerCall?.parent;
          if (argsNode?.type === 'binary_operator') {
            argsNode = argsNode.parent;           // walk up through when-guard
          }
          if (argsNode?.type === 'arguments') {
            const defCall = argsNode.parent;
            if (defCall?.type === 'call') {
              const defTarget = defCall.childForFieldName?.('target');
              if (defTarget && /^(def|defp|defmacro|defmacrop)$/.test(defTarget.text)) {
                continue;
              }
            }
          }
        }

        // Find enclosing function/method for the call; fall back to enclosing class
        // (e.g. calls in val/lazy val body at class level) before falling back to file.
        const callLine = callName.node.startPosition.row + 1;
        const caller = findEnclosingDefinition(entities, callLine)
          ?? findEnclosing(classRanges, callLine, '')
          ?? fileName;

        const scope = caller;
        if (!seenCalls.has(scope)) seenCalls.set(scope, new Set());
        const seen = seenCalls.get(scope)!;

        const effectiveCallee = (() => {
          // R package-qualified call (pkg::func / pkg:::func): keep the :: so the
          // patch builder can externalize it under external://<pkg> and split it
          // correctly even for multi-dot members (utils::write.csv).
          if (namespaceCapture) {
            return `${namespaceCapture.node.text}::${callee}`;
          }
          if (!qualifierCapture) {
            // Go: bare-function calls (call.name is an `identifier` — i.e.
            // pattern 1: `Foo()`) resolve to the caller's package, so prepend
            // the package name for deterministic resolution. Method-shaped
            // calls captured by the catch-all (call.name is a
            // `field_identifier` — i.e. `recv.X.Method()`) dispatch on the
            // receiver's type, NOT the caller's package, so leave them bare.
            if (
              language === SupportedLanguages.Go &&
              goPackage &&
              callName.node.type === 'identifier'
            ) {
              return `${goPackage}.${callee}`;
            }
            // Python: if the callee is a local alias for a class, substitute the class name.
            // e.g. engineclass = base.Engine; engineclass(pool, ...) → Engine(pool, ...)
            if (language === SupportedLanguages.Python) {
              const funcName = findEnclosingDefinition(entities, callLine);
              if (funcName) {
                const typeForAssign = assignTypeMap.get(funcName)?.get(callee);
                if (typeForAssign) return typeForAssign;
              }
            }
            return callee;
          }
          let qualifier = qualifierCapture.node.text;
          let phpPropertyOnThis = false;
          let phpReceiverIsSupported = true;
          if (language === SupportedLanguages.PHP) {
            const receiverNode = qualifierCapture.node;
            if (receiverNode.type === 'variable_name') {
              qualifier = receiverNode.firstNamedChild?.text ?? receiverNode.text.replace(/^\$/, '');
            } else if (receiverNode.type === 'member_access_expression') {
              qualifier = receiverNode.childForFieldName?.('name')?.text ?? receiverNode.text;
              const objectNode = receiverNode.childForFieldName?.('object');
              const objectName = objectNode?.type === 'variable_name'
                ? objectNode.firstNamedChild?.text ?? objectNode.text.replace(/^\$/, '')
                : null;
              phpPropertyOnThis = objectName === 'this';
            } else {
              phpReceiverIsSupported = false;
            }
          }
          if (!phpReceiverIsSupported) return callee;
          // Python: 'self'/'cls' always refers to the enclosing class — substitute it
          // so the edge reads 'Query.filter' instead of 'self.filter', enabling
          // same-file resolution without type inference.
          if (language === SupportedLanguages.Python && (qualifier === 'self' || qualifier === 'cls')) {
            const enclosingClass = findEnclosing(classRanges, callLine, '');
            if (enclosingClass) qualifier = enclosingClass;
          } else if (qualifier === 'this') {
            // JS/TS and PHP: 'this' inside a class method refers to the enclosing class.
            // Substitute so e.g. `this.save()` → `Document.save` instead of `this.save`.
            const enclosingClass = findEnclosing(classRanges, callLine, '');
            if (enclosingClass) qualifier = enclosingClass;
          } else if (language === SupportedLanguages.Python) {
            // Typed-parameter substitution: if the qualifier is a param with a declared type,
            // use the type name so e.g. `query.filter(...)` → `Query.filter`.
            // Also check assignTypeMap for variables assigned from constructor/ORM calls.
            const funcName = findEnclosingDefinition(entities, callLine);
            if (funcName) {
              const typeForParam = paramTypeMap.get(funcName)?.get(qualifier);
              const typeForAssign = assignTypeMap.get(funcName)?.get(qualifier);
              if (typeForParam) qualifier = typeForParam;
              else if (typeForAssign) qualifier = typeForAssign;
            }
          } else if (language === SupportedLanguages.Go) {
            // Go: if the qualifier matches a tracked parameter/receiver in the
            // enclosing function, substitute with the parameter's declared
            // type. e.g. `opts.Run()` inside `func F(opts *Options)` → use
            // qualifier "Options" so dstName is "Options.Run", which
            // edge-resolver indexes via the container.name fallback key.
            const funcName = findEnclosingDefinition(entities, callLine);
            if (funcName) {
              const typeForParam = paramTypeMap.get(funcName)?.get(qualifier);
              if (typeForParam) qualifier = typeForParam;
            }
          } else if (language === SupportedLanguages.PHP) {
            const funcName = findEnclosingDefinition(entities, callLine);
            const className = findEnclosing(classRanges, callLine, '');
            const typeForReceiver = phpPropertyOnThis
              ? (className ? declaredTypeMap.get(className)?.get(qualifier) : undefined)
              : (funcName ? paramTypeMap.get(funcName)?.get(qualifier) : undefined);
            if (typeForReceiver) qualifier = typeForReceiver;
            else return callee;
          } else if (language === SupportedLanguages.C || language === SupportedLanguages.CPlusPlus) {
            const funcName = findEnclosingDefinition(entities, callLine) ?? fileName;
            const className = findEnclosing(classRanges, callLine, '')
              ?? (funcName.includes('.') ? funcName.slice(0, funcName.lastIndexOf('.')) : undefined);
            const typeForDecl =
              declaredTypeMap.get(funcName)?.get(qualifier)
              ?? (className ? declaredTypeMap.get(className)?.get(qualifier) : undefined)
              ?? declaredTypeMap.get(fileName)?.get(qualifier);
            if (typeForDecl) qualifier = typeForDecl;
          }
          return `${qualifier}.${callee}`;
        })();

        if (!builtinCall && !qualifierCapture && !namespaceCapture && effectiveCallee === callee) {
          recordJsTsImportUse('CALLS', caller, effectiveCallee, callName.node, callee);
        }

        const callKey = phpCallKind ? `${phpCallKind}:${effectiveCallee}` : effectiveCallee;
        const bareKey = `${scope}\x00${callKey}`;
        if (!builtinCall && tracksBareCalls) {
          let isBare: boolean;
          if (isJsTs) {
            // `foo()` / `new Foo()`: the JS/TS queries capture the callee as an
            // `identifier` only there; `obj.foo()` captures a property_identifier.
            // (Read from the node's own type: `.parent` walks down from the root
            // in these bindings, which is quadratic in a long call chain.)
            isBare = !qualifierCapture && callName.node.type === 'identifier';
          } else if (language === SupportedLanguages.PHP) {
            // `foo()` is a function_call_expression; a method is only reachable
            // through `$obj->`, `?->`, `Class::` or `new`.
            isBare = phpCallKind === 'function';
          } else if (language === SupportedLanguages.Python) {
            // `foo()` / `f(key=foo)`: an identifier that is not the attribute of
            // `obj.foo()`. A method needs `self.` / `cls.` / `obj.`. A callee
            // rewritten through a local alias (`cls = mod.Engine; cls()`) is not
            // what the call site spelled, so it is left unmarked.
            isBare = !qualifierCapture && effectiveCallee === callee &&
              callName.node.type === 'identifier' && callName.node.parent?.type !== 'attribute';
          } else {
            // Rust: `foo()` / `foo::<T>()`. A method or associated function needs
            // `self.` / `x.` / `Type::`.
            const parentType = callName.node.parent?.type;
            isBare = !qualifierCapture && callName.node.type === 'identifier' &&
              (parentType === 'call_expression' || parentType === 'generic_function');
          }
          jsTsCallBareOnly.set(bareKey, (jsTsCallBareOnly.get(bareKey) ?? true) && isBare);
        }
        if (language === SupportedLanguages.Java && !builtinCall) {
          javaTypedSites.set(bareKey, (javaTypedSites.get(bareKey) ?? true) && typedReceiver?.type !== undefined);
        }
        if (builtinCall) {
          // Only the typed relationship below.
        } else if (!seen.has(callKey)) {
          seen.add(callKey);
          const rel: ParsedRelationship = {
            srcName: caller,
            dstName: effectiveCallee,
            predicate: 'CALLS',
            ...(phpCallKind ? { phpCallKind } : {}),
          };
          relationships.push(rel);
          callRelationships.set(bareKey, rel);
          if (tracksBareCalls) jsTsCallRelationship.set(bareKey, rel);
        } else {
          // The call also names what an earlier typed relationship named: it is
          // a call in its own right, so it keeps its name-based fallback.
          delete callRelationships.get(bareKey)?.receiverOnly;
        }
        if (typedReceiver) {
          // `Type.member`, `receiver.member` for a factory-typed receiver, or
          // Java `Type.getB().member` for a chain.
          const chain = typedReceiver.chain?.length ? `${typedReceiver.chain.map(m => `${m}()`).join('.')}.` : '';
          const typedName = `${typedReceiver.type ?? typedReceiver.receiver}.${chain}${callee}`;
          const typedKey = `${scope}\x00${typedName}`;
          const receiver = typedReceiver.type
            ? { receiverType: typedReceiver.type, ...(chain ? { receiverChain: typedReceiver.chain } : {}) }
            : { receiverFactory: typedReceiver.factory! };
          const named = callRelationships.get(typedKey);
          if (named) {
            // Same name as the call's own relationship: try the type first, then
            // fall back to that name as before.
            if (!named.receiverType && !named.receiverFactory) Object.assign(named, receiver);
          } else if (!seen.has(typedName)) {
            seen.add(typedName);
            const rel: ParsedRelationship = { srcName: caller, dstName: typedName, predicate: 'CALLS', ...receiver, receiverOnly: true };
            relationships.push(rel);
            callRelationships.set(typedKey, rel);
          }
        }
        continue;
      }

      // Type reference captures
      const refType = match.captures.find((c: any) => c.name === 'reference.type');
      if (refType) {
        const typeName = refType.node.text;
        if (!typeName || TYPE_BUILTINS.has(typeName) || typeName.length <= 1) continue;

        // Prefer the enclosing function/method so parameter and return-type references
        // point back to the actual caller. Fall back to class, then file.
        const refLine = refType.node.startPosition.row + 1;
        const src = findEnclosingDefinition(entities, refLine)
          ?? findEnclosing(classRanges, refLine, typeName)
          ?? fileName;

        recordJsTsImportUse('REFERENCES', src, typeName, refType.node, typeName, 'type');

        if (!seenRefs.has(src)) seenRefs.set(src, new Set());
        const seen = seenRefs.get(src)!;
        if (!seen.has(typeName)) {
          seen.add(typeName);
          relationships.push({ srcName: src, dstName: typeName, predicate: 'REFERENCES' });
        }
        continue;
      }
    }

    for (const [bareKey, rel] of jsTsCallRelationship) {
      if (jsTsCallBareOnly.get(bareKey) === true) rel.bareCall = true;
    }
    const receiverTypedCalls = [...javaTypedSites].filter(([key, all]) => all && callRelationships.has(key))
      .map(([key]) => `${callRelationships.get(key)!.srcName}\0${callRelationships.get(key)!.dstName}`);

    // A single relationship can represent multiple same-name uses in one scope.
    // Mark it local-only only when every captured use is shadowed; if any use still
    // sees the import, the cross-file edge remains meaningful.
    for (const rel of relationships) {
      const key = `${rel.predicate}\x00${rel.srcName}\x00${rel.dstName}`;
      const hasUnshadowedUse = jsTsImportUseHasUnshadowed.get(key);
      if (hasUnshadowedUse === false) {
        rel.importBinding = false;
      } else if (
        hasUnshadowedUse === true &&
        entities.some(entity => entity.kind !== 'file' && entity.kind !== 'module' && entity.name === rel.dstName)
      ) {
        // Usually an unshadowed import needs no annotation. Preserve an explicit
        // true only when a same-file definition elsewhere would otherwise make
        // the resolver apply its backward-compatible file-wide shadow fallback.
        rel.importBinding = true;
      }
    }

    for (const pendingChunk of pendingChunks) {
      const chunkText = source.slice(pendingChunk.startByte, pendingChunk.endByte);
      const contentHash = crypto.createHash('sha256').update(chunkText).digest('hex').slice(0, 16);
      chunks.push({
        ...pendingChunk,
        contentHash,
      });
    }

    // Fallback: if no semantic chunks found, emit one file_body chunk covering the whole file
    if (chunks.length === 0) {
      const contentHash = crypto.createHash('sha256').update(source).digest('hex').slice(0, 16);
      chunks.push({
        name: null,
        chunkKind: 'file_body',
        lineStart: 1,
        lineEnd: sourceLineCount,
        startByte: 0,
        endByte: source.length,
        contentHash,
        language,
      });
    }

    // Elixir: a function/macro with multiple clauses (guards, pattern-matched heads,
    // or several arities) is emitted as one entity per clause; they collapse to a
    // single node keyed by (container, name). Merge them so the surviving node spans
    // the whole clause group (first clause start .. last clause end) instead of only
    // the first clause. (Per-arity identity, e.g. changeset/2 vs changeset/3, is a
    // larger follow-up: it needs call-arity capture to keep call resolution precise.)
    if (language === SupportedLanguages.Elixir) {
      const firstByKey = new Map<string, ParsedEntity>();
      const dropIdx: number[] = [];
      entities.forEach((e, i) => {
        if (e.kind !== 'function' && e.kind !== 'macro') return;
        const key = `${e.kind} ${e.container ?? ''} ${e.name}`;
        const keep = firstByKey.get(key);
        if (keep) {
          keep.lineStart = Math.min(keep.lineStart, e.lineStart);
          keep.lineEnd = Math.max(keep.lineEnd, e.lineEnd);
          dropIdx.push(i);
        } else {
          firstByKey.set(key, e);
        }
      });
      for (let j = dropIdx.length - 1; j >= 0; j--) entities.splice(dropIdx[j], 1);
    }

    const exportPublicNames = isJsTs ? extractJsExportPublicNames(tree.rootNode) : [];

    return {
      filePath,
      language,
      entities,
      chunks,
      relationships,
      importAliases: Object.keys(importAliases).length > 0 ? importAliases : undefined,
      importBindings: importBindings.length > 0 ? importBindings : undefined,
      exportPublicNames: exportPublicNames.length > 0 ? exportPublicNames : undefined,
      // Spread rather than `: undefined` so the key is absent for every non-PHP
      // file. A key that is present-but-undefined still serializes, which would
      // rewrite every checked-in parseFile snapshot for no behavioural reason.
      ...(phpNamespaces.blocks > 0 ? { phpNamespaceBlocks: phpNamespaces.blocks } : {}),
      // Absent unless true, for the same reason.
      ...(tree.rootNode.hasError ? { hasParseErrors: true as const } : {}),
      ...(receiverFacts?.factories.length ? { receiverFactories: receiverFacts.factories } : {}),
      ...(receiverFacts?.heritage.length ? { receiverHeritage: receiverFacts.heritage } : {}),
      ...(receiverFacts?.package ? { receiverPackage: receiverFacts.package } : {}),
      ...(receiverTypedCalls.length ? { receiverTypedCalls } : {}),
      fileRole: classifyFileRole(filePath, source),
    };
  } catch (e) {
    if (process.env.IX_PARSE_DEBUG === '1') console.error('parseFile threw:', e);
    opts.onFailure?.({ reason: e instanceof ParseBudgetExceeded ? 'timeout' : 'error', message: String(e) });
    return null;
  }
}

// ---------------------------------------------------------------------------
// Cross-file CALLS resolution
// ---------------------------------------------------------------------------

export interface ResolvedCallEdge {
  callerFilePath: string;
  callerName: string;           // the caller entity (function/method/file)
  calleeFilePath: string;       // the file where the callee is actually defined
  calleeName: string;           // plain name as it appears in the CALLS relationship
  calleeQualifiedKey: string;   // qualified key used for nodeId in the callee file
                                // e.g. 'PaymentService.charge' for a class method,
                                // or plain 'processPayment' for a module-level function
  confidence: number;           // 0.9 import-scoped | 0.5 global
}

/** Generalised form of ResolvedCallEdge that covers any cross-file edge predicate. */
export interface ResolvedEdge {
  srcFilePath: string;
  srcName: string;
  dstFilePath: string;          // file where the destination symbol is actually defined
  dstName: string;              // plain name as it appears in the relationship
  dstQualifiedKey: string;      // qualified key used for nodeId in the defining file
  predicate: string;            // "CALLS" | "EXTENDS"
  confidence: number;           // 0.9 import-scoped | 0.8 transitive | 0.5 global
  /** Which resolution tier produced the edge; written on the edge with `confidence`. */
  tier?: ResolutionTier;
  phpCallKind?: ParsedRelationship['phpCallKind'];
}

/**
 * `type`: a lexical receiver type resolved an exact member (confidence 0.95).
 * `binding`: an explicit import binding names the target. `import`: the
 * target is in a file this one imports (or the import itself). `transitive`:
 * one re-export hop away. `qualifier`: a dotted name's qualifier picked the
 * file. `global`: the only definition of the name anywhere.
 */
export type ResolutionTier = 'type' | 'binding' | 'import' | 'transitive' | 'qualifier' | 'global';

// ---------------------------------------------------------------------------
// resolveCallEdges helpers
// ---------------------------------------------------------------------------

/** Build the qualified key for an entity (mirrors buildPatch's entityQKey logic). */
function qualifiedKey(e: ParsedEntity): string {
  return e.container ? `${e.container}.${e.name}` : e.name;
}

const PHP_TYPE_KINDS = new Set(['class', 'interface', 'trait', 'enum']);

function trimPhpNamespace(namespace: string | undefined): string {
  if (!namespace) return '';
  let start = 0;
  let end = namespace.length;
  while (start < end && namespace.charCodeAt(start) === 92) start++;
  while (end > start && namespace.charCodeAt(end - 1) === 92) end--;
  return namespace.slice(start, end);
}

function phpTypeFqcn(entity: ParsedEntity): string | undefined {
  if (entity.language !== SupportedLanguages.PHP || !PHP_TYPE_KINDS.has(entity.kind) || entity.container) {
    return undefined;
  }
  const namespace = trimPhpNamespace(entity.packageScope);
  return `${namespace ? `${namespace}\\` : ''}${entity.name}`.toLowerCase();
}

function ambiguousPhpTypeNames(entities: ParsedEntity[]): Set<string> {
  const counts = new Map<string, number>();
  for (const entity of entities) {
    if (entity.language !== SupportedLanguages.PHP || !PHP_TYPE_KINDS.has(entity.kind) || entity.container) {
      continue;
    }
    const name = entity.name.toLowerCase();
    counts.set(name, (counts.get(name) ?? 0) + 1);
  }
  return new Set([...counts].filter(([, count]) => count > 1).map(([name]) => name));
}

/**
 * What resolution needs from a file it resolves TO (see `FileSummary`). The
 * same rules `resolveEdges` applies to a batch file, so a file looks the same
 * to resolution whether it is in the batch or only in the index.
 */
export function summarizeParseResult(r: FileParseResult): FileSummary {
  const qkeys: Array<[string, string]> = [];
  for (const e of r.entities) {
    if (e.kind === 'file' || e.kind === 'module') continue;
    qkeys.push([e.name, qualifiedKey(e)]);
  }
  const exportPublicNames = r.exportPublicNames?.map((n): [string, string] => [n.public, n.local]);
  let phpTypes: Array<[string, string]> | undefined;
  if (r.language === SupportedLanguages.PHP) {
    const ambiguous = ambiguousPhpTypeNames(r.entities);
    phpTypes = [];
    for (const e of r.entities) {
      const fqcn = phpTypeFqcn(e);
      if (fqcn && !ambiguous.has(e.name.toLowerCase())) phpTypes.push([fqcn, e.name]);
    }
  }
  const imports: FileSummary['imports'] = [];
  const refs = new Set<string>();
  for (const rel of r.relationships) {
    if (rel.predicate === 'IMPORTS') {
      imports.push({
        dstName: rel.dstName,
        ...(typeof rel.importRaw === 'string' ? { importRaw: rel.importRaw } : {}),
        ...(rel.importVia ? { importVia: rel.importVia } : {}),
      });
    } else if (rel.predicate === 'CALLS' || rel.predicate === 'REFERENCES' || rel.predicate === 'EXTENDS') {
      refs.add(rel.dstName);
      if (rel.receiverType) refs.add(rel.receiverType);
      if (rel.receiverFactory) refs.add(rel.receiverFactory);
    }
  }
  const summary = {
    filePath: r.filePath,
    language: r.language,
    entityCount: r.entities.length,
    qkeys,
    ...(exportPublicNames ? { exportPublicNames } : {}),
    imports,
    ...(phpTypes ? { phpTypes } : {}),
    ...(r.receiverFactories ? { receiverFactories: r.receiverFactories } : {}),
    ...(r.receiverHeritage ? { receiverHeritage: r.receiverHeritage } : {}),
    ...(r.receiverPackage ? { receiverPackage: r.receiverPackage } : {}),
    ...(r.importAliases ? { importAliases: r.importAliases } : {}),
    refs: [...refs].sort(),
  };
  return { ...summary, sig: summarySignature(summary) };
}

/**
 * Given a file's qualified-key map and a plain callee name, return the single
 * unambiguous qualified key, or null if the name maps to 0 or >1 entities.
 * Callers must treat null as "do not emit" to avoid dangling nodeIds.
 */
function bestQKey(
  fileQKeys: Map<string, Map<string, string[]>>,
  filePath: string,
  plainName: string,
  preferredQKey?: string,
): string | null {
  const qks = [...new Set(fileQKeys.get(filePath)?.get(plainName) ?? [])];
  if (preferredQKey && qks.includes(preferredQKey)) return preferredQKey;
  return qks.length === 1 ? qks[0] : null;
}

function bestPhpQKey(
  fileQKeys: Map<string, Map<string, string[]>>,
  filePath: string,
  plainName: string,
  preferredQKey?: string,
): string | null {
  const qks = [...new Set(
    [...(fileQKeys.get(filePath) ?? [])]
      .filter(([name]) => name.toLowerCase() === plainName.toLowerCase())
      .flatMap(([, keys]) => keys),
  )];
  if (preferredQKey) {
    const preferred = qks.find(key => key.toLowerCase() === preferredQKey.toLowerCase());
    if (preferred) return preferred;
  }
  return qks.length === 1 ? qks[0] : null;
}

// ---------------------------------------------------------------------------
// Global resolution index — pre-scan for cross-batch edge resolution
// ---------------------------------------------------------------------------

export interface GlobalResolutionIndex {
  fileHasSymbol:    Map<string, Set<string>>;
  fileQKeys:        Map<string, Map<string, string[]>>;
  filePublicNames?: Map<string, Map<string, string>>;
  symbolToFiles:    Map<string, string[]>;
  stemToFiles:      Map<string, string[]>;
  dirToIndexFiles:  Map<string, string[]>;
  packageToFiles:   Map<string, string[]>;
  goPkgDirToFiles:  Map<string, string[]>;
  goPkgPathToFiles: Map<string, string[]>;
  phpFqcnToTypes?:  Map<string, Array<{ filePath: string; typeName: string }>>;
  /**
   * Per-file summaries, every language, when the caller supplied them. With
   * them `resolveEdges` sees every target file exactly as it would if the file
   * were in the batch, so the batching does not change the result.
   */
  summaries?:       Map<string, FileSummary>;
}

/** `name -> qualified keys`, in entity order: what `resolveEdges` and buildPatch key on. */
function qkeyMapOf(summary: FileSummary): Map<string, string[]> {
  const map = new Map<string, string[]>();
  for (const [name, qk] of summary.qkeys) {
    const list = map.get(name) ?? [];
    list.push(qk);
    map.set(name, list);
  }
  return map;
}

/**
 * Build a GlobalResolutionIndex from a list of file paths (and optional source
 * texts for entity extraction). Covers the entire repository so that each
 * streaming batch can resolve edges pointing to files outside the batch.
 */
export function buildGlobalResolutionIndex(
  filePaths: string[],
  sources?: Map<string, string>,
  // Parse results the caller already has. The parser-derived language blocks
  // below (PHP, JS/TS, R, SAS) call parseFile synchronously on the main thread,
  // which is fine for a handful of files and not fine for a whole repository's
  // worth of TypeScript. The CLI owns a worker pool; letting it parse in
  // parallel and hand the results in keeps the work off this thread entirely.
  // Absent an entry, each block falls back to parsing here, so callers that do
  // not have a pool (tests, library use) behave exactly as before.
  preParsed?: Map<string, FileParseResult>,
  // Summaries of any files, any language (see FileSummary). A summarized file's
  // symbols come from its summary, not from the per-language blocks below,
  // which then only serve callers that have no summaries.
  summaries?: Map<string, FileSummary>,
): GlobalResolutionIndex {
  const stemToFiles = new Map<string, string[]>();
  const dirToIndexFiles = new Map<string, string[]>();
  const packageToFiles = new Map<string, string[]>();
  const goPkgDirToFiles = new Map<string, string[]>();
  const goPkgPathToFiles = new Map<string, string[]>();
  const phpFqcnToTypes = new Map<string, Array<{ filePath: string; typeName: string }>>();

  // A summarized file is indexed by path too, so `resolveEdges` can rely on
  // the index's path maps holding every file it has a summary for.
  const indexPaths = summaries
    ? [...new Set([...filePaths, ...summaries.keys()])]
    : filePaths;
  for (const fp of indexPaths) {
    const ext = nodePath.extname(fp);
    const stem = nodePath.basename(fp, ext);

    // stemToFiles
    const stemList = stemToFiles.get(stem) ?? [];
    stemList.push(fp);
    stemToFiles.set(stem, stemList);

    // dirToIndexFiles
    if (stem === 'index') {
      const dirName = nodePath.basename(nodePath.dirname(fp));
      const dirList = dirToIndexFiles.get(dirName) ?? [];
      dirList.push(fp);
      dirToIndexFiles.set(dirName, dirList);
    }

    // packageToFiles (Scala/Java)
    if (ext === '.scala' || ext === '.java') {
      const dir = nodePath.dirname(fp);
      const parts = dir.split(/[/\\]/);
      const maxDepth = Math.min(8, parts.length);
      for (let i = parts.length - 1; i >= parts.length - maxDepth; i--) {
        const pkg = parts.slice(i).join('.');
        const list = packageToFiles.get(pkg) ?? [];
        list.push(fp);
        packageToFiles.set(pkg, list);
      }
    }

    // goPkgDirToFiles / goPkgPathToFiles (Go)
    if (ext === '.go') {
      const dirName = nodePath.basename(nodePath.dirname(fp));
      const goDirList = goPkgDirToFiles.get(dirName) ?? [];
      goDirList.push(fp);
      goPkgDirToFiles.set(dirName, goDirList);

      const parts = nodePath.dirname(fp).replace(/\\/g, '/').split('/').filter(Boolean);
      const maxDepth = Math.min(8, parts.length);
      for (let i = parts.length - 1; i >= parts.length - maxDepth; i--) {
        const pkgPath = parts.slice(i).join('/');
        const pkgList = goPkgPathToFiles.get(pkgPath) ?? [];
        pkgList.push(fp);
        goPkgPathToFiles.set(pkgPath, pkgList);
      }
    }
  }

  // Entity maps (built from sources if provided, via fast regex scan)
  const fileQKeys = new Map<string, Map<string, string[]>>();
  const filePublicNames = new Map<string, Map<string, string>>();
  const fileHasSymbol = new Map<string, Set<string>>();
  const symbolToFiles = new Map<string, string[]>();

  if (sources) {
    const pkgRe = /^package\s+(\w+)/m;
    const typeRe = /^type\s+([A-Z]\w*)\s+/gm;
    const funcRe = /^func\s+([A-Z]\w*)\s*[(\[]/gm;
    const methodRe = /^func\s+\([^)]+\)\s+([A-Z]\w*)\s*[(\[]/gm;

    for (const [fp, src] of sources) {
      if (nodePath.extname(fp) !== '.go') continue;

      const qkMap = new Map<string, string[]>();

      // Package name — critical for qualifier-assisted REFERENCES resolution
      const pkgMatch = pkgRe.exec(src);
      if (pkgMatch) {
        const name = pkgMatch[1];
        qkMap.set(name, [name]);
      }

      // Exported types (struct/interface/aliases/type defs)
      typeRe.lastIndex = 0;
      let m: RegExpExecArray | null;
      while ((m = typeRe.exec(src)) !== null) {
        const name = m[1];
        if (!qkMap.has(name)) qkMap.set(name, [name]);
      }

      // Exported top-level functions
      funcRe.lastIndex = 0;
      while ((m = funcRe.exec(src)) !== null) {
        const name = m[1];
        if (!qkMap.has(name)) qkMap.set(name, [name]);
      }

      // Exported methods (receiver form)
      methodRe.lastIndex = 0;
      while ((m = methodRe.exec(src)) !== null) {
        const name = m[1];
        if (!qkMap.has(name)) qkMap.set(name, [name]);
      }

      if (qkMap.size > 0) {
        fileQKeys.set(fp, qkMap);
        fileHasSymbol.set(fp, new Set(qkMap.keys()));
      }
    }

    // JavaScript/TypeScript: index definitions for cross-batch resolution from
    // the same parser output used by the normal ingest path. A path-only index
    // can find an imported file outside the current streaming batch, but without
    // its symbols resolveEdges cannot verify the destination and drops the edge.
    const jsTsExtensions = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx']);
    for (const [fp, src] of sources) {
      if (!jsTsExtensions.has(nodePath.extname(fp).toLowerCase())) continue;
      const parsed = preParsed?.get(fp) ?? parseFile(fp, src);
      if (!parsed) continue;
      const qkMap = new Map<string, string[]>();
      for (const e of parsed.entities) {
        if (e.kind === 'file' || e.kind === 'module') continue;
        const list = qkMap.get(e.name) ?? [];
        list.push(qualifiedKey(e));
        qkMap.set(e.name, list);
      }
      if (qkMap.size > 0) {
        fileQKeys.set(fp, qkMap);
        fileHasSymbol.set(fp, new Set(qkMap.keys()));
      }
      if (parsed.exportPublicNames) {
        filePublicNames.set(fp, new Map(parsed.exportPublicNames.map(name => [name.public, name.local])));
      }
    }

    // R: index function definitions for cross-batch Tier-3 resolution. Derive
    // them from the parser's definition.function entities (not a regex) so this
    // never drifts from what the in-batch path extracts in resolveEdges — the
    // parser also captures forms a regex misses (`= function`, string-keyed S3
    // method names like "print.myClass"). Mirrors the qkMap construction at
    // resolveEdges (key by name, value qkey). Same pattern as the SAS index.
    for (const [fp, src] of sources) {
      if (nodePath.extname(fp).toLowerCase() !== '.r') continue;
      const parsed = preParsed?.get(fp) ?? parseFile(fp, src);
      if (!parsed) continue;
      const qkMap = new Map<string, string[]>();
      for (const e of parsed.entities) {
        if (e.kind !== 'function') continue;
        const list = qkMap.get(e.name) ?? [];
        list.push(qualifiedKey(e));
        qkMap.set(e.name, list);
      }
      if (qkMap.size > 0) {
        fileQKeys.set(fp, qkMap);
        fileHasSymbol.set(fp, new Set(qkMap.keys()));
      }
    }

    // PHP: index definitions so an incremental batch can resolve typed receiver
    // calls to classes and interfaces in unchanged files.
    for (const [fp, src] of sources) {
      if (nodePath.extname(fp).toLowerCase() !== '.php') continue;
      const parsed = preParsed?.get(fp) ?? parseFile(fp, src);
      if (!parsed) continue;
      const qkMap = new Map<string, string[]>();
      const ambiguousTypes = ambiguousPhpTypeNames(parsed.entities);
      for (const e of parsed.entities) {
        if (e.kind === 'file' || e.kind === 'module') continue;
        const list = qkMap.get(e.name) ?? [];
        list.push(qualifiedKey(e));
        qkMap.set(e.name, list);
        const fqcn = phpTypeFqcn(e);
        if (fqcn && !ambiguousTypes.has(e.name.toLowerCase())) {
          const entries = phpFqcnToTypes.get(fqcn) ?? [];
          if (!entries.some(entry => entry.filePath === fp && entry.typeName === e.name)) {
            entries.push({ filePath: fp, typeName: e.name });
          }
          phpFqcnToTypes.set(fqcn, entries);
        }
      }
      if (qkMap.size > 0) {
        fileQKeys.set(fp, qkMap);
        fileHasSymbol.set(fp, new Set(qkMap.keys()));
      }
    }

    // SAS: index macro definitions for cross-batch Tier-3 resolution. Derive
    // them from the parser's definition.macro entities (not a regex) so this
    // never drifts from what the in-batch path extracts in resolveEdges — the
    // parser also captures forms a regex misses (e.g. %macro /*comment*/ name).
    // Mirrors the qkMap construction at resolveEdges (key by name, value qkey).
    for (const [fp, src] of sources) {
      if (nodePath.extname(fp).toLowerCase() !== '.sas') continue;
      const parsed = preParsed?.get(fp) ?? parseFile(fp, src);
      if (!parsed) continue;
      const qkMap = new Map<string, string[]>();
      for (const e of parsed.entities) {
        if (e.kind !== 'macro') continue;
        const list = qkMap.get(e.name) ?? [];
        list.push(qualifiedKey(e));
        qkMap.set(e.name, list);
      }
      if (qkMap.size > 0) {
        fileQKeys.set(fp, qkMap);
        fileHasSymbol.set(fp, new Set(qkMap.keys()));
      }
    }

  }

  if (summaries) {
    for (const [fp, summary] of summaries) {
      const qkMap = qkeyMapOf(summary);
      fileQKeys.set(fp, qkMap);
      fileHasSymbol.set(fp, new Set(qkMap.keys()));
      if (summary.exportPublicNames) filePublicNames.set(fp, new Map(summary.exportPublicNames));
      else filePublicNames.delete(fp);
    }
    // PHP types for summarized files come from their summaries alone.
    for (const [fqcn, entries] of phpFqcnToTypes) {
      phpFqcnToTypes.set(fqcn, entries.filter(entry => !summaries.has(entry.filePath)));
    }
    for (const [fp, summary] of summaries) {
      for (const [fqcn, typeName] of summary.phpTypes ?? []) {
        const entries = phpFqcnToTypes.get(fqcn) ?? [];
        if (!entries.some(entry => entry.filePath === fp && entry.typeName === typeName)) {
          entries.push({ filePath: fp, typeName });
        }
        phpFqcnToTypes.set(fqcn, entries);
      }
    }
  }

  for (const [fp, symbols] of fileHasSymbol) {
    for (const sym of symbols) {
      const list = symbolToFiles.get(sym) ?? [];
      list.push(fp);
      symbolToFiles.set(sym, list);
    }
  }

  return {
    fileHasSymbol,
    fileQKeys,
    filePublicNames,
    symbolToFiles,
    stemToFiles,
    dirToIndexFiles,
    packageToFiles,
    goPkgDirToFiles,
    goPkgPathToFiles,
    phpFqcnToTypes,
    ...(summaries ? { summaries } : {}),
  };
}

// Commodity callee names for the fuzzy resolution tiers (transitive re-export +
// global symbol fallback; see resolveEdges). Those tiers resolve a call on bare
// name alone and can cross module/package/repo boundaries. Builtin / stdlib
// instance methods (`path.resolve()`, `arr.map()`, `obj.get()`, `promise.then()`)
// are recorded by the parser as a bare callee name, so a single narrowed match
// links them to whatever unrelated file happens to export a top-level symbol of
// the same name (observed: `path.resolve()` -> an unrelated repo's `resolve`;
// `.get()`/`.map()` -> a client class's `get`/`map`).
//
// Deliberately conservative: ONLY names that are overwhelmingly builtin instance
// methods (Array / Object / Map / Set / Promise / Function / JSON) and are
// essentially never legitimate standalone project-function targets. Domain verbs
// that double as real function names (run, build, create, save, parse, process,
// handle, load, send, start, init, filter, find, on/emit, ...) are intentionally
// EXCLUDED — projects legitimately resolve those across files, so gating them
// would drop real edges. The frequency gate below catches project-specific
// commodities that this static list does not. The precise direct-import tier
// (confidence 0.9) is never gated, so an explicitly-imported `get`/`map` still
// resolves.
const COMMODITY_CALLEE_NAMES: ReadonlySet<string> = new Set([
  // Array / iterable builtins
  'map', 'forEach', 'reduce', 'reduceRight', 'flatMap', 'flat',
  'push', 'pop', 'shift', 'unshift', 'splice', 'slice', 'concat',
  // Map / Set / Object builtins
  'get', 'set', 'has', 'keys', 'values', 'entries',
  // Promise builtins
  'then', 'catch', 'finally', 'resolve', 'race', 'allSettled',
  // Function / JSON / Object builtins
  'bind', 'call', 'apply', 'stringify', 'toString', 'valueOf', 'hasOwnProperty',
]);

// JS/TS globals that test runners (vitest `globals: true`, jest, mocha) and
// runtimes inject without an import. In an ES/CommonJS module a bare identifier
// is either declared in the file, bound by an import, or a global — a
// module-scope function in some other file is never in scope. An UNBOUND call to
// one of these names is therefore the global, and resolveEdges does not link it
// to whatever in-repo symbol shares the name (observed: every test file's
// `describe(...)` resolved to test-fixtures' `SampleCommand.describe`). An
// explicit import binding or a same-file definition still wins.
const JS_AMBIENT_CALLEES: ReadonlySet<string> = new Set([
  'describe', 'it', 'test', 'expect', 'suite', 'bench',
  'beforeEach', 'afterEach', 'beforeAll', 'afterAll',
  'xdescribe', 'fdescribe', 'xit', 'fit', 'xtest',
  'vi', 'jest',
  'queueMicrotask', 'structuredClone', 'setImmediate', 'clearImmediate',
  'atob', 'btoa', 'encodeURIComponent', 'decodeURIComponent', 'encodeURI', 'decodeURI',
]);

/** A JS/TS import specifier that names a package rather than a path. */
function isBarePackageSpecifier(spec: string): boolean {
  return spec.length > 0 && !spec.startsWith('.') && !spec.startsWith('/') && !/^[A-Za-z]:[\\/]/.test(spec);
}

/**
 * Whether `filePath` plausibly lives inside the package a bare specifier names:
 * some directory on its path is the package name (`@acme/utils` ->
 * `.../utils/...`) or its unscoped monorepo spelling (`@babel/types` ->
 * `.../babel-types/...`). Node builtins (`node:fs`) are never in-repo.
 */
function fileIsInsidePackage(
  filePath: string,
  spec: string,
  packageDirOf?: (packageName: string) => string | undefined,
): boolean {
  // A package this repo declares (its tracked package.json names it) is
  // exactly that directory, whatever it is called: a library's own tests
  // import it by name (`from "mylib"`) from a folder no directory name
  // matches. The directory-name guess below is for everything else.
  const declared = packageDirOf?.(packageNameOf(spec));
  if (declared !== undefined) {
    const file = filePath.replace(/\\/g, '/');
    return declared === '' || file.startsWith(`${declared}/`);
  }
  if (spec.startsWith('node:')) return false;
  const parts = spec.split('/');
  const scope = spec.startsWith('@') ? parts[0].slice(1) : undefined;
  const name = scope !== undefined ? parts[1] : parts[0];
  if (!name) return false;
  const dirs = filePath.replace(/\\/g, '/').split('/').slice(0, -1);
  return dirs.includes(name) || (scope !== undefined && dirs.includes(`${scope}-${name}`));
}

/** The package part of a bare specifier: `@acme/utils/dates` -> `@acme/utils`, `lodash/fp` -> `lodash`. */
function packageNameOf(spec: string): string {
  const parts = spec.split('/');
  return spec.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
}

// A symbol defined in this many or more distinct files across the resolution
// set is a project-level commodity; a single narrowed fuzzy-tier match for it is
// not trustworthy. (Tunable; the named-list above carries the builtin-method load.)
const COMMODITY_DEF_FILE_THRESHOLD = 5;

/**
 * Resolves CALLS and EXTENDS relationships to their cross-file targets by
 * building a symbol table and import map over the full batch of parsed files.
 *
 * Tiers (in priority order):
 *   0.9 — import-scoped: dst is in a file the src explicitly imports
 *   0.8 — transitive import-scoped: one re-export hop away
 *   0.5 — global fallback: dst exists in exactly one other file (unambiguous)
 *
 * Same-file edges are already handled correctly by buildPatch and are not
 * emitted here.
 *
 * Import resolution handles:
 *   - Stem-based:      './payments'     → 'payments.ts'
 *   - Path-aliased:    '@/lib/payments' → 'payments.ts'  (last segment)
 *   - Directory index: './services'     → 'services/index.ts'
 *   - Bare aliases:    '@components'    → 'components.ts' (strip leading non-word chars)
 *   - Dotted paths:    'ix.memory.model.Edge' → stem 'Edge' → 'Edge.scala'
 *                      (handles Scala/Java package imports where tree-sitter
 *                       emits each identifier separately)
 *
 * Qualified-key resolution:
 *   - Module-level function/class: dstQualifiedKey === dstName
 *   - Unambiguous class method: dstQualifiedKey === 'ClassName.method'
 *   - Ambiguous (two entities share the same plain name): edge not emitted
 */
export function resolveEdges(
  results: FileParseResult[],
  stats?: {
    importLookups: number; transitiveLookups: number; globalFallbacks: number;
    globalCandidateTotal: number; resolvedImport: number; resolvedTransitive: number;
    resolvedGlobal: number; resolvedQualifier: number; skippedSameFile: number; skippedAmbiguous: number;
    /** Exact members of an inferred receiver type (optional for older callers). */
    resolvedType?: number;
  },
  globalIndex?: GlobalResolutionIndex,
  opts?: {
    // Multi-repo co-ingest (Ix#225 Path 1). repoOf maps a file path to its repo;
    // packageOf maps an import module name to the repo that publishes it. With
    // both, a CROSS-repo edge is kept only when the source repo actually imports
    // the target repo's package — killing same-named-symbol false edges between
    // unrelated repos while preserving genuine cross-repo edges (which ARE
    // dependency-backed). Absent (single-repo ingest) => no gating, no change.
    repoOf?: (filePath: string) => string | undefined;
    packageOf?: (moduleName: string) => string | undefined;
    // Ground-truth member->member dependency graph from build manifests (npm deps,
    // Cargo [dependencies], go.mod require, Maven <dependency>, ...). Seeds the
    // cross-repo gate so genuine edges survive even where import-to-package matching
    // can't bridge the gap (e.g. Java's Maven artifactId vs `import com.google...`).
    declaredRepoDeps?: Record<string, string[]>;
    // JS/TS package name -> the directory (workspace-relative, POSIX, '' for
    // the root) whose package.json declares it, when exactly one does.
    packageDirOf?: (packageName: string) => string | undefined;
    // Workspace-aware JS/TS module resolution supplied by the CLI. `undefined`
    // preserves the existing fallback; an empty array is authoritative and
    // prevents a configured import from falling through to an unrelated stem.
    resolveModuleSpecifier?: (
      srcFilePath: string,
      specifier: string,
      kind?: 'runtime' | 'types',
    ) => string[] | undefined;
  },
): ResolvedEdge[] {
  // Provide a default no-op stats bag when caller passes none (backward compat).
  if (!stats) stats = {
    importLookups: 0, transitiveLookups: 0, globalFallbacks: 0,
    globalCandidateTotal: 0, resolvedImport: 0, resolvedTransitive: 0,
    resolvedGlobal: 0, resolvedQualifier: 0, skippedSameFile: 0, skippedAmbiguous: 0,
  };
  // Every file this call can resolve TO: the index's summaries with the batch's
  // own laid over them. Everything below that describes a target file -- its
  // symbols, exports, language, imports -- is derived from this and never from
  // `results`, so a batch resolves exactly as the whole repository would
  // (IN-09). `results` is only the set of files whose edges are resolved.
  // Files the index knows only through its older per-language maps (a caller
  // that passed no summaries) keep those entries.
  const batchSummaries = results.map(summarizeParseResult);
  const summaries = new Map<string, FileSummary>(globalIndex?.summaries ?? []);
  for (const s of batchSummaries) summaries.set(s.filePath, s);
  // The index's maps already hold every file it has a summary for (its symbol
  // maps from the summaries, its path maps from paths and summaries alike), so
  // only the batch's own summaries are laid over them below. Redoing the whole
  // index here cost every call O(repository), and the path maps' de-dup made
  // it quadratic in the size of a common stem (`index`, `__init__`).
  // Renamed-import call resolution (Z): a call to a renamed local binding (`import
  // { format as fmt }; fmt()`) should resolve as the provider's public symbol
  // (`format`), so in-repo AND co-ingest resolution link it to the real definition.
  // Map per file: local binding name -> imported public symbol, excluding default
  // and no-op named imports from the by-name rewrite. Provider public-name
  // resolution below handles those bindings against the imported file itself.
  const callBindings = new Map<string, Map<string, string>>();
  const importBindingsByLocal = new Map<string, Map<string, ImportBinding>>();
  const relativeCallBindings = new Map<string, Set<string>>();
  for (const r of results) {
    if (!r.importBindings) continue;
    for (const b of r.importBindings) {
      let imports = importBindingsByLocal.get(r.filePath);
      if (!imports) { imports = new Map(); importBindingsByLocal.set(r.filePath, imports); }
      if (!imports.has(b.local)) imports.set(b.local, b);
      if (
        b.pkg.startsWith('./') || b.pkg.startsWith('../') ||
        (r.language === SupportedLanguages.Python && b.pkg.startsWith('.'))
      ) {
        let bindings = relativeCallBindings.get(r.filePath);
        if (!bindings) { bindings = new Set(); relativeCallBindings.set(r.filePath, bindings); }
        bindings.add(b.local);
      }
      if (b.imported === 'default' || b.local === b.imported) continue;
      let m = callBindings.get(r.filePath);
      if (!m) { m = new Map(); callBindings.set(r.filePath, m); }
      if (!m.has(b.local)) m.set(b.local, b.imported);
    }
  }
  const phpFqcnImportsByLocal = new Map<string, Map<string, string | null>>();
  for (const result of results) {
    if (result.language !== SupportedLanguages.PHP) continue;
    // A `use` is scoped to its namespace *block*, but this index is per file.
    // In a file with several namespaces, an import in one block would be
    // applied to the others — resolving a name that a later block declares
    // itself, and pointing it confidently at the wrong file. One namespace per
    // file is the PSR-12 norm, so skip the rare multi-block file entirely
    // rather than mis-resolve it; it simply keeps the pre-existing behaviour.
    //
    // The count comes from the parser's `namespace_definition` nodes, NOT from
    // the entities' packageScope. Two things are invisible from the entity side:
    // two blocks may declare the SAME namespace name (one distinct scope string,
    // still two scopes), and a block containing only `use` statements declares
    // no entities at all (no scope string, but its imports are still confined
    // to it). Both were mis-classified as single-namespace files.
    if ((result.phpNamespaceBlocks ?? 0) > 1) continue;
    for (const rel of result.relationships) {
      if (
        rel.predicate !== 'IMPORTS' ||
        rel.importKind === 'function' ||
        rel.importKind === 'const' ||
        rel.importAliased ||
        typeof rel.importRaw !== 'string'
      ) continue;
      const fqcn = rel.importRaw.replace(/^\\+/, '').toLowerCase();
      const local = fqcn.split('\\').pop();
      if (!local) continue;
      const imports = phpFqcnImportsByLocal.get(result.filePath) ?? new Map<string, string | null>();
      if (!imports.has(local)) imports.set(local, fqcn);
      else if (imports.get(local) !== fqcn) imports.set(local, null);
      phpFqcnImportsByLocal.set(result.filePath, imports);
    }
  }
  // Cross-repo dependency graph: repo R depends on repo D when any file in R
  // imports a module published by D. Built from the raw IMPORTS relationships.
  const repoOf = opts?.repoOf;
  const packageOf = opts?.packageOf;
  let repoDeps: Map<string, Set<string>> | undefined;
  if (repoOf && packageOf) {
    repoDeps = new Map<string, Set<string>>();
    // Seed from the ground-truth declared-dependency graph (manifest deps). This
    // is the robust signal: it catches deps that import-matching misses (Java).
    if (opts?.declaredRepoDeps) {
      for (const [srcRepo, deps] of Object.entries(opts.declaredRepoDeps)) {
        for (const depRepo of deps) {
          if (depRepo === srcRepo) continue;
          let set = repoDeps.get(srcRepo);
          if (!set) { set = new Set<string>(); repoDeps.set(srcRepo, set); }
          set.add(depRepo);
        }
      }
    }
    for (const s of summaries.values()) {
      const srcRepo = repoOf(s.filePath);
      if (srcRepo === undefined) continue;
      for (const rel of s.imports) {
        // Prefer the raw specifier when the parser preserved it: a relative import
        // (./x, ../x) is intra-repo by construction and can NEVER denote another
        // repo's package, so packageOf rejects it and it seeds no cross-repo dep.
        // Only bare/package specifiers (@scope/name, name) can. Falls back to the
        // flattened stem for imports without a raw specifier (no behavior change).
        const mod = typeof rel.importRaw === 'string' ? rel.importRaw
                  : typeof rel.dstName === 'string' ? rel.dstName : '';
        const depRepo = mod ? packageOf(mod) : undefined;
        if (depRepo !== undefined && depRepo !== srcRepo) {
          let set = repoDeps.get(srcRepo);
          if (!set) { set = new Set<string>(); repoDeps.set(srcRepo, set); }
          set.add(depRepo);
        }
      }
    }
    // Transitive closure: a monorepo package re-exports its own dependencies
    // (e.g. @babel/core re-exports @babel/types), so a repo legitimately uses the
    // symbols of repos it depends on TRANSITIVELY. Without this, genuine
    // transitive cross-repo edges (helper -> core -> types) would be dropped.
    // Unrelated repos with no import path between them stay disconnected.
    let changed = true;
    while (changed) {
      changed = false;
      for (const [, deps] of repoDeps) {
        for (const b of [...deps]) {
          const bdeps = repoDeps.get(b);
          if (bdeps) for (const c of bdeps) {
            if (!deps.has(c)) { deps.add(c); changed = true; }
          }
        }
      }
    }
  }
  // Disambiguate multiple candidates using the declared-dependency graph: a symbol
  // defined identically in several members (e.g. two repos each export `init`)
  // resolves to the one the SOURCE repo actually depends on. Same-repo and
  // unknown-repo candidates are always kept; cross-repo candidates survive only if
  // the source repo depends on their repo. This mirrors the post-resolution
  // cross-repo gate below, but is applied DURING resolution so an ambiguous-by-name
  // match folds onto the real cross-repo node instead of being skipped (which left
  // the call unresolved -> a phantom same-file dst / dangling edge, Ix#225). No-op
  // for single-repo ingests (no repoDeps) and for unambiguous matches (<= 1).
  const narrowByRepoDeps = (candidates: string[], srcFilePath: string): string[] => {
    if (!repoOf || !repoDeps || candidates.length <= 1) return candidates;
    const sr = repoOf(srcFilePath);
    if (sr === undefined) return candidates;
    const kept = candidates.filter(fp => {
      const dr = repoOf!(fp);
      if (dr === undefined || dr === sr) return true;
      return repoDeps!.get(sr)?.has(dr) === true;
    });
    return kept.length > 0 ? kept : candidates;
  };

  // A deterministic "entry file" per member repo: the file a cross-repo package
  // import couples to when no specific symbol resolves (e.g. a dynamic/property
  // API like `chalk[color]`). Prefers an index/main-style basename, then the
  // shallowest path, then lexical order — a total order, so it is independent of
  // the parse/iteration order. Only built for co-ingest (repoOf present).
  let entryFileOf: Map<string, string> | undefined;
  if (repoOf) {
    entryFileOf = new Map<string, string>();
    const ENTRY_NAMES = new Set(['index', 'main', 'mod', 'lib', '__init__', 'app', 'init']);
    const entryScore = (fp: string): [number, number, string] => {
      const norm = fp.replace(/\\/g, '/');
      const base = nodePath.basename(norm).replace(/\.[^.]+$/, '').toLowerCase();
      return [ENTRY_NAMES.has(base) ? 0 : 1, norm.split('/').length, norm];
    };
    const better = (a: [number, number, string], b: [number, number, string]) =>
      a[0] !== b[0] ? a[0] < b[0] : a[1] !== b[1] ? a[1] < b[1] : a[2] < b[2];
    const bestScore = new Map<string, [number, number, string]>();
    for (const filePath of summaries.keys()) {
      const repo = repoOf(filePath);
      if (repo === undefined) continue;
      const s = entryScore(filePath);
      const cur = bestScore.get(repo);
      if (!cur || better(s, cur)) { bestScore.set(repo, s); entryFileOf.set(repo, filePath); }
    }
  }
  // fileQKeys: seed from global index (cross-batch files), then batch entries override.
  // Mirrors the entityQKey computation in buildPatch so nodeIds match exactly.
  const fileQKeys = globalIndex
    ? new Map<string, Map<string, string[]>>(globalIndex.fileQKeys)
    : new Map<string, Map<string, string[]>>();
  for (const s of batchSummaries) fileQKeys.set(s.filePath, qkeyMapOf(s));  // overrides the index's own entry

  const filePublicNames = globalIndex
    ? new Map<string, Map<string, string>>(globalIndex.filePublicNames ?? [])
    : new Map<string, Map<string, string>>();
  for (const s of batchSummaries) {
    if (s.exportPublicNames) filePublicNames.set(s.filePath, new Map(s.exportPublicNames));
    else filePublicNames.delete(s.filePath);
  }

  // fileHasSymbol: rebuilt from merged fileQKeys so per-batch overrides take effect.
  const fileHasSymbol = new Map<string, Set<string>>();
  for (const [fp, qkMap] of fileQKeys) {
    fileHasSymbol.set(fp, new Set(qkMap.keys()));
  }

  // Index entries for files that have no summary, then every summarized file's
  // own types, in summary order.
  const phpFqcnToTypes = new Map<string, Array<{ filePath: string; typeName: string }>>();
  for (const [fqcn, entries] of globalIndex?.phpFqcnToTypes ?? []) {
    const unsummarized = entries.filter(entry => !summaries.has(entry.filePath));
    if (unsummarized.length > 0) phpFqcnToTypes.set(fqcn, unsummarized);
  }
  for (const s of summaries.values()) {
    for (const [fqcn, typeName] of s.phpTypes ?? []) {
      const entries = phpFqcnToTypes.get(fqcn) ?? [];
      if (!entries.some(entry => entry.filePath === s.filePath && entry.typeName === typeName)) {
        entries.push({ filePath: s.filePath, typeName });
      }
      phpFqcnToTypes.set(fqcn, entries);
    }
  }

  // symbolToFiles: rebuilt from merged fileHasSymbol (not seeded directly — per-batch
  // overrides can change which files define a symbol).
  const symbolToFiles = new Map<string, string[]>();
  for (const [fp, symbols] of fileHasSymbol) {
    for (const sym of symbols) {
      const list = symbolToFiles.get(sym) ?? [];
      list.push(fp);
      symbolToFiles.set(sym, list);
    }
  }

  // fileLanguage: filePath → SupportedLanguages (fast language lookup without re-calling languageFromPath)
  const fileLanguage = new Map<string, SupportedLanguages>();
  for (const s of summaries.values()) fileLanguage.set(s.filePath, s.language);

  // "A.b" -> files whose qualified keys include it. The qualifier fallback
  // asked every file in the batch per dotted call; this answers it once.
  const qualifiedToFiles = new Map<string, string[]>();
  for (const [fp, qkMap] of fileQKeys) {
    for (const keys of qkMap.values()) {
      for (const qk of new Set(keys)) {
        const list = qualifiedToFiles.get(qk) ?? [];
        list.push(fp);
        qualifiedToFiles.set(qk, list);
      }
    }
  }

  // Add `fp` under `key` without touching the index's own array: the maps are
  // shallow copies, and pushing into a shared list leaked one batch's files
  // into the index every later batch resolves against.
  const addPath = (map: Map<string, string[]>, key: string, fp: string): void => {
    const list = map.get(key);
    if (!list) map.set(key, [fp]);
    else if (!list.includes(fp)) map.set(key, [...list, fp]);
  };

  // stemToFiles: seed from global index, then add batch entries.
  const stemToFiles = globalIndex
    ? new Map<string, string[]>(globalIndex.stemToFiles)
    : new Map<string, string[]>();
  for (const r of batchSummaries) {
    addPath(stemToFiles, nodePath.basename(r.filePath, nodePath.extname(r.filePath)), r.filePath);
  }

  // dirToIndexFiles: seed from global index, then add batch entries.
  const dirToIndexFiles = globalIndex
    ? new Map<string, string[]>(globalIndex.dirToIndexFiles)
    : new Map<string, string[]>();
  for (const r of batchSummaries) {
    const stem = nodePath.basename(r.filePath, nodePath.extname(r.filePath));
    if (stem === 'index') addPath(dirToIndexFiles, nodePath.basename(nodePath.dirname(r.filePath)), r.filePath);
  }

  // Relative imports must be resolved against the importing file's directory.
  // Keep a normalized path lookup so they do not fall back to a same-named file
  // elsewhere in the repository.
  const normalizedPathToFiles = new Map<string, string[]>();
  const normalizedPathKey = (filePath: string): string => {
    const normalized = nodePath.posix.normalize(filePath.replace(/\\/g, '/'));
    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
  };
  const addIndexedPath = (filePath: string): void => {
    const normalized = normalizedPathKey(filePath);
    const files = normalizedPathToFiles.get(normalized) ?? [];
    if (!files.includes(filePath)) files.push(filePath);
    normalizedPathToFiles.set(normalized, files);
  };
  for (const files of stemToFiles.values()) {
    for (const filePath of files) addIndexedPath(filePath);
  }
  for (const files of dirToIndexFiles.values()) {
    for (const filePath of files) addIndexedPath(filePath);
  }

  // packageToFiles: seed from global index, then add batch entries.
  // e.g. "ix.memory.model" → all .scala files under .../ix/memory/model/
  const packageToFiles = globalIndex
    ? new Map<string, string[]>(globalIndex.packageToFiles)
    : new Map<string, string[]>();
  for (const r of batchSummaries) {
    const ext = nodePath.extname(r.filePath);
    if (ext !== '.scala' && ext !== '.java') continue;
    const dir = nodePath.dirname(r.filePath);
    const parts = dir.split(/[/\\]/);
    const maxDepth = Math.min(8, parts.length);
    for (let i = parts.length - 1; i >= parts.length - maxDepth; i--) {
      addPath(packageToFiles, parts.slice(i).join('.'), r.filePath);
    }
  }

  // goPkgDirToFiles / goPkgPathToFiles: seed from global index, then add batch entries.
  const goPkgDirToFiles = globalIndex
    ? new Map<string, string[]>(globalIndex.goPkgDirToFiles)
    : new Map<string, string[]>();
  const goPkgPathToFiles = globalIndex
    ? new Map<string, string[]>(globalIndex.goPkgPathToFiles)
    : new Map<string, string[]>();
  for (const r of batchSummaries) {
    if (nodePath.extname(r.filePath) !== '.go') continue;
    addPath(goPkgDirToFiles, nodePath.basename(nodePath.dirname(r.filePath)), r.filePath);
    const parts = nodePath.dirname(r.filePath).replace(/\\/g, '/').split('/').filter(Boolean);
    const maxDepth = Math.min(8, parts.length);
    for (let i = parts.length - 1; i >= parts.length - maxDepth; i--) {
      addPath(goPkgPathToFiles, parts.slice(i).join('/'), r.filePath);
    }
  }

  // ── Helpers ────────────────────────────────────────────────────────

  function normalizeImportTarget(modName: unknown): string {
    if (typeof modName === 'string') return modName;
    if (modName == null) return '';
    return String(modName);
  }

  /** Resolve a module name to matching file paths in the batch. */
  function modNameToFiles(modName: unknown, excludeFp: string): string[] {
    const normalizedModName = normalizeImportTarget(modName);
    if (!normalizedModName) return [];
    const fps: string[] = [];
    // Strip leading non-word chars for bare aliases: '@components' → 'components'
    const candidates = [normalizedModName];
    const stripped = normalizedModName.replace(/^[^a-zA-Z0-9_]+/, '');
    if (stripped && stripped !== normalizedModName) candidates.push(stripped);
    // Strip file extensions so "explain.js" resolves to the "explain" stem
    // (TS/JS ESM imports use .js extensions that map to .ts source files)
    // Only the SAS extension is case-insensitive (real SAS uses .sas/.SAS
    // interchangeably). Keeping the rest case-sensitive avoids stripping
    // uppercase .C/.H (legitimate C++ source) or .TS/.JAVA across languages.
    const noExt = normalizedModName.replace(/\.(js|ts|mjs|cjs|jsx|tsx|py|scala|java|c|cc|cpp|cxx|h|hh|hpp|hxx|[Ss][Aa][Ss])$/, '');
    if (noExt !== normalizedModName && noExt && !candidates.includes(noExt)) candidates.push(noExt);
    const pathBasename = nodePath.posix.basename(normalizedModName);
    if (pathBasename && !candidates.includes(pathBasename)) candidates.push(pathBasename);
    const pathBasenameNoExt = nodePath.posix.basename(noExt);
    if (pathBasenameNoExt && !candidates.includes(pathBasenameNoExt)) candidates.push(pathBasenameNoExt);
    // For dotted paths (Scala/Java: 'ix.memory.model.Edge'), also try last segment
    const lastDot = normalizedModName.lastIndexOf('.');
    if (lastDot !== -1) {
      const lastSegment = normalizedModName.slice(lastDot + 1);
      if (lastSegment && !candidates.includes(lastSegment)) candidates.push(lastSegment);
    }
    for (const cand of candidates) {
      for (const fp of stemToFiles.get(cand) ?? []) {
        if (fp !== excludeFp) fps.push(fp);
      }
      for (const fp of dirToIndexFiles.get(cand) ?? []) {
        if (fp !== excludeFp) fps.push(fp);
      }
    }
    // Package-path wildcard resolution (Scala/Java): "ix.memory.model" → all files in that dir
    for (const fp of packageToFiles.get(normalizedModName) ?? []) {
      if (fp !== excludeFp && !fps.includes(fp)) fps.push(fp);
    }
    // Go package directory resolution: "etcdserver" → all .go files in .../etcdserver/
    // The last segment of a Go import path is the package directory name, not a file stem.
    for (const fp of goPkgDirToFiles.get(normalizedModName) ?? []) {
      if (fp !== excludeFp && !fps.includes(fp)) fps.push(fp);
    }
    const slashParts = normalizedModName.replace(/\\/g, '/').split('/').filter(Boolean);
    const maxSlashDepth = Math.min(8, slashParts.length);
    for (let i = 0; i < maxSlashDepth; i++) {
      const suffix = slashParts.slice(slashParts.length - 1 - i).join('/');
      for (const fp of goPkgPathToFiles.get(suffix) ?? []) {
        if (fp !== excludeFp && !fps.includes(fp)) fps.push(fp);
      }
    }
    return fps;
  }

  function goImportSuffixes(modName: unknown): string[] {
    const normalizedModName = normalizeImportTarget(modName);
    if (!normalizedModName) return [];
    const parts = normalizedModName.replace(/\\/g, '/').split('/').filter(Boolean);
    const suffixes: string[] = [];
    const maxDepth = Math.min(8, parts.length);
    for (let i = 0; i < maxDepth; i++) {
      suffixes.push(parts.slice(parts.length - 1 - i).join('/'));
    }
    return suffixes;
  }

  function pickGoPackageAnchor(files: string[]): string | null {
    if (files.length === 0) return null;
    const nonTestFiles = files.filter(fp => !fp.endsWith('_test.go'));
    const pool = nonTestFiles.length > 0 ? nonTestFiles : files;
    const dirName = nodePath.basename(nodePath.dirname(pool[0])).toLowerCase();

    const exactStemMatch = pool.filter(fp => candidateStem(fp) === dirName);
    if (exactStemMatch.length === 1) return exactStemMatch[0];

    const ranked = [...pool].sort((a, b) => {
      const aSummary = summaries.get(a);
      const bSummary = summaries.get(b);
      const aImports = aSummary?.imports.length ?? 0;
      const bImports = bSummary?.imports.length ?? 0;
      if (aImports !== bImports) return bImports - aImports;

      // Fall back to the index's symbol count for a file with no summary.
      // fileQKeys is seeded from buildGlobalResolutionIndex, so substantive
      // files like instance.go score higher than package-doc stubs like doc.go
      // (which only has the package name).
      const aEntities = aSummary?.entityCount ?? fileQKeys.get(a)?.size ?? 0;
      const bEntities = bSummary?.entityCount ?? fileQKeys.get(b)?.size ?? 0;
      if (aEntities !== bEntities) return bEntities - aEntities;

      return a.localeCompare(b);
    });
    return ranked[0] ?? null;
  }

  function narrowGoImportCandidates(
    srcFilePath: string,
    modName: unknown,
    importMatches: string[],
    pickFromSingleDir: (files: string[]) => string[],
  ): string[] {
    const suffixes = goImportSuffixes(modName);
    const scored = importMatches.map(fp => {
      const dirPath = nodePath.dirname(fp).replace(/\\/g, '/');
      let bestSuffixLen = -1;
      for (const suffix of suffixes) {
        if (dirPath === suffix || dirPath.endsWith(`/${suffix}`)) {
          if (suffix.length > bestSuffixLen) bestSuffixLen = suffix.length;
        }
      }
      return { fp, bestSuffixLen };
    });

    const bestSuffixLen = Math.max(...scored.map(item => item.bestSuffixLen));
    const narrowed = bestSuffixLen >= 0
      ? scored.filter(item => item.bestSuffixLen === bestSuffixLen).map(item => item.fp)
      : importMatches;

    const dirGroups = new Map<string, string[]>();
    for (const fp of narrowed) {
      const key = nodePath.dirname(fp).replace(/\\/g, '/');
      const list = dirGroups.get(key) ?? [];
      list.push(fp);
      dirGroups.set(key, list);
    }

    if (dirGroups.size === 1) return pickFromSingleDir([...dirGroups.values()][0]);
    return narrowed;
  }

  // An import targets a file in a compatible language. modNameToFiles matches by
  // stem alone, so without this a Python `import select` would resolve to a Rust
  // `select.rs` (observed in cross-language co-ingest). Some languages are one
  // family: JS+TS (TS imports JS/.d.ts) and C+C++ (a .h header is shared, and
  // parseFile's content-based detection labels the same .h as `c` or `cpp`
  // depending on whether it holds a struct or a class — so a C++ file including a
  // C-classified header must still resolve). Everything else must match exactly.
  const langFamily = (l: SupportedLanguages): string => {
    if (l === SupportedLanguages.JavaScript || l === SupportedLanguages.TypeScript) return 'jsts';
    if (l === SupportedLanguages.C || l === SupportedLanguages.CPlusPlus) return 'c';
    return l;
  };
  const importLanguageCompatible = (src: SupportedLanguages, dst: SupportedLanguages | undefined | null): boolean => {
    if (dst == null || src === dst) return true;
    return langFamily(src) === langFamily(dst);
  };

  function relativeImportTarget(srcFilePath: string, srcLanguage: SupportedLanguages, importRaw: unknown): string | null {
    if (typeof importRaw !== 'string') return null;
    const sourceDir = nodePath.posix.dirname(srcFilePath.replace(/\\/g, '/'));

    if (
      (srcLanguage === SupportedLanguages.JavaScript || srcLanguage === SupportedLanguages.TypeScript) &&
      (importRaw.startsWith('./') || importRaw.startsWith('../'))
    ) {
      // Bundlers use query/hash suffixes to select loaders or virtual variants;
      // the on-disk module path is the portion before that URL metadata.
      const queryIndex = importRaw.indexOf('?');
      const fragmentIndex = importRaw.indexOf('#');
      const suffixIndex = queryIndex === -1
        ? fragmentIndex
        : fragmentIndex === -1 ? queryIndex : Math.min(queryIndex, fragmentIndex);
      const pathSpecifier = suffixIndex === -1 ? importRaw : importRaw.slice(0, suffixIndex);
      return nodePath.posix.normalize(nodePath.posix.join(sourceDir, pathSpecifier));
    }

    if (srcLanguage === SupportedLanguages.Python && importRaw.startsWith('.')) {
      const dots = importRaw.match(/^\.+/)?.[0].length ?? 0;
      let packageDir = sourceDir;
      for (let i = 1; i < dots; i++) packageDir = nodePath.posix.dirname(packageDir);
      const modulePath = importRaw.slice(dots).replace(/\./g, '/');
      return nodePath.posix.normalize(nodePath.posix.join(packageDir, modulePath));
    }

    return null;
  }

  function resolveRelativeImportTargets(
    srcFilePath: string,
    srcLanguage: SupportedLanguages,
    importRaw: unknown,
  ): string[] | null {
    const target = relativeImportTarget(srcFilePath, srcLanguage, importRaw);
    if (target === null) return null;

    const candidatePaths: string[] = [];
    if (srcLanguage === SupportedLanguages.Python) {
      if (target.endsWith('.py')) {
        candidatePaths.push(target);
      } else {
        candidatePaths.push(nodePath.posix.join(target, '__init__.py'), `${target}.py`);
      }
    } else {
      const extension = nodePath.posix.extname(target).toLowerCase();
      const base = extension.length > 0 ? target.slice(0, -extension.length) : target;
      const addSourceVariants = (pathBase: string): void => {
        const suffixes = srcLanguage === SupportedLanguages.JavaScript
          ? ['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.d.ts']
          : ['.ts', '.tsx', '.d.ts', '.js', '.jsx', '.mjs', '.cjs'];
        for (const suffix of suffixes) {
          candidatePaths.push(`${pathBase}${suffix}`);
        }
      };

      if (extension.length === 0) {
        addSourceVariants(target);
        addSourceVariants(nodePath.posix.join(target, 'index'));
      } else if (extension === '.js') {
        const suffixes = srcLanguage === SupportedLanguages.JavaScript
          ? ['.js', '.ts', '.tsx', '.d.ts']
          : ['.ts', '.tsx', '.d.ts', '.js'];
        for (const suffix of suffixes) candidatePaths.push(`${base}${suffix}`);
      } else if (extension === '.jsx') {
        const suffixes = srcLanguage === SupportedLanguages.JavaScript
          ? ['.jsx', '.tsx', '.d.ts']
          : ['.tsx', '.d.ts', '.jsx'];
        for (const suffix of suffixes) candidatePaths.push(`${base}${suffix}`);
      } else if (extension === '.mjs' || extension === '.cjs') {
        // `.mts` compiles to `.mjs` and `.cts` to `.cjs`, as `.ts` does to `.js`.
        const sourceExt = extension === '.mjs' ? '.mts' : '.cts';
        const suffixes = srcLanguage === SupportedLanguages.JavaScript
          ? [extension, sourceExt]
          : [sourceExt, extension];
        for (const suffix of suffixes) candidatePaths.push(`${base}${suffix}`);
      } else {
        candidatePaths.push(target);
      }
      // A path into build output (`../pkg/dist/x.js`, typical of a dynamic
      // import of a sibling package's compiled module) names a file that is
      // not tracked; its source is the same path under `src/`. Tried only
      // after every direct candidate, so a tracked `dist/` file still wins.
      // Mirrors `sourceForms` in ix-cli's explain/text-references.ts, but uses
      // the dist segment nearest the file: that is the package's outDir.
      // Not from a file inside that same dist/ tree: build output importing its
      // own siblings (a tracked `dist/x.d.ts` importing `./y.ts`) depends on the
      // sibling build file, not on src/, and mapping it would add an edge from
      // every such file into src/.
      const lastDist = target.lastIndexOf('/dist/');
      const distAt = lastDist !== -1 ? lastDist + 1 : target.startsWith('dist/') ? 0 : -1;
      const distPrefix = distAt !== -1 ? `${target.slice(0, distAt)}dist/` : undefined;
      if (distPrefix !== undefined && !srcFilePath.replace(/\\/g, '/').startsWith(distPrefix)) {
        const srcPrefix = `${target.slice(0, distAt)}src/`;
        for (const candidatePath of [...candidatePaths]) {
          if (candidatePath.startsWith(distPrefix)) {
            candidatePaths.push(srcPrefix + candidatePath.slice(distPrefix.length));
          }
        }
      }
    }

    for (const candidatePath of candidatePaths) {
      const matches = (normalizedPathToFiles.get(normalizedPathKey(candidatePath)) ?? [])
        .filter(filePath => normalizedPathKey(filePath) !== normalizedPathKey(srcFilePath));
      if (matches.length > 0) return matches;
    }
    return [];
  }

  function resolveImportTargets(
    srcFilePath: string,
    srcLanguage: SupportedLanguages,
    modName: unknown,
    importRaw?: unknown,
    kind: 'runtime' | 'types' = 'runtime',
  ): string[] {
    const configuredMatches =
      (srcLanguage === SupportedLanguages.JavaScript || srcLanguage === SupportedLanguages.TypeScript) &&
      typeof importRaw === 'string' &&
      !importRaw.startsWith('./') &&
      !importRaw.startsWith('../')
        ? opts?.resolveModuleSpecifier?.(srcFilePath, importRaw, kind)
        : undefined;
    const indexedConfiguredMatches = configuredMatches?.flatMap(filePath =>
      normalizedPathToFiles.get(normalizedPathKey(filePath)) ?? []
    ).filter(filePath => normalizedPathKey(filePath) !== normalizedPathKey(srcFilePath));
    // fileLanguage only covers the current parse batch; cross-batch candidates
    // come from the global stem index, so fall back to the extension-derived
    // language (always available) — otherwise an undefined dst language would
    // slip cross-language matches (e.g. a Python import -> a Rust/Elixir file).
    const importMatches = (configuredMatches === undefined
      ? resolveRelativeImportTargets(srcFilePath, srcLanguage, importRaw) ?? modNameToFiles(modName, srcFilePath)
      : indexedConfiguredMatches ?? [])
      .filter(fp => importLanguageCompatible(srcLanguage, fileLanguage.get(fp) ?? languageFromPath(fp)));
    if (srcLanguage !== SupportedLanguages.Go || importMatches.length <= 1) return importMatches;
    return narrowGoImportCandidates(srcFilePath, modName, importMatches, files => {
      const anchor = pickGoPackageAnchor(files);
      return anchor ? [anchor] : [];
    });
  }

  function resolveImportQualifierTargets(srcFilePath: string, srcLanguage: SupportedLanguages, modName: unknown): string[] {
    const importMatches = modNameToFiles(modName, srcFilePath);
    if (srcLanguage !== SupportedLanguages.Go || importMatches.length <= 1) return importMatches;
    return narrowGoImportCandidates(srcFilePath, modName, importMatches, files => files);
  }

  function tokenizeSymbolParts(value: string): string[] {
    return value
      .replace(/([a-z\d])([A-Z])/g, '$1 $2')
      .replace(/[^a-zA-Z0-9]+/g, ' ')
      .toLowerCase()
      .split(/\s+/)
      .filter(Boolean);
  }

  const GENERIC_RESOLUTION_TOKENS = new Set([
    'run', 'job', 'file', 'files', 'table', 'tables', 'output', 'outputs',
    'input', 'inputs', 'background',
  ]);

  function candidateStem(filePath: string): string {
    return nodePath.basename(filePath, nodePath.extname(filePath)).toLowerCase();
  }

  function pickCallerAlignedCandidate(
    matches: string[],
    srcName: string,
    dstName: string,
  ): { chosen: string | null; best: Array<{ fp: string; overlap: number }> } | null {
    if (matches.length === 0) return null;
    const srcTokens = new Set(
      tokenizeSymbolParts(srcName).filter(token => !GENERIC_RESOLUTION_TOKENS.has(token)),
    );
    const overlapScores = matches.map(fp => {
      const qKeys = fileQKeys.get(fp)?.get(dstName) ?? [];
      const candidateTokens = new Set<string>(tokenizeSymbolParts(candidateStem(fp)));
      for (const qKey of qKeys) {
        for (const token of tokenizeSymbolParts(qKey)) candidateTokens.add(token);
      }
      let overlap = 0;
      for (const token of candidateTokens) {
        if (!GENERIC_RESOLUTION_TOKENS.has(token) && srcTokens.has(token)) overlap++;
      }
      return { fp, overlap };
    });
    const maxOverlap = Math.max(...overlapScores.map(x => x.overlap));
    if (maxOverlap <= 0) return null;
    const bestMatches = overlapScores.filter(x => x.overlap === maxOverlap);
    return {
      chosen: bestMatches.length === 1 ? bestMatches[0].fp : null,
      best: bestMatches,
    };
  }

  function narrowCCandidates(
    matches: string[],
    srcFilePath: string,
    srcLanguage: SupportedLanguages,
    srcName: string,
    dstName: string,
  ): string[] {
    if (matches.length <= 1) return matches;

    // C# partial class narrowing: multiple files may define the same class via
    // partial class (e.g. JsonReader.cs + JsonReader.Async.cs both define JsonReader).
    // Prefer the canonical file whose stem exactly matches the destination class name
    // over variant files that have additional dot-segments in the stem.
    if (srcLanguage === SupportedLanguages.CSharp) {
      const dstNameLower = dstName.toLowerCase();
      const canonicalMatches = matches.filter(fp => candidateStem(fp) === dstNameLower);
      if (canonicalMatches.length === 1) return canonicalMatches;
    }

    if (srcLanguage === SupportedLanguages.Java || srcLanguage === SupportedLanguages.SAS) {
      const srcParts = srcFilePath.replace(/\\/g, '/').split('/');
      const withProximity = matches.map(fp => {
        const fpParts = fp.replace(/\\/g, '/').split('/');
        let common = 0;
        while (common < srcParts.length && common < fpParts.length && srcParts[common] === fpParts[common]) {
          common++;
        }
        return { fp, common };
      });
      const maxCommon = Math.max(...withProximity.map(x => x.common));
      const proximityMatches = withProximity.filter(x => x.common === maxCommon).map(x => x.fp);
      if (proximityMatches.length === 1) return proximityMatches;
    }

    if (srcLanguage !== SupportedLanguages.C && srcLanguage !== SupportedLanguages.CPlusPlus) return matches;

    let narrowed = matches;
    const implExts = ['.c', '.cpp', '.cc', '.cxx'];
    const implMatches = narrowed.filter(fp => implExts.some(ext => fp.endsWith(ext)));
    if (implMatches.length === 1) narrowed = implMatches;

    if (narrowed.length <= 1) return narrowed;

    const srcParts = srcFilePath.replace(/\\/g, '/').split('/');
    const withProximity = narrowed.map(fp => {
      const fpParts = fp.replace(/\\/g, '/').split('/');
      let common = 0;
      while (common < srcParts.length && common < fpParts.length && srcParts[common] === fpParts[common]) {
        common++;
      }
      return { fp, common };
    });
    const maxCommon = Math.max(...withProximity.map(x => x.common));
    const proximityMatches = withProximity.filter(x => x.common === maxCommon).map(x => x.fp);
    if (proximityMatches.length === 1) return proximityMatches;

    const callerAligned = pickCallerAlignedCandidate(narrowed, srcName, dstName);
    if (callerAligned?.chosen) return [callerAligned.chosen];

    const callerAlignedCandidates = pickCallerAlignedCandidate(matches, srcName, dstName);
    if (callerAlignedCandidates?.best) {
      const implAlignedMatches = callerAlignedCandidates.best
        .map(match => match.fp)
        .filter(fp => ['.c', '.cpp', '.cc', '.cxx'].some(ext => fp.endsWith(ext)));
      if (implAlignedMatches.length === 1) return implAlignedMatches;
    }

    return narrowed;
  }

  // Receiver types resolve exact members, in the defining file's import context
  // as well (factory returns and inheritance).
  // A Go qualifier names an aliased import, or an unaliased one by its last path element.
  function goImportForQualifier(summary: FileSummary | undefined, qualifier: string): string | undefined {
    const aliased = summary?.importAliases?.[qualifier];
    if (aliased) return aliased;
    const named = [...new Set((summary?.imports ?? []).map(imp => imp.dstName)
      .filter(dst => dst.split('/').pop() === qualifier))];
    return named.length === 1 ? named[0] : undefined;
  }
  /**
   * The names a Scala file's imports bring into scope. Imports are summarized
   * as written per selector: `a.b.X`, `a.b` (from `a.b._`), and from braces or
   * Scala 3 `a.b.X => Y` / `a.b.X as Y` (renamed), `a.b.X => _` (hidden),
   * `a.b._` / `a.b.*` (wildcard).
   */
  function scalaImportScope(summary: FileSummary | undefined): {
    named: Map<string, string[]>; wildcards: Set<string>; excluded: Set<string>;
  } {
    const named = new Map<string, string[]>();
    const wildcards = new Set<string>();
    const excluded = new Set<string>();
    const bind = (local: string, fq: string) => named.set(local, [...(named.get(local) ?? []), fq]);
    for (const { dstName } of summary?.imports ?? []) {
      const renamed = /^(\S+?)\s*=>\s*(\S+)$/.exec(dstName) ?? /^(\S+)\s+as\s+(\S+)$/.exec(dstName);
      if (renamed) {
        // The original name is not imported, not even by a wildcard beside it.
        excluded.add(renamed[1]);
        if (renamed[2] !== '_') bind(renamed[2], renamed[1]);
        continue;
      }
      if (dstName.endsWith('._') || dstName.endsWith('.*')) {
        wildcards.add(dstName.slice(0, -2));
        continue;
      }
      // `a.b.X`, or the package of a top-level wildcard (`import a.b._`).
      wildcards.add(dstName);
      if (dstName.includes('.')) bind(dstName.slice(dstName.lastIndexOf('.') + 1), dstName);
    }
    return { named, wildcards, excluded };
  }
  function findReceiverProviders(context: string, rawType: string): Array<{ fp: string; type: string }> {
    const summary = summaries.get(context);
    const language = summary?.language ?? languageFromPath(context);
    const parts = rawType.split('.');
    let type = parts.pop()!;
    if (language === SupportedLanguages.Scala) {
      const candidates = (symbolToFiles.get(type) ?? []).filter(fp => summaries.get(fp)?.language === language);
      if (parts.length) return candidates.filter(fp => summaries.get(fp)?.receiverPackage === parts.join('.')).map(fp => ({ fp, type }));
      const scope = scalaImportScope(summary);
      // An explicit import binds the name, renamed (`{Target => T}`) or not, to
      // that type only: never a same-named type of this package.
      const named = scope.named.get(type);
      if (named) {
        return named.flatMap(fq => {
          const dot = fq.lastIndexOf('.');
          const original = fq.slice(dot + 1);
          return (symbolToFiles.get(original) ?? [])
            .filter(fp => summaries.get(fp)?.language === language && dot > 0 && summaries.get(fp)?.receiverPackage === fq.slice(0, dot))
            .map(fp => ({ fp, type: original }));
        });
      }
      if (fileHasSymbol.get(context)?.has(type)) return [{ fp: context, type }];
      // Otherwise only a type in scope: this package's, or a wildcard-imported
      // package's (`import p._` is summarized as `p`) unless the import renamed
      // or hid it (`{Target => T, _}`, `{Target => _, _}`). Never a same-named
      // type elsewhere, which is how `Option` would land on an unrelated class.
      return candidates.filter(fp => {
        const pkg = summaries.get(fp)?.receiverPackage;
        if (pkg === summary?.receiverPackage) return true;
        return pkg !== undefined && scope.wildcards.has(pkg) && !scope.excluded.has(`${pkg}.${type}`);
      }).map(fp => ({ fp, type }));
    }
    if (language === SupportedLanguages.Java) return javaReceiverProviders(context, summary, parts, type);
    const binding = importBindingsByLocal.get(context)?.get(type);
    // A same-named declaration in the importing file can only be a nested
    // shadow (a `namespace` class); without scope facts, guess neither.
    if (binding && parts.length === 0 && fileHasSymbol.get(context)?.has(type)) return [];
    if (binding && parts.length === 0) {
      const files = resolveImportTargets(context, language!, binding.pkg, binding.pkg, 'types');
      type = binding.imported === 'default'
        ? (files.length === 1 ? filePublicNames.get(files[0])?.get('default') ?? type : type)
        : binding.imported;
      return files.filter(fp => fileHasSymbol.get(fp)?.has(type)).map(fp => ({ fp, type }));
    }
    if (parts.length && language === SupportedLanguages.Go) {
      const prefix = parts.join('.');
      const alias = goImportForQualifier(summary, prefix);
      if (!alias) return [];
      return resolveImportQualifierTargets(context, language, alias)
        .filter(fp => fileHasSymbol.get(fp)?.has(type)).map(fp => ({ fp, type }));
    }
    // A namespace-qualified TS type must not degrade to an unrelated bare type.
    if (parts.length && language === SupportedLanguages.TypeScript) return [];
    if (!parts.length && fileHasSymbol.get(context)?.has(type)) return [{ fp: context, type }];
    // TypeScript: a type neither defined here nor imported is a global or
    // library type (`Map`, `Response`), never a same-named class elsewhere.
    if (language !== SupportedLanguages.Go) return [];
    const compatible = (fp: string): boolean => importLanguageCompatible(language, fileLanguage.get(fp) ?? languageFromPath(fp));
    return (symbolToFiles.get(type) ?? []).filter(compatible)
      .filter(fp => goPackageKey(fp) === goPackageKey(context)).map(fp => ({ fp, type }));
  }

  /**
   * A Java type name in scope, in the order Java looks: this file, a
   * single-type import, this package, an on-demand import (`import p.*`,
   * summarized as `p`). The first that has it decides; several files there
   * mean no type. A qualified `p.T` names its package (or `Outer.T` a nested
   * type of a type in scope). Summaries without Java facts have no package,
   * so they provide nothing.
   */
  function javaReceiverProviders(context: string, summary: FileSummary | undefined, parts: string[], type: string): Array<{ fp: string; type: string }> {
    const inPackage = (pkg: string, name: string): string[] => (symbolToFiles.get(name) ?? [])
      .filter(fp => summaries.get(fp)?.language === SupportedLanguages.Java && summaries.get(fp)?.receiverPackage === pkg);
    const named = (fq: string): string[] => {
      const dot = fq.lastIndexOf('.');
      if (dot <= 0) return [];
      const prefix = fq.slice(0, dot);
      const name = fq.slice(dot + 1);
      const direct = inPackage(prefix, name);
      if (direct.length) return direct;
      // `p.Outer.T`: a nested type is declared in its outer type's file.
      const outer = prefix.lastIndexOf('.');
      return outer > 0 ? inPackage(prefix.slice(0, outer), name).filter(fp => fileHasSymbol.get(fp)?.has(prefix.slice(outer + 1))) : [];
    };
    const as = (fps: string[]) => [...new Set(fps)].map(fp => ({ fp, type }));
    if (parts.length) {
      const packaged = named(`${parts.join('.')}.${type}`);
      if (packaged.length || parts.length > 1) return as(packaged);
      const outer = receiverProviders(context, parts[0]);
      return outer.length === 1 && fileHasSymbol.get(outer[0].fp)?.has(type) ? [{ fp: outer[0].fp, type }] : [];
    }
    if (fileHasSymbol.get(context)?.has(type)) return [{ fp: context, type }];
    const imports = (summary?.imports ?? []).map(i => i.dstName);
    // A single-type import shadows the package, even of a type not in the repo.
    const single = imports.filter(fq => fq.endsWith(`.${type}`));
    if (single.length) return as(single.flatMap(named));
    const samePackage = summary?.receiverPackage ? inPackage(summary.receiverPackage, type) : [];
    if (samePackage.length) return as(samePackage);
    return as(imports.flatMap(pkg => inPackage(pkg, type)));
  }

  const receiverProviderCache = new Map<string, Array<{ fp: string; type: string }>>();
  function receiverProviders(context: string, type: string): Array<{ fp: string; type: string }> {
    const key = `${context}\0${type}`;
    if (!receiverProviderCache.has(key)) receiverProviderCache.set(key, findReceiverProviders(context, type));
    return receiverProviderCache.get(key)!;
  }
  const goReceiverFiles = new Map<string, string[]>();
  const goPackageKey = (fp: string): string => `${nodePath.dirname(fp)}\0${summaries.get(fp)?.receiverPackage ?? ''}`;
  for (const [fp, summary] of summaries) if (summary.language === SupportedLanguages.Go) {
    const key = goPackageKey(fp);
    const files = goReceiverFiles.get(key) ?? [];
    files.push(fp);
    goReceiverFiles.set(key, files);
  }

  function receiverMembers(context: string, type: string, member: string, seen = new Set<string>()): Array<{ fp: string; key: string }> {
    const providers = receiverProviders(context, type);
    if (providers.length !== 1) return [];
    const { fp, type: name } = providers[0];
    const marker = `${fp}\0${name}`;
    if (seen.has(marker)) return [];
    const nextSeen = new Set(seen).add(marker);
    const key = `${name}.${member}`;
    if (summaries.get(fp)?.language === SupportedLanguages.Go) {
      const targets = (qualifiedToFiles.get(key) ?? [])
        .filter(candidate => summaries.get(candidate)?.language === SupportedLanguages.Go && goPackageKey(candidate) === goPackageKey(fp))
        .flatMap(candidate => (fileQKeys.get(candidate)?.get(member) ?? [])
          .filter(q => q === key).map(() => ({ fp: candidate, key })));
      return targets.length === 1 ? targets : [];
    }
    const exact = (fileQKeys.get(fp)?.get(member) ?? []).filter(q => q === key);
    const java = summaries.get(fp)?.language === SupportedLanguages.Java;
    // Multiple definitions include overloads. Do not guess a signature. Java
    // overloads in one class are one node (one key), so they are one target.
    if (exact.length) return exact.length === 1 || java ? [{ fp, key }] : [];
    const parents = (summaries.get(fp)?.receiverHeritage ?? []).filter(([child]) => child === name);
    if (java) {
      // The nearest declaration: the superclass chain (listed first), then
      // each interface in declaration order.
      for (const [, parent] of parents) {
        const found = receiverMembers(fp, parent, member, nextSeen);
        if (found.length) return found;
      }
      return [];
    }
    const inherited = parents.flatMap(([, parent]) => receiverMembers(fp, parent, member, nextSeen));
    const unique = new Map(inherited.map(target => [`${target.fp}\0${target.key}`, target]));
    return [...unique.values()];
  }

  /**
   * Java `a.getB().m()`: the receiver after each call in `chain`, from the
   * declared return type of the one method that call resolves to. Stops at the
   * first step that does not resolve or does not return a class type.
   */
  function javaChainReceiver(context: string, type: string, chain: string[]): { context: string; type: string } | undefined {
    let at = { context, type };
    for (const method of chain) {
      const targets = receiverMembers(at.context, at.type, method);
      if (targets.length !== 1) return;
      const { fp, key } = targets[0];
      const returns = new Set((summaries.get(fp)?.receiverFactories ?? []).filter(([fn]) => fn === key).map(([, t]) => t));
      const [returned] = returns;
      // Overloads with different results (or a primitive one) are not guessed.
      if (returns.size !== 1 || !returned) return;
      at = { context: fp, type: returned };
    }
    return at;
  }

  /** The one member a typed CALLS relationship names, if it names exactly one. */
  function typedCallTarget(srcFilePath: string, rel: ParsedRelationship): { fp: string; key: string } | undefined {
    const receiver = rel.receiverType
      ? rel.receiverChain ? javaChainReceiver(srcFilePath, rel.receiverType, rel.receiverChain) : { context: srcFilePath, type: rel.receiverType }
      : factoryReceiver(srcFilePath, rel.receiverFactory!);
    const member = rel.dstName.slice(rel.dstName.lastIndexOf('.') + 1);
    const targets = receiver ? receiverMembers(receiver.context, receiver.type, member) : [];
    return targets.length === 1 ? targets[0] : undefined;
  }

  function factoryReceiver(context: string, factory: string): { context: string; type: string } | undefined {
    const summary = summaries.get(context);
    const language = summary?.language;
    let name = factory;
    let pool = [context];
    if (language === SupportedLanguages.Go) {
      const dot = factory.lastIndexOf('.');
      if (dot >= 0) {
        name = factory.slice(dot + 1);
        const alias = goImportForQualifier(summary, factory.slice(0, dot));
        pool = alias ? resolveImportQualifierTargets(context, language, alias) : [];
      } else pool = goReceiverFiles.get(goPackageKey(context)) ?? [];
    } else {
      const owner = factory.replace(/\.apply$/, '');
      const providers = receiverProviders(context, owner);
      if (providers.length !== 1) return;
      pool = [providers[0].fp];
      name = factory.endsWith('.apply') ? `${providers[0].type}.apply` : providers[0].type;
    }
    const matches = pool.flatMap(fp => (summaries.get(fp)?.receiverFactories ?? [])
      .filter(([fn]) => fn === name).map(([, type]) => ({ context: fp, type })));
    return matches.length === 1 && matches[0].type ? matches[0] : undefined;
  }

  // ── Main resolution loop ───────────────────────────────────────────


  /**
   * The files of `pool` that define `name`, in `pool` order -- what a loop over
   * the pool asking `fileHasSymbol` returns, but walking whichever side is
   * smaller. A source file's import set grows with the repository (a common
   * stem matches more files), and walking it once per call made resolution
   * quadratic.
   */
  function definersIn(pool: Set<string>, order: Map<string, number>, name: string): string[] {
    const definers = symbolToFiles.get(name);
    if (!definers) return [];
    if (definers.length >= pool.size) return [...pool].filter(fp => fileHasSymbol.get(fp)?.has(name));
    return definers.filter(fp => pool.has(fp)).sort((a, b) => order.get(a)! - order.get(b)!);
  }

  function fileDefinesQualifiedMember(filePath: string, qualifierPart: string, memberPart: string): boolean {
    const qks = fileQKeys.get(filePath)?.get(memberPart) ?? [];
    return qks.includes(`${qualifierPart}.${memberPart}`);
  }

  function sameScopeDefines(result: FileParseResult, srcName: string, dstName: string): boolean {
    const sourceEntities = result.entities.filter(e => e.name === srcName || qualifiedKey(e) === srcName);
    if (sourceEntities.length === 0) return false;
    return result.entities.some(definition =>
      definition.name === dstName && sourceEntities.some(source =>
        definition.lineStart >= source.lineStart && definition.lineEnd <= source.lineEnd,
      ),
    );
  }

  function importedPhpType(srcFilePath: string, rel: ParsedRelationship): {
    entries: Array<{ filePath: string; typeName: string }>;
    memberName?: string;
  } | undefined {
    if (rel.predicate === 'IMPORTS' && (rel.importKind === 'function' || rel.importKind === 'const')) {
      return undefined;
    }
    const parts = rel.dstName.split('.');
    if (rel.predicate === 'CALLS' && parts.length === 1 && rel.phpCallKind !== 'constructor') {
      return undefined;
    }
    const imports = phpFqcnImportsByLocal.get(srcFilePath);
    const local = parts[0].toLowerCase();
    if (!imports?.has(local)) return undefined;
    const fqcn = imports.get(local);
    if (!fqcn) return { entries: [] };
    return {
      entries: phpFqcnToTypes.get(fqcn) ?? [],
      memberName: parts.length > 1 ? parts[parts.length - 1] : undefined,
    };
  }

  const resolved: ResolvedEdge[] = [];

  for (const result of results) {
    const srcFilePath = result.filePath;
    const srcLanguage = result.language;
    const pythonHasRelativeModuleImport = srcLanguage === SupportedLanguages.Python &&
      result.relationships.some(rel => rel.predicate === 'IMPORTS' && rel.importRaw?.startsWith('.'));

    // Build the set of file paths this file explicitly imports.
    const importedFilePaths = new Set<string>();
    for (const rel of result.relationships) {
      if (rel.predicate !== 'IMPORTS') continue;
      if (pythonHasRelativeModuleImport && rel.importRaw === undefined) continue;
      const phpType = srcLanguage === SupportedLanguages.PHP
        ? importedPhpType(srcFilePath, rel)
        : undefined;
      if (phpType) {
        for (const entry of phpType.entries) importedFilePaths.add(entry.filePath);
        continue;
      }
      // A helper-literal import is inferred and binds no names: it becomes an
      // IMPORTS edge below but does not widen call-resolution scope.
      if (rel.importVia === 'helper') continue;
      for (const fp of resolveImportTargets(srcFilePath, srcLanguage, rel.dstName, rel.importRaw)) {
        importedFilePaths.add(fp);
      }
    }

    // Build one-hop transitive import set.
    // Handles re-exports: baz.ts → index.ts (re-exports from bar.ts) → bar.ts
    const transitiveFilePaths = new Set<string>();
    for (const fp of importedFilePaths) {
      const fpSummary = summaries.get(fp);
      if (!fpSummary) continue;
      for (const rel of fpSummary.imports) {
        if (rel.importVia === 'helper') continue;
        for (const transitiveFp of resolveImportTargets(fp, fpSummary.language, rel.dstName, rel.importRaw)) {
          if (!importedFilePaths.has(transitiveFp)) transitiveFilePaths.add(transitiveFp);
        }
      }
    }
    // Position of each file in the two sets, so `definersIn` can return its
    // matches in set order without walking the whole set per relationship.
    const importedOrder = new Map([...importedFilePaths].map((fp, i) => [fp, i]));
    const transitiveOrder = new Map([...transitiveFilePaths].map((fp, i) => [fp, i]));

    const typedCalls = result.receiverTypedCalls?.length ? new Set(result.receiverTypedCalls) : undefined;
    let typedByCall: Map<string, ParsedRelationship[]> | undefined;
    // The typed relationships of a call's sites: same caller, same member name.
    const typedSites = (srcName: string, member: string): ParsedRelationship[] => {
      if (!typedByCall) {
        typedByCall = new Map();
        for (const r of result.relationships) {
          if (r.predicate !== 'CALLS' || !r.receiverType) continue;
          const key = `${r.srcName}\0${r.dstName.slice(r.dstName.lastIndexOf('.') + 1)}`;
          const list = typedByCall.get(key);
          if (list) list.push(r); else typedByCall.set(key, [r]);
        }
      }
      return typedByCall.get(`${srcName}\0${member}`) ?? [];
    };

    for (const rel of result.relationships) {
      if (rel.predicate !== 'CALLS' && rel.predicate !== 'EXTENDS' && rel.predicate !== 'REFERENCES' && rel.predicate !== 'IMPORTS') continue;

      // Resolve Scala/Java dotted class imports (e.g. "ix.memory.model.ClaimId")
      // to the actual indexed entity node in the defining file.
      // Uses package-path lookup: extract package ("ix.memory.model") and entity
      // name ("ClaimId"), find files registered under that package, then find
      // the one that defines the entity.
      if (rel.predicate === 'IMPORTS') {
        const phpType = srcLanguage === SupportedLanguages.PHP
          ? importedPhpType(srcFilePath, rel)
          : undefined;
        if (phpType) {
          if (phpType.entries.length === 1) {
            const fp = phpType.entries[0].filePath;
            resolved.push({
              srcFilePath,
              srcName: rel.srcName,
              dstFilePath: fp,
              dstName: rel.dstName,
              dstQualifiedKey: fileEntityName(fp),
              predicate: 'IMPORTS',
              confidence: 0.9,
              tier: 'import',
            });
            stats.resolvedImport++;
          } else if (phpType.entries.length > 1) {
            stats.skippedAmbiguous++;
          }
          continue;
        }
        if (result.language === SupportedLanguages.Scala || result.language === SupportedLanguages.Java) {
          const dstName = rel.dstName;
          const lastDot = dstName.lastIndexOf('.');
          if (lastDot !== -1) {
            const entityName = dstName.slice(lastDot + 1);
            if (entityName && entityName !== '_') {
              const pkgPath = dstName.slice(0, lastDot);
              const pkgFiles = packageToFiles.get(pkgPath) ?? [];
              const matchFiles = pkgFiles.filter(fp => fp !== srcFilePath && fileHasSymbol.get(fp)?.has(entityName));
              if (matchFiles.length === 1) {
                const fp = matchFiles[0];
                const dstQualifiedKey = bestQKey(fileQKeys, fp, entityName);
                if (dstQualifiedKey !== null) {
                  resolved.push({ srcFilePath, srcName: rel.srcName, dstFilePath: fp, dstName, dstQualifiedKey, predicate: 'IMPORTS', confidence: 0.9, tier: 'import' });
                  stats.resolvedImport++;
                  continue;
                }
              }
            }
          }
        }

        const importMatches = pythonHasRelativeModuleImport && rel.importRaw === undefined
          ? []
          : resolveImportTargets(srcFilePath, result.language, rel.dstName, rel.importRaw);
        // A helper-literal import (`importModule(resolve("../x/dist/y.js"))`) is
        // inferred from a string, so it is kept only when that path names
        // exactly one tracked file — never through the package fallbacks below.
        if (rel.importVia === 'helper' && importMatches.length !== 1) {
          if (importMatches.length > 1) stats.skippedAmbiguous++;
          continue;
        }
        if (importMatches.length === 1) {
          const fp = importMatches[0];
          resolved.push({
            srcFilePath,
            srcName: rel.srcName,
            dstFilePath: fp,
            dstName: rel.dstName,
            dstQualifiedKey: fileEntityName(fp),
            predicate: 'IMPORTS',
            confidence: 0.9,
            tier: 'import',
          });
          stats.resolvedImport++;
          continue;
        } else if (importMatches.length > 1) {
          stats.skippedAmbiguous++;
          continue;
        }
        // importMatches.length === 0: no in-repo file resolves the import.
        // Cross-repo package import (co-ingest): the specifier names another
        // co-ingested member's published package (packageOf), so emit an IMPORTS
        // edge to that member's entry file. This couples genuinely-dependent repos
        // even when the consumer uses a dynamic/property API that resolves no
        // symbol call (e.g. ora -> chalk via `chalk[color]`). Ground truth: the
        // import specifier IS the dependency. Down-weighted by G3 at the map layer;
        // the post-resolution dep gate keeps it (the same import seeds repoDeps).
        // No-op for single-repo (no repoOf/entryFileOf).
        if (repoOf && packageOf && entryFileOf && !(pythonHasRelativeModuleImport && rel.importRaw === undefined)) {
          const srcRepo = repoOf(srcFilePath);
          const mod = typeof rel.importRaw === 'string' ? rel.importRaw : rel.dstName;
          const depRepo = mod ? packageOf(mod) : undefined;
          if (srcRepo !== undefined && depRepo !== undefined && depRepo !== srcRepo) {
            const entryFp = entryFileOf.get(depRepo);
            if (entryFp && entryFp !== srcFilePath) {
              resolved.push({ srcFilePath, srcName: rel.srcName, dstFilePath: entryFp, dstName: rel.dstName, dstQualifiedKey: fileEntityName(entryFp), predicate: 'IMPORTS', confidence: 0.7, tier: 'import' });
              stats.resolvedImport++;
              continue;
            }
          }
        }
        // if dstName is a PascalCase symbol (class/function name captured via
        // import.name from "from X import ClassName"), fall through to Tier 2/3
        // symbol resolution so the edge connects to the actual class node rather than a file.
        if (srcLanguage !== SupportedLanguages.Python || !/^[A-Z]/.test(rel.dstName)) continue;
        // fall through to Tier 1b → Tier 2 → Tier 3 below
      }

      const phpType = srcLanguage === SupportedLanguages.PHP
        ? importedPhpType(srcFilePath, rel)
        : undefined;
      if (phpType) {
        if (phpType.entries.length === 1) {
          const entry = phpType.entries[0];
          const plainName = phpType.memberName ?? entry.typeName;
          const preferredQKey = phpType.memberName
            ? `${entry.typeName}.${phpType.memberName}`
            : entry.typeName;
          const dstQualifiedKey = bestPhpQKey(fileQKeys, entry.filePath, plainName, preferredQKey);
          if (dstQualifiedKey !== null) {
            resolved.push({
              srcFilePath,
              srcName: rel.srcName,
              dstFilePath: entry.filePath,
              dstName: rel.dstName,
              dstQualifiedKey,
              predicate: rel.predicate,
              confidence: 0.9,
              tier: 'binding',
              ...(rel.phpCallKind ? { phpCallKind: rel.phpCallKind } : {}),
            });
            stats.resolvedQualifier++;
          }
        } else if (phpType.entries.length > 1) {
          stats.skippedAmbiguous++;
        }
        continue;
      }

      // A typed receiver resolves to its exact member. Otherwise a receiver-only
      // relationship stops here, and any other resolves by its own name below.
      if (rel.predicate === 'CALLS' && (rel.receiverType || rel.receiverFactory)) {
        const target = typedCallTarget(srcFilePath, rel);
        if (target) {
          resolved.push({ srcFilePath, srcName: rel.srcName, dstFilePath: target.fp, dstName: rel.dstName,
            dstQualifiedKey: target.key, predicate: 'CALLS', confidence: 0.95, tier: 'type' });
          stats.resolvedType = (stats.resolvedType ?? 0) + 1;
          continue;
        }
        if (rel.receiverOnly) continue;
      }
      const origDstName = rel.dstName;
      // Z: resolve a renamed-import call by the provider's public symbol, but keep the
      // ORIGINAL local name on the emitted edge (buildPatchWithResolution maps the edge
      // back to the source call by name). No-op unless this is a renamed-import call.
      const dstName = (rel.predicate === 'CALLS' ? callBindings.get(srcFilePath)?.get(rel.dstName) : undefined) ?? rel.dstName;
      const srcName = rel.srcName;
      const binding = rel.importBinding === false
        ? undefined
        : importBindingsByLocal.get(srcFilePath)?.get(origDstName);
      const configuredBindingTargets = binding &&
        (srcLanguage === SupportedLanguages.JavaScript || srcLanguage === SupportedLanguages.TypeScript) &&
        !binding.pkg.startsWith('./') &&
        !binding.pkg.startsWith('../')
          ? opts?.resolveModuleSpecifier?.(
              srcFilePath,
              binding.pkg,
              rel.predicate === 'CALLS' ? 'runtime' : 'types',
            )
          : undefined;

      // Tier 1: same-file — already correct in buildPatch, skip here. Check the
      // call-site name before any import binding rewrite so a local shadow wins.
      // Without an import binding, preserve the existing file-wide preference.
      const hasSameFileDefinition = fileHasSymbol.get(srcFilePath)?.has(origDstName) === true;
      // Java: when every site of this call has a typed receiver and each one
      // resolved to a member in another file, a same-named method here is
      // some other class's. The call goes to a typed target (which its typed
      // relationship writes anyway), never to this file.
      if (hasSameFileDefinition && rel.predicate === 'CALLS' && typedCalls?.has(`${rel.srcName}\0${rel.dstName}`)) {
        const sites = typedSites(rel.srcName, rel.dstName).map(site => typedCallTarget(srcFilePath, site));
        if (sites.length && sites.every(t => t && t.fp !== srcFilePath)) {
          resolved.push({ srcFilePath, srcName, dstFilePath: sites[0]!.fp, dstName: origDstName,
            dstQualifiedKey: sites[0]!.key, predicate: 'CALLS', confidence: 0.95, tier: 'type' });
          stats.resolvedType = (stats.resolvedType ?? 0) + 1;
          continue;
        }
      }
      if (
        hasSameFileDefinition &&
        (!binding || (rel.importBinding !== true && sameScopeDefines(result, srcName, origDstName)))
      ) continue;
      if (rel.importBinding === false) continue;

      // Lexical scope (JS/TS) — see JS_AMBIENT_CALLEES. An unbound bare call to
      // a test-runner / runtime global has no in-repo target beyond the files
      // the caller imports, whatever shares its name elsewhere; it stops after
      // the import tier below. The import tier still runs because CommonJS
      // destructuring (`const { test } = require('./helpers')`) records no
      // import binding. (`obj.describe()` is a member call, not the global.)
      const srcIsJsTs = srcLanguage === SupportedLanguages.JavaScript || srcLanguage === SupportedLanguages.TypeScript;
      const unboundAmbientCall = srcIsJsTs && rel.predicate === 'CALLS' && rel.bareCall === true &&
        !binding && JS_AMBIENT_CALLEES.has(origDstName);

      let bindingProviderFiles: string[] | undefined;
      if (rel.predicate === 'CALLS' || rel.predicate === 'EXTENDS' || rel.predicate === 'REFERENCES') {
        if (binding) {
          const providerFiles = bindingProviderFiles = [...new Set(resolveImportTargets(
            srcFilePath,
            srcLanguage,
            binding.pkg,
            binding.pkg,
            rel.predicate === 'CALLS' ? 'runtime' : 'types',
          ))];
          if (
            configuredBindingTargets !== undefined &&
            providerFiles.length === 1 &&
            fileHasSymbol.get(providerFiles[0])?.has(binding.imported)
          ) {
            const fp = providerFiles[0];
            const dstQualifiedKey = bestQKey(fileQKeys, fp, binding.imported);
            if (dstQualifiedKey !== null) {
              resolved.push({
                srcFilePath,
                srcName,
                dstFilePath: fp,
                dstName: origDstName,
                dstQualifiedKey,
                predicate: rel.predicate,
                confidence: 0.9,
                tier: 'binding',
              });
              continue;
            }
          }
          const publicMatches: Array<{ fp: string; local: string }> = [];
          for (const fp of providerFiles.length === 1 ? providerFiles : []) {
            // `imported` is the literal sentinel 'default' for a default import, never a
            // real export name, so a provider member that happens to be *called* `default`
            // (a method, getter, or static) must not satisfy the fallback.
            const local = filePublicNames.get(fp)?.get(binding.imported)
              ?? (binding.imported !== 'default' && fileHasSymbol.get(fp)?.has(binding.imported)
                ? binding.imported
                : undefined);
            if (local && fileHasSymbol.get(fp)?.has(local)) publicMatches.push({ fp, local });
          }
          if (publicMatches.length === 1) {
            const { fp, local } = publicMatches[0];
            const dstQualifiedKey = bestQKey(fileQKeys, fp, local);
            if (dstQualifiedKey !== null) {
              resolved.push({
                srcFilePath,
                srcName,
                dstFilePath: fp,
                dstName: origDstName,
                dstQualifiedKey,
                predicate: rel.predicate,
                confidence: 0.9,
                tier: 'binding',
              });
              continue;
            }
          }
        }
      }

      // Reachability filter for every cross-file tier below:
      //   - A bare call (`foo()`, rel.bareCall; set by the parser for JS/TS,
      //     Python, Rust and PHP) is resolved by lexical scope, so
      //     it can only denote a module-scope declaration. A class member of the
      //     same name (`SampleCommand.describe`) is reachable only through a
      //     receiver and is never a candidate.
      //   - A name bound by an explicit import of a bare package specifier that
      //     resolves to no in-repo file (`import { describe } from 'vitest'`)
      //     comes from THAT package. Only a file plausibly inside it may match:
      //     one in the co-ingested repo that publishes it (packageOf), else one
      //     under a directory named after it (`packages/utils/**` for
      //     `@acme/utils`, `packages/babel-types/**` for `@babel/types`). This
      //     keeps monorepo workspace imports resolving while an external
      //     package's names stop landing on unrelated same-named symbols (JS/TS only).
      // The global tier applies the first rule differently -- see there.
      const bareCall = rel.predicate === 'CALLS' && rel.bareCall === true;
      const boundPackage = srcIsJsTs && binding && isBarePackageSpecifier(binding.pkg) &&
        (bindingProviderFiles?.length ?? 0) === 0 && !(configuredBindingTargets?.length)
        ? binding.pkg
        : undefined;
      const boundPackageRepo = boundPackage !== undefined ? packageOf?.(boundPackage) : undefined;
      const definesAtModuleScope = (fp: string): boolean =>
        (fileQKeys.get(fp)?.get(dstName) ?? []).includes(dstName);
      const insideBoundPackage = (fp: string): boolean => {
        if (boundPackage === undefined) return true;
        if (boundPackageRepo !== undefined && repoOf) return repoOf(fp) === boundPackageRepo;
        return fileIsInsidePackage(fp, boundPackage, opts?.packageDirOf);
      };
      const reachable = (fp: string): boolean =>
        (!bareCall || definesAtModuleScope(fp)) && insideBoundPackage(fp);
      // A bare call's target is the module-scope key, even when the file also
      // has a same-named member that would make bestQKey ambiguous.
      const targetQKey = (fp: string): string | null => bareCall ? dstName : bestQKey(fileQKeys, fp, dstName);

      // Tier 1b: qualifier-assisted (confidence 0.9 / 0.7)
      // For dotted names like "NodeKind.Decision" (emitted by field_expression queries):
      // find the file defining the qualifier, then check it also defines the member.
      // This breaks ties where both NodeKind.Decision and SourceType.Decision exist.
      const qualDot = dstName.lastIndexOf('.');
      if (qualDot !== -1) {
        const qualifierPart = dstName.slice(0, qualDot);
        const memberPart = dstName.slice(qualDot + 1);
        if (memberPart && qualifierPart) {
          const elixirAliasedModule = srcLanguage === SupportedLanguages.Elixir ? result.importAliases?.[qualifierPart]: undefined;
          const aliasedImportMatches = srcLanguage === SupportedLanguages.Go ? resolveImportQualifierTargets(srcFilePath, srcLanguage, result.importAliases?.[qualifierPart] ?? '')
          : elixirAliasedModule ? (symbolToFiles.get(elixirAliasedModule) ?? []).filter(fp => fp !== srcFilePath)
          : [];
          // Try import-scoped qualifier first
          const qualifierSearchPool = aliasedImportMatches.length > 0
            ? aliasedImportMatches
            : [...importedFilePaths];
          const qualImportMatches: string[] = [];
          for (const fp of qualifierSearchPool) {
            if (fileDefinesQualifiedMember(fp, qualifierPart, memberPart) || fileHasSymbol.get(fp)?.has(qualifierPart)) {
              qualImportMatches.push(fp);
            }
          }
          if (qualImportMatches.length === 0 && aliasedImportMatches.length > 0) {
            for (const fp of aliasedImportMatches) {
              if (fileHasSymbol.get(fp)?.has(memberPart)) qualImportMatches.push(fp);
            }
          }
          if (qualImportMatches.length === 1) {
            const qfp = qualImportMatches[0];
            const preferredQKey = elixirAliasedModule ? `${elixirAliasedModule}.${memberPart}` : aliasedImportMatches.length > 0 ? undefined : `${qualifierPart}.${memberPart}`;
            if (fileHasSymbol.get(qfp)?.has(memberPart)) {
              const dstQualifiedKey = bestQKey(fileQKeys, qfp, memberPart, preferredQKey);
              if (dstQualifiedKey !== null) {
                // dstName must match rel.dstName so buildPatchWithResolution can look it up
                resolved.push({ srcFilePath, srcName, dstFilePath: qfp, dstName: origDstName, dstQualifiedKey, predicate: rel.predicate, confidence: 0.9, tier: 'qualifier' });
              }
            }
            continue;
          }
          // Global qualifier fallback — check files that define the qualified member.
          // Commodity gate (mirrors the bare-name global fallback below): a member
          // call like `client.map()` / `cache.get()` resolves on the member name
          // across module/repo boundaries; for builtin/stdlib member names that is a
          // false positive, so skip the global fallback (the import-scoped qualifier
          // tier above already had its chance). Favor under-connection.
          if (COMMODITY_CALLEE_NAMES.has(memberPart)) {
            stats.skippedAmbiguous++;
            continue;
          }
          // Every file that defines `qualifier.member` -- the whole index, not
          // just this batch (a lookup, where it was a scan per call).
          const qualGlobalMatches = (qualifiedToFiles.get(`${qualifierPart}.${memberPart}`) ?? [])
            .filter(fp => fp !== srcFilePath
              && importLanguageCompatible(srcLanguage, fileLanguage.get(fp) ?? languageFromPath(fp)));
          if (qualGlobalMatches.length === 1) {
            const qfp = qualGlobalMatches[0];
            if (fileHasSymbol.get(qfp)?.has(memberPart)) {
              const dstQualifiedKey = bestQKey(fileQKeys, qfp, memberPart, `${qualifierPart}.${memberPart}`);
              if (dstQualifiedKey !== null) {
                resolved.push({ srcFilePath, srcName, dstFilePath: qfp, dstName: origDstName, dstQualifiedKey, predicate: rel.predicate, confidence: 0.7, tier: 'qualifier' });
              }
            }
          }
          continue; // qualified name exhausted — don't try bare-name tiers
        }
      }

      // Tier 2: import-scoped (confidence 0.9)
      const importMatches = definersIn(importedFilePaths, importedOrder, dstName).filter(reachable);
      const narrowedImportMatches = narrowByRepoDeps(narrowCCandidates(importMatches, srcFilePath, srcLanguage, srcName, dstName), srcFilePath);

      if (narrowedImportMatches.length === 1) {
        const fp = narrowedImportMatches[0];
        const dstQualifiedKey = targetQKey(fp);
        if (dstQualifiedKey === null) continue; // ambiguous — do not emit bad nodeId
        resolved.push({ srcFilePath, srcName, dstFilePath: fp, dstName: origDstName, dstQualifiedKey, predicate: rel.predicate, confidence: 0.9, tier: 'import' });
        continue;
      }
      if (unboundAmbientCall) continue;
      // Commodity gate: beyond the precise import-scoped tier above, the remaining
      // tiers (transitive re-export hops at 0.8, global symbol fallback at 0.5)
      // resolve a bare call on name alone and can cross module/package/repo
      // boundaries. For builtin/stdlib member names (`.get()`, `.map()`, `.then()`)
      // a single narrowed match is a false positive (observed: core-ingestion's
      // `.map()`/`.get()` linking to an unrelated client's `map`/`get`). Symbols
      // defined in many files are project-level commodities with the same problem.
      // Favor under-connection: stop here rather than emit a bogus cross-boundary
      // edge. The explicit import-scoped tier above is unaffected.
      if (COMMODITY_CALLEE_NAMES.has(dstName) || (symbolToFiles.get(dstName)?.length ?? 0) >= COMMODITY_DEF_FILE_THRESHOLD) {
        stats.skippedAmbiguous++;
        continue;
      }
      // Tier 2.5: transitive import-scoped (confidence 0.8) — one re-export hop away
      const transitiveMatches = definersIn(transitiveFilePaths, transitiveOrder, dstName).filter(reachable);
      const narrowedTransitiveMatches = narrowByRepoDeps(narrowCCandidates(transitiveMatches, srcFilePath, srcLanguage, srcName, dstName), srcFilePath);

      if (narrowedTransitiveMatches.length === 1) {
        const fp = narrowedTransitiveMatches[0];
        const dstQualifiedKey = targetQKey(fp);
        if (dstQualifiedKey === null) continue;
        resolved.push({ srcFilePath, srcName, dstFilePath: fp, dstName: origDstName, dstQualifiedKey, predicate: rel.predicate, confidence: 0.8, tier: 'transitive' });
        continue;
      }
      if (configuredBindingTargets?.length === 0) continue;
      if (rel.predicate === 'CALLS' && relativeCallBindings.get(srcFilePath)?.has(origDstName)) {
        stats.skippedAmbiguous++;
        continue;
      }
      // Tier 3: global fallback (confidence 0.5) — uses inverted symbol index
      // instead of scanning all files.
      // Skip for C/C++ REFERENCES: struct/type references that don't resolve via the
      // import chain come from system headers (e.g. <net/if.h>) and must not be
      // linked to an in-repo definition of the same name.
      if (rel.predicate === 'REFERENCES' &&
          (srcLanguage === SupportedLanguages.C || srcLanguage === SupportedLanguages.CPlusPlus)) {
        continue;
      }
      stats.globalFallbacks++;
      const candidates = symbolToFiles.get(dstName) ?? [];
      // A bare call never lands on a class member, but here -- unlike the import
      // tiers -- members still count toward ambiguity. Nothing ties an unbound
      // name to this tier's candidates: in an ES module it is usually a local,
      // a parameter or a closure variable (`const gte = ...; gte(x)`). Filtering
      // the members out first would turn an ambiguous name into a "unique" one
      // and link that local to an unrelated module's function of the same name.
      let globalMatches = candidates.filter(fp =>
        fp !== srcFilePath && fileLanguage.get(fp) === srcLanguage && insideBoundPackage(fp));
      const importHint = pickCallerAlignedCandidate(importMatches, srcName, dstName)?.chosen
        ?? pickCallerAlignedCandidate(transitiveMatches, srcName, dstName)?.chosen;
      if (importHint) {
        const hintedStem = candidateStem(importHint);
        const stemMatches = globalMatches.filter(fp => candidateStem(fp) === hintedStem);
        if (stemMatches.length > 0) globalMatches = stemMatches;
      }
      stats.globalCandidateTotal += globalMatches.length;

      const resolvedMatches = narrowByRepoDeps(narrowCCandidates(globalMatches, srcFilePath, srcLanguage, srcName, dstName), srcFilePath);

      if (resolvedMatches.length === 1) {
        const fp = resolvedMatches[0];
        if (bareCall && !definesAtModuleScope(fp)) continue; // only a member of that name
        const dstQualifiedKey = targetQKey(fp);
        if (dstQualifiedKey === null) continue; // ambiguous — do not emit bad nodeId
        resolved.push({ srcFilePath, srcName, dstFilePath: fp, dstName: origDstName, dstQualifiedKey, predicate: rel.predicate, confidence: 0.5, tier: 'global' });
        stats.resolvedGlobal++;
        continue;
      }
      if (narrowedImportMatches.length > 1 || narrowedTransitiveMatches.length > 1 || resolvedMatches.length > 1) {
        stats.skippedAmbiguous++;
      }
      // 0 or >1 matches after all tiers — leave as dangling edge, do not emit
    }
  }

  // Cross-repo dependency gate (co-ingest): keep a cross-repo edge only when the
  // source repo imports the target repo's package. Intra-repo and single-repo
  // edges are untouched. A repo with no detected dependency to the target is
  // treated as unrelated — its same-named-symbol matches are dropped.
  if (repoOf && repoDeps) {
    return resolved.filter(e => {
      const sr = repoOf(e.srcFilePath);
      const dr = repoOf(e.dstFilePath);
      if (sr === undefined || dr === undefined || sr === dr) return true;
      return repoDeps!.get(sr)?.has(dr) === true;
    });
  }
  return resolved;
}

/** @deprecated Use resolveEdges instead. */
export function resolveCallEdges(results: FileParseResult[]): ResolvedCallEdge[] {
  return resolveEdges(results).map(e => ({
    callerFilePath: e.srcFilePath,
    callerName: e.srcName,
    calleeFilePath: e.dstFilePath,
    calleeName: e.dstName,
    calleeQualifiedKey: e.dstQualifiedKey,
    confidence: e.confidence,
  }));
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

function findEnclosing(
  ranges: Array<{ name: string; start: number; end: number }>,
  line: number,
  excludeName: string
): string | null {
  // Find the innermost class/interface that contains this line
  let best: { name: string; start: number; end: number } | null = null;
  for (const r of ranges) {
    if (r.name === excludeName) continue;
    if (line >= r.start && line <= r.end) {
      if (!best || (r.end - r.start) < (best.end - best.start)) {
        best = r;
      }
    }
  }
  return best?.name ?? null;
}

/**
 * The innermost definition whose body contains `line` — what a call or a
 * reference on that line should be attributed to.
 *
 * `constant` counts. A constant's initializer is a body like any other: the
 * `z.object(...)` in `const schema = z.object({...})` is a call made by
 * `schema`, and a Scala `var baz: NodeKind = NodeKind.File` is the holder of
 * the reference to `NodeKind`, not its enclosing class (#557). Those constants
 * arrived here as `kind: 'function'` until Ix#679 gave them their own kind, so
 * leaving them out would have quietly re-coarsened every such edge to the class
 * or the file.
 */
function findEnclosingDefinition(
  entities: ParsedEntity[],
  line: number
): string | null {
  let best: ParsedEntity | null = null;
  for (const e of entities) {
    if (e.kind !== 'function' && e.kind !== 'method' && e.kind !== 'constant') continue;
    if (line >= e.lineStart && line <= e.lineEnd) {
      if (!best || (e.lineEnd - e.lineStart) < (best.lineEnd - best.lineStart)) {
        best = e;
      }
    }
  }
  return best ? (best.container ? `${best.container}.${best.name}` : best.name) : null;
}