mirror of
https://github.com/colbymchenry/codegraph.git
synced 2026-11-01 08:12:59 +08:00
Colby MchenryandClaude Opus 5.5
16bc05a208
Receiver inference read `v := T{}`, `var v T` and parameters, never a
local bound from a type assertion. So `flusher.Flush()` after
`flusher, ok := w.(http.Flusher)` went to whichever project method name
matching picked, and calls like etcd's `fi.Action()` after
`fi := s.kvindex.(*fakeIndex)` linked to nothing.
A Go local whose declaration in scope at the call binds the value of a
type assertion (`v := x.(T)`, `v, ok := x.(T)`, `var v, _ = x.(T)`) now
has the asserted type, found where Go finds it, as #2444 does for a call
made through the assertion itself (`x.(T).M()`). Calls, method values and
field chains through the local (`wr.job.Start()`) reach the type's own
method, its interface's, or one embedding promotes into it. The binding is
the one the scope reader from #2448 finds in scope at the call: an `if`
header's ends with its statement, and a nearer declaration in a block that
has ended does not hide it. A type switch's variable and a value that only
starts with an assertion (`x.(T).field`) resolve as before.
A type from outside the project, a predeclared type or an alias of an
outside type links nothing, as for the assertion itself. A type the index
can't tell is left to name matching, as before: a type literal
(`interface{ GetDeadline() time.Time }`) or a type declared inside a
function (grpc-go's `internalInfo` and `grpcstatus`). A local bound from an
assertion and named like a standard-library package
(`parser, ok := builder.(balancer.ConfigParser)`) is no longer dropped as
a call into that package.
On etcd, harbor, kratos and grpc-go, 358 call sites change. 216 gain a
link, 38 move to the asserted type's method and 89 keep their target, now
resolved through the asserted type. 15 lose a link that went through a
type from outside the project, or from a field read to a same-named
function.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3515 lines
164 KiB
TypeScript
3515 lines
164 KiB
TypeScript
/**
|
||
* Reference Resolution Orchestrator
|
||
*
|
||
* Coordinates all reference resolution strategies.
|
||
*/
|
||
|
||
import * as fs from 'fs';
|
||
import * as path from 'path';
|
||
import { Language, Node, UnresolvedReference, Edge } from '../types';
|
||
import { QueryBuilder } from '../db/queries';
|
||
import { SynthesisStage } from '../db/synthesis-stage';
|
||
import {
|
||
UnresolvedRef,
|
||
ResolvedRef,
|
||
ResolutionResult,
|
||
ResolutionContext,
|
||
FrameworkResolver,
|
||
ImportMapping,
|
||
isSupertypeTarget,
|
||
isInheritanceRef,
|
||
isImportableKind,
|
||
CPP_DEFINE_SIGNATURE,
|
||
} from './types';
|
||
import { isPythonSelfCall, matchJsStoreBindingCall, isUnresolvedJsMemberCall, matchObjectPathCall, thisScopeCaller, isVisibleAcrossFiles, matchReference, matchFunctionRef, matchDottedCallChain, matchScopedCallChain, matchMethodCall, sameLanguageFamily, crossesCodeBoundary, gateLanguageMatch, dumpNameMatcherProfile, clearNameMatcherMemos, isRustNameInScope, CASE_INSENSITIVE_LANGUAGES, isDartMemberRead, matchDartMemberRead, isDartChainLink, matchDartChainLink, isDartAnnotation, matchDartAnnotation, isStdMethodName, isGoUnknownQualified, isGoBareName, goTypePositionTarget, GO_TYPE_KINDS, matchGoAssertedCall, isGoAssertedLocal } from './name-matcher';
|
||
import { isVisibleCppMacro, clearCppMacroVisibility } from './cpp-macro-visibility';
|
||
import { isCppConstructorRef, matchCppConstructor } from './cpp-constructor';
|
||
import { isCppSupertypeRef, matchCppSupertype, clearCppSupertypeMemos } from './cpp-supertypes';
|
||
import { gateSwiftTypeTarget, clearSwiftTypeVisibility, swiftExtendedConformances } from './swift-type-visibility';
|
||
import { clearDartLibraryMemos } from './dart-libraries';
|
||
import { clearVbnetReceiverMemos, isVbMemberRead, isVbPathCall, matchVbMemberRead, matchVbPathCall } from './vbnet-receivers';
|
||
import { gateTypeParameter, clearTypeParameterMemos } from './type-parameters';
|
||
import { gateDartLocal, clearDartLocalScopeMemos } from './dart-local-scope';
|
||
import { clearCppTypeAliasMemos } from './cpp-type-aliases';
|
||
import { clearCppIncluderMemos } from './cpp-includers';
|
||
import { matchShopifyThemeFile } from './shopify-themes';
|
||
import { resolveViaImport, resolvePhpImportedStaticCall, resolvePhpQualifiedClassRef, resolveJvmImport, extractImportMappings, extractReExports, loadCppIncludeDirs, isPhpIncludePathRef, isCobolCopybookRef, isNixPathImportRef, isDartImportRef, isLuaRequireRef, isJsPathImportRef, isBoundToOutOfRepoImport, importBindingTail, clearImportResolverMemos, resolveImportPath, isExternalImport } from './import-resolver';
|
||
import { ResolverPool, minRefsForPool, shouldEngageAdaptively } from './resolver-pool';
|
||
import { resolveAliasBinding } from './alias-binding';
|
||
import { detectFrameworks, getResolvingFrameworks } from './frameworks';
|
||
import { synthesizeCallbackEdges } from './callback-synthesizer';
|
||
import { createYielder, type MaybeYield } from './cooperative-yield';
|
||
import { MAX_SOURCE_FILE_SIZE_BYTES } from '../file-limits';
|
||
import { loadProjectAliases, type AliasMap } from './path-aliases';
|
||
import { findGoModuleForImport, goModulePackageDir, loadGoModule, type GoModule } from './go-module';
|
||
import { loadWorkspacePackages, type WorkspacePackages } from './workspace-packages';
|
||
import { logDebug } from '../errors';
|
||
import { lexicalPathWithinRoot } from '../utils';
|
||
import type { CrossFileNodes, ReExport } from './types';
|
||
import { resurrectRefFromDroppedEdge } from './resurrect-ref';
|
||
import { LRUCache } from './lru-cache';
|
||
import { JS_BUILT_INS } from './js-builtins';
|
||
import { builtinModules } from 'module';
|
||
import { parse as parseJsonc } from 'jsonc-parser';
|
||
|
||
const NODE_BUILTINS = new Set(builtinModules);
|
||
|
||
/** Node kinds that can declare supertypes (extends/implements). */
|
||
const SUPERTYPE_BEARING_KINDS = new Set<Node['kind']>([
|
||
'class', 'struct', 'interface', 'trait', 'protocol', 'enum',
|
||
]);
|
||
|
||
/**
|
||
* The only edges resolving a reference reads (getSupertypes' walk). The batch
|
||
* loop commits a batch that made any of these before the next batch fans out;
|
||
* its other edges land while that batch resolves. A resolution strategy that
|
||
* reads another edge kind must be added here.
|
||
*/
|
||
const RESOLUTION_READ_EDGE_KINDS: Edge['kind'][] = ['implements', 'extends'];
|
||
|
||
// SUPERTYPE_TARGET_KINDS (the kinds an extends/implements edge may TARGET)
|
||
// lives in ./types — the name-matcher needs the same set to restrict its
|
||
// candidate pool before ranking. It is deliberately wider than
|
||
// SUPERTYPE_BEARING_KINDS above, which is about the DECLARING side.
|
||
|
||
/**
|
||
* Languages whose chained static-factory/fluent calls defer to the conformance
|
||
* second pass. Dotted-receiver languages resolve via matchDottedCallChain; the
|
||
* `::`-receiver ones (Rust) via matchScopedCallChain.
|
||
*/
|
||
const CHAIN_LANGUAGES = new Set(['java', 'kotlin', 'csharp', 'swift', 'rust', 'go', 'scala', 'dart', 'objc', 'pascal']);
|
||
const SCOPED_CHAIN_LANGUAGES = new Set(['rust']);
|
||
|
||
/** The extractor's chained-receiver encoding: `<inner>().<method>`. */
|
||
const CHAIN_SHAPE = /^(.+)\(\)\.(\w+)$/;
|
||
|
||
/** PHP `$this->prop->method()` encoded as `this->prop.method` — no `()`, so CHAIN_SHAPE misses it. */
|
||
const PHP_PROP_SHAPE = /^this->\w+\.\w+$/;
|
||
|
||
/**
|
||
* Cache size limits. Each per-resolver cache is bounded so memory
|
||
* stays flat on large codebases (20k+ files). Sizes were chosen to
|
||
* cover the working set for typical resolution batches without
|
||
* exceeding a few hundred MB worst-case. Override via the env var
|
||
* `CODEGRAPH_RESOLVER_CACHE_SIZE` (single integer applied to all
|
||
* caches) when tuning for very large or very small projects.
|
||
*/
|
||
const DEFAULT_CACHE_LIMIT = 5_000;
|
||
function resolveCacheLimit(): number {
|
||
const raw = process.env.CODEGRAPH_RESOLVER_CACHE_SIZE;
|
||
if (!raw) return DEFAULT_CACHE_LIMIT;
|
||
const parsed = Number.parseInt(raw, 10);
|
||
if (Number.isFinite(parsed) && parsed > 0) return parsed;
|
||
return DEFAULT_CACHE_LIMIT;
|
||
}
|
||
|
||
// Re-export types
|
||
export * from './types';
|
||
|
||
// Pre-built Sets for O(1) built-in lookups (allocated once, shared across all instances)
|
||
const REACT_HOOKS = new Set([
|
||
'useState', 'useEffect', 'useContext', 'useReducer', 'useCallback',
|
||
'useMemo', 'useRef', 'useLayoutEffect', 'useImperativeHandle', 'useDebugValue',
|
||
]);
|
||
|
||
const PYTHON_BUILT_INS = new Set([
|
||
'print', 'len', 'range', 'str', 'int', 'float', 'list', 'dict', 'set', 'tuple',
|
||
'open', 'input', 'type', 'isinstance', 'hasattr', 'getattr', 'setattr',
|
||
'super', 'self', 'cls', 'None', 'True', 'False',
|
||
]);
|
||
|
||
const PYTHON_BUILT_IN_TYPES = new Set([
|
||
'list', 'dict', 'set', 'tuple', 'str', 'int', 'float', 'bool',
|
||
'bytes', 'bytearray', 'frozenset', 'object', 'super',
|
||
]);
|
||
|
||
const PYTHON_BUILT_IN_METHODS = new Set([
|
||
'append', 'extend', 'insert', 'remove', 'pop', 'clear', 'sort', 'reverse', 'copy',
|
||
'update', 'keys', 'values', 'items', 'get',
|
||
'add', 'discard', 'union', 'intersection', 'difference',
|
||
'split', 'join', 'strip', 'lstrip', 'rstrip', 'replace', 'lower', 'upper',
|
||
'startswith', 'endswith', 'find', 'index', 'count', 'encode', 'decode',
|
||
'format', 'isdigit', 'isalpha', 'isalnum',
|
||
'read', 'write', 'readline', 'readlines', 'close', 'flush', 'seek',
|
||
]);
|
||
|
||
const GO_STDLIB_PACKAGES = new Set([
|
||
'fmt', 'os', 'io', 'net', 'http', 'log', 'math', 'sort', 'sync',
|
||
'time', 'path', 'bytes', 'strings', 'strconv', 'errors', 'context',
|
||
'json', 'xml', 'csv', 'html', 'template', 'regexp', 'reflect',
|
||
'runtime', 'testing', 'flag', 'bufio', 'crypto', 'encoding',
|
||
'filepath', 'hash', 'mime', 'rand', 'signal', 'sql', 'syscall',
|
||
'unicode', 'unsafe', 'atomic', 'binary', 'debug', 'exec', 'heap',
|
||
'ring', 'scanner', 'tar', 'zip', 'gzip', 'zlib', 'tls', 'url',
|
||
'user', 'pprof', 'trace', 'ast', 'build', 'parser', 'printer',
|
||
'token', 'types', 'cgo', 'plugin', 'race', 'ioutil',
|
||
// Kubernetes-common stdlib aliases
|
||
'utilruntime', 'utilwait', 'utilnet',
|
||
]);
|
||
|
||
const GO_BUILT_INS = new Set([
|
||
'make', 'new', 'len', 'cap', 'append', 'copy', 'delete', 'close',
|
||
'panic', 'recover', 'print', 'println', 'complex', 'real', 'imag',
|
||
'error', 'nil', 'true', 'false', 'iota',
|
||
'int', 'int8', 'int16', 'int32', 'int64',
|
||
'uint', 'uint8', 'uint16', 'uint32', 'uint64', 'uintptr',
|
||
'float32', 'float64', 'complex64', 'complex128',
|
||
'string', 'bool', 'byte', 'rune', 'any',
|
||
]);
|
||
|
||
const PASCAL_UNIT_PREFIXES = [
|
||
'System.', 'Winapi.', 'Vcl.', 'Fmx.', 'Data.', 'Datasnap.',
|
||
'Soap.', 'Xml.', 'Web.', 'REST.', 'FireDAC.', 'IBX.',
|
||
'IdHTTP', 'IdTCP', 'IdSSL',
|
||
];
|
||
|
||
const PASCAL_BUILT_INS = new Set([
|
||
'System', 'SysUtils', 'Classes', 'Types', 'Variants', 'StrUtils',
|
||
'Math', 'DateUtils', 'IOUtils', 'Generics.Collections', 'Generics.Defaults',
|
||
'Rtti', 'TypInfo', 'SyncObjs', 'RegularExpressions',
|
||
'SysInit', 'Windows', 'Messages', 'Graphics', 'Controls', 'Forms',
|
||
'Dialogs', 'StdCtrls', 'ExtCtrls', 'ComCtrls', 'Menus', 'ActnList',
|
||
'WriteLn', 'Write', 'ReadLn', 'Read', 'Inc', 'Dec', 'Ord', 'Chr',
|
||
'Length', 'SetLength', 'High', 'Low', 'Assigned', 'FreeAndNil',
|
||
'Format', 'IntToStr', 'StrToInt', 'FloatToStr', 'StrToFloat',
|
||
'Trim', 'UpperCase', 'LowerCase', 'Pos', 'Copy', 'Delete', 'Insert',
|
||
'Now', 'Date', 'Time', 'DateToStr', 'StrToDate',
|
||
'Raise', 'Exit', 'Break', 'Continue', 'Abort',
|
||
'True', 'False', 'nil', 'Self', 'Result',
|
||
'Create', 'Destroy', 'Free',
|
||
'TObject', 'TComponent', 'TPersistent', 'TInterfacedObject',
|
||
'TList', 'TStringList', 'TStrings', 'TStream', 'TMemoryStream', 'TFileStream',
|
||
'Exception', 'EAbort', 'EConvertError', 'EAccessViolation',
|
||
'IInterface', 'IUnknown',
|
||
]);
|
||
|
||
const C_BUILT_INS = new Set([
|
||
// Standard C library functions
|
||
'printf', 'fprintf', 'sprintf', 'snprintf', 'scanf', 'fscanf', 'sscanf',
|
||
'malloc', 'calloc', 'realloc', 'free',
|
||
'memcpy', 'memmove', 'memset', 'memcmp', 'memchr',
|
||
'strlen', 'strcpy', 'strncpy', 'strcat', 'strncat', 'strcmp', 'strncmp',
|
||
'strstr', 'strchr', 'strrchr', 'strtok', 'strdup',
|
||
'fopen', 'fclose', 'fread', 'fwrite', 'fgets', 'fputs', 'fputc', 'fgetc',
|
||
'feof', 'ferror', 'fflush', 'fseek', 'ftell', 'rewind',
|
||
'exit', 'abort', 'atexit', 'atoi', 'atol', 'atof', 'strtol', 'strtoul', 'strtod',
|
||
'qsort', 'bsearch',
|
||
'abs', 'labs', 'rand', 'srand',
|
||
'sin', 'cos', 'tan', 'sqrt', 'pow', 'log', 'log10', 'exp', 'ceil', 'floor', 'fabs',
|
||
'time', 'clock', 'difftime', 'mktime', 'localtime', 'gmtime', 'strftime', 'asctime',
|
||
'assert', 'errno',
|
||
'perror', 'remove', 'rename', 'tmpfile', 'tmpnam',
|
||
'getenv', 'system',
|
||
'signal', 'raise',
|
||
'setjmp', 'longjmp',
|
||
'va_start', 'va_end', 'va_arg', 'va_copy',
|
||
'NULL', 'EOF', 'BUFSIZ', 'FILENAME_MAX', 'RAND_MAX', 'EXIT_SUCCESS', 'EXIT_FAILURE',
|
||
'size_t', 'ptrdiff_t', 'wchar_t', 'intptr_t', 'uintptr_t',
|
||
'int8_t', 'int16_t', 'int32_t', 'int64_t',
|
||
'uint8_t', 'uint16_t', 'uint32_t', 'uint64_t',
|
||
'FILE',
|
||
// POSIX additions commonly seen
|
||
'stat', 'lstat', 'fstat', 'open', 'close', 'read', 'write', 'pipe',
|
||
'fork', 'exec', 'waitpid', 'getpid', 'getppid', 'kill', 'sleep', 'usleep',
|
||
'pthread_create', 'pthread_join', 'pthread_mutex_lock', 'pthread_mutex_unlock',
|
||
'dlopen', 'dlsym', 'dlclose',
|
||
]);
|
||
|
||
const CPP_BUILT_INS = new Set([
|
||
// iostream objects (often used without std:: prefix via using)
|
||
'cout', 'cin', 'cerr', 'clog', 'endl', 'flush', 'ws',
|
||
'std', // the namespace itself when used as std::something
|
||
// Common C++ keywords that leak as references
|
||
'nullptr', 'true', 'false', 'this', 'sizeof', 'alignof', 'typeid',
|
||
'static_cast', 'dynamic_cast', 'reinterpret_cast', 'const_cast',
|
||
'make_unique', 'make_shared', 'make_pair',
|
||
'move', 'forward', 'swap',
|
||
]);
|
||
|
||
/**
|
||
* Reference Resolver
|
||
*
|
||
* Orchestrates reference resolution using multiple strategies.
|
||
*/
|
||
export class ReferenceResolver {
|
||
private projectRoot: string;
|
||
private queries: QueryBuilder;
|
||
private context: ResolutionContext;
|
||
private frameworks: FrameworkResolver[] = [];
|
||
/** `frameworks` narrowed to those that resolve each reference language (see getResolvingFrameworks). */
|
||
private frameworksByLanguage = new Map<Language, FrameworkResolver[]>();
|
||
// Chained static-factory/fluent call refs the first pass couldn't resolve,
|
||
// collected in-memory and left pending in the DB until the post-pass
|
||
// finishes, so a restart can recover the queue (#1577). Drained by
|
||
// resolveChainedCallsViaConformance
|
||
// once implements/extends edges exist, to resolve methods on a supertype the
|
||
// receiver conforms to (#750).
|
||
private deferredChainRefs: UnresolvedRef[] = [];
|
||
// `this.<member>` function-as-value refs whose member is NOT on the
|
||
// enclosing class itself — possibly inherited. Collected in-memory for the
|
||
// same reason as deferredChainRefs and drained by
|
||
// resolveDeferredThisMemberRefs once implements/extends edges exist (#808).
|
||
private deferredThisMemberRefs: UnresolvedRef[] = [];
|
||
private deferredRowIds = new Set<number>();
|
||
// Per-`.razor`/`.cshtml`-file `@using` namespace set (own directives + folder
|
||
// `_Imports.razor`, cascading to the project root). Used to disambiguate a
|
||
// markup type ref to the right C# namespace.
|
||
private razorUsingsCache = new Map<string, string[]>();
|
||
// All per-resolver caches are LRU-bounded. Previously these were
|
||
// unbounded Maps that grew with every distinct lookup and OOM'd on
|
||
// codebases with 20k+ files (see issue: unbounded cache growth).
|
||
private nodeCache: LRUCache<string, Node[]>; // per-file node cache
|
||
private fileCache: LRUCache<string, string | null>; // per-file content cache
|
||
private importMappingCache: LRUCache<string, ImportMapping[]>;
|
||
private reExportCache: LRUCache<string, ReExport[]>;
|
||
private nameCache: LRUCache<string, Node[]>; // name → nodes cache
|
||
private lowerNameCache: LRUCache<string, Node[]>; // lower(name) → nodes cache
|
||
private qualifiedNameCache: LRUCache<string, Node[]>; // qualified_name → nodes cache
|
||
private fileLinesCache: LRUCache<string, string[] | null>; // file → split lines cache
|
||
// id → node for the resolver's own point reads. Every resolved reference
|
||
// re-reads its target a few times (kind gate, language gate, alias
|
||
// following, edge creation) and targets recur ~5× on large repos; the query
|
||
// layer's cache is too small for that working set. Same stable window as the
|
||
// name caches above; absent ids are not cached.
|
||
private nodeByIdCache: LRUCache<string, Node>;
|
||
private methodMatchCache: LRUCache<string, Node[]>; // lang\0Type::method → matching method nodes
|
||
// Per-(language, methodName) owner index for getMethodMatches: buckets a
|
||
// method name's candidates by their qualifiedName's last two segments so a
|
||
// (type, method) query is a lookup instead of an O(candidates) filter per
|
||
// methodMatchCache miss. Derived purely from node rows (stable through the
|
||
// resolution loop, same window nameCache relies on); dropped in clearCaches.
|
||
private methodOwnerIndexCache = new Map<string, Map<string, Node[]>>();
|
||
// Generation-tagged memo for getSupertypes. Supertype edges GROW during the
|
||
// resolution loop (batch k persists its implements/extends edges BEFORE
|
||
// batch k+1 fans out — the #1320 ordering), so a plain cache would freeze an
|
||
// early batch's emptier answer and change later batches' outcomes. Within
|
||
// one batch the edge state is fixed by that same ordering, so entries are
|
||
// tagged with a generation that advances at every batch entry point
|
||
// (resolveBatchYielding / resolveListForAdmission) — a stale-gen entry is
|
||
// recomputed, making the memo behavior-identical to no memo at every point
|
||
// in time. On the Swift compiler the unmemoized walk ran 971k times for
|
||
// 565s of combined worker time (~581µs each, recursion-multiplied).
|
||
private supertypeGen = 0;
|
||
private supertypeMemo = new Map<string, { gen: number; supers: string[] }>();
|
||
// getSupertypeNodes' memo, by node id, under the same generation tag.
|
||
private supertypeNodeMemo = new Map<string, { gen: number; nodes: Node[] }>();
|
||
|
||
/** Invalidate the getSupertypes memo — call when resolved edges may have advanced. */
|
||
private advanceSupertypeGeneration(): void {
|
||
this.supertypeGen++;
|
||
// Lazy invalidation via the gen tag; bound the map so a long run over many
|
||
// batches doesn't accrete dead entries.
|
||
if (this.supertypeMemo.size > 50_000) this.supertypeMemo.clear();
|
||
if (this.supertypeNodeMemo.size > 50_000) this.supertypeNodeMemo.clear();
|
||
}
|
||
// Node kinds are a small fixed set (~24), so this is a plain Map, not an LRU.
|
||
// getNodesByKind returns the FULL node list for a kind; it was previously
|
||
// uncached — a per-ref `SELECT * FROM nodes WHERE kind=?` + row-mapping. Called
|
||
// for every dotted call ref by the Spring resolver (constants) and every
|
||
// `hook_` ref by the Drupal resolver (functions), that scan dominated
|
||
// resolution on large repos (#1180). The node set is stable within a
|
||
// resolution pass (same lifetime assumption as nameCache); clearCaches() resets
|
||
// it between passes. Callers must treat the returned array as read-only.
|
||
private nodesByKindCache = new Map<Node['kind'], Node[]>();
|
||
// Filesystem existence probes behind context.fileExists (paths not in knownFiles).
|
||
private fileExistsMemo = new Map<string, boolean>();
|
||
private knownNames: Set<string> | null = null; // all known symbol names for fast pre-filtering
|
||
private knownFiles: Set<string> | null = null;
|
||
private cachesWarmed = false;
|
||
// tsconfig/jsconfig path-alias map. `undefined` = not yet computed,
|
||
// `null` = computed and absent. Treated as immutable for the
|
||
// resolver's lifetime; callers re-create the resolver if config changes.
|
||
private projectAliases: AliasMap | null | undefined = undefined;
|
||
// Per directory: the aliases of the nearest non-root tsconfig declaring `paths`.
|
||
private dirAliases = new Map<string, AliasMap | null>();
|
||
// Per project-relative directory ('' = the root): the module of the nearest
|
||
// go.mod at or above it, up to the project root. Same lazy/immutable
|
||
// convention as dirAliases.
|
||
private goModuleByDir = new Map<string, GoModule | null>();
|
||
// The project's Go modules: the root one plus every module that owns an
|
||
// indexed .go file. Depends on the file set, like knownFiles, so
|
||
// clearCaches drops it.
|
||
private goModules: GoModule[] | null = null;
|
||
// getGoPackageDir answers, keyed by import path and the importing file's
|
||
// module. Derived from goModules, so dropped with it.
|
||
private goPackageDirs = new Map<string, string | null>();
|
||
// Monorepo workspace member packages. Same lazy/immutable convention.
|
||
private workspacePackages: WorkspacePackages | null | undefined = undefined;
|
||
|
||
constructor(projectRoot: string, queries: QueryBuilder) {
|
||
this.projectRoot = projectRoot;
|
||
this.queries = queries;
|
||
|
||
const limit = resolveCacheLimit();
|
||
// The content cache is heavier (full file text), so we give it a
|
||
// smaller budget than the metadata caches.
|
||
const contentLimit = Math.max(64, Math.floor(limit / 5));
|
||
this.nodeCache = new LRUCache(limit);
|
||
this.fileCache = new LRUCache(contentLimit);
|
||
this.importMappingCache = new LRUCache(limit);
|
||
this.reExportCache = new LRUCache(limit);
|
||
this.nameCache = new LRUCache(limit);
|
||
this.lowerNameCache = new LRUCache(limit);
|
||
this.qualifiedNameCache = new LRUCache(limit);
|
||
// Split-lines arrays are heavier than content strings; refs arrive
|
||
// file-ordered, so a small cache still hits nearly always.
|
||
this.fileLinesCache = new LRUCache(contentLimit);
|
||
this.nodeByIdCache = new LRUCache(Math.max(limit * 4, 20_000));
|
||
this.methodMatchCache = new LRUCache(limit);
|
||
|
||
this.context = this.createContext();
|
||
}
|
||
|
||
/**
|
||
* Initialize the resolver (detect frameworks, etc.)
|
||
*/
|
||
initialize(): void {
|
||
this.frameworks = detectFrameworks(this.context);
|
||
this.frameworksByLanguage.clear();
|
||
this.clearCaches();
|
||
}
|
||
|
||
/** The detected frameworks whose `resolve()` reads a reference written in `language`. */
|
||
private frameworksFor(language: Language): FrameworkResolver[] {
|
||
let frameworks = this.frameworksByLanguage.get(language);
|
||
if (!frameworks) {
|
||
frameworks = getResolvingFrameworks(this.frameworks, language);
|
||
this.frameworksByLanguage.set(language, frameworks);
|
||
}
|
||
return frameworks;
|
||
}
|
||
|
||
/**
|
||
* Run each framework resolver's cross-file finalization pass and persist
|
||
* the returned node updates. Idempotent — safe to call after every indexAll
|
||
* and every incremental sync. Returns the number of nodes updated.
|
||
*
|
||
* Caches are cleared before/after so the post-extract pass sees fresh DB
|
||
* state and downstream queries see the updated names.
|
||
*/
|
||
runPostExtract(): number {
|
||
let updated = 0;
|
||
this.clearCaches();
|
||
for (const fw of this.frameworks) {
|
||
if (!fw.postExtract) continue;
|
||
try {
|
||
const nodes = fw.postExtract(this.context);
|
||
for (const node of nodes) {
|
||
this.queries.updateNode(node);
|
||
updated++;
|
||
}
|
||
} catch (err) {
|
||
logDebug(`Framework '${fw.name}' postExtract failed`, {
|
||
error: err instanceof Error ? err.message : String(err),
|
||
});
|
||
}
|
||
}
|
||
for (const fw of this.frameworks) {
|
||
if (!fw.crossFileNodes) continue;
|
||
try {
|
||
updated += this.reconcileCrossFileNodes(fw.crossFileNodes(this.context));
|
||
} catch (err) {
|
||
logDebug(`Framework '${fw.name}' crossFileNodes failed`, {
|
||
error: err instanceof Error ? err.message : String(err),
|
||
});
|
||
}
|
||
}
|
||
if (updated > 0) this.clearCaches();
|
||
return updated;
|
||
}
|
||
|
||
/**
|
||
* Bring a framework's cross-file nodes in line with what it wants now:
|
||
* insert the new ones with their references (pending, for the resolution
|
||
* that follows), rename the ones whose name changed, and remove the ones it
|
||
* no longer wants. A removed node's incoming resolution edges go back to
|
||
* being the references that made them, exactly as when a file is deleted,
|
||
* so they rebind elsewhere or park as failed. Unchanged nodes are not
|
||
* touched, so their edges survive. Returns the number of nodes changed.
|
||
*/
|
||
private reconcileCrossFileNodes(result: CrossFileNodes): number {
|
||
const wanted = new Map<string, Node>();
|
||
for (const node of result.nodes) if (result.owns(node)) wanted.set(node.id, node);
|
||
const existing = new Map<string, Node>();
|
||
for (const node of this.queries.getNodesByKind(result.kind)) if (result.owns(node)) existing.set(node.id, node);
|
||
let changed = 0;
|
||
for (const [id, old] of existing) {
|
||
if (wanted.has(id)) continue;
|
||
const refs = this.queries.getCrossFileIncomingEdgesWithTarget(old.filePath)
|
||
.filter((e) => e.target === id)
|
||
.map((e) => resurrectRefFromDroppedEdge(e))
|
||
.filter((r): r is UnresolvedReference => r !== null);
|
||
if (refs.length > 0) this.queries.insertUnresolvedRefsBatch(refs);
|
||
this.queries.deleteNode(id);
|
||
changed++;
|
||
}
|
||
const added: Node[] = [];
|
||
for (const [id, node] of wanted) {
|
||
const old = existing.get(id);
|
||
if (!old) added.push(node);
|
||
else if (old.name !== node.name || old.qualifiedName !== node.qualifiedName) {
|
||
this.queries.updateNode(node);
|
||
changed++;
|
||
}
|
||
}
|
||
if (added.length > 0) {
|
||
this.queries.insertNodes(added);
|
||
const ids = new Set(added.map((n) => n.id));
|
||
this.queries.insertUnresolvedRefsBatch(result.references.filter((r) => ids.has(r.fromNodeId)));
|
||
changed += added.length;
|
||
}
|
||
return changed;
|
||
}
|
||
|
||
/**
|
||
* Put back in the pending set the route references whose answer reads a
|
||
* module in `changedFilePaths` (`FrameworkResolver.lazyModules`), for a
|
||
* sync's resolution sweep. Returns the number put back.
|
||
*
|
||
* A route that renders a same-file `const Docs = lazy(() =>
|
||
* import('./pages/Docs'))` binds to the declaration while the module is
|
||
* missing, and nothing revisited it once the module was added: the
|
||
* reference had resolved, so it was never parked for the failed-ref retry,
|
||
* and the rebind of the names a sync defines (CG-33) reaches it only when
|
||
* the module's component is named like the declaration. An edit that gives
|
||
* the module its default export, or moves it to another component, changes
|
||
* the answer the same way: a route's edge follows its old target through
|
||
* the module's re-index. So does a page behind a barrel the module
|
||
* forwards. References written in a changed file were resolved against the
|
||
* new files already.
|
||
*/
|
||
reopenRouteModuleReaders(changedFilePaths: readonly string[]): number {
|
||
const readers = this.frameworks.filter((f) => f.lazyModules);
|
||
if (readers.length === 0 || changedFilePaths.length === 0) return 0;
|
||
const changed = new Set(changedFilePaths);
|
||
const edgeIds: number[] = [];
|
||
const refs: UnresolvedReference[] = [];
|
||
for (const edge of this.queries.getRouteEdgesMovedBy(changedFilePaths)) {
|
||
const ref = resurrectRefFromDroppedEdge(edge);
|
||
if (!ref) continue;
|
||
const asked: UnresolvedRef = { ...ref, filePath: edge.sourceFilePath, language: edge.sourceLanguage };
|
||
const reads = readers.some((f) => f.lazyModules!(asked, this.context).some((file) => changed.has(file)));
|
||
if (!reads) continue;
|
||
edgeIds.push(edge.edgeId);
|
||
refs.push(ref);
|
||
}
|
||
if (refs.length > 0) this.queries.replaceResolutionEdgesWithUnresolvedRefs(edgeIds, refs);
|
||
return refs.length;
|
||
}
|
||
|
||
/**
|
||
* Pre-build lightweight caches for resolution.
|
||
* Node lookups are now handled by indexed SQLite queries instead of
|
||
* loading all nodes into memory (which caused OOM on large codebases).
|
||
* We cache the set of known symbol names for fast pre-filtering.
|
||
*/
|
||
warmCaches(): void {
|
||
if (this.cachesWarmed) return;
|
||
|
||
// Only cache the set of known file paths (lightweight string set)
|
||
this.knownFiles = new Set(this.queries.getAllFilePaths());
|
||
|
||
// Cache all distinct symbol names for fast pre-filtering (just strings, not full nodes)
|
||
this.knownNames = new Set(this.queries.getAllNodeNames());
|
||
|
||
this.cachesWarmed = true;
|
||
}
|
||
|
||
/**
|
||
* warmCaches for the async resolution entry points: streams the distinct
|
||
* name set with periodic yields instead of one synchronous `.all()`. On a
|
||
* multi-million-node index the DISTINCT scan is a solid multi-second block
|
||
* (measured up to 28s inside `codegraph sync` on the Linux kernel index),
|
||
* long enough to matter to the #850 watchdog on slower hardware. Same
|
||
* result, same memory — only the event loop keeps turning.
|
||
*/
|
||
async warmCachesYielding(onYield: MaybeYield): Promise<void> {
|
||
if (this.cachesWarmed) return;
|
||
|
||
this.knownFiles = new Set(this.queries.getAllFilePaths());
|
||
|
||
const names = new Set<string>();
|
||
let scanned = 0;
|
||
for (const name of this.queries.iterateNodeNames()) {
|
||
names.add(name);
|
||
if ((++scanned & 8191) === 0) await onYield();
|
||
}
|
||
this.knownNames = names;
|
||
|
||
this.cachesWarmed = true;
|
||
}
|
||
|
||
/** `queries.getNodeById` through the resolver's own id → node cache. */
|
||
private nodeById(id: string): Node | null {
|
||
const cached = this.nodeByIdCache.get(id);
|
||
if (cached !== undefined) return cached;
|
||
const node = this.queries.getNodeById(id);
|
||
if (node) this.nodeByIdCache.set(id, node);
|
||
return node;
|
||
}
|
||
|
||
/**
|
||
* Clear internal caches
|
||
*/
|
||
clearCaches(): void {
|
||
this.nodeCache.clear();
|
||
this.fileCache.clear();
|
||
this.importMappingCache.clear();
|
||
this.reExportCache.clear();
|
||
this.nameCache.clear();
|
||
this.lowerNameCache.clear();
|
||
this.qualifiedNameCache.clear();
|
||
this.fileLinesCache.clear();
|
||
this.nodeByIdCache.clear();
|
||
this.methodMatchCache.clear();
|
||
this.methodOwnerIndexCache.clear();
|
||
this.supertypeMemo.clear();
|
||
this.supertypeNodeMemo.clear();
|
||
this.supertypeGen++;
|
||
this.nodesByKindCache.clear();
|
||
this.fileExistsMemo.clear();
|
||
this.manifestScopes.clear();
|
||
this.knownNames = null;
|
||
this.knownLowerNames = null;
|
||
this.knownFiles = null;
|
||
this.goModules = null;
|
||
this.goPackageDirs.clear();
|
||
this.cachesWarmed = false;
|
||
// The import-resolver's and name-matcher's per-context memos assume the
|
||
// same stable window as the caches above — drop them together.
|
||
if (this.context) {
|
||
clearImportResolverMemos(this.context);
|
||
clearNameMatcherMemos(this.context);
|
||
clearCppMacroVisibility(this.context);
|
||
clearSwiftTypeVisibility(this.context);
|
||
clearDartLibraryMemos(this.context);
|
||
clearVbnetReceiverMemos(this.context);
|
||
clearTypeParameterMemos(this.context);
|
||
clearDartLocalScopeMemos(this.context);
|
||
clearCppTypeAliasMemos(this.context);
|
||
clearCppSupertypeMemos(this.context);
|
||
clearCppIncluderMemos(this.context);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* The module of the nearest `go.mod` at or above project-relative `dir`
|
||
* ('' = the root), never above the project root (#2322). Each directory
|
||
* is read at most once: every directory the walk passes is memoized.
|
||
*/
|
||
private nearestGoModule(dir: string): GoModule | null {
|
||
const walked: string[] = [];
|
||
let found: GoModule | null | undefined;
|
||
for (;;) {
|
||
found = this.goModuleByDir.get(dir);
|
||
if (found !== undefined) break;
|
||
walked.push(dir);
|
||
found = loadGoModule(path.join(this.projectRoot, dir));
|
||
if (found || dir === '') break;
|
||
dir = goDirOf(dir);
|
||
}
|
||
for (const d of walked) this.goModuleByDir.set(d, found);
|
||
return found;
|
||
}
|
||
|
||
/**
|
||
* The project's Go modules: the root `go.mod`'s, and the nearest `go.mod`
|
||
* of every directory holding an indexed `.go` file — so an ignored or
|
||
* vendored tree, which holds no indexed file, adds none, and nothing walks
|
||
* the disk. The go tool ignores `testdata/` and `_`/`.`-prefixed
|
||
* directories, so a module there serves only its own files (#2322).
|
||
*/
|
||
private getGoModules(): GoModule[] {
|
||
if (this.goModules) return this.goModules;
|
||
const dirs = new Set<string>(['']);
|
||
for (const file of this.knownFiles ?? this.queries.getAllFilePaths()) {
|
||
if (file.endsWith('.go')) dirs.add(goDirOf(file));
|
||
}
|
||
const modules = new Set<GoModule>();
|
||
for (const dir of dirs) {
|
||
const mod = this.nearestGoModule(dir);
|
||
const modDir = mod ? path.relative(this.projectRoot, mod.rootDir).split(path.sep).join('/') : '';
|
||
if (mod && !/(?:^|\/)(?:testdata|[_.][^/]*)(?:\/|$)/.test(modDir)) modules.add(mod);
|
||
}
|
||
this.goModules = [...modules];
|
||
return this.goModules;
|
||
}
|
||
|
||
/** `readFile` through the LRU content cache (null = read failed, also cached). */
|
||
private readFileCached(filePath: string): string | null {
|
||
if (this.fileCache.has(filePath)) {
|
||
return this.fileCache.get(filePath)!;
|
||
}
|
||
const fullPath = path.join(this.projectRoot, filePath);
|
||
try {
|
||
// Import resolvers may follow package metadata to an archive (`file:*.har`,
|
||
// for example). Reject anything extraction would not accept before UTF-8
|
||
// decoding can multiply a large binary blob into gigabytes of V8 heap.
|
||
const stats = fs.statSync(fullPath);
|
||
if (!stats.isFile() || stats.size > MAX_SOURCE_FILE_SIZE_BYTES) {
|
||
this.fileCache.set(filePath, null);
|
||
return null;
|
||
}
|
||
const content = fs.readFileSync(fullPath, 'utf-8');
|
||
this.fileCache.set(filePath, content);
|
||
return content;
|
||
} catch (error) {
|
||
logDebug('Failed to read file for resolution', { filePath, error: String(error) });
|
||
this.fileCache.set(filePath, null);
|
||
return null;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* `readFileCached(filePath)?.includes(needle)` for an ASCII needle, searched
|
||
* in the raw bytes: an ASCII byte sequence survives UTF-8 decoding
|
||
* unchanged, and decoding is most of reading a file nobody keeps.
|
||
*/
|
||
private fileContains(filePath: string, needle: string): boolean {
|
||
if (this.fileCache.has(filePath)) return this.fileCache.get(filePath)?.includes(needle) ?? false;
|
||
const fullPath = path.join(this.projectRoot, filePath);
|
||
try {
|
||
const stats = fs.statSync(fullPath);
|
||
if (!stats.isFile() || stats.size > MAX_SOURCE_FILE_SIZE_BYTES) return false;
|
||
return fs.readFileSync(fullPath).includes(needle);
|
||
} catch {
|
||
return false;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Create the resolution context
|
||
*/
|
||
private createContext(): ResolutionContext {
|
||
return {
|
||
resolveImport: (ref) => resolveViaImport(ref, this.context),
|
||
// A path alias makes an import the project's only when it maps the
|
||
// import to a file the index holds. Matching its prefix is not enough:
|
||
// cord-field's `"*": ["./typings/*"]` matches every package, and
|
||
// counting the match bound 169 imports of `@mui/material`'s Typography
|
||
// to its own. Nor is a path that exists on disk: home-assistant's
|
||
// `"lit/decorators": ["./node_modules/lit/decorators.js"]` lands in
|
||
// `node_modules`, topcoder's `config` package on its `config/` folder.
|
||
isOutOfRepoImport: (source, fromFile, language) => {
|
||
if (!isExternalImport(source, language, this.context, { aliasPrefixes: false })) return false;
|
||
const resolved = resolveImportPath(source, fromFile, language, this.context);
|
||
if (resolved !== null && this.isIndexedFile(resolved)) return false;
|
||
return this.isDeclaredOutsidePackage(source, fromFile);
|
||
},
|
||
getNodesInFile: (filePath: string) => {
|
||
if (!this.nodeCache.has(filePath)) {
|
||
this.nodeCache.set(filePath, this.queries.getNodesByFile(filePath));
|
||
}
|
||
return this.nodeCache.get(filePath)!;
|
||
},
|
||
|
||
fileHasExportedNode: (filePath: string) => {
|
||
const cached = this.nodeCache.get(filePath);
|
||
return cached !== undefined ? cached.some((n) => n.isExported) : this.queries.fileHasExportedNode(filePath);
|
||
},
|
||
|
||
getExportedNodesInFile: (filePath: string) => {
|
||
const cached = this.nodeCache.get(filePath);
|
||
return cached !== undefined ? cached.filter((n) => n.isExported) : this.queries.getExportedNodesByFile(filePath);
|
||
},
|
||
|
||
getNodesInFileNamed: (filePath: string, name: string) => {
|
||
const cached = this.nodeCache.get(filePath);
|
||
return cached !== undefined ? cached.filter((n) => n.name === name) : this.queries.getNodesByFileAndName(filePath, name);
|
||
},
|
||
|
||
getNodesByName: (name: string) => {
|
||
const cached = this.nameCache.get(name);
|
||
if (cached !== undefined) return cached;
|
||
const result = this.queries.getNodesByName(name);
|
||
this.nameCache.set(name, result);
|
||
return result;
|
||
},
|
||
|
||
getMethodMatches: (typeName: string, methodName: string, language: Language) => {
|
||
const key = `${language} ${typeName}::${methodName}`;
|
||
const cached = this.methodMatchCache.get(key);
|
||
if (cached !== undefined) return cached;
|
||
let candidates = this.nameCache.get(methodName);
|
||
if (candidates === undefined) {
|
||
candidates = this.queries.getNodesByName(methodName);
|
||
this.nameCache.set(methodName, candidates);
|
||
}
|
||
const want = `${typeName}::${methodName}`;
|
||
let matches: Node[];
|
||
if (typeName.includes('::') || methodName.includes(':')) {
|
||
// Legacy linear filter for the shapes the owner index below can't
|
||
// key exactly: a multi-segment typeName (the endsWith test then
|
||
// spans more than two `::` segments) and ObjC selectors (whose
|
||
// single/empty-keyword colons defeat the segment split). Tiny
|
||
// populations; the per-key memo above still amortizes them.
|
||
matches = [];
|
||
for (const m of candidates) {
|
||
if (m.kind !== 'method') continue;
|
||
if (!sameLanguageFamily(m.language, language)) continue;
|
||
const qn = m.qualifiedName;
|
||
if (qn === want || qn.endsWith(`::${want}`)) matches.push(m);
|
||
}
|
||
} else {
|
||
// Owner index: the linear filter above is O(all same-named methods)
|
||
// per CACHE MISS, and on overload-heavy landscapes the distinct
|
||
// (type, method) key space is so large the per-key memo never
|
||
// amortizes — Swift's `init` has tens of thousands of candidates
|
||
// and the compiler repo measured 732µs per failing call, most of it
|
||
// this scan (re-entered once per supertype recursion level, too).
|
||
// Bucket each (language, methodName)'s candidates ONCE by the
|
||
// qualifiedName's last two `::` segments — exactly the span the
|
||
// `qn === want || qn.endsWith('::' + want)` predicate tests for a
|
||
// segment-clean typeName — then every query is a map lookup.
|
||
// Bucket insertion follows candidate order, so each bucket is
|
||
// byte-identical to what the linear filter produced.
|
||
const idxKey = `${language} ${methodName}`;
|
||
let ownerIndex = this.methodOwnerIndexCache.get(idxKey);
|
||
if (!ownerIndex) {
|
||
ownerIndex = new Map<string, Node[]>();
|
||
for (const m of candidates) {
|
||
if (m.kind !== 'method') continue;
|
||
if (!sameLanguageFamily(m.language, language)) continue;
|
||
const qn = m.qualifiedName;
|
||
const i2 = qn.lastIndexOf('::');
|
||
if (i2 < 0) continue; // single-segment qn can never match `T::m`
|
||
const i1 = qn.lastIndexOf('::', i2 - 1);
|
||
const bucketKey = i1 < 0 ? qn : qn.slice(i1 + 2);
|
||
const bucket = ownerIndex.get(bucketKey);
|
||
if (bucket) bucket.push(m);
|
||
else ownerIndex.set(bucketKey, [m]);
|
||
}
|
||
this.methodOwnerIndexCache.set(idxKey, ownerIndex);
|
||
}
|
||
matches = ownerIndex.get(want) ?? [];
|
||
}
|
||
this.methodMatchCache.set(key, matches);
|
||
return matches;
|
||
},
|
||
|
||
getNodesByQualifiedName: (qualifiedName: string) => {
|
||
const cached = this.qualifiedNameCache.get(qualifiedName);
|
||
if (cached !== undefined) return cached;
|
||
const result = this.queries.getNodesByQualifiedNameExact(qualifiedName);
|
||
this.qualifiedNameCache.set(qualifiedName, result);
|
||
return result;
|
||
},
|
||
|
||
getNodesByKind: (kind: Node['kind']) => {
|
||
const cached = this.nodesByKindCache.get(kind);
|
||
if (cached !== undefined) return cached;
|
||
const result = this.queries.getNodesByKind(kind);
|
||
this.nodesByKindCache.set(kind, result);
|
||
return result;
|
||
},
|
||
|
||
// Streamed, uncached — synthesizers scan-and-filter whole kinds, and
|
||
// both the materialized array AND the per-kind cache retention are
|
||
// O(nodes) memory (#1212). Per-ref resolvers keep the cached array
|
||
// variant above.
|
||
iterateNodesByKind: (kind: Node['kind']) => this.queries.iterateNodesByKind(kind),
|
||
|
||
fileExists: (filePath: string) => {
|
||
// Check pre-built known files set first (O(1))
|
||
if (this.knownFiles) {
|
||
const normalized = filePath.replace(/\\/g, '/');
|
||
if (this.knownFiles.has(filePath) || this.knownFiles.has(normalized)) {
|
||
return true;
|
||
}
|
||
}
|
||
// Fall back to filesystem for files not yet indexed. `path.join` does
|
||
// not clamp, and relative-import resolution hands us paths carrying
|
||
// `../` segments, so the probe has to be contained (#1631): a path
|
||
// outside the root can never be an indexed project file, and the
|
||
// `knownFiles` check above already answered for everything that is.
|
||
// Lexical containment only: this is a per-candidate hot path, and the
|
||
// symlink half of `validatePathWithinRoot` costs two `realpathSync`
|
||
// calls per probe (~70x slower here). It would also be wrong to apply
|
||
// — indexing deliberately follows in-root symlinks whose targets live
|
||
// outside the root (#935), so only the `../` escape is refused.
|
||
// Memoized: import resolution probes the same candidate paths (every
|
||
// extension of a specifier) from every file that imports it, and the
|
||
// tree does not change within a resolution pass (same window as the
|
||
// file-content cache; dropped by clearCaches).
|
||
const probed = this.fileExistsMemo.get(filePath);
|
||
if (probed !== undefined) return probed;
|
||
const fullPath = lexicalPathWithinRoot(this.projectRoot, filePath);
|
||
let exists = false;
|
||
if (fullPath !== null) {
|
||
try {
|
||
exists = fs.existsSync(fullPath);
|
||
} catch (error) {
|
||
logDebug('Error checking file existence', { filePath, error: String(error) });
|
||
}
|
||
}
|
||
if (this.fileExistsMemo.size >= 200_000) this.fileExistsMemo.clear();
|
||
this.fileExistsMemo.set(filePath, exists);
|
||
return exists;
|
||
},
|
||
|
||
readFile: (filePath: string) => this.readFileCached(filePath),
|
||
|
||
fileContains: (filePath: string, needle: string) => this.fileContains(filePath, needle),
|
||
|
||
getFileLines: (filePath: string) => {
|
||
const cached = this.fileLinesCache.get(filePath);
|
||
if (cached !== undefined) return cached;
|
||
const source = this.readFileCached(filePath);
|
||
const lines = source === null ? null : source.split(/\r?\n/);
|
||
this.fileLinesCache.set(filePath, lines);
|
||
return lines;
|
||
},
|
||
|
||
getProjectRoot: () => this.projectRoot,
|
||
|
||
getAllFiles: () => {
|
||
return this.queries.getAllFilePaths();
|
||
},
|
||
|
||
listDirectories: (relativePath: string) => {
|
||
const target = relativePath === '.' || relativePath === ''
|
||
? this.projectRoot
|
||
: path.join(this.projectRoot, relativePath);
|
||
try {
|
||
return fs
|
||
.readdirSync(target, { withFileTypes: true })
|
||
.filter((entry) => entry.isDirectory())
|
||
.map((entry) => entry.name);
|
||
} catch (error) {
|
||
logDebug('Failed to list directory for resolution', {
|
||
relativePath,
|
||
error: String(error),
|
||
});
|
||
return [];
|
||
}
|
||
},
|
||
|
||
getNodesByLowerName: (lowerName: string) => {
|
||
const cached = this.lowerNameCache.get(lowerName);
|
||
if (cached !== undefined) return cached;
|
||
const result = this.queries.getNodesByLowerName(lowerName);
|
||
this.lowerNameCache.set(lowerName, result);
|
||
return result;
|
||
},
|
||
|
||
getNodeById: (id: string) => {
|
||
return this.nodeById(id);
|
||
},
|
||
|
||
getSupertypes: (typeName: string, language) => {
|
||
// Union the `implements`/`extends` targets of every same-named type node.
|
||
// Matching by simple name (not id) reconciles a type declared in one node
|
||
// (`KF::Builder`) with conformance declared in a separate extension node
|
||
// (`KF.Builder: KFOptionSetter`) — both have name `Builder`.
|
||
// Memoized per batch generation (see supertypeMemo): within a batch the
|
||
// edge state is fixed, and the conformance walk re-queries the same
|
||
// popular supertypes (Swift stdlib protocols especially) thousands of
|
||
// times per batch.
|
||
const memoKey = `${language} ${typeName}`;
|
||
const hit = this.supertypeMemo.get(memoKey);
|
||
if (hit && hit.gen === this.supertypeGen) return hit.supers;
|
||
const typeNodes = this.context
|
||
.getNodesByName(typeName)
|
||
// Scala singletons can inherit members even though they cannot be parents.
|
||
.filter((n) => n.language === language && (SUPERTYPE_BEARING_KINDS.has(n.kind) ||
|
||
(n.language === 'scala' && n.kind === 'module')));
|
||
let supers: string[];
|
||
if (typeNodes.length === 0) {
|
||
supers = [];
|
||
} else {
|
||
const supertypes = new Set<string>();
|
||
for (const tn of typeNodes) {
|
||
for (const edge of this.queries.getOutgoingEdges(tn.id, RESOLUTION_READ_EDGE_KINDS)) {
|
||
const target = this.nodeById(edge.target);
|
||
if (target?.name && target.name !== typeName) supertypes.add(target.name);
|
||
}
|
||
// A Swift conformance to a type the project only extends (SwiftUI's
|
||
// `View`) resolves to nothing — the extension is not the type — yet
|
||
// the members its extensions add are still the conformer's.
|
||
if (language === 'swift') {
|
||
for (const name of swiftExtendedConformances(tn, this.context)) {
|
||
if (name !== typeName) supertypes.add(name);
|
||
}
|
||
}
|
||
}
|
||
supers = [...supertypes];
|
||
}
|
||
this.supertypeMemo.set(memoKey, { gen: this.supertypeGen, supers });
|
||
return supers;
|
||
},
|
||
|
||
getSupertypeNodes: (id: string) => {
|
||
const hit = this.supertypeNodeMemo.get(id);
|
||
if (hit && hit.gen === this.supertypeGen) return hit.nodes;
|
||
const nodes: Node[] = [];
|
||
for (const edge of this.queries.getOutgoingEdges(id, RESOLUTION_READ_EDGE_KINDS)) {
|
||
const target = this.nodeById(edge.target);
|
||
if (target) nodes.push(target);
|
||
}
|
||
this.supertypeNodeMemo.set(id, { gen: this.supertypeGen, nodes });
|
||
return nodes;
|
||
},
|
||
|
||
getImportMappings: (filePath: string, language) => {
|
||
const cacheKey = filePath;
|
||
const cached = this.importMappingCache.get(cacheKey);
|
||
if (cached) return cached;
|
||
|
||
const content = this.context.readFile(filePath);
|
||
if (!content) {
|
||
this.importMappingCache.set(cacheKey, []);
|
||
return [];
|
||
}
|
||
|
||
const mappings = extractImportMappings(filePath, content, language);
|
||
this.importMappingCache.set(cacheKey, mappings);
|
||
return mappings;
|
||
},
|
||
|
||
getProjectAliases: () => {
|
||
if (this.projectAliases === undefined) {
|
||
this.projectAliases = loadProjectAliases(this.projectRoot);
|
||
}
|
||
return this.projectAliases;
|
||
},
|
||
|
||
getNearestAliases: (fromFile: string) => {
|
||
let dir = path.posix.dirname(fromFile.replace(/\\/g, '/'));
|
||
const walked: string[] = [];
|
||
let found: AliasMap | null = null;
|
||
while (dir && dir !== '.' && dir !== '/') {
|
||
const hit = this.dirAliases.get(dir);
|
||
if (hit !== undefined) {
|
||
found = hit;
|
||
break;
|
||
}
|
||
walked.push(dir);
|
||
const abs = path.join(this.projectRoot, dir);
|
||
if (['tsconfig.json', 'jsconfig.json'].some((name) => fs.existsSync(path.join(abs, name)))) {
|
||
const aliases = loadProjectAliases(abs);
|
||
if (aliases) {
|
||
found = aliases;
|
||
break;
|
||
}
|
||
}
|
||
dir = path.posix.dirname(dir);
|
||
}
|
||
for (const d of walked) this.dirAliases.set(d, found);
|
||
return found;
|
||
},
|
||
|
||
getGoPackageDir: (importPath: string, fromFile?: string) => {
|
||
const own = fromFile === undefined ? null : this.nearestGoModule(goDirOf(fromFile));
|
||
const key = `${importPath}\0${own?.rootDir ?? ''}`;
|
||
const hit = this.goPackageDirs.get(key);
|
||
if (hit !== undefined) return hit;
|
||
const mod = findGoModuleForImport(importPath, this.getGoModules(), own);
|
||
const dir = mod ? goModulePackageDir(importPath, mod, this.projectRoot) : null;
|
||
this.goPackageDirs.set(key, dir);
|
||
return dir;
|
||
},
|
||
|
||
getWorkspacePackages: () => {
|
||
if (this.workspacePackages === undefined) {
|
||
this.workspacePackages = loadWorkspacePackages(this.projectRoot);
|
||
}
|
||
return this.workspacePackages;
|
||
},
|
||
|
||
getReExports: (filePath: string, language) => {
|
||
const cached = this.reExportCache.get(filePath);
|
||
if (cached) return cached;
|
||
const content = this.context.readFile(filePath);
|
||
if (!content) {
|
||
this.reExportCache.set(filePath, []);
|
||
return [];
|
||
}
|
||
// Re-exports are a JS/TS-only construct, and what matters is the
|
||
// BARREL file's own language — not the consuming reference's. A
|
||
// `.svelte`/`.vue` consumer threads its own language down the
|
||
// re-export chase, which would make extractReExports() bail on a
|
||
// `.ts` index barrel and silently break the chain (#629). Re-key
|
||
// the parse on the barrel's extension so the chase works no matter
|
||
// what kind of file imports through it.
|
||
const isJsFamily = /\.(?:d\.ts|[cm]?tsx?|[cm]?jsx?|ets)$/i.test(filePath);
|
||
const reExports = extractReExports(content, isJsFamily ? 'typescript' : language);
|
||
this.reExportCache.set(filePath, reExports);
|
||
return reExports;
|
||
},
|
||
|
||
getCppIncludeDirs: () => {
|
||
return loadCppIncludeDirs(this.projectRoot);
|
||
},
|
||
|
||
getCppIncludeNodes: () => this.queries.getCppIncludeNodes(),
|
||
};
|
||
}
|
||
|
||
/**
|
||
* Resolve all unresolved references
|
||
*/
|
||
resolveAll(
|
||
unresolvedRefs: UnresolvedReference[],
|
||
onProgress?: (current: number, total: number) => void
|
||
): ResolutionResult {
|
||
// Pre-load all nodes into memory for fast lookups
|
||
this.warmCaches();
|
||
this.advanceSupertypeGeneration();
|
||
|
||
const resolved: ResolvedRef[] = [];
|
||
const unresolved: UnresolvedRef[] = [];
|
||
const byMethod: Record<string, number> = {};
|
||
|
||
// Convert to our internal format, using denormalized fields when available
|
||
const refs: UnresolvedRef[] = unresolvedRefs.map((ref) => ({
|
||
fromNodeId: ref.fromNodeId,
|
||
referenceName: ref.referenceName,
|
||
referenceKind: ref.referenceKind,
|
||
line: ref.line,
|
||
column: ref.column,
|
||
filePath: ref.filePath || this.getFilePathFromNodeId(ref.fromNodeId),
|
||
language: ref.language || this.getLanguageFromNodeId(ref.fromNodeId),
|
||
rowId: ref.rowId,
|
||
}));
|
||
|
||
const total = refs.length;
|
||
let lastReportedPercent = -1;
|
||
|
||
for (let i = 0; i < refs.length; i++) {
|
||
const ref = refs[i]!; // Array index is guaranteed to be in bounds
|
||
const result = this.resolveOneTimed(ref);
|
||
|
||
if (result) {
|
||
resolved.push(result);
|
||
byMethod[result.resolvedBy] = (byMethod[result.resolvedBy] || 0) + 1;
|
||
} else {
|
||
unresolved.push(this.parkable(ref));
|
||
}
|
||
|
||
// Report progress every 1% to avoid too many updates
|
||
if (onProgress) {
|
||
const currentPercent = Math.floor((i / total) * 100);
|
||
if (currentPercent > lastReportedPercent) {
|
||
lastReportedPercent = currentPercent;
|
||
onProgress(i + 1, total);
|
||
}
|
||
}
|
||
}
|
||
|
||
// Final progress report
|
||
if (onProgress && total > 0) {
|
||
onProgress(total, total);
|
||
}
|
||
|
||
return {
|
||
resolved,
|
||
unresolved,
|
||
stats: {
|
||
total: refs.length,
|
||
resolved: resolved.length,
|
||
unresolved: unresolved.length,
|
||
byMethod,
|
||
},
|
||
};
|
||
}
|
||
|
||
/** Lowercased `knownNames`, built the first time a case-insensitive language asks. */
|
||
private knownLowerNames: Set<string> | null = null;
|
||
|
||
/** `hasAnyPossibleMatch` for a language whose names ignore case: the name, or any `.`/`::`/`->` part of it. */
|
||
private hasAnyPossibleMatchIgnoringCase(name: string): boolean {
|
||
if (!this.knownNames) return true;
|
||
if (!this.knownLowerNames || this.knownLowerNames.size === 0) {
|
||
this.knownLowerNames = new Set();
|
||
for (const known of this.knownNames) this.knownLowerNames.add(known.toLowerCase());
|
||
}
|
||
const lower = name.toLowerCase();
|
||
if (this.knownLowerNames.has(lower)) return true;
|
||
return lower.split(/::|->|\./).some((part) => part.length > 0 && this.knownLowerNames!.has(part));
|
||
}
|
||
|
||
/**
|
||
* Check if a reference name has any possible match in the codebase.
|
||
* Uses the pre-built knownNames set to skip expensive resolution
|
||
* for names that definitely don't exist as symbols.
|
||
*/
|
||
private hasAnyPossibleMatch(name: string): boolean {
|
||
if (!this.knownNames) return true; // no pre-filter available
|
||
|
||
// Direct name match
|
||
if (this.knownNames.has(name)) return true;
|
||
|
||
// For qualified names like "obj.method" or "Class::method", check the parts
|
||
const dotIdx = name.indexOf('.');
|
||
if (dotIdx > 0) {
|
||
const receiver = name.substring(0, dotIdx);
|
||
const member = name.substring(dotIdx + 1);
|
||
if (this.knownNames.has(receiver) || this.knownNames.has(member)) return true;
|
||
// Also check capitalized receiver (instance-method resolution)
|
||
const capitalized = receiver.charAt(0).toUpperCase() + receiver.slice(1);
|
||
if (this.knownNames.has(capitalized)) return true;
|
||
// JVM FQN: `com.example.foo.Bar` — the only useful segment is the
|
||
// last one (`Bar`); the earlier check finds `example.foo.Bar` which
|
||
// never matches a node name.
|
||
const lastDot = name.lastIndexOf('.');
|
||
if (lastDot > dotIdx) {
|
||
const tail = name.substring(lastDot + 1);
|
||
if (tail && this.knownNames.has(tail)) return true;
|
||
}
|
||
}
|
||
const colonIdx = name.indexOf('::');
|
||
if (colonIdx > 0) {
|
||
const receiver = name.substring(0, colonIdx);
|
||
const member = name.substring(colonIdx + 2);
|
||
if (this.knownNames.has(receiver) || this.knownNames.has(member)) return true;
|
||
// Multi-segment path `a::b::c` (a Rust/C++ module call like
|
||
// `database::profiles::find`) — the only segment that names a symbol is
|
||
// the last (`c`); `member` above is `b::c`, which never matches a node
|
||
// name, so without this the pre-filter drops the ref before the Rust path
|
||
// resolver ever sees it. Mirror the dotted-name leaf check above.
|
||
const lastColon = name.lastIndexOf('::');
|
||
if (lastColon > colonIdx) {
|
||
const tail = name.substring(lastColon + 2);
|
||
if (tail && this.knownNames.has(tail)) return true;
|
||
}
|
||
}
|
||
|
||
// Lua/Luau method calls use a single `:` (`lg:log`); R uses `$` (`lg$log`).
|
||
// Check the member (and receiver) around these separators too, so the ref
|
||
// isn't dropped here before the method-call resolver ever sees it. The `:`
|
||
// case is skipped when the name actually contains `::` (handled above).
|
||
for (const sep of [':', '$']) {
|
||
if (sep === ':' && name.includes('::')) continue;
|
||
const sepIdx = name.indexOf(sep);
|
||
if (sepIdx > 0) {
|
||
const receiver = name.substring(0, sepIdx);
|
||
const member = name.substring(sepIdx + 1);
|
||
if (this.knownNames.has(member) || this.knownNames.has(receiver)) return true;
|
||
const capitalized = receiver.charAt(0).toUpperCase() + receiver.slice(1);
|
||
if (this.knownNames.has(capitalized)) return true;
|
||
}
|
||
}
|
||
|
||
// For path-like references (e.g., "snippets/drawer-menu.liquid"), check the filename
|
||
const slashIdx = name.lastIndexOf('/');
|
||
if (slashIdx > 0) {
|
||
const fileName = name.substring(slashIdx + 1);
|
||
if (this.knownNames.has(fileName)) return true;
|
||
}
|
||
|
||
return false;
|
||
}
|
||
|
||
/**
|
||
* Does `ref.referenceName` match an import declared in its containing
|
||
* file? Used as a pre-filter escape so re-export chain resolution
|
||
* still gets a chance when the name has no project-wide declaration.
|
||
*/
|
||
private matchesAnyImport(ref: UnresolvedRef): boolean {
|
||
const imports = this.context.getImportMappings(ref.filePath, ref.language);
|
||
if (imports.length === 0) return false;
|
||
for (const imp of imports) {
|
||
if (
|
||
imp.localName === ref.referenceName ||
|
||
ref.referenceName.startsWith(imp.localName + '.')
|
||
) {
|
||
return true;
|
||
}
|
||
}
|
||
return false;
|
||
}
|
||
|
||
/**
|
||
* Resolve a single reference.
|
||
*
|
||
* Thin decorator over `resolveOneInner` so every strategy — framework,
|
||
* import, name-match, chain, CFML component path — passes through the
|
||
* inheritance target-kind gate at ONE seam. Filtering inside the
|
||
* name-matcher would have covered `matchByExactName` only.
|
||
* Calls that land on an alias binding then forward once to the callable
|
||
* the alias names (see ./alias-binding), regardless of the strategy.
|
||
*/
|
||
resolveOne(ref: UnresolvedRef): ResolvedRef | null {
|
||
// A C/C++ "call" whose name is a function-like macro visible in this
|
||
// translation unit is a macro expansion, not a call — it must never bind
|
||
// to a same-named function in another file (#1838).
|
||
if (isVisibleCppMacro(ref, this.context)) return null;
|
||
// A Swift type reference never lands on an `extension X {}` node, nor on a
|
||
// nested type it cannot name bare (see ./swift-type-visibility).
|
||
// A name a declaration around the reference declares as a type parameter
|
||
// (`def f[A]`, `class Foo<T>`) is that parameter (see ./type-parameters),
|
||
// and a Dart call to a parameter or local calls that (./dart-local-scope).
|
||
const candidate = gateDartLocal(
|
||
gateTypeParameter(
|
||
gateSwiftTypeTarget(this.gateTargetKind(this.resolveOneInner(ref), ref), ref, this.context),
|
||
ref,
|
||
this.context,
|
||
),
|
||
ref,
|
||
this.context,
|
||
);
|
||
const scoped = this.gateRustScope(candidate, ref);
|
||
const resolved = this.gateSuperSelfCall(
|
||
scoped?.resolvedBy === 'framework' ? this.gateFrameworkLanguage(scoped, ref) : this.gateLanguage(scoped, ref),
|
||
ref,
|
||
);
|
||
// A Dart class whose field holds its own type (`class Node { Node? next; }`)
|
||
// names itself: a self-edge that says nothing (#2327).
|
||
if (resolved && ref.language === 'dart' && ref.referenceKind === 'references' &&
|
||
resolved.targetNodeId === ref.fromNodeId) return null;
|
||
if (!resolved || ref.referenceKind !== 'calls') return resolved;
|
||
|
||
const target = this.nodeById(resolved.targetNodeId);
|
||
if (!target) return resolved;
|
||
|
||
const dot = ref.referenceName.lastIndexOf('.');
|
||
const memberName = dot >= 0 ? ref.referenceName.slice(dot + 1) : null;
|
||
const forwarded = resolveAliasBinding(target, memberName, this.context);
|
||
if (!forwarded || forwarded.id === resolved.targetNodeId) return resolved;
|
||
|
||
return this.gateLanguage({
|
||
...resolved,
|
||
targetNodeId: forwarded.id,
|
||
confidence: Math.min(resolved.confidence, 0.85),
|
||
}, ref);
|
||
}
|
||
|
||
private resolveOneInner(ref: UnresolvedRef): ResolvedRef | null {
|
||
// A local C++ object construction (`T obj(args)`, ref `ns::T::T/1`)
|
||
// resolves ONLY to a constructor of the lexically nearest `T` (#1839).
|
||
if (isCppConstructorRef(ref)) return matchCppConstructor(ref, this.context);
|
||
// A C or C++ base class is the one C++ name lookup finds from where the
|
||
// class is declared — never a namesake of another namespace or language,
|
||
// which a framework's heuristics or name matching would take (see
|
||
// ./cpp-supertypes).
|
||
if (isCppSupertypeRef(ref)) return matchCppSupertype(ref, this.context);
|
||
|
||
// A Dart member read (`x.area`) links the getter the receiver's type
|
||
// reaches, as a call, or nothing — never a guess by name (#2338).
|
||
if (isDartMemberRead(ref)) return matchDartMemberRead(ref, this.context);
|
||
// So does a later link of a Dart call chain (`X.autoDispose.family(…)`,
|
||
// `events.map(f).transform(…)`), which arrives by its bare name: a member
|
||
// of what the chain's head and links are declared to be, or nothing (#750).
|
||
if (isDartChainLink(ref, this.context)) return matchDartChainLink(ref, this.context);
|
||
// A Dart annotation (`@riverpod`, `@Riverpod(…)`) is a constant or a
|
||
// constructor call, as written — never a method or function by its name.
|
||
if (isDartAnnotation(ref)) return matchDartAnnotation(ref, this.context);
|
||
// A Go call through a type assertion (`srv.(KVServer).Range(ctx, in)`),
|
||
// which arrives by its bare name, is to a method of the asserted type, or
|
||
// to nothing the project declares.
|
||
const asserted = matchGoAssertedCall(ref, this.context);
|
||
if (asserted !== undefined) return asserted;
|
||
|
||
// A section or snippet a Shopify theme's file names is that theme's own,
|
||
// or nothing: Shopify never looks in another theme (see ./shopify-themes).
|
||
const themeFile = matchShopifyThemeFile(ref, this.context);
|
||
if (themeFile !== undefined) return themeFile;
|
||
|
||
// Skip built-in/external references
|
||
if (this.isBuiltInOrExternal(ref)) {
|
||
return null;
|
||
}
|
||
|
||
// CFML component paths in inheritance (#1152): `extends="coldbox.system.web.
|
||
// Controller"` names the supertype by its dot-separated path (or `extends=
|
||
// "../base"` by relative file path) — the graph indexes the class under its
|
||
// final segment only, so these die at the fast pre-filter below and never
|
||
// resolved. Handled by a dedicated path-corroborated matcher, gated to
|
||
// inheritance refs only (a dotted `calls` ref is a member-access chain, not
|
||
// a component path). No fallthrough on miss: the full path string can only
|
||
// ever mis-match downstream, and an unresolvable supertype usually lives in
|
||
// an out-of-repo library (mxunit, testbox) — silent beats wrong.
|
||
if (
|
||
(ref.language === 'cfml' || ref.language === 'cfscript') &&
|
||
(ref.referenceKind === 'extends' || ref.referenceKind === 'implements') &&
|
||
(ref.referenceName.includes('.') || ref.referenceName.includes('/'))
|
||
) {
|
||
return this.resolveCfmlComponentPath(ref);
|
||
}
|
||
|
||
// A PHP class written with a namespace in it — `new Alias\X()` through a
|
||
// `use Ns as Alias;` namespace alias, `extends Sub\Base`, `\Ns\X::make()`
|
||
// (#2256). The pre-filter below would drop most of these before any import
|
||
// strategy ran, and PHP gives each one exactly one meaning; resolve it first.
|
||
const phpQualified = resolvePhpQualifiedClassRef(ref, this.context);
|
||
if (phpQualified !== undefined) return this.gateLanguage(phpQualified, ref);
|
||
|
||
// Fast pre-filter: skip if no symbol with this name exists anywhere
|
||
// AND the name doesn't match a local import. The import escape is
|
||
// necessary because re-export rename chains (`import { login }
|
||
// from './barrel'` where the barrel has `export { signIn as login }
|
||
// from './auth'`) intentionally call a name that has no
|
||
// declaration anywhere — only the renamed upstream symbol does.
|
||
// ArkTS chained-attribute refs carry a leading dot (`.titleStyle`) that
|
||
// routes them to the decorator-gated matcher; the symbol itself is
|
||
// indexed under the bare name, so the existence check strips the dot.
|
||
// Nix static path imports (`import ./x.nix`) and JS/TS module paths
|
||
// (`require('./x')`) name a FILE, not a symbol — they bypass the
|
||
// symbol-existence check and resolve via resolveViaImport.
|
||
let existenceName =
|
||
ref.language === 'arkts' && ref.referenceName.startsWith('.')
|
||
? ref.referenceName.slice(1)
|
||
: ref.referenceName;
|
||
// Erlang refs carry the call-site arity (`f/1`, `mod::f/2` — #1610); the
|
||
// name index stores bare names, so existence is checked arity-less.
|
||
if (ref.language === 'erlang') existenceName = existenceName.replace(/\/\d{1,3}$/, '');
|
||
// A C or C++ name written from the global scope (`::_pbi::PrivateAccess::
|
||
// GenerateParseTable`, `::memset`) exists when the name under the `::` does.
|
||
if ((ref.language === 'cpp' || ref.language === 'c') && existenceName.startsWith('::')) {
|
||
existenceName = existenceName.slice(2);
|
||
}
|
||
const tPre = this.profileStages ? process.hrtime.bigint() : 0n;
|
||
const preFilterPass =
|
||
isNixPathImportRef(ref) ||
|
||
isJsPathImportRef(ref) ||
|
||
this.hasAnyPossibleMatch(existenceName) ||
|
||
// PHP, Pascal, CFML, COBOL and VB.NET names ignore case: `formatprice()`
|
||
// calls `FormatPrice`, which the exact-name set never lists.
|
||
(CASE_INSENSITIVE_LANGUAGES.has(ref.language) && this.hasAnyPossibleMatchIgnoringCase(existenceName)) ||
|
||
this.matchesAnyImport(ref) ||
|
||
this.frameworksFor(ref.language).some((f) => f.claimsReference?.(ref.referenceName));
|
||
if (this.profileStages) this.stageAdd('preFilter', ref, preFilterPass, tPre);
|
||
if (!preFilterPass) {
|
||
return this.gateLanguage(matchJsStoreBindingCall(ref, this.context), ref);
|
||
}
|
||
|
||
// A VB.NET member read (`AppSession.SessionId`, #2305; `x.Normal`,
|
||
// `Me._h.Title`) means what VB.NET's scoping says its receiver is — a
|
||
// project type, whose member and the type itself it links, or a value,
|
||
// whose declared type's member it links — and no framework, import or
|
||
// name strategy guesses past that. Nor past a `With` block's call through
|
||
// a receiver path (`.Run()` in `With Me._h`).
|
||
if (isVbMemberRead(ref)) return this.gateLanguage(matchVbMemberRead(ref, this.context), ref);
|
||
if (isVbPathCall(ref)) {
|
||
return this.gateLanguage(matchVbPathCall(ref, this.context, (name) => isStdMethodName('vbnet', name)), ref);
|
||
}
|
||
|
||
// Function-as-value refs (#756) get a dedicated, strictly-gated path:
|
||
// import-based resolution first (an imported callback resolves through its
|
||
// import, the most precise cross-file signal), then matchFunctionRef
|
||
// (same-file first, unique-only cross-file, function/method targets only).
|
||
// They never reach the framework or fuzzy strategies below.
|
||
if (ref.referenceKind === 'function_ref') {
|
||
// `this.<member>` values (TS/JS) resolve ONLY against the enclosing
|
||
// class's own members — never a same-named symbol elsewhere.
|
||
if (ref.referenceName.startsWith('this.')) {
|
||
return this.gateLanguage(this.resolveThisMemberFnRef(ref), ref);
|
||
}
|
||
if ((ref.language === 'python' || ref.language === 'go') && ref.referenceName.includes('.')) {
|
||
return this.gateLanguage(matchFunctionRef(ref, this.context), ref);
|
||
}
|
||
const viaImport = this.gateLanguage(resolveViaImport(ref, this.context), ref);
|
||
if (viaImport) {
|
||
const target = this.nodeById(viaImport.targetNodeId);
|
||
if (
|
||
target &&
|
||
(target.kind === 'function' ||
|
||
target.kind === 'method' ||
|
||
// Python (#1478): an imported class used as a value (`return
|
||
// OrgSerializerFull`) resolves through its import like any
|
||
// callback — mirrors matchFunctionRef's bareClassOk.
|
||
(ref.language === 'python' && target.kind === 'class'))
|
||
) {
|
||
return viaImport;
|
||
}
|
||
}
|
||
return this.gateLanguage(matchFunctionRef(ref, this.context), ref);
|
||
}
|
||
|
||
// JVM FQN imports skip framework/name-matcher: `import com.example.Bar`
|
||
// resolves directly through the qualifiedName index, which is unambiguous
|
||
// even when several `Bar` classes exist in different packages.
|
||
const tJvm = this.profileStages ? process.hrtime.bigint() : 0n;
|
||
const jvmImport = resolveJvmImport(ref, this.context);
|
||
if (this.profileStages) this.stageAdd('jvmImport', ref, !!jvmImport, tJvm);
|
||
if (jvmImport) return jvmImport;
|
||
|
||
// Razor/Blazor: a markup or `@code` type ref resolves through the file's
|
||
// `@using` namespaces (incl. folder `_Imports.razor`). This precisely
|
||
// disambiguates a simple name that exists in several namespaces — e.g.
|
||
// `CatalogBrand` resolving to `BlazorShared.Models::CatalogBrand` (the DTO,
|
||
// which the `.razor` `@using`s) rather than the same-named domain entity.
|
||
if (ref.language === 'razor') {
|
||
const razorResult = this.resolveRazorUsing(ref);
|
||
if (razorResult) return razorResult;
|
||
}
|
||
|
||
// An explicit PHP class import owns its static calls, including an
|
||
// unavailable method. Do not let same-name fallbacks change the receiver
|
||
// to an unrelated Service/Repository type (#1545).
|
||
const phpStaticImport = resolvePhpImportedStaticCall(ref, this.context);
|
||
if (phpStaticImport !== undefined) return this.gateLanguage(phpStaticImport, ref);
|
||
|
||
const candidates: ResolvedRef[] = [];
|
||
|
||
// Strategy 1: Try framework-specific resolution, by the frameworks that
|
||
// read this reference's language: Express's `logger` middleware rule took
|
||
// a Go method's `*zap.Logger` result for the method itself (etcd).
|
||
// Cross-language bridges are deliberately preserved (Drupal `routing.yml`
|
||
// → PHP controller, RN JS → native `calls`); each lists the language its
|
||
// references are written in. Other code references obey the shared
|
||
// family gate.
|
||
const tFw = this.profileStages ? process.hrtime.bigint() : 0n;
|
||
let fwEarly: ResolvedRef | null = null;
|
||
for (const framework of this.frameworksFor(ref.language)) {
|
||
const resolved = this.gateFrameworkLanguage(framework.resolve(ref, this.context), ref);
|
||
// Name the resolver on the edge (`metadata.framework`): a Swift→ObjC or
|
||
// React Native bridge hop says how it got into the graph, as a
|
||
// synthesized edge's `synthesizedBy` does.
|
||
const result = resolved ? { ...resolved, metadata: { ...resolved.metadata, framework: framework.name } } : null;
|
||
if (result) {
|
||
if (result.confidence >= 0.9) {
|
||
fwEarly = result; // High confidence, return immediately (below)
|
||
break;
|
||
}
|
||
candidates.push(result);
|
||
}
|
||
}
|
||
if (this.profileStages) this.stageAdd('frameworks', ref, fwEarly !== null, tFw);
|
||
if (fwEarly) return fwEarly;
|
||
// A retained untyped chain supplies effect/call-site evidence only. In
|
||
// particular, importing its root does not make the root its call target.
|
||
// A path through module namespaces is not untyped: `z.coerce.number()`
|
||
// after `import * as z`, where the barrel has `export * as coerce`.
|
||
if (isUnresolvedJsMemberCall(ref)) {
|
||
const root = ref.referenceName.slice(0, ref.referenceName.indexOf('.'));
|
||
const namespace = this.context.getImportMappings(ref.filePath, ref.language).some((m) => m.isNamespace && m.localName === root);
|
||
// `App.utils.fmt()` through a path an object literal was hung on (#2300).
|
||
if (!namespace) return this.gateLanguage(matchObjectPathCall(ref, this.context), ref);
|
||
const viaNamespace = this.gateLanguage(resolveViaImport(ref, this.context), ref);
|
||
const target = viaNamespace ? this.nodeById(viaNamespace.targetNodeId) : null;
|
||
return target && (target.kind === 'function' || target.kind === 'method' || target.kind === 'class' || target.kind === 'constant' || target.kind === 'variable')
|
||
? viaNamespace : null;
|
||
}
|
||
|
||
// Strategy 2: Try import-based resolution
|
||
// A TS/JS/Python call-receiver chain (`useStore.getState().reset`, #1683)
|
||
// names the ROOT's import, not the method's: letting resolveViaImport see
|
||
// it binds the call to the imported store constant and the method is
|
||
// never looked up. The name-matcher owns the chain shape for these
|
||
// languages — the Java/Kotlin/C++ chains keep their existing path.
|
||
if (
|
||
ref.referenceKind === 'calls' &&
|
||
CHAIN_SHAPE.test(ref.referenceName) &&
|
||
(ref.language === 'typescript' || ref.language === 'javascript' || ref.language === 'tsx' || ref.language === 'jsx' || ref.language === 'python')
|
||
) {
|
||
return this.gateLanguage(matchReference(ref, this.context), ref);
|
||
}
|
||
|
||
const tImp = this.profileStages ? process.hrtime.bigint() : 0n;
|
||
// `self.get_ip()` is a method call on the instance even when the file
|
||
// also imports a function named `get_ip`: the import never names it.
|
||
const selfCall = ref.language === 'python' && ref.referenceKind === 'calls' &&
|
||
this.context.getImportMappings(ref.filePath, ref.language).some((m) => m.localName === ref.referenceName) &&
|
||
isPythonSelfCall(ref, this.context);
|
||
const importResult = selfCall ? null : this.gateLanguage(resolveViaImport(ref, this.context), ref);
|
||
if (this.profileStages) this.stageAdd('viaImport', ref, !!importResult, tImp);
|
||
if (importResult) {
|
||
if (importResult.confidence >= 0.9) return importResult;
|
||
candidates.push(importResult);
|
||
}
|
||
|
||
// PHP include/require paths resolve to files via import resolution only.
|
||
// If that didn't find the file, do NOT fall back to the symbol
|
||
// name-matcher — it would mis-connect e.g. "inc/db.php" to an unrelated
|
||
// db.php elsewhere in the tree (a wrong edge is worse than none, #660).
|
||
// Terraform refs are directory-scoped by language semantics — the
|
||
// framework resolver IS the whole rulebook (`var.X` can never legally
|
||
// bind outside its module directory), so the name-matcher's
|
||
// qualified-name fallback would only ever add wrong cross-module edges.
|
||
// Nix static path imports are file references for the same reason —
|
||
// falling through would let "./x.nix" name-match an unrelated node. So
|
||
// is a Dart import's URI: `package:flutter/foundation.dart` matched by
|
||
// its last segment went to riverpod's own foundation.dart. And a Lua
|
||
// `require`, whose leaf matched the local it is assigned to.
|
||
if (isPhpIncludePathRef(ref) || isCobolCopybookRef(ref) || isNixPathImportRef(ref) || isDartImportRef(ref) || isLuaRequireRef(ref) || ref.language === 'terraform') {
|
||
return candidates.length > 0
|
||
? candidates.reduce((best, curr) =>
|
||
curr.confidence > best.confidence ? curr : best
|
||
)
|
||
: null;
|
||
}
|
||
|
||
// Strategy 3: Try name matching
|
||
const tName = this.profileStages ? process.hrtime.bigint() : 0n;
|
||
let nameResult = this.gateLanguage(matchReference(ref, this.context), ref);
|
||
if (this.profileStages) this.stageAdd('nameMatch', ref, !!nameResult, tName);
|
||
// Nix has no ambient cross-file namespace — a callee binds lexically
|
||
// (same file) or through explicit import/callPackage wiring (the import
|
||
// path above). A cross-file name match is wrong by construction: every
|
||
// module `inherit (lib) mkOption`s the same nixpkgs helpers, so the
|
||
// matcher would link each `mkOption` call to whichever file's inherit
|
||
// binding it happened to pick. Same-file matches only.
|
||
if (nameResult) {
|
||
const target = this.nodeById(nameResult.targetNodeId);
|
||
// A definition its language makes file-local — a C `static`, a Kotlin
|
||
// `private fun`, a Go unexported name in another package, a Rust
|
||
// non-`pub` item outside its module subtree — cannot be what a name in
|
||
// another file means, whichever strategy chose it (#1730).
|
||
if (target && !isVisibleAcrossFiles(target, ref, this.context)) {
|
||
nameResult = null;
|
||
} else if (ref.language === 'nix') {
|
||
if (!target || target.filePath !== ref.filePath) {
|
||
nameResult = null;
|
||
}
|
||
} else if (target && target.language === 'nix') {
|
||
// The reverse direction is just as impossible: no other language can
|
||
// symbolically call into a .nix binding (interop is eval/CLI, never a
|
||
// linkable symbol) — without this, a Python script's `split()` lands
|
||
// on some module's `split = ...` binding as a low-confidence match.
|
||
nameResult = null;
|
||
}
|
||
}
|
||
if (nameResult) {
|
||
candidates.push(nameResult);
|
||
}
|
||
|
||
if (candidates.length === 0) {
|
||
// Defer a chained static-factory/fluent call the first pass couldn't
|
||
// resolve — its method may live on a supertype the receiver conforms to,
|
||
// resolvable once implements/extends edges exist (the conformance pass).
|
||
if (
|
||
ref.referenceKind === 'calls' &&
|
||
CHAIN_LANGUAGES.has(ref.language) &&
|
||
CHAIN_SHAPE.test(ref.referenceName)
|
||
) {
|
||
this.deferReference(ref, this.deferredChainRefs);
|
||
} else if (
|
||
// PHP `$this->prop->method()` (encoded `this->prop.method`): its method
|
||
// may live on the property's declared supertype, resolvable only once
|
||
// implements/extends edges exist — defer to the same conformance pass.
|
||
ref.referenceKind === 'calls' &&
|
||
ref.language === 'php' &&
|
||
PHP_PROP_SHAPE.test(ref.referenceName)
|
||
) {
|
||
this.deferReference(ref, this.deferredChainRefs);
|
||
}
|
||
return null;
|
||
}
|
||
|
||
// Return highest confidence candidate
|
||
return candidates.reduce((best, curr) =>
|
||
curr.confidence > best.confidence ? curr : best
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Create edges from resolved references
|
||
*/
|
||
createEdges(resolved: ResolvedRef[]): Edge[] {
|
||
return resolved.flatMap((ref) => {
|
||
// `function_ref` (#756) is internal-only: it persists as a `references`
|
||
// edge (the registration site depends on the callback), distinguishable
|
||
// by metadata.resolvedBy === 'function-ref'. callers/impact already
|
||
// traverse `references`, so registration sites surface with no
|
||
// graph-layer changes.
|
||
let kind: Edge['kind'] =
|
||
ref.edgeKind ??
|
||
(ref.original.referenceKind === 'function_ref' ? 'references' : ref.original.referenceKind);
|
||
|
||
// Promote "extends" to "implements" when a class/struct targets an interface
|
||
if (kind === 'extends') {
|
||
const targetNode = this.nodeById(ref.targetNodeId);
|
||
if (targetNode && (targetNode.kind === 'interface' || targetNode.kind === 'protocol')) {
|
||
const sourceNode = this.nodeById(ref.original.fromNodeId);
|
||
if (sourceNode && sourceNode.kind !== 'interface' && sourceNode.kind !== 'protocol') {
|
||
kind = 'implements';
|
||
}
|
||
}
|
||
}
|
||
|
||
// Promote "calls" to "instantiates" when the resolved target is a
|
||
// class/struct/union. Languages without a `new` keyword (Python, Ruby)
|
||
// express instantiation as `Foo()` — extraction can't tell that
|
||
// apart from a function call without symbol info, but resolution
|
||
// can: if `Foo` resolves to a class, the call IS an instantiation.
|
||
if (kind === 'calls') {
|
||
const targetNode = this.nodeById(ref.targetNodeId);
|
||
if (
|
||
targetNode &&
|
||
(targetNode.kind === 'class' || targetNode.kind === 'struct' || targetNode.kind === 'union')
|
||
) {
|
||
kind = 'instantiates';
|
||
}
|
||
}
|
||
|
||
// One reference can name several targets — a navigation whose
|
||
// destination is a conditional reaches every arm. Each becomes its own
|
||
// edge, sharing this resolution's kind and confidence.
|
||
const targets = [
|
||
{ targetNodeId: ref.targetNodeId, metadata: ref.metadata },
|
||
...(ref.alsoTargets ?? []),
|
||
];
|
||
return targets.map((t) => ({
|
||
source: ref.original.fromNodeId,
|
||
target: t.targetNodeId,
|
||
kind,
|
||
line: ref.original.line,
|
||
column: ref.original.column,
|
||
metadata: {
|
||
...(t.metadata ?? {}),
|
||
confidence: ref.confidence,
|
||
resolvedBy: ref.resolvedBy,
|
||
// The ORIGINAL reference text (and kind, when edge-kind promotion
|
||
// rewrote it — calls→instantiates, extends→implements,
|
||
// function_ref→references). If this edge's target is later removed
|
||
// by a re-index, the edge is resurrected as exactly this ref and
|
||
// re-resolved (#1240 removal case) — a faithful resurrection, so
|
||
// re-resolution can never bind anywhere a full re-index wouldn't.
|
||
// Reconstruction from the target node's name instead would strip
|
||
// receiver/qualifier context (`h.greet` → `greet`) and risk a
|
||
// wrong rebind; edges without refName (pre-#1240, synthesized) are
|
||
// deliberately NOT resurrected for the same reason.
|
||
refName: ref.original.referenceName,
|
||
...(ref.original.referenceKind !== kind ? { refKind: ref.original.referenceKind } : {}),
|
||
// Uniform marker for function-as-value edges (#756), regardless of
|
||
// which strategy resolved them (import vs matchFunctionRef) — lets
|
||
// tooling label "callback registration" and lets validation diff
|
||
// exactly the edges this feature added.
|
||
...(ref.original.referenceKind === 'function_ref' ? { fnRef: true } : {}),
|
||
},
|
||
}));
|
||
});
|
||
}
|
||
|
||
/**
|
||
* Split resolved refs into rows deletable by id and hand-built refs that
|
||
* must fall back to the key-tuple delete. Rows loaded from the database
|
||
* carry their row id and are deleted by exactly that id; the key tuple
|
||
* omits line/col, so it also removes SIBLING rows — the same caller calling
|
||
* the same callee at other lines — that a later batch hadn't attempted yet:
|
||
* when a batch boundary split a caller's same-named call sites, the later
|
||
* sites' edges were silently never created (#1269).
|
||
*/
|
||
private static partitionResolvedCleanup(resolved: ResolvedRef[]): {
|
||
rowIds: number[];
|
||
legacyKeys: Array<{ fromNodeId: string; referenceName: string; referenceKind: string }>;
|
||
} {
|
||
const rowIds: number[] = [];
|
||
const legacyKeys: Array<{ fromNodeId: string; referenceName: string; referenceKind: string }> = [];
|
||
for (const r of resolved) {
|
||
if (r.original.rowId != null) rowIds.push(r.original.rowId);
|
||
else legacyKeys.push({
|
||
fromNodeId: r.original.fromNodeId,
|
||
referenceName: r.original.referenceName,
|
||
referenceKind: r.original.referenceKind,
|
||
});
|
||
}
|
||
return { rowIds, legacyKeys };
|
||
}
|
||
|
||
/**
|
||
* Same row-id precision for parking unresolvable refs as status='failed'
|
||
* (#1240): the key-tuple fallback would flip same-key sibling rows in later
|
||
* batches to 'failed' before they were ever attempted, and resolution
|
||
* outcome can differ per call site (receiver-type inference reads the
|
||
* ref's line), so a sibling must not inherit this row's failure (#1269).
|
||
*/
|
||
private static partitionFailedCleanup(unresolved: UnresolvedRef[]): {
|
||
byRowId: Array<{ rowId: number; referenceName: string; referenceKind: string; nameTail?: string }>;
|
||
legacyKeys: Array<{ fromNodeId: string; referenceName: string; referenceKind: string; nameTail?: string }>;
|
||
} {
|
||
const byRowId: Array<{ rowId: number; referenceName: string; referenceKind: string; nameTail?: string }> = [];
|
||
const legacyKeys: Array<{ fromNodeId: string; referenceName: string; referenceKind: string; nameTail?: string }> = [];
|
||
for (const r of unresolved) {
|
||
if (r.rowId != null) byRowId.push({ rowId: r.rowId, referenceName: r.referenceName, referenceKind: r.referenceKind, nameTail: r.nameTail });
|
||
else legacyKeys.push({
|
||
fromNodeId: r.fromNodeId,
|
||
referenceName: r.referenceName,
|
||
referenceKind: r.referenceKind,
|
||
nameTail: r.nameTail,
|
||
});
|
||
}
|
||
return { byRowId, legacyKeys };
|
||
}
|
||
|
||
/**
|
||
* `ref`, which no strategy resolved, with the tail it is parked under when
|
||
* that is not the one its name gives: a reference through an import
|
||
* binding the module doesn't declare by that name waits for the module
|
||
* (see importBindingTail). Decided here, where the file's import mappings
|
||
* are still cached from the attempt — in a resolver-pool worker too.
|
||
*/
|
||
private parkable(ref: UnresolvedRef): UnresolvedRef {
|
||
const tail = importBindingTail(ref, this.context);
|
||
if (tail) ref.nameTail = tail;
|
||
return ref;
|
||
}
|
||
|
||
/** A deferred attempt is unfinished work, not a final failure (#1577). */
|
||
private nonDeferredFailures(unresolved: UnresolvedRef[]): UnresolvedRef[] {
|
||
return unresolved.filter((ref) => ref.rowId == null || !this.deferredRowIds.has(ref.rowId));
|
||
}
|
||
|
||
private deferReference(ref: UnresolvedRef, queue: UnresolvedRef[]): void {
|
||
queue.push(ref);
|
||
if (ref.rowId != null) this.deferredRowIds.add(ref.rowId);
|
||
}
|
||
|
||
/**
|
||
* Resolve and persist edges to database
|
||
*/
|
||
resolveAndPersist(
|
||
unresolvedRefs: UnresolvedReference[],
|
||
onProgress?: (current: number, total: number) => void
|
||
): ResolutionResult {
|
||
const prerequisites = unresolvedRefs.filter(ReferenceResolver.isPrerequisite);
|
||
if (prerequisites.length > 0 && prerequisites.length < unresolvedRefs.length) {
|
||
const first = this.resolveAndPersist(prerequisites, (current) => onProgress?.(current, unresolvedRefs.length));
|
||
const rest = this.resolveAndPersist(
|
||
unresolvedRefs.filter((ref) => !ReferenceResolver.isPrerequisite(ref)),
|
||
(current) => onProgress?.(prerequisites.length + current, unresolvedRefs.length)
|
||
);
|
||
return ReferenceResolver.mergeResults(first, rest);
|
||
}
|
||
const result = this.resolveAll(unresolvedRefs, onProgress);
|
||
|
||
// Create edges from resolved references
|
||
const edges = this.createEdges(result.resolved);
|
||
|
||
// Insert edges into database
|
||
if (edges.length > 0) {
|
||
this.queries.insertEdges(edges);
|
||
}
|
||
|
||
// Clean up resolved refs from unresolved_refs table so metrics are accurate
|
||
if (result.resolved.length > 0) {
|
||
const { rowIds, legacyKeys } = ReferenceResolver.partitionResolvedCleanup(result.resolved);
|
||
this.queries.deleteReferencesByRowIds(rowIds);
|
||
this.queries.deleteSpecificResolvedReferences(legacyKeys);
|
||
}
|
||
|
||
// Park unresolvable refs as status='failed' — parity with
|
||
// resolveAndPersistBatched. Deleting them was wrong (#1240): a ref whose
|
||
// own file never changes is otherwise gone forever, so when a DIFFERENT
|
||
// file later gains the export/symbol that would satisfy it, no sync can
|
||
// recreate the edge — only a full re-index. Failed rows are excluded from
|
||
// the pending readers, which preserves the #1187 orphan sweep's
|
||
// invariant in status form: after a COMPLETED pass nothing it processed
|
||
// is still 'pending', so any pending row at rest belongs to an
|
||
// interrupted run and the sweep can key off the pending count.
|
||
if (result.unresolved.length > 0) {
|
||
const { byRowId, legacyKeys } = ReferenceResolver.partitionFailedCleanup(this.nonDeferredFailures(result.unresolved));
|
||
this.queries.markReferencesFailedByRowIds(byRowId);
|
||
this.queries.markReferencesFailed(legacyKeys);
|
||
}
|
||
|
||
return result;
|
||
}
|
||
|
||
/**
|
||
* Yielding counterpart of {@link resolveAndPersist} for a caller-supplied
|
||
* ref list — used by sync's failed-ref retry pass (#1240). Same persistence
|
||
* semantics: resolved refs become edges and their rows are deleted;
|
||
* still-unresolvable refs are (re-)marked failed (a no-op for rows already
|
||
* in that status). Yields per-ref because sync can run on the daemon's
|
||
* liveness-watchdog thread (#850/#1091) and a retry set is unbounded when
|
||
* a large edit lands many popular symbol names at once.
|
||
*/
|
||
async resolveAndPersistListYielding(refs: UnresolvedReference[]): Promise<ResolutionResult> {
|
||
const prerequisites = refs.filter(ReferenceResolver.isPrerequisite);
|
||
if (prerequisites.length > 0 && prerequisites.length < refs.length) {
|
||
const first = await this.resolveAndPersistListYielding(prerequisites);
|
||
const rest = await this.resolveAndPersistListYielding(refs.filter((ref) => !ReferenceResolver.isPrerequisite(ref)));
|
||
return ReferenceResolver.mergeResults(first, rest);
|
||
}
|
||
const maybeYield = createYielder();
|
||
const result = await this.resolveBatchYielding(refs, maybeYield);
|
||
await this.persistResolutionResult(result, maybeYield);
|
||
return result;
|
||
}
|
||
|
||
private async persistResolutionResult(result: ResolutionResult, maybeYield: MaybeYield): Promise<number> {
|
||
const PERSIST_CHUNK = 1000;
|
||
const edges = this.createEdges(result.resolved);
|
||
for (let i = 0; i < edges.length; i += PERSIST_CHUNK) {
|
||
this.queries.insertEdges(edges.slice(i, i + PERSIST_CHUNK));
|
||
await maybeYield();
|
||
}
|
||
|
||
const resolvedCleanup = ReferenceResolver.partitionResolvedCleanup(result.resolved);
|
||
for (let i = 0; i < resolvedCleanup.rowIds.length; i += PERSIST_CHUNK) {
|
||
this.queries.deleteReferencesByRowIds(resolvedCleanup.rowIds.slice(i, i + PERSIST_CHUNK));
|
||
await maybeYield();
|
||
}
|
||
for (let i = 0; i < resolvedCleanup.legacyKeys.length; i += PERSIST_CHUNK) {
|
||
this.queries.deleteSpecificResolvedReferences(resolvedCleanup.legacyKeys.slice(i, i + PERSIST_CHUNK));
|
||
await maybeYield();
|
||
}
|
||
|
||
const failedCleanup = ReferenceResolver.partitionFailedCleanup(this.nonDeferredFailures(result.unresolved));
|
||
for (let i = 0; i < failedCleanup.byRowId.length; i += PERSIST_CHUNK) {
|
||
this.queries.markReferencesFailedByRowIds(failedCleanup.byRowId.slice(i, i + PERSIST_CHUNK));
|
||
await maybeYield();
|
||
}
|
||
for (let i = 0; i < failedCleanup.legacyKeys.length; i += PERSIST_CHUNK) {
|
||
this.queries.markReferencesFailed(failedCleanup.legacyKeys.slice(i, i + PERSIST_CHUNK));
|
||
await maybeYield();
|
||
}
|
||
|
||
return edges.length;
|
||
}
|
||
|
||
/** Finalize the durable queue only AFTER its edges have been inserted. */
|
||
private async persistDeferredReferences(deferred: UnresolvedRef[], resolved: ResolvedRef[]): Promise<number> {
|
||
for (const ref of deferred) if (ref.rowId != null) this.deferredRowIds.delete(ref.rowId);
|
||
const matched = new Set(resolved.map((ref) => ref.original));
|
||
const unresolved = deferred.filter((ref) => !matched.has(ref));
|
||
const count = await this.persistResolutionResult({
|
||
resolved,
|
||
unresolved,
|
||
stats: { total: deferred.length, resolved: resolved.length, unresolved: unresolved.length, byMethod: {} },
|
||
}, createYielder());
|
||
if (count > 0) this.clearCaches();
|
||
return count;
|
||
}
|
||
|
||
/** Same two phases as the bounded DB reader: persist wiring before calls. */
|
||
private static isPrerequisite(ref: UnresolvedReference): boolean {
|
||
return ref.referenceKind === 'imports' || ref.referenceKind === 'extends' || ref.referenceKind === 'implements';
|
||
}
|
||
|
||
private static mergeResults(first: ResolutionResult, rest: ResolutionResult): ResolutionResult {
|
||
const byMethod = { ...first.stats.byMethod };
|
||
for (const [method, count] of Object.entries(rest.stats.byMethod)) {
|
||
byMethod[method] = (byMethod[method] ?? 0) + count;
|
||
}
|
||
return {
|
||
resolved: first.resolved.concat(rest.resolved),
|
||
unresolved: first.unresolved.concat(rest.unresolved),
|
||
stats: {
|
||
total: first.stats.total + rest.stats.total,
|
||
resolved: first.stats.resolved + rest.stats.resolved,
|
||
unresolved: first.stats.unresolved + rest.stats.unresolved,
|
||
byMethod,
|
||
},
|
||
};
|
||
}
|
||
|
||
/**
|
||
* Second resolution pass for chained static-factory / fluent calls whose
|
||
* chained method is defined on a SUPERTYPE the receiver's type conforms to —
|
||
* a protocol-extension / inherited / default-interface method (#750). The
|
||
* first pass can't resolve these because `implements`/`extends` edges aren't
|
||
* built yet; this runs AFTER edges are persisted, so `context.getSupertypes`
|
||
* (and the conformance fallback in resolveMethodOnType) can walk them.
|
||
*
|
||
* Operates only on the leftover unresolved refs that have the `inner().method`
|
||
* chain shape, for the dotted-chain languages — a small set — and is idempotent
|
||
* (re-resolving an already-resolved ref is a no-op since it's been deleted).
|
||
* Returns the number of newly-created edges.
|
||
*/
|
||
async resolveChainedCallsViaConformance(): Promise<number> {
|
||
const deferred = this.deferredChainRefs;
|
||
this.deferredChainRefs = [];
|
||
if (deferred.length === 0) return 0;
|
||
|
||
// Read fresh edges (the main pass built the implements/extends edges after
|
||
// these refs were deferred). matchDottedCallChain now resolves a method on a
|
||
// supertype via context.getSupertypes -> resolveMethodOnType's conformance walk.
|
||
this.clearCaches();
|
||
// This post-pass runs synchronously on the indexer's main thread; yield
|
||
// periodically so the #850 liveness watchdog heartbeat can fire on a repo
|
||
// with many deferred chained calls (#1091).
|
||
const maybeYield = createYielder();
|
||
const resolved: ResolvedRef[] = [];
|
||
for (const ref of deferred) {
|
||
// PHP `this->prop.method` resolves via matchMethodCall (declared-type
|
||
// inference + resolveMethodOnType conformance walk); `::`-receiver
|
||
// languages (Rust) split on `::` (matchScopedCallChain); other
|
||
// dotted-receiver languages on `.` (matchDottedCallChain).
|
||
const chainMatch = (ref.language === 'php' && PHP_PROP_SHAPE.test(ref.referenceName))
|
||
? matchMethodCall(ref, this.context)
|
||
: SCOPED_CHAIN_LANGUAGES.has(ref.language)
|
||
? matchScopedCallChain(ref, this.context)
|
||
: matchDottedCallChain(ref, this.context);
|
||
const match = this.gateLanguage(chainMatch, ref);
|
||
if (match) resolved.push(match);
|
||
await maybeYield();
|
||
}
|
||
return this.persistDeferredReferences(deferred, resolved);
|
||
}
|
||
|
||
/**
|
||
* Resolve one batch with a yield checkpoint between EVERY ref so the #850
|
||
* liveness heartbeat can fire on a slow/dense batch (#1091). The checkpoint
|
||
* granularity is per-ref — not per-N-refs — because per-ref cost is unbounded
|
||
* in the worst case (a collision-heavy method name whose candidate set misses
|
||
* the LRU re-fetches tens of thousands of rows): any fixed N multiplies that
|
||
* worst case into the watchdog window, which is how v1.2.0 still got killed
|
||
* at "Resolving refs" on large Java monorepos (#1122). `maybeYield()` is a
|
||
* ~ns time check when under budget, so per-ref checkpoints cost nothing.
|
||
* Behaviourally identical to `resolveAll(batch)`: `warmCaches()` is
|
||
* idempotent (guarded) and `resolveOne` is independent per ref, so yielding
|
||
* between refs changes only timing, never which edges get created.
|
||
*/
|
||
private async resolveBatchYielding(
|
||
batch: UnresolvedReference[],
|
||
maybeYield: MaybeYield
|
||
): Promise<ResolutionResult> {
|
||
this.warmCaches();
|
||
this.advanceSupertypeGeneration();
|
||
|
||
const resolved: ResolvedRef[] = [];
|
||
const unresolved: UnresolvedRef[] = [];
|
||
const byMethod: Record<string, number> = {};
|
||
|
||
for (const raw of batch) {
|
||
const ref: UnresolvedRef = {
|
||
fromNodeId: raw.fromNodeId,
|
||
referenceName: raw.referenceName,
|
||
referenceKind: raw.referenceKind,
|
||
line: raw.line,
|
||
column: raw.column,
|
||
filePath: raw.filePath || this.getFilePathFromNodeId(raw.fromNodeId),
|
||
language: raw.language || this.getLanguageFromNodeId(raw.fromNodeId),
|
||
rowId: raw.rowId,
|
||
};
|
||
const result = this.resolveOneTimed(ref);
|
||
if (result) {
|
||
resolved.push(result);
|
||
byMethod[result.resolvedBy] = (byMethod[result.resolvedBy] || 0) + 1;
|
||
} else {
|
||
unresolved.push(this.parkable(ref));
|
||
}
|
||
// Fast-path the per-ref yield check: awaiting the async no-op costs a
|
||
// microtask hop per ref, which dominates at ~10⁵ refs (see MaybeYield).
|
||
const y = maybeYield();
|
||
if (y) await y;
|
||
}
|
||
|
||
return {
|
||
resolved,
|
||
unresolved,
|
||
stats: {
|
||
total: batch.length,
|
||
resolved: resolved.length,
|
||
unresolved: unresolved.length,
|
||
byMethod,
|
||
},
|
||
};
|
||
}
|
||
|
||
/**
|
||
* Resolve a list of refs and return everything the ADMISSION side needs to
|
||
* persist the outcome: resolutions, failures, the deferred post-pass refs
|
||
* this run produced (drained, so the caller owns routing them), and stats.
|
||
* This is the resolver-worker entry point — it runs the exact per-ref loop
|
||
* of resolveBatchYielding, minus the main-thread yields (worker threads have
|
||
* no watchdog heartbeat to starve). Results are in input order.
|
||
*/
|
||
/**
|
||
* CODEGRAPH_RESOLVE_PROFILE=1: per-outcome wall-clock histogram of
|
||
* resolveOne, keyed by the winning strategy (`resolvedBy`) or
|
||
* `fail:<referenceKind>` — the §7a.2 "profile the per-ref path" probe. The
|
||
* kernel-scale batch loop is ~430s and CORE-INVARIANT (835.9s pooled-4-on-8
|
||
* ≈ 812.5s sequential-on-2 for the whole superphase), so the next lever is
|
||
* which CLASS of ref the time belongs to, not more parallelism. Off by
|
||
* default: the hrtime pair costs ~100ns/ref only when the env is set.
|
||
*/
|
||
private resolveProfile: Map<string, { n: number; ns: bigint }> | null =
|
||
process.env.CODEGRAPH_RESOLVE_PROFILE ? new Map() : null;
|
||
|
||
/**
|
||
* CODEGRAPH_RESOLVE_PROFILE=2 additionally attributes time to the
|
||
* STRATEGIES inside resolveOne (`stage:<name>|<refKind>|hit/miss` rows in
|
||
* the same histogram) — i.e. WHICH machinery a failing class of refs pays
|
||
* for, not just that it fails. =1 keeps the per-outcome rows only.
|
||
*/
|
||
private profileStages: boolean = process.env.CODEGRAPH_RESOLVE_PROFILE === '2';
|
||
|
||
private stageAdd(stage: string, ref: UnresolvedRef, hit: boolean, t0: bigint): void {
|
||
if (!this.resolveProfile) return;
|
||
const dt = process.hrtime.bigint() - t0;
|
||
const key = `stage:${stage}|${ref.referenceKind}|${hit ? 'hit' : 'miss'}`;
|
||
const slot = this.resolveProfile.get(key);
|
||
if (slot) {
|
||
slot.n++;
|
||
slot.ns += dt;
|
||
} else {
|
||
this.resolveProfile.set(key, { n: 1, ns: dt });
|
||
}
|
||
}
|
||
|
||
private resolveOneTimed(ref: UnresolvedRef): ResolvedRef | null {
|
||
if (!this.resolveProfile) return this.resolveOne(ref);
|
||
const t0 = process.hrtime.bigint();
|
||
const result = this.resolveOne(ref);
|
||
const dt = process.hrtime.bigint() - t0;
|
||
const key = result ? result.resolvedBy : `fail:${ref.referenceKind}`;
|
||
const slot = this.resolveProfile.get(key);
|
||
if (slot) {
|
||
slot.n++;
|
||
slot.ns += dt;
|
||
} else {
|
||
this.resolveProfile.set(key, { n: 1, ns: dt });
|
||
}
|
||
return result;
|
||
}
|
||
|
||
/** Dump the CODEGRAPH_RESOLVE_PROFILE histogram to stderr (no-op when off). */
|
||
dumpResolveProfile(label: string): void {
|
||
if (!this.resolveProfile || this.resolveProfile.size === 0) return;
|
||
const rows = [...this.resolveProfile.entries()]
|
||
.map(([k, v]) => ({ k, n: v.n, ms: Number(v.ns / 1_000_000n) }))
|
||
.sort((a, b) => b.ms - a.ms);
|
||
for (const r of rows) {
|
||
console.error(
|
||
`[resolve-profile] ${label} ${r.k}: n=${r.n} total=${(r.ms / 1000).toFixed(1)}s avg=${((r.ms * 1000) / Math.max(1, r.n)).toFixed(0)}µs`
|
||
);
|
||
}
|
||
// =2 only: this thread's matchReference sub-stage table rides along.
|
||
dumpNameMatcherProfile(label);
|
||
}
|
||
|
||
resolveListForAdmission(refs: UnresolvedReference[]): {
|
||
resolved: ResolvedRef[];
|
||
unresolved: UnresolvedRef[];
|
||
deferredChain: UnresolvedRef[];
|
||
deferredThisMember: UnresolvedRef[];
|
||
byMethod: Record<string, number>;
|
||
} {
|
||
this.warmCaches();
|
||
this.advanceSupertypeGeneration();
|
||
const resolved: ResolvedRef[] = [];
|
||
const unresolved: UnresolvedRef[] = [];
|
||
const byMethod: Record<string, number> = {};
|
||
for (const raw of refs) {
|
||
const ref: UnresolvedRef = {
|
||
fromNodeId: raw.fromNodeId,
|
||
referenceName: raw.referenceName,
|
||
referenceKind: raw.referenceKind,
|
||
line: raw.line,
|
||
column: raw.column,
|
||
filePath: raw.filePath || this.getFilePathFromNodeId(raw.fromNodeId),
|
||
language: raw.language || this.getLanguageFromNodeId(raw.fromNodeId),
|
||
rowId: raw.rowId,
|
||
};
|
||
const result = this.resolveOneTimed(ref);
|
||
if (result) {
|
||
resolved.push(result);
|
||
byMethod[result.resolvedBy] = (byMethod[result.resolvedBy] || 0) + 1;
|
||
} else {
|
||
unresolved.push(this.parkable(ref));
|
||
}
|
||
}
|
||
this.deferredRowIds.clear(); // the admission side now owns both queues
|
||
return {
|
||
resolved,
|
||
unresolved,
|
||
deferredChain: this.deferredChainRefs.splice(0),
|
||
deferredThisMember: this.deferredThisMemberRefs.splice(0),
|
||
byMethod,
|
||
};
|
||
}
|
||
|
||
/**
|
||
* The resolver's live ResolutionContext — resolver-pool workers use it to
|
||
* run synthesis passes against their own read-only connection.
|
||
*/
|
||
getResolutionContext(): ResolutionContext {
|
||
return this.context;
|
||
}
|
||
|
||
/**
|
||
* Re-queue deferred post-pass refs produced by resolver workers, preserving
|
||
* their admission order so resolveChainedCallsViaConformance /
|
||
* resolveDeferredThisMemberRefs process them exactly as the sequential path
|
||
* would have.
|
||
*/
|
||
appendDeferredFromWorkers(deferredChain: UnresolvedRef[], deferredThisMember: UnresolvedRef[]): void {
|
||
for (const ref of deferredChain) this.deferReference(ref, this.deferredChainRefs);
|
||
for (const ref of deferredThisMember) this.deferReference(ref, this.deferredThisMemberRefs);
|
||
}
|
||
|
||
/**
|
||
* Resolve and persist in batches to keep memory bounded.
|
||
* Processes unresolved references in chunks, persisting edges and cleaning
|
||
* up resolved refs after each batch to avoid accumulating large arrays.
|
||
*/
|
||
async resolveAndPersistBatched(
|
||
onProgress?: (current: number, total: number) => void,
|
||
batchSize: number = 5000,
|
||
onSynthesisProgress?: (done: number, total: number) => void,
|
||
// When provided, big batches fan out across a read-only resolver-worker
|
||
// pool with results admitted in canonical order (see resolver-pool.ts).
|
||
// Sequential fallback on any pool failure. CODEGRAPH_NO_PARALLEL_RESOLVE=1
|
||
// disables entirely. bulkEdgeLoad hooks (when provided) bracket the batch
|
||
// loop with drop/recreate of the non-unique edge indexes on big runs —
|
||
// see DatabaseConnection.beginBulkEdgeLoad. backpressure (when provided)
|
||
// is the WAL valve's writer-side backstop (WalCheckpointValve.backpressure):
|
||
// called at pool-idle boundaries so a full backfill can actually complete —
|
||
// the valve's timer-driven passive passes stay perpetually partial against
|
||
// the pool's continuous reads, which is how a kernel-scale resolution grew
|
||
// a 22GB WAL on a 4.6GB DB (migration plan §7a.1).
|
||
parallel?: {
|
||
dbPath: string;
|
||
bulkEdgeLoad?: {
|
||
begin: () => void;
|
||
end: () => void | Promise<void>;
|
||
/** Indexes `end` leaves for later; built while the pool runs synthesis. */
|
||
deferred?: () => void;
|
||
};
|
||
/** unresolved_refs index window for the batched loop — the loop only
|
||
* reads the status index + PK; dropping the sync-path ref indexes cuts
|
||
* each per-batch DELETE's B-tree work (DatabaseConnection.beginBulkRefLoad). */
|
||
refIndexLoad?: { begin: () => void; end: () => void | Promise<void> };
|
||
backpressure?: () => Promise<void> | null;
|
||
},
|
||
synthesize: boolean = true
|
||
): Promise<ResolutionResult> {
|
||
// Resolution runs on the indexer's MAIN thread, and the #850 liveness
|
||
// watchdog SIGKILLs a process whose event loop stalls past its window (60s
|
||
// by default). A single dense batch's resolveAll — or the synthesis pass
|
||
// below — can exceed that on a large repo, killing a VALID in-progress index
|
||
// (#1091). A shared yielder lets both give the watchdog heartbeat a regular
|
||
// window to fire; see ./cooperative-yield.
|
||
const maybeYield = createYielder();
|
||
|
||
if (process.env.CODEGRAPH_SYNTH_TIMINGS) {
|
||
console.error(`[pool-timing] backpressure hook: ${parallel?.backpressure ? 'present' : 'absent'}`);
|
||
}
|
||
|
||
// CODEGRAPH_RESOLVE_PROFILE loop-stage attribution: the §7a.2 kernel-scale
|
||
// histogram showed resolveOne owns only ~93s of the ~436s batch loop —
|
||
// these counters name where the other ~340s goes (reads, edge build+insert,
|
||
// deletes/marks, the per-batch count guard).
|
||
const loopProf: Record<string, number> | null = process.env.CODEGRAPH_RESOLVE_PROFILE
|
||
? { read: 0, settle: 0, backpressure: 0, recycle: 0, createEdges: 0, insertEdges: 0, deletes: 0, marks: 0, countGuard: 0 }
|
||
: null;
|
||
const lp = (k: string, t0: number): void => { if (loopProf) loopProf[k] = (loopProf[k] ?? 0) + (Date.now() - t0); };
|
||
let tLp = 0;
|
||
|
||
await this.warmCachesYielding(maybeYield);
|
||
|
||
const total = this.queries.getUnresolvedReferencesCount();
|
||
let processed = 0;
|
||
const aggregateStats = {
|
||
total: 0,
|
||
resolved: 0,
|
||
unresolved: 0,
|
||
byMethod: {} as Record<string, number>,
|
||
};
|
||
|
||
// Parallel pool, started immediately but never awaited up front: early
|
||
// batches run sequentially while the workers boot (module load + readonly
|
||
// DB open + framework detect + cache warm ≈ hundreds of ms), and the loop
|
||
// switches to fan-out the moment the pool reports ready — so pool boot
|
||
// costs zero wall-clock. Any failure downgrades to sequential permanently.
|
||
let pool: ResolverPool | null = null;
|
||
let poolReady = false;
|
||
// True once pool creation has been attempted by EITHER engage site (the
|
||
// up-front ref-count gate or the adaptive projection below) — a pool that
|
||
// failed or was destroyed must stay down (downgrade is permanent), and
|
||
// tryCreate's sizing probes shouldn't re-run every batch on hosts that
|
||
// declined.
|
||
let poolEngageTried = false;
|
||
const createPool = (t0: number, why: string): ResolverPool | null => {
|
||
poolEngageTried = true;
|
||
if (!parallel) return null;
|
||
const p = ResolverPool.tryCreate(parallel.dbPath, this.projectRoot);
|
||
p?.ready().then(
|
||
() => {
|
||
poolReady = true;
|
||
if (process.env.CODEGRAPH_SYNTH_TIMINGS) console.error(`[pool-timing] pool ready after ${Date.now() - t0}ms (${why})`);
|
||
},
|
||
() => {
|
||
void p.destroy().catch(() => undefined);
|
||
if (pool === p) pool = null;
|
||
}
|
||
);
|
||
return p;
|
||
};
|
||
if (parallel && total >= minRefsForPool()) {
|
||
pool = createPool(Date.now(), 'ref-count');
|
||
}
|
||
// Adaptive engagement bar (see the batch-loop hook): projected remaining
|
||
// sequential settle above this boots the pool mid-loop. Boot is async and
|
||
// fan-out waits for ready, so a marginal engage costs background boot
|
||
// only; the bar just needs to clear the fan-out's own overhead class.
|
||
const ADAPTIVE_ENGAGE_SETTLE_MS = 400;
|
||
let adaptiveSeqMs = 0;
|
||
let adaptiveSeqRefs = 0;
|
||
|
||
// Process in PIPELINED batches (double-buffer). The enumeration is the
|
||
// head of the pending set in rowid order; every ref a persisted batch
|
||
// processed leaves the pending set (resolved rows are deleted,
|
||
// unresolvable ones flip to status='failed'), shifting the remaining
|
||
// pending rows forward.
|
||
let prevRemaining = Number.POSITIVE_INFINITY;
|
||
|
||
// Cadence for the worker connection recycling below — ~8 batches
|
||
// ≈ 40k refs between recycles keeps the WAL shallow at kernel scale
|
||
// while a small sync never recycles at all. (25 recovered only half
|
||
// the write tax — the WAL re-deepened between recycles; reopens are
|
||
// sub-millisecond so the shorter cadence is ~free.)
|
||
const RECYCLE_EVERY_BATCHES = 8;
|
||
let batchesSinceRecycle = 0;
|
||
|
||
// Fan-out result of ResolverPool.resolveBatch, settled (never rejecting)
|
||
// so a fan-out begun before the previous batch's persist can't produce an
|
||
// unhandled rejection while it waits to be awaited.
|
||
type PoolSettled =
|
||
| { ok: true; out: Awaited<ReturnType<ResolverPool['resolveBatch']>> }
|
||
| { ok: false; err: unknown };
|
||
type InFlight = { mode: 'pool'; settled: Promise<PoolSettled> } | { mode: 'seq' };
|
||
|
||
// Begin one batch: fan out to the pool when it's ready and the batch is
|
||
// big enough — workers then resolve batch k+1 WHILE the main thread
|
||
// persists batch k (persist measured at ~58% of resolution wall on a
|
||
// 255k-ref repo, all of it previously spent with the pool idle).
|
||
// Sequential batches stay lazy: they run on the main thread at settle
|
||
// time, where an early start would only contend with the persist.
|
||
const beginBatch = (batch: UnresolvedReference[]): InFlight => {
|
||
if (pool && poolReady && ResolverPool.worthParallel(batch.length)) {
|
||
return {
|
||
mode: 'pool',
|
||
settled: pool.resolveBatch(batch).then(
|
||
(out) => ({ ok: true as const, out }),
|
||
(err: unknown) => ({ ok: false as const, err })
|
||
),
|
||
};
|
||
}
|
||
return { mode: 'seq' };
|
||
};
|
||
|
||
// Settle an in-flight batch to a ResolutionResult. Deferred post-pass refs
|
||
// are appended HERE, in loop order — never inside the fan-out promise — so
|
||
// admission order stays exactly the sequential order even while a later
|
||
// batch resolves concurrently. A pool failure downgrades to sequential
|
||
// permanently and re-resolves this batch on the main thread.
|
||
const settleBatch = async (
|
||
inFlight: InFlight,
|
||
batch: UnresolvedReference[]
|
||
): Promise<ResolutionResult> => {
|
||
if (inFlight.mode === 'pool') {
|
||
const settled = await inFlight.settled;
|
||
if (settled.ok) {
|
||
this.appendDeferredFromWorkers(settled.out.deferredChain, settled.out.deferredThisMember);
|
||
return {
|
||
resolved: settled.out.resolved,
|
||
unresolved: settled.out.unresolved,
|
||
stats: {
|
||
total: batch.length,
|
||
resolved: settled.out.resolved.length,
|
||
unresolved: settled.out.unresolved.length,
|
||
byMethod: settled.out.byMethod,
|
||
},
|
||
};
|
||
}
|
||
logDebug('Parallel resolution failed; falling back to sequential', {
|
||
error: settled.err instanceof Error ? settled.err.message : String(settled.err),
|
||
});
|
||
if (pool) await pool.destroy().catch(() => undefined);
|
||
pool = null;
|
||
}
|
||
return this.resolveBatchYielding(batch, maybeYield);
|
||
};
|
||
|
||
// Bulk edge load: on big runs, drop the non-unique edge indexes for the
|
||
// duration of the batch loop (the identity index stays — OR IGNORE dedup
|
||
// and the source-keyed supertype-walk reads both live on it). Recreated in
|
||
// the inner finally BEFORE synthesis, whose passes read kind-keyed.
|
||
// Measured on a 224k-edge resolution set: insert 2.8s → 1.1s + 0.3s
|
||
// recreate. Same ref-count gate as the pool so small syncs never pay the
|
||
// recreate cost.
|
||
let bulkEdgesActive = false;
|
||
if (parallel?.bulkEdgeLoad && total >= minRefsForPool()) {
|
||
try {
|
||
parallel.bulkEdgeLoad.begin();
|
||
bulkEdgesActive = true;
|
||
} catch { /* keep the indexes; inserts just pay the per-row maintenance */ }
|
||
}
|
||
// Same gate for the ref-index window: the loop's deletes stop maintaining
|
||
// the five sync-path unresolved_refs indexes, and the end-of-loop rebuild
|
||
// is near-free (only failed refs survive the loop).
|
||
let bulkRefsActive = false;
|
||
if (parallel?.refIndexLoad && total >= minRefsForPool()) {
|
||
try {
|
||
parallel.refIndexLoad.begin();
|
||
bulkRefsActive = true;
|
||
} catch { /* keep the indexes; deletes just pay the per-row maintenance */ }
|
||
}
|
||
|
||
try {
|
||
try {
|
||
// Orphans retain interruption/re-extraction order, not clean-index order.
|
||
// A caller can precede its imports or supertypes by many batches (#1577).
|
||
// Drain those prerequisites first, then start a fresh keyset cursor over
|
||
// the remaining kinds. The disjoint filters let us prefetch across the
|
||
// phase boundary before cleanup without re-reading the current batch.
|
||
let prerequisites = true;
|
||
let afterRowId = 0;
|
||
const readNextBatch = (): UnresolvedReference[] => {
|
||
let next = this.queries.getUnresolvedReferencesBatchAfter(afterRowId, batchSize, prerequisites);
|
||
if (next.length === 0 && prerequisites) {
|
||
prerequisites = false;
|
||
afterRowId = 0;
|
||
next = this.queries.getUnresolvedReferencesBatchAfter(afterRowId, batchSize, prerequisites);
|
||
}
|
||
if (next.length > 0) afterRowId = next[next.length - 1]!.rowId!;
|
||
return next;
|
||
};
|
||
tLp = Date.now();
|
||
let batch = readNextBatch();
|
||
lp('read', tLp);
|
||
let inFlight: InFlight | null = batch.length > 0 ? beginBatch(batch) : null;
|
||
while (batch.length > 0 && inFlight) {
|
||
// Prefetch the NEXT batch before this one persists: this batch's rows
|
||
// are still pending (nothing has mutated the table since they were
|
||
// read), so seeking past this batch's last row id in the same rowid
|
||
// enumeration yields the following batch (keyset — OFFSET re-walked the
|
||
// accumulated failed prefix every read, 54.6s at kernel scale, §7a.2).
|
||
tLp = Date.now();
|
||
const nextBatch = readNextBatch();
|
||
lp('read', tLp);
|
||
|
||
const tBatch = Date.now();
|
||
const result = await settleBatch(inFlight, batch);
|
||
if (process.env.CODEGRAPH_SYNTH_TIMINGS) console.error(`[pool-timing] batch ${inFlight.mode}: ${batch.length} refs in ${Date.now() - tBatch}ms`);
|
||
lp('settle', tBatch);
|
||
|
||
// Adaptive pool engagement: the fixed ref-count gate can't see PER-REF
|
||
// cost, and settle rates differ ~9× by language (56k Rust refs cost
|
||
// more sequential settle than 154k Go refs — 36µs vs 4µs measured on
|
||
// tokio/prometheus). After each sequential batch, project the remaining
|
||
// settle from the observed rate and boot the pool mid-loop when it
|
||
// clears the bar. The loop already switches to fan-out only when the
|
||
// async boot reports ready, admission order is mode-independent, and
|
||
// 2-core/low-memory hosts still decline inside tryCreate's sizing —
|
||
// so the switch changes wall-clock, never the graph.
|
||
if (inFlight.mode === 'seq' && parallel && pool === null && !poolEngageTried) {
|
||
adaptiveSeqMs += Date.now() - tBatch;
|
||
adaptiveSeqRefs += batch.length;
|
||
const remaining = total - processed - batch.length;
|
||
const projectedMs = (adaptiveSeqMs / Math.max(1, adaptiveSeqRefs)) * Math.max(0, remaining);
|
||
if (shouldEngageAdaptively(projectedMs, remaining, ADAPTIVE_ENGAGE_SETTLE_MS)) {
|
||
if (process.env.CODEGRAPH_SYNTH_TIMINGS) {
|
||
console.error(`[pool-timing] adaptive engage: projected ${Math.round(projectedMs)}ms sequential settle over ${remaining} remaining refs`);
|
||
}
|
||
pool = createPool(Date.now(), 'adaptive');
|
||
}
|
||
}
|
||
|
||
// WAL-valve backstop at the ONE pool-idle boundary of the double-buffer
|
||
// (this batch settled, the next not yet fanned out): past the hard cap
|
||
// the writer parks for a full backfill here, where the pool's readers
|
||
// are all between statements — so the backfill completes, readers
|
||
// re-enter at SQLite's backfilled mark, and the next persist commit
|
||
// WRAPS the WAL instead of growing it. No-op (one fstat) under the cap.
|
||
tLp = Date.now();
|
||
const bp = parallel?.backpressure?.();
|
||
if (bp) await bp;
|
||
lp('backpressure', tLp);
|
||
|
||
// Recycle the workers' read connections periodically at this same
|
||
// worker-idle boundary (batch k settled, batch k+1 not yet fanned
|
||
// out): a long-lived reader pins WAL checkpoint progress, and the
|
||
// deep WAL that accumulates behind it taxes the writer's OWN page
|
||
// operations — the §7a.6 writes-under-readers finding (deletes
|
||
// 42.6s → 118.8s from 0 to 4 attached readers; an aggressive valve
|
||
// recovered the writes but paid +129s in full-park folds). Releasing
|
||
// the read marks every ~25 batches lets the existing checkpoints
|
||
// advance instead, at ~milliseconds of reopen cost. A failed recycle
|
||
// downgrades to sequential permanently, same as a failed fan-out.
|
||
if (pool && poolReady && ++batchesSinceRecycle >= RECYCLE_EVERY_BATCHES) {
|
||
batchesSinceRecycle = 0;
|
||
tLp = Date.now();
|
||
try {
|
||
await pool.recycleWorkers();
|
||
} catch (err) {
|
||
logDebug('Worker connection recycle failed; falling back to sequential', {
|
||
error: err instanceof Error ? err.message : String(err),
|
||
});
|
||
await pool.destroy().catch(() => undefined);
|
||
pool = null;
|
||
}
|
||
lp('recycle', tLp);
|
||
}
|
||
|
||
// Persist in bounded sub-transactions with yields between: a whole
|
||
// batch's edge insert / keyed deletes are otherwise one solid
|
||
// synchronous span each on a multi-GB index, sitting BETWEEN the
|
||
// per-ref yields — the last unyielded stretch of the resolution loop.
|
||
// Crash semantics are unchanged (already several transactions): edges
|
||
// land before their refs are deleted, so a kill mid-way re-resolves
|
||
// the remainder idempotently on the next run/sweep (#1187).
|
||
const PERSIST_CHUNK = 1000;
|
||
const tPersist = Date.now();
|
||
|
||
// A batch that made `extends`/`implements` edges persists them BEFORE
|
||
// fanning out the next batch: later batches read them —
|
||
// resolveMethodOnType walks supertype chains over edges that earlier
|
||
// batches resolved, so a receiver typed as a subclass only reaches a
|
||
// method declared on its base class if those edges are visible.
|
||
// (Validated on dubbo: fanning out first downgraded exactly those
|
||
// supertype-method resolutions from the 0.9 typed-receiver path to the
|
||
// 0.65 word-overlap fallback.) They are the only edges resolution reads
|
||
// (RESOLUTION_READ_EDGE_KINDS), so a batch that made none — every batch
|
||
// after the prerequisite phase readNextBatch drains first — fans the
|
||
// next batch out now and inserts while it resolves: the same writes in
|
||
// the same order, and nothing the workers read differs.
|
||
tLp = Date.now();
|
||
const edges = this.createEdges(result.resolved);
|
||
lp('createEdges', tLp);
|
||
const readEdge = edges.some((e) => RESOLUTION_READ_EDGE_KINDS.includes(e.kind));
|
||
let nextInFlight = !readEdge && nextBatch.length > 0 ? beginBatch(nextBatch) : null;
|
||
tLp = Date.now();
|
||
for (let i = 0; i < edges.length; i += PERSIST_CHUNK) {
|
||
this.queries.insertEdges(edges.slice(i, i + PERSIST_CHUNK));
|
||
await maybeYield();
|
||
}
|
||
lp('insertEdges', tLp);
|
||
|
||
// NOW fan the next batch out (if not already) — workers see exactly the
|
||
// edge state the sequential baseline would (every batch ≤ this one
|
||
// committed), while the main thread spends the REST of the persist (ref
|
||
// deletes + failed parking below) overlapped with their resolution —
|
||
// the double-buffer.
|
||
if (!nextInFlight && nextBatch.length > 0) nextInFlight = beginBatch(nextBatch);
|
||
|
||
// Clean up resolved refs so they don't appear in the next batch —
|
||
// by row id, so a same-key sibling ref in a LATER batch (same caller
|
||
// calling the same callee at another line) is left pending for its own
|
||
// attempt instead of being swept out with this batch's rows (#1269).
|
||
tLp = Date.now();
|
||
let removedThisBatch = 0;
|
||
const resolvedCleanup = ReferenceResolver.partitionResolvedCleanup(result.resolved);
|
||
for (let i = 0; i < resolvedCleanup.rowIds.length; i += PERSIST_CHUNK) {
|
||
removedThisBatch += this.queries.deleteReferencesByRowIds(resolvedCleanup.rowIds.slice(i, i + PERSIST_CHUNK));
|
||
await maybeYield();
|
||
}
|
||
for (let i = 0; i < resolvedCleanup.legacyKeys.length; i += PERSIST_CHUNK) {
|
||
removedThisBatch += this.queries.deleteSpecificResolvedReferences(resolvedCleanup.legacyKeys.slice(i, i + PERSIST_CHUNK));
|
||
await maybeYield();
|
||
}
|
||
lp('deletes', tLp);
|
||
|
||
// Park unresolvable refs from this batch as status='failed' so they
|
||
// leave the pending set (the batch reader and non-progress guard below
|
||
// only see pending rows) but stay retryable when a later sync adds a
|
||
// symbol that could satisfy them (#1240).
|
||
tLp = Date.now();
|
||
const failures = this.nonDeferredFailures(result.unresolved);
|
||
const deferredCount = result.unresolved.length - failures.length;
|
||
const failedCleanup = ReferenceResolver.partitionFailedCleanup(failures);
|
||
for (let i = 0; i < failedCleanup.byRowId.length; i += PERSIST_CHUNK) {
|
||
removedThisBatch += this.queries.markReferencesFailedByRowIds(failedCleanup.byRowId.slice(i, i + PERSIST_CHUNK));
|
||
await maybeYield();
|
||
}
|
||
for (let i = 0; i < failedCleanup.legacyKeys.length; i += PERSIST_CHUNK) {
|
||
removedThisBatch += this.queries.markReferencesFailed(failedCleanup.legacyKeys.slice(i, i + PERSIST_CHUNK));
|
||
await maybeYield();
|
||
}
|
||
lp('marks', tLp);
|
||
|
||
if (process.env.CODEGRAPH_SYNTH_TIMINGS) console.error(`[pool-timing] batch persist: ${Date.now() - tPersist}ms`);
|
||
|
||
// Aggregate stats
|
||
aggregateStats.total += result.stats.total;
|
||
aggregateStats.resolved += result.stats.resolved;
|
||
aggregateStats.unresolved += result.stats.unresolved;
|
||
for (const [method, count] of Object.entries(result.stats.byMethod)) {
|
||
aggregateStats.byMethod[method] = (aggregateStats.byMethod[method] || 0) + count;
|
||
}
|
||
|
||
processed += batch.length;
|
||
onProgress?.(processed, total);
|
||
|
||
// Yield so progress UI can render between batches
|
||
await new Promise(resolve => setImmediate(resolve));
|
||
|
||
// NOTE: there used to be an extra early break here when a batch resolved
|
||
// nothing (`result.unresolved.length === batch.length`). That was wrong:
|
||
// an all-unresolvable batch still DELETES its rows (progress), yet the
|
||
// break abandoned every batch after it in the same run — on a repo whose
|
||
// first 5000 refs are all external/stdlib calls, resolution stopped at
|
||
// batch one and left the rest of the table as permanent orphans (#1187).
|
||
// The count-based guard below catches the true no-progress case.
|
||
|
||
// Non-progress guard (defense-in-depth). Ordinary attempts must leave
|
||
// the pending set; a mismatched original reference can make legacy-key
|
||
// cleanup a no-op. Keep the guard against that broken persistence even
|
||
// though keyset pagination now advances independently of row cleanup.
|
||
// An abandoned prefetched batch has no side effects until settleBatch.
|
||
// Non-progress signal, now O(1): `changes` summed across this batch's
|
||
// deletes + failed-parks is the DIRECT evidence the guard's old count
|
||
// diff inferred — a resolver returning a mismatched name makes the keyed
|
||
// cleanup no-op, which shows up here as zero removals. The per-batch
|
||
// COUNT(*) it replaces walked every remaining pending row — O(N²/batch)
|
||
// over a run, 93.9s of the kernel-scale batch loop (§7a.2). A REAL count
|
||
// runs only on the suspicious path (claimed-work batch removed nothing —
|
||
// e.g. every row was a sibling a legacy-key sweep already consumed),
|
||
// where it arbitrates stop-vs-continue exactly as before.
|
||
// Deferred refs legitimately remain pending for the post-pass. The
|
||
// keyset cursor advances past them; they must not trigger this guard.
|
||
if (removedThisBatch + deferredCount <= 0 && batch.length > 0) {
|
||
tLp = Date.now();
|
||
const remaining = this.queries.getUnresolvedReferencesCount();
|
||
lp('countGuard', tLp);
|
||
if (remaining >= prevRemaining) break;
|
||
prevRemaining = remaining;
|
||
}
|
||
|
||
// Advance the pipeline: the prefetched batch (already fanned out when
|
||
// the pool is on) becomes the current one.
|
||
batch = nextBatch;
|
||
inFlight = nextInFlight;
|
||
}
|
||
} finally {
|
||
// Recreate the edge indexes BEFORE synthesis (kind-keyed reads) and on
|
||
// any error path. A crash before this line is healed by the next
|
||
// DatabaseConnection open (schema.sql re-applies IF NOT EXISTS).
|
||
if (bulkRefsActive) {
|
||
const tRef = Date.now();
|
||
await parallel!.refIndexLoad!.end();
|
||
if (process.env.CODEGRAPH_SYNTH_TIMINGS) console.error(`[phase-timing] ref-index-recreate: ${Date.now() - tRef}ms`);
|
||
}
|
||
if (bulkEdgesActive) {
|
||
const tIdx = Date.now();
|
||
await parallel!.bulkEdgeLoad!.end();
|
||
if (process.env.CODEGRAPH_SYNTH_TIMINGS) console.error(`[phase-timing] edge-index-recreate: ${Date.now() - tIdx}ms`);
|
||
// The recreate just wrote every non-unique edge index into the WAL
|
||
// (multi-GB at kernel scale) with the pool idle — fold before the
|
||
// synthesis passes pin readers against it for minutes.
|
||
const bp = parallel?.backpressure?.();
|
||
if (bp) await bp;
|
||
}
|
||
}
|
||
|
||
// Indexes the bulk-edge window's end deferred: built once, while the pool
|
||
// is busy with synthesis when it is, and in any case before this returns.
|
||
let deferredBuilt = !bulkEdgesActive || !parallel?.bulkEdgeLoad?.deferred;
|
||
const buildDeferredIndexes = (): void => {
|
||
if (deferredBuilt) return;
|
||
deferredBuilt = true;
|
||
const tDeferred = Date.now();
|
||
try {
|
||
parallel!.bulkEdgeLoad!.deferred!();
|
||
} catch { /* healed by schema.sql on the next open, like a crash in the window */ }
|
||
if (process.env.CODEGRAPH_SYNTH_TIMINGS) console.error(`[phase-timing] deferred-edge-index: ${Date.now() - tDeferred}ms`);
|
||
};
|
||
|
||
// Dynamic-edge synthesis: now that all base `calls` edges are persisted,
|
||
// synthesize observer/callback dispatch edges (dispatcher → registered
|
||
// callbacks) that static parsing leaves out. Best-effort — never fail the
|
||
// index on it. The pool (when it survived resolution) is REUSED to fan the
|
||
// independent passes across its read-only workers — that's why its destroy
|
||
// lives in the finally below, after synthesis, not at the end of the batch
|
||
// loop. See docs/design/callback-edge-synthesis.md.
|
||
const tSynth = Date.now();
|
||
try {
|
||
if (synthesize) aggregateStats.byMethod['callback-synthesis'] = await synthesizeCallbackEdges(
|
||
this.queries,
|
||
this.context,
|
||
onSynthesisProgress,
|
||
pool,
|
||
parallel?.backpressure,
|
||
buildDeferredIndexes
|
||
);
|
||
} catch {
|
||
// synthesis is additive and optional; ignore failures
|
||
}
|
||
buildDeferredIndexes();
|
||
if (process.env.CODEGRAPH_SYNTH_TIMINGS) console.error(`[phase-timing] callback-synthesis: ${Date.now() - tSynth}ms`);
|
||
} finally {
|
||
if (pool) await pool.destroy().catch(() => undefined);
|
||
}
|
||
|
||
if (loopProf) {
|
||
const parts = Object.entries(loopProf).map(([k, v]) => `${k}=${(v / 1000).toFixed(1)}s`).join(' ');
|
||
console.error(`[resolve-profile] loop-stages ${parts}`);
|
||
}
|
||
this.dumpResolveProfile('main');
|
||
|
||
return {
|
||
resolved: [],
|
||
unresolved: [],
|
||
stats: aggregateStats,
|
||
};
|
||
}
|
||
|
||
/** Replace synthesis only after every base-resolution pass has finished. */
|
||
async refreshSynthesis(
|
||
dbPath: string,
|
||
onProgress?: (done: number, total: number) => void,
|
||
backpressure?: () => Promise<void> | null
|
||
): Promise<number> {
|
||
this.clearCaches();
|
||
const stage = new SynthesisStage(dbPath);
|
||
try {
|
||
const fresh = new ReferenceResolver(this.projectRoot, stage.queries);
|
||
const count = await synthesizeCallbackEdges(stage.queries, fresh.context, onProgress, null, backpressure);
|
||
await stage.publish(backpressure);
|
||
return count;
|
||
} finally {
|
||
stage.close();
|
||
this.clearCaches();
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Get detected frameworks
|
||
*/
|
||
getDetectedFrameworks(): string[] {
|
||
return this.frameworks.map((f) => f.name);
|
||
}
|
||
|
||
/** True when a detected router binds navigation calls to its routes (see {@link reopenNavigationsFor}). */
|
||
hasNavigationRouters(): boolean {
|
||
return this.frameworks.some((f) => f.navigation !== undefined);
|
||
}
|
||
|
||
/**
|
||
* Put back in the pending set the navigation calls `routes` — route nodes a
|
||
* sync added, removed or renamed ({@link changedRoutes}) — may now resolve
|
||
* differently, for the sync's resolution sweep: the calls parked as failed,
|
||
* and the calls whose `navigates` edges a router's resolver made. Calls in
|
||
* `changedFilePaths` are left alone; the sync resolved them against the new
|
||
* routes already. Returns the number of references put back.
|
||
*
|
||
* A navigation call names its route by path (`navigate('/login')`) and its
|
||
* reference by the router's method (`navigate`, `history.push`), so a route
|
||
* table that changed in another file is invisible to the rest of sync. A
|
||
* call parked as failed while its route was missing is keyed on `push`,
|
||
* which no synced file defines, and a resolved call keeps the route it bound
|
||
* to while a better one was missing (a catch-all, a parameter route, one arm
|
||
* of a conditional) or a route renamed under it. A full index resolves every
|
||
* call against the final table. Each router says which calls a route of its
|
||
* own can answer (`FrameworkResolver.navigation`): the method tails, and the
|
||
* apps whose files match against that route's table. A name more of those
|
||
* calls share than `perNameCeiling` is skipped, as the symbol retry skips a
|
||
* common tail.
|
||
*/
|
||
reopenNavigationsFor(routes: readonly Node[], changedFilePaths: readonly string[] = [], perNameCeiling: number = 500): number {
|
||
if (routes.length === 0) return 0;
|
||
const plans: Array<{ router: FrameworkResolver; scopes: string[] }> = [];
|
||
const tails = new Set<string>();
|
||
for (const router of this.frameworks) {
|
||
if (!router.navigation) continue;
|
||
const scopes = new Set<string>();
|
||
for (const route of routes) {
|
||
for (const scope of router.navigation.scope(route, this.context) ?? []) scopes.add(scope);
|
||
}
|
||
if (scopes.size === 0) continue;
|
||
plans.push({ router, scopes: [...scopes] });
|
||
for (const tail of router.navigation.tails) tails.add(tail);
|
||
}
|
||
if (plans.length === 0) return 0;
|
||
const claimed = (name: string, filePath: string): boolean =>
|
||
plans.some(({ router, scopes }) => scopes.some((scope) => filePath.startsWith(scope)) && router.claimsReference?.(name) === true);
|
||
|
||
const fresh = new Set(changedFilePaths);
|
||
const failed = new Map<string, number[]>();
|
||
for (const ref of this.queries.getFailedCallsByTail([...tails])) {
|
||
if (fresh.has(ref.filePath) || !claimed(ref.referenceName, ref.filePath)) continue;
|
||
const rowIds = failed.get(ref.referenceName);
|
||
if (rowIds) rowIds.push(ref.rowId);
|
||
else failed.set(ref.referenceName, [ref.rowId]);
|
||
}
|
||
const resolved = new Map<string, Array<Edge & { edgeId: number; sourceFilePath: string; sourceLanguage: Language }>>();
|
||
for (const edge of this.queries.getResolvedNavigations()) {
|
||
const name = edge.metadata?.refName;
|
||
if (typeof name !== 'string' || fresh.has(edge.sourceFilePath) || !claimed(name, edge.sourceFilePath)) continue;
|
||
const edges = resolved.get(name);
|
||
if (edges) edges.push(edge);
|
||
else resolved.set(name, [edge]);
|
||
}
|
||
|
||
const rowIds: number[] = [];
|
||
const edgeIds: number[] = [];
|
||
const refs: UnresolvedReference[] = [];
|
||
// A conditional's arms are edges of one call: it goes back as one reference.
|
||
const sites = new Set<string>();
|
||
for (const name of new Set([...failed.keys(), ...resolved.keys()])) {
|
||
const rows = failed.get(name) ?? [];
|
||
const edges = resolved.get(name) ?? [];
|
||
if (rows.length + edges.length > perNameCeiling) continue;
|
||
for (const rowId of rows) rowIds.push(rowId);
|
||
for (const edge of edges) {
|
||
const ref = resurrectRefFromDroppedEdge(edge);
|
||
if (!ref) continue;
|
||
edgeIds.push(edge.edgeId);
|
||
const site = `${ref.fromNodeId}\0${ref.referenceName}\0${ref.line}\0${ref.column}`;
|
||
if (sites.has(site)) continue;
|
||
sites.add(site);
|
||
refs.push(ref);
|
||
}
|
||
}
|
||
if (edgeIds.length > 0) this.queries.replaceResolutionEdgesWithUnresolvedRefs(edgeIds, refs);
|
||
return this.queries.reopenFailedReferences(rowIds) + refs.length;
|
||
}
|
||
|
||
/**
|
||
* True when `receiver` is a local name bound by an import that resolves to a
|
||
* file IN THIS PROJECT — the only case where letting a python
|
||
* built-in-method name through the filter is safe (#1681).
|
||
*
|
||
* Asking only whether SOME import bound the local name is not enough: every
|
||
* import produces a mapping, stdlib and PyPI included, so that would also be
|
||
* true for `os`, `requests`, `np`. Opening the filter for them lets
|
||
* resolveViaImport find no project file, fall through to bare-name matching,
|
||
* and bind `os.remove(p)` to whatever project method happens to be named
|
||
* `remove` — reintroducing, through its own escape hatch, the fabricated-edge
|
||
* class this filter exists to prevent.
|
||
*
|
||
* Resolving the specifier is the same question resolveViaImport will ask
|
||
* next, so a receiver that passes here is one the qualified path can actually
|
||
* serve; anything else stays a silent miss rather than a wrong edge.
|
||
*/
|
||
private isPythonProjectModule(ref: UnresolvedRef, receiver: string): boolean {
|
||
for (const imp of this.context.getImportMappings(ref.filePath, ref.language)) {
|
||
if (imp.localName !== receiver) continue;
|
||
// `import pkg.mod` / `import pkg.mod as m` binds the module `source`
|
||
// names. `from pkg import mod` binds `pkg.mod`, and `from . import mod`
|
||
// binds `.mod` — join without doubling the dot that makes `.` mean the
|
||
// current package.
|
||
const specifier = imp.isNamespace
|
||
? imp.source
|
||
: imp.source.endsWith('.')
|
||
? `${imp.source}${imp.exportedName}`
|
||
: `${imp.source}.${imp.exportedName}`;
|
||
if (resolveImportPath(specifier, ref.filePath, ref.language!, this.context)) {
|
||
return true;
|
||
}
|
||
}
|
||
return false;
|
||
}
|
||
|
||
/**
|
||
* Check if reference is to a built-in or external symbol
|
||
*/
|
||
private isBuiltInOrExternal(ref: UnresolvedRef): boolean {
|
||
const name = ref.referenceName;
|
||
const isJsTs = ref.language === 'typescript' || ref.language === 'javascript'
|
||
|| ref.language === 'tsx' || ref.language === 'jsx' || ref.language === 'arkts'
|
||
|| ref.language === 'vue' || ref.language === 'svelte' || ref.language === 'astro';
|
||
|
||
// JavaScript/TypeScript built-ins — unless the file imports its own
|
||
// binding of that name (`import Map from './Map.svelte'`).
|
||
if (isJsTs && JS_BUILT_INS.has(name) &&
|
||
!this.context.getImportMappings(ref.filePath, ref.language).some((m) => m.localName === name)) {
|
||
return true;
|
||
}
|
||
|
||
// ArkTS resource-reference intrinsics — `$r('app.string.x')` /
|
||
// `$rawfile('x.png')` are framework-provided and appear dozens of times
|
||
// per UI file; without this they can resolve to a stray same-named
|
||
// symbol (e.g. a checked-in hvigor wrapper's `$r`).
|
||
if (ref.language === 'arkts' && (name === '$r' || name === '$rawfile')) {
|
||
return true;
|
||
}
|
||
|
||
// Common JS/TS library calls (console.log, Math.floor, JSON.parse)
|
||
if (isJsTs && (name.startsWith('console.') || name.startsWith('Math.') || name.startsWith('JSON.'))) {
|
||
return true;
|
||
}
|
||
|
||
// React hooks from React itself
|
||
if (isJsTs && REACT_HOOKS.has(name)) {
|
||
return true;
|
||
}
|
||
|
||
// Python built-ins (bare calls only — dotted calls like console.print are method calls)
|
||
if (ref.language === 'python' && PYTHON_BUILT_INS.has(name)) {
|
||
return true;
|
||
}
|
||
|
||
// Python built-in method calls (e.g., list.extend, dict.update)
|
||
if (ref.language === 'python') {
|
||
const dotIdx = name.indexOf('.');
|
||
if (dotIdx > 0) {
|
||
const receiver = name.substring(0, dotIdx);
|
||
const method = name.substring(dotIdx + 1);
|
||
// Filter calls on built-in types (list.append, dict.update, etc.)
|
||
if (PYTHON_BUILT_IN_TYPES.has(receiver)) {
|
||
return true;
|
||
}
|
||
// Filter built-in methods on non-class receivers
|
||
// (e.g., items.append where items is a local list variable)
|
||
// But allow if the capitalized receiver matches a known codebase class,
|
||
// OR the receiver is itself an imported project module — a module can
|
||
// export a top-level function sharing a common collection-method name
|
||
// (`ledger.append`, `from . import ledger`), and that call is a real
|
||
// project dependency, not `list.append` (#1681). Without this, the
|
||
// qualified ref never reaches resolveViaImport / resolvePythonModuleMember.
|
||
if (PYTHON_BUILT_IN_METHODS.has(method)) {
|
||
// A module-scope collection binding is stronger evidence than a
|
||
// coincidentally matching class name (#1652). Only use this file's
|
||
// binding: an unrelated module may reuse the receiver for a collection.
|
||
const isCollection = this.context.getNodesByName(receiver).some((node) =>
|
||
node.language === 'python' && node.filePath === ref.filePath &&
|
||
(node.kind === 'variable' || node.kind === 'constant') &&
|
||
node.qualifiedName === receiver &&
|
||
/^=\s*(?:[\[{]|(?:dict|list|set|tuple|frozenset)\s*\(|\(\s*\)|\([^()]*,)/.test(node.signature ?? '')
|
||
);
|
||
if (isCollection) return true;
|
||
|
||
const capitalized = receiver.charAt(0).toUpperCase() + receiver.slice(1);
|
||
const isKnownClass = this.context.getNodesByName(capitalized).some((node) =>
|
||
node.language === 'python' &&
|
||
(node.kind === 'class' || node.kind === 'struct' || node.kind === 'interface')
|
||
);
|
||
const isProjectModule =
|
||
!isKnownClass && this.isPythonProjectModule(ref, receiver);
|
||
if (!isKnownClass && !isProjectModule) {
|
||
return true;
|
||
}
|
||
}
|
||
}
|
||
// A bare name colliding with a builtin method (index, get, update, count…)
|
||
// is only a builtin when NOTHING in the codebase declares it. A declared
|
||
// symbol with that exact name — e.g. a Flask/FastAPI view `def index()` or
|
||
// `def get()` — is a real reference target. Without this guard, every
|
||
// handler named after a builtin method silently loses its route→handler edge.
|
||
if (PYTHON_BUILT_IN_METHODS.has(name) && !this.knownNames?.has(name)) {
|
||
return true;
|
||
}
|
||
}
|
||
|
||
// Go standard library packages — refs like "fmt.Println", "http.ListenAndServe", etc.
|
||
if (ref.language === 'go') {
|
||
const dotIdx = name.indexOf('.');
|
||
if (dotIdx > 0) {
|
||
const pkg = name.substring(0, dotIdx);
|
||
// Not a local bound from a type assertion that is named like one:
|
||
// grpc-go's `parser.ParseConfig(…)` after `parser, ok :=
|
||
// b.(balancer.ConfigParser)`.
|
||
if (GO_STDLIB_PACKAGES.has(pkg) && !isGoAssertedLocal(pkg, ref, this.context)) {
|
||
return true;
|
||
}
|
||
}
|
||
if (GO_BUILT_INS.has(name)) {
|
||
return true;
|
||
}
|
||
}
|
||
|
||
// Pascal/Delphi built-ins and standard library units
|
||
if (ref.language === 'pascal') {
|
||
if (PASCAL_UNIT_PREFIXES.some((p) => name.startsWith(p))) {
|
||
return true;
|
||
}
|
||
if (PASCAL_BUILT_INS.has(name)) {
|
||
return true;
|
||
}
|
||
}
|
||
|
||
// C/C++ standard library symbols (printf, malloc, std::vector, etc.).
|
||
// Names that collide with user-defined symbols are NOT filtered —
|
||
// C and C++ projects routinely shadow stdlib names (custom allocators
|
||
// define `malloc`/`free`, stream wrappers define `read`/`write`/`open`,
|
||
// containers define `move`/`swap`, logging libs wrap `printf`). Killing
|
||
// those resolutions makes the graph wrong, not cleaner. We only filter
|
||
// when there's no user node with this name — then name-matching would
|
||
// produce zero edges anyway and the filter just short-circuits work.
|
||
if (ref.language === 'c' || ref.language === 'cpp') {
|
||
// A leading `::` names the global scope: `::std::move` is `std::move`,
|
||
// `::memset` is `memset`.
|
||
const scoped = name.startsWith('::') ? name.slice(2) : name;
|
||
// C++ std:: namespace prefix — safe to filter unconditionally,
|
||
// since `std::foo` is never a user-defined qualified name in
|
||
// tree-sitter output.
|
||
if (scoped.startsWith('std::')) return true;
|
||
if (C_BUILT_INS.has(scoped) || CPP_BUILT_INS.has(scoped)) {
|
||
return !this.hasAnyPossibleMatch(scoped);
|
||
}
|
||
}
|
||
|
||
return false;
|
||
}
|
||
|
||
/**
|
||
* Get file path from node ID
|
||
*/
|
||
private getFilePathFromNodeId(nodeId: string): string {
|
||
const node = this.nodeById(nodeId);
|
||
return node?.filePath || '';
|
||
}
|
||
|
||
/**
|
||
* Get language from node ID
|
||
*/
|
||
private getLanguageFromNodeId(nodeId: string): UnresolvedRef['language'] {
|
||
const node = this.nodeById(nodeId);
|
||
return node?.language || 'unknown';
|
||
}
|
||
|
||
/**
|
||
* Collect the `@using` namespaces in scope for a `.razor`/`.cshtml` file: its
|
||
* own `@using` directives plus every `_Imports.razor` from the file's folder up
|
||
* to the project root (Razor `_Imports` cascade). Cached per file.
|
||
*/
|
||
private getRazorUsings(filePath: string): string[] {
|
||
const cached = this.razorUsingsCache.get(filePath);
|
||
if (cached) return cached;
|
||
const usings = new Set<string>();
|
||
const addFrom = (src: string | null): void => {
|
||
if (!src) return;
|
||
for (const m of src.matchAll(/^\s*@using\s+(?:static\s+)?([A-Za-z_][\w.]*)/gm)) usings.add(m[1]!);
|
||
};
|
||
addFrom(this.context.readFile(filePath));
|
||
let dir = filePath.includes('/') ? filePath.slice(0, filePath.lastIndexOf('/')) : '';
|
||
// Walk up to the project root, reading each level's _Imports.razor.
|
||
for (;;) {
|
||
addFrom(this.context.readFile(dir ? `${dir}/_Imports.razor` : '_Imports.razor'));
|
||
if (!dir) break;
|
||
const slash = dir.lastIndexOf('/');
|
||
dir = slash >= 0 ? dir.slice(0, slash) : '';
|
||
}
|
||
const arr = [...usings];
|
||
this.razorUsingsCache.set(filePath, arr);
|
||
return arr;
|
||
}
|
||
|
||
/**
|
||
* Resolve a Razor/Blazor simple type ref through the file's `@using`
|
||
* namespaces: `CatalogBrand` + `@using BlazorShared.Models` → the node whose
|
||
* qualified name is `BlazorShared.Models::CatalogBrand`. Only resolves when the
|
||
* `@using` set yields exactly ONE type (otherwise it stays ambiguous and falls
|
||
* through to name-matching).
|
||
*/
|
||
private resolveRazorUsing(ref: UnresolvedRef): ResolvedRef | null {
|
||
if (ref.referenceName.includes('.') || ref.referenceName.includes('::')) return null;
|
||
const usings = this.getRazorUsings(ref.filePath);
|
||
if (usings.length === 0) return null;
|
||
const found = new Map<string, Node>();
|
||
for (const ns of usings) {
|
||
for (const cand of this.context.getNodesByQualifiedName(`${ns}::${ref.referenceName}`)) {
|
||
found.set(cand.id, cand);
|
||
}
|
||
}
|
||
if (found.size !== 1) return null;
|
||
const target = found.values().next().value!;
|
||
return { original: ref, targetNodeId: target.id, confidence: 0.9, resolvedBy: 'import' };
|
||
}
|
||
|
||
/**
|
||
* Resolve a CFML inheritance reference written as a component path (#1152).
|
||
* Two forms exist in real code:
|
||
*
|
||
* - Dotted: `extends="coldbox.system.web.Controller"` — dots are directory
|
||
* separators from the webroot or a CFML mapping. Mappings live in server
|
||
* config / Application.cfc, so the leading segments may not exist in the
|
||
* repo at all (in the coldbox repo itself the path is `system/web/
|
||
* Controller.cfc` — the `coldbox.` root IS the repo). Matched by final
|
||
* segment (the class), corroborated right-to-left against the candidate's
|
||
* parent directories.
|
||
* - Relative: `extends="../base"` / `extends="./base"` (the FW/1 style) —
|
||
* resolved against the referencing file's own directory.
|
||
*
|
||
* Conservative by design: a candidate needs at least one corroborating
|
||
* directory segment (a dotted path whose only same-named class sits in an
|
||
* unrelated directory is almost always an out-of-repo library supertype —
|
||
* mxunit/testbox/coldbox-as-dependency), and a corroboration tie yields no
|
||
* edge. Directory comparison is case-insensitive (CFML path resolution is);
|
||
* the class segment itself is matched exactly, which real code satisfies —
|
||
* dotted paths are written to match the on-disk file name.
|
||
*/
|
||
private resolveCfmlComponentPath(ref: UnresolvedRef): ResolvedRef | null {
|
||
const cfmlCandidates = (name: string): Node[] =>
|
||
this.context
|
||
.getNodesByName(name)
|
||
.filter(
|
||
(n) =>
|
||
(n.kind === 'class' || n.kind === 'interface') &&
|
||
(n.language === 'cfml' || n.language === 'cfscript')
|
||
);
|
||
const norm = (p: string): string => p.replace(/\\/g, '/').toLowerCase();
|
||
|
||
// Relative-path form: `../base`, `./base`, `sub/thing` — resolve against
|
||
// the referencing file's directory and require an exact (case-insensitive)
|
||
// file match.
|
||
if (ref.referenceName.includes('/')) {
|
||
const rel = ref.referenceName.replace(/\.cfc$/i, '');
|
||
const fromDir = ref.filePath.replace(/\\/g, '/').split('/').slice(0, -1);
|
||
const parts = [...fromDir];
|
||
for (const seg of rel.split('/')) {
|
||
if (seg === '' || seg === '.') continue;
|
||
if (seg === '..') {
|
||
if (parts.length === 0) return null; // escapes the project root
|
||
parts.pop();
|
||
} else {
|
||
parts.push(seg);
|
||
}
|
||
}
|
||
const wantPath = norm(parts.join('/') + '.cfc');
|
||
const className = parts[parts.length - 1];
|
||
if (!className) return null;
|
||
const target = cfmlCandidates(className).find((c) => norm(c.filePath) === wantPath);
|
||
return target
|
||
? { original: ref, targetNodeId: target.id, confidence: 0.95, resolvedBy: 'file-path' }
|
||
: null;
|
||
}
|
||
|
||
// Dotted form.
|
||
const segments = ref.referenceName.split('.').map((s) => s.trim()).filter(Boolean);
|
||
if (segments.length < 2) return null;
|
||
const className = segments[segments.length - 1]!;
|
||
const dirSegments = segments.slice(0, -1);
|
||
|
||
let best: Node | null = null;
|
||
let bestScore = 0;
|
||
let tie = false;
|
||
for (const cand of cfmlCandidates(className)) {
|
||
const dirs = cand.filePath.replace(/\\/g, '/').split('/').slice(0, -1);
|
||
// Count matching directory segments right-to-left: for
|
||
// `coldbox.system.web.Controller` vs `system/web/Controller.cfc`,
|
||
// `web` and `system` match, then the repo root ends the run → score 2.
|
||
let score = 0;
|
||
while (
|
||
score < dirSegments.length &&
|
||
score < dirs.length &&
|
||
dirSegments[dirSegments.length - 1 - score]!.toLowerCase() ===
|
||
dirs[dirs.length - 1 - score]!.toLowerCase()
|
||
) {
|
||
score++;
|
||
}
|
||
if (score > bestScore) {
|
||
best = cand;
|
||
bestScore = score;
|
||
tie = false;
|
||
} else if (score === bestScore && score > 0) {
|
||
tie = true;
|
||
}
|
||
}
|
||
if (!best || bestScore === 0 || tie) return null;
|
||
return { original: ref, targetNodeId: best.id, confidence: 0.9, resolvedBy: 'qualified-name' };
|
||
}
|
||
|
||
/**
|
||
* Resolve a `this.<member>` function-as-value reference (#756/#808) to the
|
||
* ENCLOSING CLASS's own member — never a same-named symbol elsewhere. The
|
||
* registration idiom (`btn.on('click', this.handleClick)`) names a member
|
||
* of the class being defined, so the only valid target shares the
|
||
* from-symbol's qualified-name scope. Function/method targets only — a
|
||
* property (a data field, post-#808 classification) yields no edge — same
|
||
* file required, no fallback of any kind.
|
||
*/
|
||
private resolveThisMemberFnRef(ref: UnresolvedRef): ResolvedRef | null {
|
||
const member = ref.referenceName.slice('this.'.length);
|
||
if (!member) return null;
|
||
const written = this.nodeById(ref.fromNodeId);
|
||
if (!written) return null;
|
||
// Inside an object literal: its own method's `this` is the object, an
|
||
// arrow member's is the method around the literal (#2300).
|
||
const fromNode = thisScopeCaller(written, this.context);
|
||
// A hook declared at class-body level (Ruby `before_action :authenticate`)
|
||
// attributes to the CLASS node itself — its qualified name IS the scope.
|
||
// For members, strip the member segment.
|
||
let classPrefix: string;
|
||
if (SUPERTYPE_BEARING_KINDS.has(fromNode.kind) || fromNode.kind === 'module') {
|
||
classPrefix = fromNode.qualifiedName;
|
||
} else {
|
||
const sep = fromNode.qualifiedName.lastIndexOf('::');
|
||
if (sep <= 0) return null; // not inside a class scope
|
||
classPrefix = fromNode.qualifiedName.slice(0, sep);
|
||
}
|
||
const candidates = this.context
|
||
.getNodesByQualifiedName(`${classPrefix}::${member}`)
|
||
.filter(
|
||
(n) =>
|
||
(n.kind === 'function' || n.kind === 'method') &&
|
||
n.filePath === ref.filePath &&
|
||
n.id !== ref.fromNodeId
|
||
);
|
||
if (candidates.length === 0) {
|
||
// Not on the class itself — possibly INHERITED. implements/extends
|
||
// edges don't exist yet in this pass, so retry in the supertype pass
|
||
// (resolveDeferredThisMemberRefs) instead of giving up.
|
||
this.deferReference(ref, this.deferredThisMemberRefs);
|
||
return null;
|
||
}
|
||
const target = candidates.reduce((a, b) => (a.startLine <= b.startLine ? a : b));
|
||
return {
|
||
original: ref,
|
||
targetNodeId: target.id,
|
||
confidence: 0.95,
|
||
resolvedBy: 'function-ref',
|
||
};
|
||
}
|
||
|
||
/**
|
||
* Second pass for `this.<member>` refs whose member wasn't on the enclosing
|
||
* class itself (#808): once implements/extends edges exist, walk the
|
||
* class's supertypes (transitively, depth-capped) and resolve the member on
|
||
* the nearest one that declares it — `this.handleSubmit` registered in a
|
||
* subclass resolves to `FormBase::handleSubmit`. Validated targets only
|
||
* (function/method kind, same language family); no match → no edge.
|
||
* Mirrors resolveChainedCallsViaConformance's lifecycle. Returns the number
|
||
* of newly-created edges.
|
||
*/
|
||
async resolveDeferredThisMemberRefs(): Promise<number> {
|
||
const deferred = this.deferredThisMemberRefs;
|
||
this.deferredThisMemberRefs = [];
|
||
if (deferred.length === 0) return 0;
|
||
|
||
this.clearCaches();
|
||
// Synchronous main-thread post-pass with a per-ref supertype BFS — yield
|
||
// periodically so the #850 liveness watchdog heartbeat can fire (#1091).
|
||
const maybeYield = createYielder();
|
||
const resolved: ResolvedRef[] = [];
|
||
// Refs share supertypes (every `this.dispose` walks the same chain), and
|
||
// nothing is written until the loop ends: read each type's supertype
|
||
// edges, and each supertype's callable members by name, once.
|
||
const supertypeEdges = new Map<string, Edge[]>();
|
||
const callableMembers = new Map<string, Map<string, Node[]>>();
|
||
const supertypesOf = (id: string): Edge[] => {
|
||
let edges = supertypeEdges.get(id);
|
||
if (!edges) {
|
||
edges = this.queries.getOutgoingEdges(id, ['implements', 'extends']);
|
||
supertypeEdges.set(id, edges);
|
||
}
|
||
return edges;
|
||
};
|
||
const callableMembersOf = (id: string): Map<string, Node[]> => {
|
||
let byName = callableMembers.get(id);
|
||
if (!byName) {
|
||
byName = new Map();
|
||
for (const c of this.queries.getOutgoingEdges(id, ['contains'])) {
|
||
const m = this.nodeById(c.target);
|
||
if (!m || (m.kind !== 'function' && m.kind !== 'method')) continue;
|
||
const list = byName.get(m.name);
|
||
if (list) list.push(m);
|
||
else byName.set(m.name, [m]);
|
||
}
|
||
callableMembers.set(id, byName);
|
||
}
|
||
return byName;
|
||
};
|
||
for (const ref of deferred) {
|
||
await maybeYield();
|
||
const member = ref.referenceName.slice('this.'.length);
|
||
const written = this.nodeById(ref.fromNodeId);
|
||
if (!written || !member) continue;
|
||
const fromNode = thisScopeCaller(written, this.context);
|
||
// Class-body-level hooks (Ruby) attribute to the CLASS node itself.
|
||
let className: string;
|
||
if (SUPERTYPE_BEARING_KINDS.has(fromNode.kind) || fromNode.kind === 'module') {
|
||
className = fromNode.name;
|
||
} else {
|
||
const sep = fromNode.qualifiedName.lastIndexOf('::');
|
||
if (sep <= 0) continue;
|
||
const classPrefix = fromNode.qualifiedName.slice(0, sep);
|
||
className = classPrefix.includes('::')
|
||
? classPrefix.slice(classPrefix.lastIndexOf('::') + 2)
|
||
: classPrefix;
|
||
}
|
||
|
||
// NODE-anchored BFS up the supertype graph: start from the class node
|
||
// in the ref's own file (never a same-named class elsewhere — rails has
|
||
// a dozen `Engine`s), follow implements/extends EDGES to supertype
|
||
// NODES, and look members up through `contains` edges. No name-based
|
||
// unions anywhere — a name-keyed getSupertypes('Engine') merged every
|
||
// Engine's parents and produced a cross-class wrong edge on rails.
|
||
let frontierNodes = this.context
|
||
.getNodesByName(className)
|
||
.filter(
|
||
(n) =>
|
||
SUPERTYPE_BEARING_KINDS.has(n.kind) &&
|
||
n.filePath === ref.filePath
|
||
);
|
||
if (frontierNodes.length === 0) {
|
||
// The class itself may be declared in another file (partial/reopened
|
||
// classes); fall back to same-family nodes of that name.
|
||
frontierNodes = this.context
|
||
.getNodesByName(className)
|
||
.filter(
|
||
(n) =>
|
||
SUPERTYPE_BEARING_KINDS.has(n.kind) &&
|
||
sameLanguageFamily(n.language, ref.language)
|
||
);
|
||
}
|
||
const seenNodes = new Set<string>(frontierNodes.map((n) => n.id));
|
||
let target: Node | null = null;
|
||
for (let depth = 0; depth < 5 && frontierNodes.length > 0 && !target; depth++) {
|
||
const next: Node[] = [];
|
||
for (const typeNode of frontierNodes) {
|
||
for (const edge of supertypesOf(typeNode.id)) {
|
||
const superNode = this.nodeById(edge.target);
|
||
if (!superNode || seenNodes.has(superNode.id)) continue;
|
||
seenNodes.add(superNode.id);
|
||
if (!SUPERTYPE_BEARING_KINDS.has(superNode.kind)) continue;
|
||
// Member lookup anchored on the supertype's contains edges.
|
||
target =
|
||
callableMembersOf(superNode.id)
|
||
.get(member)
|
||
?.find((m) => sameLanguageFamily(m.language, ref.language)) ?? null;
|
||
if (target) break;
|
||
next.push(superNode);
|
||
}
|
||
if (target) break;
|
||
}
|
||
frontierNodes = next;
|
||
}
|
||
|
||
if (target) {
|
||
resolved.push({
|
||
original: ref,
|
||
targetNodeId: target.id,
|
||
confidence: 0.85,
|
||
resolvedBy: 'function-ref',
|
||
});
|
||
}
|
||
}
|
||
return this.persistDeferredReferences(deferred, resolved);
|
||
}
|
||
|
||
/**
|
||
* Drop a resolution whose target cannot be what the reference names.
|
||
* Applied at the `resolveOne` seam so it covers every strategy uniformly —
|
||
* framework, import, name-match, chain, CFML component path.
|
||
*
|
||
* For `imports`: the target must be importable. A member that only exists
|
||
* inside a type never is, and neither is the import statement the reference
|
||
* was written in.
|
||
*
|
||
* For a Go type position: the target is a type of the package Go reads the
|
||
* name from, moved there when a strategy found a method, a function or
|
||
* another package's type (see goTypePositionTarget).
|
||
*
|
||
* For `extends`/`implements`, it cannot be describing a real supertype when:
|
||
*
|
||
* 1. The target's kind can never be a supertype (an enum member, a method,
|
||
* a variable). `matchByExactName` additionally narrows its candidate
|
||
* pool by the same set, so a legitimate supertype outranks a same-named
|
||
* non-type rather than merely losing its edge.
|
||
* 2. The name is imported from outside the repo, so NO local node is the
|
||
* referent. Without this, filtering by kind alone just relocates the
|
||
* false edge onto the next same-named local type.
|
||
*
|
||
* One exception to (1): a TypeScript VALUE that shares its name with a type
|
||
* in the same file. `export const IFoo = createDecorator<IFoo>('foo')` beside
|
||
* `export interface IFoo` is how VS Code declares every service, and an
|
||
* import of `IFoo` resolves to the file with both — a strategy that takes the
|
||
* first export of that name gets the value. The strategy found the right
|
||
* file and name; the type declared there is the supertype, so the edge moves
|
||
* to it rather than being dropped (dropping it lost ~900 `implements` edges
|
||
* on vscode).
|
||
*
|
||
* Otherwise this only ever REMOVES an edge, never adds one. A dropped ref
|
||
* stays in `unresolved_refs` as `failed`, which is the honest record for a
|
||
* supertype that lives outside the repo — silent beats wrong.
|
||
*/
|
||
private gateTargetKind(result: ResolvedRef | null, ref: UnresolvedRef): ResolvedRef | null {
|
||
if (!result) return result;
|
||
|
||
// A `#define` is a value, never a callee (#1838): a macro defined only in
|
||
// an unrelated file is not what `NAME(x)` here expands to either.
|
||
if (ref.referenceKind === 'calls') {
|
||
const target = this.nodeById(result.targetNodeId);
|
||
if (target?.kind === 'constant' && CPP_DEFINE_SIGNATURE.test(target.signature ?? '')) return null;
|
||
// A Go call made through an expression — `h.Validate().Error()`, a
|
||
// `.Metrics()` chained onto the line above — calls a method of whatever
|
||
// the expression is. A type is called only bare (`T(x)`, `(*T)(x)`) or
|
||
// through its package; as a struct here it read as an instantiation.
|
||
if (target && ref.language === 'go' && GO_TYPE_KINDS.has(target.kind) &&
|
||
!ref.referenceName.includes('.') && !isGoBareName(ref, this.context)) return null;
|
||
}
|
||
|
||
// An `imports` reference names something importable — never a member that
|
||
// only exists inside a type, nor its own import statement. A module path
|
||
// that names no file (`./missing`, `stdio.h`, `pkg.mod`, a C# `using` of
|
||
// an outside namespace) reaches the statement by its qualified name; as an
|
||
// edge to itself it is never retried, while a failed ref is retried by the
|
||
// sync that adds the file it names.
|
||
if (ref.referenceKind === 'imports') {
|
||
const target = this.nodeById(result.targetNodeId);
|
||
if (target?.kind === 'import' && target.filePath === ref.filePath) return null;
|
||
return target && !isImportableKind(target.kind) ? null : result;
|
||
}
|
||
|
||
// A Go alias names its type as an embedding does (below): written through
|
||
// a package that is none of the file's imports as indexed, the type found
|
||
// by its bare name is another package's namesake, or the alias itself.
|
||
if (ref.language === 'go' && ref.referenceKind === 'references' &&
|
||
this.nodeById(ref.fromNodeId)?.kind === 'type_alias' && isGoUnknownQualified(ref, this.context)) return null;
|
||
|
||
// A Go type position — a parameter or result type, a composite literal's
|
||
// type — names a type of the package Go reads it from (route handlers are
|
||
// `references` too, but values).
|
||
if (ref.language === 'go' && (ref.referenceKind === 'instantiates' ||
|
||
(ref.referenceKind === 'references' && this.nodeById(ref.fromNodeId)?.kind !== 'route'))) {
|
||
return goTypePositionTarget(result, ref, this.context);
|
||
}
|
||
|
||
if (!isInheritanceRef(ref)) return result;
|
||
const target = this.nodeById(result.targetNodeId);
|
||
if (target && !isSupertypeTarget(target)) {
|
||
const type = this.sameNamedTypeOfValue(target);
|
||
if (!type) return null;
|
||
result = { ...result, targetNodeId: type.id };
|
||
}
|
||
if (isBoundToOutOfRepoImport(ref, this.context)) return null;
|
||
// A Go type embedded through a package (`clientv3.KV`) is that package's.
|
||
// When the package is none of the file's imports as indexed (clientv3
|
||
// imported unaliased as `go.etcd.io/etcd/client/v3`), a type found by its
|
||
// bare name is some other package's namesake.
|
||
if (ref.language === 'go' && isGoUnknownQualified(ref, this.context)) return null;
|
||
return result;
|
||
}
|
||
|
||
/**
|
||
* `super.didMoveToWindow()` inside an override of `didMoveToWindow` calls
|
||
* the PARENT's implementation, never the method making the call. Extraction
|
||
* keeps a `super` call under the bare method name, so every strategy found
|
||
* the enclosing method itself: one expo-camera view had eleven of its
|
||
* overrides "calling" themselves. The parent's method is usually a
|
||
* framework's (UIKit, Android, React); a self-edge is never it. Real
|
||
* recursion keeps its edge — only a call written through `super` / `base`
|
||
* (C#) / `[super …]` (Objective-C) / `parent::` (PHP) / `super().` (Python)
|
||
* is declined.
|
||
*/
|
||
private gateSuperSelfCall(result: ResolvedRef | null, ref: UnresolvedRef): ResolvedRef | null {
|
||
if (!result || ref.referenceKind !== 'calls' || result.targetNodeId !== ref.fromNodeId) return result;
|
||
const name = ref.referenceName.slice(Math.max(ref.referenceName.lastIndexOf('.'), ref.referenceName.lastIndexOf(':')) + 1);
|
||
if (!/^[A-Za-z_$][\w$]*$/.test(name)) return result;
|
||
const line = (this.context.getFileLines?.(ref.filePath) ?? this.context.readFile(ref.filePath)?.split(/\r?\n/))?.[ref.line - 1];
|
||
if (!line) return result;
|
||
const escaped = name.replace(/\$/g, '\\$');
|
||
const viaSuper = new RegExp(
|
||
String.raw`(?:\b(?:super|base)\s*(?:\(\s*(?:[\w.]+\s*,\s*\w+)?\s*\))?\s*\??\.\s*|\[\s*super\s+|\bparent\s*::\s*)` + escaped + String.raw`\b`,
|
||
);
|
||
return viaSuper.test(line) ? null : result;
|
||
}
|
||
|
||
/**
|
||
* A bare Rust name reaches only what is in scope — every strategy's result,
|
||
* a framework resolver's `Ok(x)` → `struct Ok` construction included (see
|
||
* isRustNameInScope).
|
||
*/
|
||
private gateRustScope(result: ResolvedRef | null, ref: UnresolvedRef): ResolvedRef | null {
|
||
if (!result || ref.language !== 'rust' || !/^[A-Za-z_]\w*$/.test(ref.referenceName)) return result;
|
||
const target = this.nodeById(result.targetNodeId);
|
||
return target && !isRustNameInScope(target, ref, this.context) ? null : result;
|
||
}
|
||
|
||
/** Is `filePath` (project-relative) one of the files the index holds? */
|
||
private isIndexedFile(filePath: string): boolean {
|
||
const normalized = filePath.replace(/\\/g, '/');
|
||
return this.knownFiles ? this.knownFiles.has(normalized) : this.queries.getFileByPath(normalized) !== null;
|
||
}
|
||
|
||
/** The repository's own package name, from its root package.json; null without one. */
|
||
/** Per directory: the package names its package.json and every enclosing one own and depend on. */
|
||
private manifestScopes = new Map<string, { own: Set<string>; deps: Set<string> }>();
|
||
|
||
/**
|
||
* Is `source` a package from outside the repository? Only when the importing
|
||
* file's package.json (or an enclosing one) declares it, or it is a Node
|
||
* built-in or a runtime's virtual module. A specifier nothing declares is
|
||
* an alias this resolver does not know — SvelteKit's `$lib/…`, Nuxt's
|
||
* `~/…`, a nested app's own `@/…` — and stays the project's.
|
||
*/
|
||
private isDeclaredOutsidePackage(source: string, fromFile: string): boolean {
|
||
// Deno's standard library is `@std/…` from JSR.
|
||
if (/^(?:node|bun|jsr|npm|https?):/.test(source) || source.startsWith('@std/') || NODE_BUILTINS.has(source)) return true;
|
||
const name = source.startsWith('@') ? source.split('/').slice(0, 2).join('/') : source.split('/')[0]!;
|
||
const normalized = fromFile.replace(/\\/g, '/');
|
||
const scope = this.manifestScope(normalized.includes('/') ? normalized.slice(0, normalized.lastIndexOf('/')) : '');
|
||
if (scope.own.has(name)) return false;
|
||
if (scope.deps.has(name)) return true;
|
||
// SvelteKit's `$app/…` and Astro's `astro:…` belong to the framework —
|
||
// unless this repository is that framework.
|
||
const provider = source.startsWith('astro:') ? 'astro' : /^\$(?:app|env|service-worker)(?:\/|$)/.test(source) ? '@sveltejs/kit' : null;
|
||
return provider !== null && !scope.own.has(provider) && !this.context.getWorkspacePackages?.()?.byName.has(provider);
|
||
}
|
||
|
||
private manifestScope(dir: string): { own: Set<string>; deps: Set<string> } {
|
||
const memo = this.manifestScopes.get(dir);
|
||
if (memo) return memo;
|
||
const parent = dir === '' ? null : this.manifestScope(dir.includes('/') ? dir.slice(0, dir.lastIndexOf('/')) : '');
|
||
let scope = parent ?? { own: new Set<string>(), deps: new Set<string>() };
|
||
try {
|
||
const json = JSON.parse(this.context.readFile(dir ? `${dir}/package.json` : 'package.json') ?? 'null') as Record<string, unknown> | null;
|
||
if (json && typeof json === 'object') {
|
||
scope = { own: new Set(scope.own), deps: new Set(scope.deps) };
|
||
if (typeof json.name === 'string' && json.name.length > 0) scope.own.add(json.name);
|
||
for (const field of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
|
||
const deps = json[field];
|
||
if (!deps || typeof deps !== 'object') continue;
|
||
for (const [dep, version] of Object.entries(deps)) {
|
||
// `workspace:*`, `file:../shared`, `link:…`: a package in this repository.
|
||
if (typeof version === 'string' && /^(?:workspace|file|link|portal):/.test(version)) scope.own.add(dep);
|
||
else scope.deps.add(dep);
|
||
}
|
||
}
|
||
}
|
||
} catch { /* no or unreadable package.json */ }
|
||
// A Deno import map names packages the same way — an entry that maps to a
|
||
// registry or a URL, not one that maps to a path in the repository.
|
||
for (const file of ['deno.json', 'deno.jsonc']) {
|
||
const raw = this.context.readFile(dir ? `${dir}/${file}` : file);
|
||
if (!raw) continue;
|
||
const json = parseJsonc(raw) as { imports?: Record<string, unknown> } | undefined;
|
||
const imports = json && typeof json === 'object' ? json.imports : undefined;
|
||
if (!imports || typeof imports !== 'object') continue;
|
||
for (const [key, target] of Object.entries(imports)) {
|
||
if (typeof target !== 'string' || !/^(?:jsr|npm|https?):/.test(target)) continue;
|
||
if (scope === parent) scope = { own: new Set(scope.own), deps: new Set(scope.deps) };
|
||
scope.deps.add(key.replace(/\/$/, ''));
|
||
}
|
||
}
|
||
this.manifestScopes.set(dir, scope);
|
||
return scope;
|
||
}
|
||
|
||
/** The one supertype-kind node a TypeScript value shares its name and file with. */
|
||
private sameNamedTypeOfValue(value: Node): Node | null {
|
||
if (value.kind !== 'constant' && value.kind !== 'variable') return null;
|
||
if (value.language !== 'typescript' && value.language !== 'tsx') return null;
|
||
const types = this.context
|
||
.getNodesInFile(value.filePath)
|
||
.filter((n) => n.name === value.name && isSupertypeTarget(n));
|
||
return types.length === 1 ? types[0]! : null;
|
||
}
|
||
|
||
private gateLanguage(result: ResolvedRef | null, ref: UnresolvedRef): ResolvedRef | null {
|
||
if (!result) return result;
|
||
return gateLanguageMatch(result, ref, this.context);
|
||
}
|
||
|
||
/**
|
||
* Framework calls carry bridge evidence (RN/Expo JS → native). Other
|
||
* framework results obey the same code-family boundary as name matches;
|
||
* markup/config transitions remain open.
|
||
*/
|
||
private gateFrameworkLanguage(result: ResolvedRef | null, ref: UnresolvedRef): ResolvedRef | null {
|
||
if (!result) return result;
|
||
if (ref.referenceKind === 'calls') return result;
|
||
const tgt = this.getLanguageFromNodeId(result.targetNodeId);
|
||
// Package imports cannot target prose found by a framework's name lookup.
|
||
if (ref.referenceKind === 'imports' && (tgt as string) === 'markdown' && (ref.language as string) !== 'markdown') return null;
|
||
if (tgt && ref.language && crossesCodeBoundary(tgt, ref.language)) return null;
|
||
return result;
|
||
}
|
||
}
|
||
|
||
/** The project-relative directory holding `p` ('' for the project root). */
|
||
function goDirOf(p: string): string {
|
||
const dir = path.posix.dirname(p.replace(/\\/g, '/'));
|
||
return dir === '.' || dir === '/' ? '' : dir;
|
||
}
|
||
|
||
/**
|
||
* The routes a sync added, removed or renamed: `before` is every route node
|
||
* before the sync changed a file, `after` every one after its post-extract
|
||
* pass, and a route whose file and path are on one side only changed. A route
|
||
* renamed in place — the same node under a new path — is in the result twice,
|
||
* as its old self and its new one.
|
||
*/
|
||
export function changedRoutes(before: readonly Node[], after: readonly Node[]): Node[] {
|
||
const key = (route: Node): string => `${route.filePath}\0${route.name}`;
|
||
const beforeKeys = new Set(before.map(key));
|
||
const afterKeys = new Set(after.map(key));
|
||
return [...before.filter((route) => !afterKeys.has(key(route))), ...after.filter((route) => !beforeKeys.has(key(route)))];
|
||
}
|
||
|
||
/**
|
||
* Create a reference resolver instance
|
||
*/
|
||
export function createResolver(projectRoot: string, queries: QueryBuilder): ReferenceResolver {
|
||
const resolver = new ReferenceResolver(projectRoot, queries);
|
||
resolver.initialize();
|
||
return resolver;
|
||
}
|