Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
// 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;
}