codedeep-mcp 0.1.0

package/dist/indexer/code-index.js

@@ -0,0 +1,1801 @@
+import { promises as fs } from 'node:fs';
+import { basename, dirname, join, posix } from 'node:path';
+import MiniSearch from 'minisearch';
+import { errMsg, log } from '../logger.js';
+import { IMPORT_DEFAULT, IMPORT_NAMESPACE, NON_CALLABLE_KINDS, RECEIVER_OPAQUE, classNameFromFqn, } from '../types.js';
+// v22: per-symbol CYCLOMATIC + COGNITIVE complexity now also computed for the
+// C-FAMILY extractors — cpp, c, AND objc (McCabe + whitepaper-pinned). The 3 shipped
+// extractor-only; this POPULATES the existing `Symbol.complexity?` /
+// `Symbol.cognitiveComplexity?` fields (added in v9/v10 for the prior languages)
+// on cpp/c/objc symbols for the first time. `isUnchanged` (mtime/size/language)
+// can't detect the extraction-logic change, so a bump is required. NOTE the bump
+// is GLOBAL: a SCHEMA_VERSION mismatch rejects the ENTIRE persisted index
+// (`isValidPersisted` checks `version === SCHEMA_VERSION` project-wide), so EVERY
+// project fully re-indexes on upgrade — even a Java/TS-only one with no C-family
+// files — the standard one-time cost of any schema bump. Closes the complexity
+// campaign across all 14 languages.
+// v21: file-scope `static` free functions/globals now extract `exported=false`
+// for C AND C++ (internal-linkage privacy; also correct for C++ file-scope free
+// functions). This is the C-extractor (13th language) slice: the new `.c`
+// language alone needs NO bump (new files self-heal via the startup scan diff),
+// but the SHARED cpp.ts `exported` flip is an extraction-logic change to the
+// EXISTING cpp language that `isUnchanged` (mtime/size/language) can't detect, so
+// the bump force-invalidates warm cpp caches to re-extract the corrected flags.
+// v20: per-symbol CYCLOMATIC + COGNITIVE complexity now also computed for RUBY
+// (`.rb`/`.rake`/`.gemspec`) — the LAST gap (the Ruby extractor shipped
+// extractor-only), completing the per-language complexity campaign across all 11
+// extractors. BOTH metrics pinned EXACT to sonar-ruby (SonarSource's SLANG-based
+// analyzer), run as a per-function oracle: the sonar-ruby-plugin's `RubyConverter`
+// (JRuby + whitequark/parser) builds the SLANG tree, then the shared
+// `org.sonarsource.slang` `CyclomaticComplexityVisitor` / `CognitiveComplexity`
+// score each function — MEASURED on a per-construct battery + the
+// sinatra/rack/liquid/devise corpus (cyclomatic 99.86% exact, cognitive 99.73%,
+// 0-unexplained). CYCLOMATIC: +1 per if/elsif/unless/ternary/modifier-if-unless,
+// each loop (while/until/for + modifier), each `when` arm (NOT the `case` container
+// or `else`), and `&&`/`||`/`and`/`or`; NOT counted (matching the pin): rescue,
+// `case/in`, `&.`, recursion. COGNITIVE (SLANG): structural+1 + nesting surcharge per
+// if/loop/whole-case/block-`rescue`; an if-with-else used as an EXPRESSION with no
+// nested BlockTree is a ternary (`else` suppressed); booleans are TEXT-based
+// source-order runs (no paren skip); blocks are transparent (no nesting). Reuses the
+// collectionIfType→set widening + two new optional engine knobs (`isExpressionTernary`,
+// `catchPredicate`), all inert for the other 10 languages. Adding the fields to Ruby
+// symbols is an extraction-logic change `isUnchanged` (mtime/size/language) can't
+// detect, so the bump force-invalidates warm caches.
+// v19: per-symbol CYCLOMATIC + COGNITIVE complexity now also computed for PHP
+// (`.php`) — the 11th and LAST extractor, BOTH metrics in one slice (the
+// Java/Rust/Swift/Kotlin/Dart/C# pattern). BOTH are pinned to SonarPHP
+// (`php-frontend` 3.38.0.12239's ComplexityVisitor / CognitiveComplexityVisitor),
+// run as a per-function Maven oracle — every value MEASURED against the real
+// analyzer. CYCLOMATIC: +1 per if/each loop (for/foreach/while/do)/ternary (incl
+// elvis `?:`)/switch `case` (NOT default)/`&&`/`||`/`and`/`or`; NOT one-word
+// `elseif` (3.38 quirk — see the project docs), `xor`, `??`, `|`, catch/try/finally, or
+// `default`. COGNITIVE (SonarPHP 3.38): structural+1 + nesting surcharge per
+// if/ternary/switch/loop/catch; elseif/else +1 flat (two-word `else if` gets an
+// extra nesting bump); `&&`/`||` SOURCE-ORDER runs (paren-unwrap, NOT `and`/`or`);
+// break/continue WITH a level arg + goto +1 flat; closures/arrow-fns roll in
+// (nestOnly); no recursion. PHP FORKS on `match`: it counts each arm like a switch
+// case (cyc) and the whole match +1 (cog) — a DELIBERATE divergence from SonarPHP
+// (which counts match in neither metric). TWO new optional engine knobs: `elseChainsIf`
+// (the PHP two-word `else if` = else-clause-contains-if hybrid) and `ternaryBranchFields`
+// (nest only a ternary's branches so a chained elvis `a ?: b ?: c` doesn't compound).
+// Both are PHP-only (the other 10 languages leave them unset). Adding the fields
+// to PHP symbols is an extraction-logic change `isUnchanged` (mtime/size/language)
+// can't detect, so the bump force-invalidates warm caches.
+// v18: per-symbol CYCLOMATIC + COGNITIVE complexity now also computed for C#
+// (`.cs`) — BOTH metrics in one slice (the Java/Rust/Swift/Kotlin/Dart pattern).
+// BOTH are pinned EXACT to SonarC# (`SonarAnalyzer.CSharp`, the Roslyn-based
+// open-source analyzer), run as a per-method oracle via its public
+// CSharpCyclomaticComplexityMetric / CSharpCognitiveComplexityMetric — so every
+// value is MEASURED against the real analyzer (the best oracle case after Dart).
+// CYCLOMATIC (S1541): +1 per if/each loop (for/foreach/while/do)/ternary/each
+// switch-EXPRESSION arm (incl `_`)/plain-constant switch-STATEMENT case (pattern
+// + `default` cases excluded)/pattern combinator `and`/`or` (not `not`)/`&&`/`||`/
+// `??`/`??=`/`?.`/`?[`; LINQ clauses and `catch`/`when`/`goto` don't. COGNITIVE
+// (S3776, sonar-java-shaped): structural+1 + nesting surcharge per if/ternary/
+// switch/loop/catch/`goto`(+goto case); else/else-if +1 flat; `&&`/`||` + pattern
+// `and`/`or` count as SOURCE-ORDER runs (paren-unwrap) but `??` is FREE; recursion
+// is +1 flat (like Go). C# is sonar-java-shaped (field-based `if`, contained
+// `catch`, source-order booleans) so it reuses the existing engine fields + the Go
+// `recursion` field; the ONE new optional engine knob is `surchargeTypes`
+// (`goto`/`goto case` surcharge +1+nesting). Adding the fields to C# symbols is an
+// extraction-logic change `isUnchanged` (mtime/size/language) can't detect, so the
+// bump force-invalidates warm caches.
+// v17: per-symbol CYCLOMATIC + COGNITIVE complexity now also computed for Dart
+// (`.dart`) — BOTH metrics in one slice. BOTH are pinned for behavioral compatibility
+// with SonarQube's Dart cyclomatic (S1541) and cognitive (S3776) rules, per the
+// published Cognitive Complexity whitepaper (pinning the public spec directly, so the
+// Kotlin "oracle the PIN, not a proxy" trap is structurally impossible). CYCLOMATIC
+// (S1541): +1 per if/collection-if/ternary/each loop/each switch case+arm (incl `_`,
+// excl `default`)/each `&&`/`||`/`??`/`?.`/`??=` (collection-if/for count; `?..` and
+// `else`/`default` don't). COGNITIVE (S3776): structural+1 + nesting surcharge per
+// if/ternary/switch/loop/catch/collection-if/for; `&&`/`||` runs count but `??` is FREE
+// (the cyc/cog divergence); recursion is FREE (measured: a self-call adds 0). The
+// nielsenko grammar + the SonarQube Dart cognitive model forced 4 additive engine knobs
+// (conditionFromNamedChildren — the `if` condition is positional; tryType — catch bodies
+// are siblings of the catch clause; collectionIfType — collection-`if` charges its else;
+// booleanByTreeParent — a `&&`/`||` run is a tree-parent operator change, the SonarQube
+// Dart model, distinct from sonar-java's source-order and SonarJS's `&&`-only). Adding the
+// fields to Dart symbols is an
+// extraction-logic change `isUnchanged` (mtime/size/language) can't detect, so the bump
+// force-invalidates warm caches.
+// v16: per-symbol CYCLOMATIC + COGNITIVE complexity now also computed for Kotlin
+// (`.kt`/`.kts`) — BOTH metrics in one slice (the Java/Rust/Swift pattern). BOTH are
+// pinned to sonar-kotlin (source-available, the "compare to SonarQube" north-star, the
+// Java/Python precedent — chosen over detekt, which counts Elvis/break/continue/catch
+// AND +1 per scope function). CYCLOMATIC: +1 per if, per EACH `when` entry INCLUDING the
+// `else` entry (a deliberate divergence from the `default`/`else`-excluded rule in the
+// C-family langs — sonar-kotlin visits every whenEntry), per loop, per `&&`/`||`; Elvis
+// `?:` is NOT counted. COGNITIVE is the SonarSource whitepaper (the engine default): NO
+// recursion, NO Elvis, paren-unwrap; Kotlin's `if` is positional with an anonymous
+// `else` and possibly brace-less branches (a new engine path,
+// ifConsequenceFromNamedChildren). Adding the fields to Kotlin symbols is an
+// extraction-logic change `isUnchanged` (mtime/size/language) can't detect, so the bump
+// force-invalidates warm caches.
+// v15: per-symbol CYCLOMATIC + COGNITIVE complexity now also computed for Swift
+// (`.swift`) — BOTH metrics in one slice (the Java/Rust pattern). CYCLOMATIC is
+// pinned to SwiftLint's `cyclomatic_complexity` (the open, runnable oracle — the
+// gocyclo/rust-code-analysis precedent of pinning the community tool; SwiftLint counts `guard`/`catch`/the 3
+// loops/every switch case incl. `default`, `fallthrough` −1, and skips nested
+// func/init; it does NOT count `&&`/`||`/ternary/`??`, so Swift is the only codedeep-mcp
+// language without cyclomatic booleans). COGNITIVE is SonarSource-whitepaper-aligned
+// (no published cognitive spec for Swift exists, so there is no
+// tool oracle; validated against
+// hand-computed whitepaper fixtures). `guard` is +1 FLAT (the Rust let-else analog /
+// Swift's nesting-reducing idiom). Swift's `if` is positional (no consequence/
+// alternative field — a new engine path) and its booleans are distinct
+// conjunction/disjunction nodes with lhs/rhs operands. Adding the fields to Swift
+// symbols is an extraction-logic change `isUnchanged` (mtime/size/language) can't
+// detect, so the bump force-invalidates warm caches.
+// v14: per-symbol CYCLOMATIC + COGNITIVE complexity now also computed for Rust
+// (`.rs`) — the first of the remaining 6 languages to get BOTH metrics at once.
+// CYCLOMATIC is pinned to Mozilla's `rust-code-analysis` (the `rust-code-analysis-cli`
+// oracle): the `?` try operator, every match arm, match-arm guards, closures, and
+// the 3 loops all count (McCabe-complete; verified exact on ripgrep + serde modulo
+// macro-internal control flow, which codedeep-mcp's grammar treats as opaque token-trees,
+// and nested fn/impl bodies, the per-symbol model). COGNITIVE is SonarSource-
+// whitepaper/sonar-rust-aligned and DELIBERATELY does NOT replicate two
+// rust-code-analysis cognitive bugs the oracle surfaced (it omits `loop` entirely,
+// and carries boolean-run state across the whole function) — codedeep-mcp counts all 3
+// loops and per-expression boolean runs, the defensible number. Adding the fields to
+// Rust symbols is an extraction-logic change `isUnchanged` (mtime/size/language)
+// can't detect, so the bump force-invalidates warm caches.
+// v13: per-symbol COGNITIVE complexity now also computed for Python (`.py`),
+// VERIFIED-EXACT against sonar-python's CognitiveComplexityVisitor (0 mismatches on
+// all ~5034 functions WITHOUT a nested scope across flask + django; differs from
+// complexipy — sonar-python-aligned: `except` surcharges, booleans count everywhere
+// with no paren-unwrap, `with`/`try` bodies are not nested, `match` is 0 structural,
+// loop bodies nest via loopBodyField). Nested fns/lambdas/classes are excluded (the
+// per-symbol model). Adding the field to Python symbols is an extraction-logic change
+// `isUnchanged` (mtime/size/language) can't detect, so the bump force-invalidates
+// warm caches.
+// v12: per-symbol COGNITIVE complexity now also computed for Go (`.go`),
+// VERIFIED-EXACT against uudashr/gocognit (376/376 functions: cobra 157 + gin 213
+// + a synthetic edge-case fixture 6; differs
+// from sonar-go — gocognit-aligned, like Go cyclomatic is gocyclo-aligned: no
+// plain-else nesting, if-init walked, no paren-unwrap in boolean chains, +1 per
+// direct-recursion call-site). Adding the field to Go symbols is an
+// extraction-logic change `isUnchanged` (mtime/size/language) can't detect, so the
+// bump force-invalidates warm caches.
+// v11: per-symbol COGNITIVE complexity now also computed for TS/JS
+// (`.ts`/`.tsx`/`.js`), VERIFIED-EXACT against SonarJS S3776 (differs from
+// sonar-java: `&&`-runs-only booleans, JSX short-circuit exclusion). Adding the
+// field to TS symbols is an extraction-logic change `isUnchanged`
+// (mtime/size/language) can't detect, so the bump force-invalidates warm caches.
+// v10: per-symbol COGNITIVE complexity (`Symbol.cognitiveComplexity?`, the
+// SonarSource whitepaper nesting-aware metric) is now computed at extract time
+// for Java, alongside cyclomatic which also rolled to Java this slice. A new
+// extraction-computed field `isUnchanged` (mtime/size/language) can't detect, so
+// the bump force-invalidates warm caches to re-extract and populate it. v9:
+// per-symbol cyclomatic complexity (`Symbol.complexity?`, 1 + decision
+// points) is now computed at extract time for TS/JS, Python, and Go. An
+// extraction-computed field `isUnchanged` (mtime/size/language) can't detect, so
+// the bump force-invalidates warm caches to re-extract and populate it. v8:
+// chained/computed member calls (`a.b().c()`, `foo().bar()`) are now
+// captured as name-keyed member refs with an opaque receiver (RECEIVER_OPAQUE).
+// A pure extraction-logic change that `isUnchanged` (mtime/size/language) can't
+// detect, so the bump force-invalidates warm caches to re-extract. v7: symbol
+// ids hash the FULL untruncated signature (the stored signature stays capped at
+// 120 chars for display). Under v6, overloads differing only past the cap shared
+// an id, silently merging their reference graphs — the bump forces the rebuild
+// that re-keys every long-signature symbol. (v6 added enum + namespace-declaration
+// extraction; v5 added persisted git enrichment: FileInfo.commitFrequency,
+// co-change lists, hotspots, gitMeta; v4 added member-expression call refs; v3
+// added ImportedName.kind.)
+// Exported so shape-validation tests can build fixtures at the CURRENT version
+// (they must pass the version gate to reach the shape validators). Hardcoding
+// the number in tests silently neutered them on each bump — see the v9→v10
+// regression where version:9 fixtures began short-circuiting at the version check.
+export const SCHEMA_VERSION = 22;
+// Below this length, names like `do`/`is`/`set` flood with false-positive
+// AST name matches across files. find_references and getCallerCount both
+// fall back to precise within-file resolution at or below this threshold.
+export const SHORT_NAME_THRESHOLD = 4;
+// Score multiplier for exported symbols in `searchSymbols` — public API
+// is the more likely target when exploring by keyword.
+const EXPORTED_BOOST = 1.5;
+// Suffix candidates appended to a relative-import resolution to match an
+// indexed file path. Order encodes language-specific resolution preference;
+// each list is selected by `normalizeImportSpecifier` based on the
+// importer's language and the specifier's explicit extension.
+// Python imports cannot resolve to non-Python at runtime — strictly Python.
+// Package directory wins over sibling module per CPython FileFinder
+// semantics (`_find_spec` checks `_path_isdir(base)` before the suffix
+// loop), so when both `pkg/b.py` and `pkg/b/__init__.py` exist,
+// `from pkg import b` resolves to the package.
+const PY_CANDIDATES = ['/__init__.py', '.py'];
+// JS importer: prefer JS-native; fall back to TS source for projects using
+// allowJs/checkJs where the `.ts` is the canonical implementation.
+const JS_CANDIDATES = [
+    '.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx',
+    '/index.js', '/index.jsx', '/index.mjs', '/index.cjs',
+    '/index.ts', '/index.tsx',
+];
+// TS/TSX importer, no explicit JS-family extension or `.js` stripped:
+// TS source first.
+const TS_CANDIDATES = [
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+    '/index.ts', '/index.tsx', '/index.js', '/index.jsx',
+    '/index.mjs', '/index.cjs',
+];
+// TS/TSX importer with `.jsx` specifier: prefer `.tsx` (Node16/NodeNext
+// emits `.jsx` for `.tsx` source), then `.jsx` (explicit user-written
+// JSX target), then `.ts` fallback. The explicit `.jsx` extension is a
+// strong user signal — it should beat an unrelated `.ts` sibling at the
+// same stem.
+const TS_FROM_JSX_CANDIDATES = [
+    '.tsx', '.jsx', '.ts', '.js', '.mjs', '.cjs',
+    '/index.tsx', '/index.jsx', '/index.ts', '/index.js',
+    '/index.mjs', '/index.cjs',
+];
+// TS/TSX importer with `.js` specifier: prefer `.js` (explicit user
+// signal — hand-written JS in mixed repos), then `.ts` (Node16/NodeNext
+// emits `.js` for `.ts` source). Mirrors the `.jsx` precedence above.
+const TS_FROM_JS_CANDIDATES = [
+    '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
+    '/index.js', '/index.jsx', '/index.ts', '/index.tsx',
+    '/index.mjs', '/index.cjs',
+];
+export const ENTRY_POINT_FILENAME_RE = /^(index|main|app|server|cli|__main__|__init__)\.(ts|tsx|js|mjs|cjs|jsx|py|java|go|rs|swift|kt|kts|dart|cs|php|rb|cpp|cc|cxx|c|m)$/i;
+// Ordinal edge weights feeding the path-confidence product, plus a rank for
+// "strongest edge wins" when one caller reaches the target several ways.
+const EDGE_WEIGHT = Object.freeze({
+    resolved: 1.0,
+    'import-connected': 0.8,
+    'name-match': 0.5,
+    'weak-member': 0.3,
+});
+const STRENGTH_RANK = Object.freeze({
+    'weak-member': 0,
+    'name-match': 1,
+    'import-connected': 2,
+    resolved: 3,
+});
+// Per-hop decay so even a chain of strong-but-unverified edges loses
+// confidence with distance from the changed symbol.
+const DEPTH_DECAY = 0.85;
+// Path-confidence floor below which an edge is shown but not expanded.
+const MIN_EXPAND_CONFIDENCE = 0.35;
+const DEFAULT_CALLER_TREE_DEPTH = 3;
+const DEFAULT_CALLER_TREE_BREADTH = 25;
+const DEFAULT_CALLER_TREE_NODES = 200;
+// Edge classes allowed to recurse by default; weak classes are leaf-only.
+const EXPANDABLE_BY_DEFAULT = new Set([
+    'resolved',
+    'import-connected',
+]);
+// Risk Hotspots (churn × coupling) cost knobs. Hybrid ranking: rank a bounded
+// candidate set by the O(1) cached fan-in, then run the expensive transitive
+// getBlastRadius only for the rows actually displayed.
+const RISK_CANDIDATE_FILES = 40; // most-churned files scanned
+const RISK_BLAST_DEPTH = 2; // caller-tree depth for the displayed blast radius
+const DEFAULT_RISK_HOTSPOTS = 10; // rows returned by getRiskHotspots
+// Static disclosure rendered as a footnote — the caller tree is upstream-only
+// and inheritance-blind by construction, so an empty/shallow tree is a blind
+// spot, not an "all clear".
+const CALLER_TREE_LIMITATIONS = Object.freeze([
+    'Upstream callers only — cross-file callees (downstream) are not traversed (LSP, Phase 2).',
+    'Inheritance/override edges are not modeled, so virtual-dispatch callers may be missing (LSP, Phase 2).',
+    'Edges are heuristic AST name-matches, not compiler-verified; confidence is ordinal, not probabilistic.',
+]);
+export const zeroSymbolsByKind = () => ({
+    function: 0,
+    class: 0,
+    interface: 0,
+    type: 0,
+    variable: 0,
+    method: 0,
+    module: 0,
+    enum: 0,
+});
+export class CodeIndex {
+    symbolById = new Map();
+    fileByPath = new Map();
+    importsByFile = new Map();
+    symbolsByName = new Map();
+    symbolsByFile = new Map();
+    callees = new Map();
+    callers = new Map();
+    // Indexed for find_references; covers both within-file and cross-file
+    // (targetId=null) calls.
+    referencesByTargetName = new Map();
+    // Lets removeFile prune in O(refsInFile) instead of scanning by name.
+    referencesBySourceFile = new Map();
+    sortedNames = [];
+    sortedNamesLower = [];
+    namesDirty = true;
+    searchIndex = null;
+    // Lazy-rebuilt cache for `getCallerCount` so find_symbol's
+    // `References: ~N` doesn't re-walk all imports per result. Mirrors
+    // the namesDirty/rebuildIndexesIfDirty pattern.
+    callerCountById = new Map();
+    callerCountsDirty = true;
+    // Inverted index of renaming value imports (`import { X as Y }`) keyed
+    // by the EXPORTED name X. Rebuilt lazily like the caches above — without
+    // it, every getReferencesByNameOrAlias call would scan every file's
+    // imports (and the caller-count rebuild multiplies that by symbol count).
+    renamingAliasesByName = new Map();
+    aliasIndexDirty = true;
+    // Sorted file paths for hasFileUnder's binary search — the watcher
+    // calls it per deleted path, so a linear scan would make bulk
+    // deletions O(deletedPaths × indexedFiles).
+    sortedFilePaths = [];
+    filePathsDirty = true;
+    // Git enrichment (schema v5). cochangesByFile is keyed by indexed
+    // paths only; partner values inside the records may be any repo path.
+    // hotspotList is <= 50 entries — linear scans are fine.
+    cochangesByFile = new Map();
+    hotspotList = [];
+    gitMetaState = null;
+    writeLock = Promise.resolve();
+    projectRoot;
+    constructor(projectRoot = '') {
+        this.projectRoot = projectRoot;
+    }
+    addFile(file, symbols, references, imports) {
+        this.fileByPath.set(file.path, file);
+        this.importsByFile.set(file.path, [...imports]);
+        this.symbolsByFile.set(file.path, [...symbols]);
+        for (const sym of symbols) {
+            this.symbolById.set(sym.id, sym);
+            pushOrInit(this.symbolsByName, sym.name, sym);
+        }
+        this.referencesBySourceFile.set(file.path, [...references]);
+        for (const ref of references) {
+            pushOrInit(this.referencesByTargetName, ref.targetName, ref);
+            // Module-level calls (sourceId=null) and cross-file unresolved refs
+            // (targetId=null) skip the id-keyed adjacency; they're queried by name
+            // via referencesByTargetName.
+            if (ref.sourceId && ref.targetId) {
+                addAdjacency(this.callees, ref.sourceId, ref.targetId);
+                addAdjacency(this.callers, ref.targetId, ref.sourceId);
+            }
+        }
+        this.namesDirty = true;
+        this.callerCountsDirty = true;
+        this.aliasIndexDirty = true;
+        this.filePathsDirty = true;
+    }
+    // Returns true when the file was actually in the index (cascade ran);
+    // false for a no-op so callers can tell mutation from idle work.
+    removeFile(path) {
+        return this.removeFileInternal(path, true);
+    }
+    // pruneGit=false is the re-index path (updateFile): the file still
+    // exists, so its co-change history and hotspot membership remain valid
+    // and must survive the remove+add cycle.
+    removeFileInternal(path, pruneGit) {
+        const symsInFile = this.symbolsByFile.get(path);
+        if (!symsInFile)
+            return false;
+        if (pruneGit)
+            this.pruneGitData(path);
+        const deletedIds = new Set();
+        for (const sym of symsInFile) {
+            deletedIds.add(sym.id);
+            this.symbolById.delete(sym.id);
+            const list = this.symbolsByName.get(sym.name);
+            if (!list)
+                continue;
+            const filtered = list.filter((s) => s.id !== sym.id);
+            if (filtered.length === 0)
+                this.symbolsByName.delete(sym.name);
+            else
+                this.symbolsByName.set(sym.name, filtered);
+        }
+        for (const id of deletedIds) {
+            this.callees.delete(id);
+            this.callers.delete(id);
+        }
+        pruneAdjacency(this.callers, deletedIds);
+        pruneAdjacency(this.callees, deletedIds);
+        const refsFromFile = this.referencesBySourceFile.get(path);
+        if (refsFromFile) {
+            // Group by targetName so each by-name list is filtered once even when
+            // a file has many refs to the same target.
+            const toRemove = new Map();
+            for (const ref of refsFromFile) {
+                let set = toRemove.get(ref.targetName);
+                if (!set) {
+                    set = new Set();
+                    toRemove.set(ref.targetName, set);
+                }
+                set.add(ref);
+            }
+            for (const [name, set] of toRemove) {
+                const list = this.referencesByTargetName.get(name);
+                if (!list)
+                    continue;
+                const kept = list.filter((r) => !set.has(r));
+                if (kept.length === 0)
+                    this.referencesByTargetName.delete(name);
+                else
+                    this.referencesByTargetName.set(name, kept);
+            }
+            this.referencesBySourceFile.delete(path);
+        }
+        this.fileByPath.delete(path);
+        this.importsByFile.delete(path);
+        this.symbolsByFile.delete(path);
+        this.namesDirty = true;
+        this.callerCountsDirty = true;
+        this.aliasIndexDirty = true;
+        this.filePathsDirty = true;
+        return true;
+    }
+    updateFile(file, symbols, references, imports) {
+        // The pipeline never sets commitFrequency — carry it over from the
+        // previous FileInfo, or every watcher flush would silently zero the
+        // touched file's git data until the next analysis.
+        const prevFrequency = this.fileByPath.get(file.path)?.commitFrequency;
+        this.removeFileInternal(file.path, false);
+        this.addFile(file, symbols, references, imports);
+        if (file.commitFrequency === undefined && prevFrequency !== undefined) {
+            file.commitFrequency = prevFrequency;
+        }
+    }
+    // True deletion only (never the re-index path): drop the file's own
+    // co-change key and hotspot membership. Records naming this file as a
+    // PARTNER in other files' lists are deliberately retained — partner
+    // values are allowed to be non-indexed paths (config/auth.yaml), and a
+    // fresh analysis would re-derive exactly those records from history,
+    // so pruning them here would just disagree with the next refresh.
+    pruneGitData(path) {
+        this.cochangesByFile.delete(path);
+        if (this.hotspotList.includes(path)) {
+            this.hotspotList = this.hotspotList.filter((p) => p !== path);
+        }
+    }
+    // Swap in a completed analysis. Runs under the write lock so a save()
+    // chained behind it persists the new data and apply can never land in
+    // the middle of a save's snapshot. Membership may have drifted since
+    // the analyzer snapshotted hasFile — re-filter keys here.
+    applyGitAnalysis(result) {
+        return this.runLocked(async () => {
+            for (const [path, fi] of this.fileByPath) {
+                fi.commitFrequency = result.counts.get(path) ?? 0;
+            }
+            const cochanges = new Map();
+            for (const [path, list] of result.cochanges) {
+                if (this.fileByPath.has(path))
+                    cochanges.set(path, [...list]);
+            }
+            this.cochangesByFile = cochanges;
+            this.hotspotList = result.hotspots.filter((p) => this.fileByPath.has(p));
+            this.gitMetaState = result.meta;
+        });
+    }
+    getCoChanges(path) {
+        const list = this.cochangesByFile.get(path);
+        return list ? [...list] : [];
+    }
+    // Ranked hotspot files with their window commit counts, strongest
+    // first. Counts come from the live FileInfo so a just-deleted file
+    // can't resurface (pruneGitData removed it from the list).
+    getHotspots(limit = 10) {
+        return this.hotspotList.slice(0, Math.max(0, limit)).map((path) => ({
+            path,
+            commits: this.fileByPath.get(path)?.commitFrequency ?? 0,
+        }));
+    }
+    // Non-null once a git analysis has landed (live or from cache). Tools
+    // gate analysis-derived sections on this; per-call git queries gate on
+    // their own null returns instead.
+    getGitMeta() {
+        return this.gitMetaState;
+    }
+    // Kill-switch / repo-gone path: when git is disabled (CODEDEEP_GIT=0) or
+    // the repo disappeared, persisted enrichment from an earlier enabled
+    // session must not keep rendering forever — it could never refresh.
+    // No-op when no git data is present.
+    clearGitData() {
+        return this.runLocked(async () => {
+            const hadData = this.gitMetaState !== null ||
+                this.cochangesByFile.size > 0 ||
+                this.hotspotList.length > 0;
+            if (!hadData)
+                return false;
+            for (const fi of this.fileByPath.values()) {
+                delete fi.commitFrequency;
+            }
+            this.cochangesByFile = new Map();
+            this.hotspotList = [];
+            this.gitMetaState = null;
+            return true;
+        });
+    }
+    findSymbolByName(name, kind, scope) {
+        const list = this.symbolsByName.get(name);
+        if (!list)
+            return [];
+        return list.filter((s) => matchesKindScope(s, kind, scope));
+    }
+    findSymbolsByPrefix(prefix, limit, kind, scope) {
+        if (!prefix || limit <= 0)
+            return [];
+        this.rebuildIndexesIfDirty();
+        const prefixLower = prefix.toLowerCase();
+        const start = lowerBound(this.sortedNamesLower, prefixLower);
+        const out = [];
+        for (let i = start; i < this.sortedNamesLower.length && out.length < limit; i++) {
+            if (!this.sortedNamesLower[i].startsWith(prefixLower))
+                break;
+            const syms = this.symbolsByName.get(this.sortedNames[i]);
+            if (!syms)
+                continue;
+            for (const s of syms) {
+                if (out.length >= limit)
+                    break;
+                if (!matchesKindScope(s, kind, scope))
+                    continue;
+                out.push(s);
+            }
+        }
+        return out;
+    }
+    suggest(query, limit, kind, scope) {
+        if (!query || limit <= 0)
+            return [];
+        this.rebuildIndexesIfDirty();
+        if (!this.searchIndex)
+            return [];
+        const results = this.searchIndex.search(query);
+        const out = [];
+        for (const r of results) {
+            if (out.length >= limit)
+                break;
+            const sym = this.symbolById.get(r.id);
+            if (!sym)
+                continue;
+            if (!matchesKindScope(sym, kind, scope))
+                continue;
+            out.push(sym);
+        }
+        return out;
+    }
+    // Keyword search across names, signatures, and docstrings for
+    // `search_structure`. Unlike `suggest` (did-you-mean, name-focused),
+    // this widens to all indexed fields and boosts exported symbols.
+    // `total` is the full match count so callers can report exactly how
+    // many results the limit cut.
+    searchSymbols(query, opts) {
+        if (!query || opts.limit <= 0)
+            return { symbols: [], total: 0 };
+        this.rebuildIndexesIfDirty();
+        if (!this.searchIndex)
+            return { symbols: [], total: 0 };
+        const { languages } = opts;
+        const results = this.searchIndex.search(query, {
+            fields: ['name', 'signature', 'doc', 'fqn'],
+            boost: { name: 3, signature: 1.5, doc: 1, fqn: 1 },
+            fuzzy: 0.2,
+            prefix: true,
+            // Equivalent to post-multiplying the total score (each term's
+            // contribution is scaled), but lets MiniSearch do the re-ranking
+            // so the limit slice below stays correct.
+            boostDocument: (id) => {
+                const sym = this.symbolById.get(id);
+                if (!sym)
+                    return 1;
+                return ((sym.exported ? EXPORTED_BOOST : 1) *
+                    (opts.boostByFile?.get(sym.file) ?? 1));
+            },
+            // Filter inside search (not after the limit slice) so results
+            // under-fill only when there genuinely aren't enough matches.
+            filter: languages
+                ? (r) => {
+                    const sym = this.symbolById.get(r.id);
+                    return sym !== undefined && languages.has(sym.language);
+                }
+                : undefined,
+        });
+        const symbols = [];
+        for (const r of results) {
+            if (symbols.length >= opts.limit)
+                break;
+            const sym = this.symbolById.get(r.id);
+            if (sym)
+                symbols.push(sym);
+        }
+        return { symbols, total: results.length };
+    }
+    getSymbolsInFile(path) {
+        const list = this.symbolsByFile.get(path);
+        return list ? [...list] : [];
+    }
+    getReferencesBySourceFile(path) {
+        const list = this.referencesBySourceFile.get(path);
+        return list ? [...list] : [];
+    }
+    getAllFiles() {
+        return [...this.fileByPath.values()];
+    }
+    hasFile(path) {
+        return this.fileByPath.has(path);
+    }
+    getFile(path) {
+        return this.fileByPath.get(path);
+    }
+    get fileCount() {
+        return this.fileByPath.size;
+    }
+    // True when any indexed file lives under `dirPrefix` (must end with '/').
+    // Binary search over the lazily-sorted path list: any key under the
+    // directory sorts >= the prefix and shares it, so checking the first
+    // key at the insertion point suffices.
+    hasFileUnder(dirPrefix) {
+        this.rebuildFilePathsIfDirty();
+        const at = lowerBound(this.sortedFilePaths, dirPrefix);
+        return this.sortedFilePaths[at]?.startsWith(dirPrefix) ?? false;
+    }
+    // All indexed file paths under `dirPrefix` (must end with '/') — the
+    // contiguous sorted range starting at the prefix's insertion point.
+    filesUnder(dirPrefix) {
+        this.rebuildFilePathsIfDirty();
+        const out = [];
+        for (let i = lowerBound(this.sortedFilePaths, dirPrefix); i < this.sortedFilePaths.length; i++) {
+            if (!this.sortedFilePaths[i].startsWith(dirPrefix))
+                break;
+            out.push(this.sortedFilePaths[i]);
+        }
+        return out;
+    }
+    getCallees(symbolId) {
+        return this.resolveIds(this.callees.get(symbolId));
+    }
+    // Fan-out: resolved within-file callees (id-keyed adjacency). A lower bound
+    // — cross-file/unresolved calls live name-keyed and are NOT counted here,
+    // unlike fan-in's getCallerCount which is reference-granular. Tag rendered
+    // surfaces accordingly.
+    getFanOut(symbolId) {
+        return this.callees.get(symbolId)?.size ?? 0;
+    }
+    getCallers(symbolId) {
+        return this.resolveIds(this.callers.get(symbolId));
+    }
+    // Symbol callers come from the id-keyed adjacency set (already deduped
+    // by sourceId); same-file module-level call sites are deduped per file
+    // by earliest line. Cross-file unresolved name-match refs live in
+    // `getCallerCount`.
+    getCallerEdges(symbolId) {
+        const sym = this.symbolById.get(symbolId);
+        if (!sym)
+            return [];
+        const out = this.resolveIds(this.callers.get(symbolId)).map((s) => ({ file: s.file, line: s.startLine, symbol: s }));
+        const refs = this.referencesByTargetName.get(sym.name);
+        if (refs) {
+            const moduleByFile = new Map();
+            for (const ref of refs) {
+                if (ref.targetId !== symbolId || ref.sourceId !== null)
+                    continue;
+                const existing = moduleByFile.get(ref.file);
+                if (existing === undefined || ref.line < existing) {
+                    moduleByFile.set(ref.file, ref.line);
+                }
+            }
+            for (const [file, line] of moduleByFile) {
+                out.push({ file, line });
+            }
+        }
+        return out;
+    }
+    // Depth-N upstream blast radius. Walks the SAME cross-file caller-recovery
+    // path as find_references (getReferencesByNameOrAlias + isCallerOf),
+    // recursively. BFS so the node/breadth budget is spent on shallow,
+    // highest-relevance callers first. Depth-1 children are exactly the
+    // find_references caller set (grouped one node per caller symbol). The
+    // amplification defenses are described above the CallerTreeNode type.
+    getCallerTree(symbolId, opts = {}) {
+        const maxDepth = opts.maxDepth ?? DEFAULT_CALLER_TREE_DEPTH;
+        const maxBreadth = opts.maxBreadth ?? DEFAULT_CALLER_TREE_BREADTH;
+        const maxNodes = opts.maxNodes ?? DEFAULT_CALLER_TREE_NODES;
+        const includeWeak = opts.includeWeak ?? false;
+        const target = this.symbolById.get(symbolId);
+        if (!target) {
+            const missing = {
+                symbolId, name: symbolId, file: '', line: 0, kind: null, depth: 0,
+                strength: 'resolved', sites: [], confidence: 1, children: [],
+                isCycle: false, isModuleLevel: false, leafByPolicy: false,
+                depthCapped: false, truncatedChildren: 0,
+            };
+            return {
+                root: missing, totalNodes: 0, truncated: false,
+                limitations: CALLER_TREE_LIMITATIONS,
+            };
+        }
+        const root = {
+            symbolId: target.id, name: target.name, file: target.file,
+            line: target.startLine, kind: target.kind, depth: 0,
+            strength: 'resolved', sites: [], confidence: 1, children: [],
+            isCycle: false, isModuleLevel: false, leafByPolicy: false,
+            depthCapped: false, truncatedChildren: 0,
+        };
+        const cache = new Map();
+        let totalNodes = 0;
+        let truncated = false;
+        const queue = [
+            { node: root, symbol: target, ancestors: new Set([target.id]) },
+        ];
+        while (queue.length > 0) {
+            const frame = queue.shift();
+            if (!frame)
+                break;
+            const { node, symbol, ancestors } = frame;
+            if (node.depth >= maxDepth)
+                continue;
+            const refs = this.resolveDirectCallers(symbol, cache);
+            const groups = this.groupCallerRefs(refs, symbol);
+            // Build candidate child nodes, then sort strongest-first before caps.
+            const candidates = groups.map((g) => {
+                const childSym = g.sourceId !== null ? this.symbolById.get(g.sourceId) ?? null : null;
+                const earliest = g.sites.reduce((a, b) => (b.line < a.line ? b : a));
+                const confidence = node.confidence * EDGE_WEIGHT[g.strength] * DEPTH_DECAY;
+                const via = node.depth === 0 ? undefined : node.name;
+                const child = childSym
+                    ? {
+                        symbolId: childSym.id, name: childSym.name, file: childSym.file,
+                        line: childSym.startLine, kind: childSym.kind,
+                        depth: node.depth + 1, strength: g.strength, sites: g.sites,
+                        confidence, via, children: [], isCycle: false,
+                        isModuleLevel: false, leafByPolicy: false, depthCapped: false,
+                        truncatedChildren: 0,
+                    }
+                    : {
+                        // Module-level (or dangling sourceId): terminal leaf anchored at
+                        // the earliest call site. The renderer supplies the display
+                        // label from isModuleLevel — the index stays free of UI strings.
+                        symbolId: null, name: '', file: earliest.file, line: earliest.line,
+                        kind: null, depth: node.depth + 1, strength: g.strength,
+                        sites: g.sites, confidence, via, children: [], isCycle: false,
+                        isModuleLevel: true, leafByPolicy: false, depthCapped: false,
+                        truncatedChildren: 0,
+                    };
+                return { child, symbol: childSym };
+            });
+            candidates.sort((a, b) => b.child.confidence - a.child.confidence ||
+                STRENGTH_RANK[b.child.strength] - STRENGTH_RANK[a.child.strength] ||
+                (a.child.file < b.child.file ? -1 : a.child.file > b.child.file ? 1 : 0) ||
+                a.child.line - b.child.line);
+            let kept = candidates;
+            if (candidates.length > maxBreadth) {
+                node.truncatedChildren += candidates.length - maxBreadth;
+                truncated = true;
+                kept = candidates.slice(0, maxBreadth);
+            }
+            for (const { child, symbol: childSym } of kept) {
+                if (totalNodes >= maxNodes) {
+                    node.truncatedChildren += 1;
+                    truncated = true;
+                    continue;
+                }
+                const cyclic = child.symbolId !== null && ancestors.has(child.symbolId);
+                const atDepthWall = child.depth >= maxDepth;
+                // include_weak is the explicit "accept the noise" override: it expands
+                // every edge class AND bypasses the confidence floor (subject only to
+                // depth/cycle/node caps). The default path expands only the stronger
+                // classes above the floor, so one wrong weak edge can never fan out
+                // into a false subtree.
+                const policyOk = includeWeak || EXPANDABLE_BY_DEFAULT.has(child.strength);
+                const confOk = includeWeak || child.confidence >= MIN_EXPAND_CONFIDENCE;
+                const expandable = child.symbolId !== null && !cyclic && policyOk && confOk;
+                // Coherent partition for a non-cyclic real-symbol child:
+                //   not-expandable        -> leafByPolicy (weak edge class OR path
+                //                            confidence below the floor) at ANY depth,
+                //                            so include_weak is the actionable hint;
+                //   expandable at the wall -> depthCapped (only the depth limit stops
+                //                            it; "raise depth" is the hint);
+                //   expandable, room left  -> recursed (no flag).
+                // Module-level children (symbolId null) are terminal leaves handled by
+                // isModuleLevel and need no flag.
+                if (cyclic) {
+                    child.isCycle = true;
+                }
+                else if (!expandable && child.symbolId !== null) {
+                    child.leafByPolicy = true;
+                }
+                else if (expandable && atDepthWall) {
+                    child.depthCapped = true;
+                }
+                node.children.push(child);
+                totalNodes++;
+                if (expandable && !atDepthWall && childSym && child.symbolId) {
+                    queue.push({
+                        node: child,
+                        symbol: childSym,
+                        ancestors: new Set(ancestors).add(child.symbolId),
+                    });
+                }
+            }
+        }
+        return { root, totalNodes, truncated, limitations: CALLER_TREE_LIMITATIONS };
+    }
+    // Transitive blast radius (impact-set size) as a scalar — the same distinct
+    // counting impact.ts renders, shared via countDistinctCallers so the two
+    // surfaces agree. NOT tree.totalNodes, which double-counts a caller reached
+    // through several upstream branches (a DAG diamond).
+    getBlastRadius(symbolId, opts) {
+        const tree = this.getCallerTree(symbolId, opts);
+        const counts = countDistinctCallers(tree.root);
+        // Lower bound if EITHER a breadth/node cap fired OR the depth wall stopped
+        // expansion — the scalar can't carry impact's two distinct hints, so one `+`.
+        return {
+            callers: counts.callers,
+            files: counts.files,
+            depths: counts.depths,
+            truncated: tree.truncated || counts.depthCapped,
+        };
+    }
+    // Risk Hotspots: files ranked by churn × coupling × complexity (the
+    // CodeScene/Feathers intersection model — churny-but-decoupled and
+    // coupled-but-frozen both fall away — refined by the offender's complexity).
+    // Empty off-git (no churn signal). Hybrid for cost: rank a bounded candidate
+    // set by the O(1) cached fan-in, run the expensive transitive blast-radius
+    // walk only for the rows returned.
+    getRiskHotspots(limit = DEFAULT_RISK_HOTSPOTS) {
+        if (this.gitMetaState === null)
+            return [];
+        // Tie-break the candidate cut by path so the slice is deterministic across
+        // re-index orderings (getAllFiles is raw Map insertion order).
+        const candidates = this.getAllFiles()
+            .filter((f) => (f.commitFrequency ?? 0) > 0)
+            .sort((a, b) => (b.commitFrequency ?? 0) - (a.commitFrequency ?? 0) ||
+            a.path.localeCompare(b.path))
+            .slice(0, RISK_CANDIDATE_FILES);
+        if (candidates.length === 0)
+            return [];
+        // Per file the offender is its single highest-fan-in symbol (MAX, not sum:
+        // a file's risk is its most-coupled hub, not a pile of trivial helpers).
+        // Single pass — only the max is consumed.
+        const scored = [];
+        for (const f of candidates) {
+            let best = null;
+            let bestFanIn = 0;
+            for (const s of this.getSymbolsInFile(f.path)) {
+                const fanIn = this.getCallerCount(s.id);
+                if (fanIn > bestFanIn) {
+                    bestFanIn = fanIn;
+                    best = s;
+                }
+            }
+            if (best && bestFanIn > 0) {
+                scored.push({
+                    file: f.path,
+                    symbol: best,
+                    fanIn: bestFanIn,
+                    churn: f.commitFrequency ?? 0,
+                });
+            }
+        }
+        if (scored.length === 0)
+            return [];
+        // Product on a log scale (heavy-tailed counts), refined by the offender's
+        // complexity. No Math.max(...spread) anywhere — the ranking is a pure
+        // per-row product, so the RangeError guard that gitBoostMap needs does not
+        // apply here. Complexity enters as a bounded factor (1 + log1p(cx)) that is
+        // ALWAYS >= 1: it amplifies a gnarly hub but never zeroes a churny+coupled-
+        // but-simple one (the dominant case, since the offender is picked by fan-in
+        // with no regard for complexity), and degrades to the exact churn × coupling
+        // score when the offender is trivial (cx === 0 → factor 1). `cx` leads with
+        // cognitive (the human-effort signal) and falls back to cyclomatic-excess —
+        // a deliberate blend, NOT a clean single metric: keep the (1 + …) guard or a
+        // cog-0 offender (cyc >= 1 by construction so cx >= 0) re-zeroes the score.
+        // Computed before the slice so complexity participates in ranking for ALL
+        // scored candidates. Tie-break by file so equal-score rows order (and
+        // survive the limit slice) deterministically.
+        const rows = scored
+            .map((s) => {
+            let cx = s.symbol.cognitiveComplexity ?? 0;
+            if (cx === 0)
+                cx = (s.symbol.complexity ?? 1) - 1;
+            return {
+                ...s,
+                score: Math.log1p(s.churn) * Math.log1p(s.fanIn) * (1 + Math.log1p(cx)),
+            };
+        })
+            .sort((a, b) => b.score - a.score || a.file.localeCompare(b.file))
+            .slice(0, Math.max(0, limit));
+        // Expensive transitive walk ONLY for the displayed rows. The offender's raw
+        // complexity is reported for display (undefined-clean when absent); a less-
+        // coupled-but-more-complex symbol in the same file is intentionally NOT the
+        // offender — the row's identity is the file's most-coupled hub.
+        return rows.map((r) => ({
+            file: r.file,
+            symbol: r.symbol.name,
+            symbolId: r.symbol.id,
+            churn: r.churn,
+            fanIn: r.fanIn,
+            blast: this.getBlastRadius(r.symbol.id, { maxDepth: RISK_BLAST_DEPTH }),
+            complexity: r.symbol.complexity,
+            cognitiveComplexity: r.symbol.cognitiveComplexity,
+            score: r.score,
+        }));
+    }
+    // Filtered + memoized direct callers of `target` — the same candidate set
+    // find_references draws from (getReferencesByNameOrAlias + isCallerOf). The
+    // underlying caller set is identical, but the RENDERED cardinality can differ:
+    // the tree groups per caller symbol and caps breadth at
+    // DEFAULT_CALLER_TREE_BREADTH, while find_references lists per ref-site and
+    // caps weak member rows at WEAK_MEMBER_ROW_CAP.
+    resolveDirectCallers(target, cache) {
+        const hit = cache.get(target.id);
+        if (hit)
+            return hit;
+        const refs = this.getReferencesByNameOrAlias(target.name, target.file, isClassMember(target)).filter((r) => isCallerOf(r, target));
+        cache.set(target.id, refs);
+        return refs;
+    }
+    // Collapse caller refs into one group per caller symbol (or per file for
+    // module-level call sites): all call sites in `sites`, strongest edge wins.
+    groupCallerRefs(refs, target) {
+        const groups = new Map();
+        for (const ref of refs) {
+            const strength = this.edgeStrength(ref, target);
+            const key = ref.sourceId ?? `\0module:${ref.file}`;
+            let g = groups.get(key);
+            if (!g) {
+                g = { sourceId: ref.sourceId, sites: [], strength };
+                groups.set(key, g);
+            }
+            g.sites.push({ file: ref.file, line: ref.line });
+            if (STRENGTH_RANK[strength] > STRENGTH_RANK[g.strength]) {
+                g.strength = strength;
+            }
+        }
+        return [...groups.values()];
+    }
+    // Classify one caller edge by how strongly its source binds to `target`.
+    edgeStrength(ref, target) {
+        if (ref.targetId !== null)
+            return 'resolved';
+        const imports = this.importsByFile.get(ref.file) ?? [];
+        if (ref.receiver === undefined) {
+            if (fileImportsName(imports, target.name) ||
+                posix.dirname(ref.file) === posix.dirname(target.file)) {
+                return 'import-connected';
+            }
+            return 'name-match';
+        }
+        // An opaque (chained/computed) receiver can never name an import, so skip
+        // the guaranteed-false scan and weak-classify directly — the same
+        // short-circuit rankRefs applies, keeping the two classifiers in lockstep on
+        // the hot impact caller-tree path (chained capture makes opaque dominant).
+        return ref.receiver !== RECEIVER_OPAQUE && fileImportsReceiver(imports, ref.receiver)
+            ? 'import-connected'
+            : 'weak-member';
+    }
+    // Approximate caller count surfaced by find_symbol's `References: ~N`.
+    // Reference-granular: one count per call site / `new` / JSX usage.
+    // O(1) lookup against a lazily rebuilt cache — `find_symbol` calls
+    // this once per result, so a per-call walk would be O(results × files
+    // × imports). The full rebuild runs at most once between index updates.
+    getCallerCount(symbolId) {
+        this.rebuildCallerCountsIfDirty();
+        return this.callerCountById.get(symbolId) ?? 0;
+    }
+    getReferencesByName(name) {
+        const list = this.referencesByTargetName.get(name);
+        return list ? [...list] : [];
+    }
+    // Alias-aware: includes refs whose `targetName` is a local alias of `name`
+    // in the importing file (`import { name as alias }`; `alias()` site). The
+    // extractor records the call-site identifier, so plain by-name lookup misses
+    // these.
+    //
+    // When `targetFile` is provided, both alias refs AND unresolved primary
+    // refs are scoped by import resolution — preventing cross-file leakage
+    // when two files define a symbol with the same name. Within-file resolved
+    // refs (targetId !== null) flow through; the caller's `isCallerOf` filter
+    // rejects refs that precisely resolve to a different homonym.
+    getReferencesByNameOrAlias(name, targetFile, targetIsMember = false) {
+        const primary = this.referencesByTargetName.get(name) ?? [];
+        const filteredPrimary = targetFile === undefined
+            ? primary
+            : primary.filter((ref) => this.primaryRefMatchesTarget(ref, name, targetFile, targetIsMember));
+        const out = filteredPrimary.slice();
+        const seen = new Set(filteredPrimary);
+        this.rebuildAliasIndexIfDirty();
+        for (const entry of this.renamingAliasesByName.get(name) ?? []) {
+            const { filePath, sourceModule, alias } = entry;
+            if (targetFile !== undefined) {
+                const importingFile = this.fileByPath.get(filePath);
+                if (!importingFile)
+                    continue;
+                const resolved = this.resolveImportTarget(importingFile, sourceModule);
+                // Skip ONLY when the specifier resolves to a known different
+                // file. null (unresolvable specifier — TS path alias, workspace
+                // pkg, Python absolute import) falls through to best-effort
+                // include; same policy as primaryRefMatchesTarget.
+                if (resolved !== null && resolved !== targetFile)
+                    continue;
+            }
+            const aliasRefs = this.referencesByTargetName.get(alias);
+            if (!aliasRefs)
+                continue;
+            for (const ref of aliasRefs) {
+                if (ref.file !== filePath)
+                    continue;
+                // `obj.h()` where h happens to equal a local import alias —
+                // a member call's property never binds through a top-level
+                // import; only bare `h()` sites do.
+                if (ref.receiver !== undefined)
+                    continue;
+                if (seen.has(ref))
+                    continue;
+                seen.add(ref);
+                out.push(ref);
+            }
+        }
+        return out;
+    }
+    getSymbolById(id) {
+        return this.symbolById.get(id);
+    }
+    getImports(filePath) {
+        const list = this.importsByFile.get(filePath);
+        return list ? [...list] : [];
+    }
+    getStats() {
+        const filesByLanguage = {};
+        for (const fi of this.fileByPath.values()) {
+            filesByLanguage[fi.language] = (filesByLanguage[fi.language] ?? 0) + 1;
+        }
+        const symbolsByKind = zeroSymbolsByKind();
+        const entries = [];
+        for (const sym of this.symbolById.values()) {
+            symbolsByKind[sym.kind]++;
+            if (sym.exported && ENTRY_POINT_FILENAME_RE.test(basename(sym.file))) {
+                entries.push({ file: sym.file, symbol: sym.name, line: sym.startLine });
+            }
+        }
+        entries.sort((a, b) => a.file.localeCompare(b.file) || a.symbol.localeCompare(b.symbol));
+        return {
+            totalFiles: this.fileByPath.size,
+            totalSymbols: this.symbolById.size,
+            filesByLanguage,
+            symbolsByKind,
+            entryPoints: entries.slice(0, 20),
+        };
+    }
+    save(cachePath) {
+        return this.runLocked(async () => {
+            const allRefs = [];
+            for (const refs of this.referencesBySourceFile.values()) {
+                for (const ref of refs)
+                    allRefs.push(ref);
+            }
+            const data = {
+                version: SCHEMA_VERSION,
+                createdAt: Date.now(),
+                projectRoot: this.projectRoot,
+                symbols: [...this.symbolById.entries()],
+                files: [...this.fileByPath.entries()],
+                imports: [...this.importsByFile.entries()],
+                callees: adjacencyToEntries(this.callees),
+                callers: adjacencyToEntries(this.callers),
+                references: allRefs,
+                cochanges: [...this.cochangesByFile.entries()],
+                hotspots: [...this.hotspotList],
+                gitMeta: this.gitMetaState,
+            };
+            const json = JSON.stringify(data);
+            const tmp = `${cachePath}.tmp.${process.pid}.${Date.now()}`;
+            await fs.mkdir(dirname(cachePath), { recursive: true });
+            try {
+                const fh = await fs.open(tmp, 'w');
+                try {
+                    await fh.writeFile(json);
+                    await fh.sync();
+                }
+                finally {
+                    await fh.close();
+                }
+                try {
+                    await fs.rename(tmp, cachePath);
+                }
+                catch {
+                    // Windows can't rename over an existing file; retry after unlink.
+                    await fs.unlink(cachePath).catch(() => undefined);
+                    await fs.rename(tmp, cachePath);
+                }
+            }
+            catch (err) {
+                await fs.unlink(tmp).catch(() => undefined);
+                throw err;
+            }
+        });
+    }
+    async load(cachePath) {
+        await this.cleanupStaleTmp(cachePath);
+        let raw;
+        try {
+            raw = await fs.readFile(cachePath, 'utf8');
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code !== 'ENOENT') {
+                log.warn(`CodeIndex.load: failed to read cache at ${cachePath}: ${errMsg(err)}`);
+            }
+            return false;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            log.warn(`CodeIndex.load: cache is malformed at ${cachePath}; deleting`);
+            await fs.unlink(cachePath).catch(() => undefined);
+            return false;
+        }
+        if (!isValidPersisted(parsed, SCHEMA_VERSION)) {
+            log.warn(`CodeIndex.load: cache failed validation at ${cachePath}; deleting`);
+            await fs.unlink(cachePath).catch(() => undefined);
+            return false;
+        }
+        if (this.projectRoot && parsed.projectRoot !== this.projectRoot) {
+            log.warn(`CodeIndex.load: cache projectRoot mismatch (cache=${parsed.projectRoot}, ` +
+                `expected=${this.projectRoot}); deleting`);
+            await fs.unlink(cachePath).catch(() => undefined);
+            return false;
+        }
+        const symbolById = new Map();
+        const fileByPath = new Map();
+        const importsByFile = new Map();
+        const symbolsByName = new Map();
+        const symbolsByFile = new Map();
+        const callees = new Map();
+        const callers = new Map();
+        const referencesByTargetName = new Map();
+        const referencesBySourceFile = new Map();
+        const cochangesByFile = new Map();
+        const hotspotList = [];
+        try {
+            for (const [id, sym] of parsed.symbols)
+                symbolById.set(id, sym);
+            for (const [path, fi] of parsed.files)
+                fileByPath.set(path, fi);
+            for (const [path, imps] of parsed.imports)
+                importsByFile.set(path, imps);
+            for (const [src, targets] of parsed.callees)
+                callees.set(src, new Set(targets));
+            for (const [tgt, sources] of parsed.callers)
+                callers.set(tgt, new Set(sources));
+            for (const ref of parsed.references) {
+                if (!isPersistedReference(ref)) {
+                    throw new Error('persisted reference has invalid shape');
+                }
+                pushOrInit(referencesByTargetName, ref.targetName, ref);
+                pushOrInit(referencesBySourceFile, ref.file, ref);
+            }
+            for (const entry of parsed.cochanges) {
+                if (!Array.isArray(entry) ||
+                    typeof entry[0] !== 'string' ||
+                    !Array.isArray(entry[1]) ||
+                    !entry[1].every(isPersistedCoChange)) {
+                    throw new Error('persisted cochange entry has invalid shape');
+                }
+                cochangesByFile.set(entry[0], entry[1]);
+            }
+            for (const path of parsed.hotspots) {
+                if (typeof path !== 'string') {
+                    throw new Error('persisted hotspot entry has invalid shape');
+                }
+                hotspotList.push(path);
+            }
+            // Seed entries for zero-symbol files so removeFile's symsInFile guard fires (mirrors addFile).
+            for (const path of fileByPath.keys())
+                symbolsByFile.set(path, []);
+            for (const sym of symbolById.values()) {
+                pushOrInit(symbolsByName, sym.name, sym);
+                pushOrInit(symbolsByFile, sym.file, sym);
+            }
+        }
+        catch (err) {
+            log.warn(`CodeIndex.load: cache failed validation at ${cachePath} (${errMsg(err)}); deleting`);
+            await fs.unlink(cachePath).catch(() => undefined);
+            return false;
+        }
+        this.symbolById = symbolById;
+        this.fileByPath = fileByPath;
+        this.importsByFile = importsByFile;
+        this.symbolsByName = symbolsByName;
+        this.symbolsByFile = symbolsByFile;
+        this.callees = callees;
+        this.callers = callers;
+        this.referencesByTargetName = referencesByTargetName;
+        this.referencesBySourceFile = referencesBySourceFile;
+        this.cochangesByFile = cochangesByFile;
+        this.hotspotList = hotspotList;
+        this.gitMetaState = parsed.gitMeta;
+        // Derived caches: reset; rebuild*IfDirty repopulates lazily.
+        this.sortedNames = [];
+        this.sortedNamesLower = [];
+        this.searchIndex = null;
+        this.namesDirty = true;
+        this.callerCountById.clear();
+        this.callerCountsDirty = true;
+        this.aliasIndexDirty = true;
+        this.filePathsDirty = true;
+        return true;
+    }
+    async cleanupStaleTmp(cachePath) {
+        try {
+            const dir = dirname(cachePath);
+            const base = basename(cachePath);
+            const entries = await fs.readdir(dir);
+            const tmpPrefix = `${base}.tmp.`;
+            await Promise.all(entries
+                .filter((e) => e.startsWith(tmpPrefix))
+                .map((e) => fs.unlink(join(dir, e)).catch(() => undefined)));
+        }
+        catch {
+            // ignore: parent dir may not exist yet
+        }
+    }
+    rebuildIndexesIfDirty() {
+        if (!this.namesDirty)
+            return;
+        const names = [...this.symbolsByName.keys()];
+        const pairs = names.map((n) => [n, n.toLowerCase()]);
+        // Codepoint compare (not localeCompare) so sort order matches `lowerBound`'s `<`.
+        pairs.sort((a, b) => (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0));
+        this.sortedNames = pairs.map((p) => p[0]);
+        this.sortedNamesLower = pairs.map((p) => p[1]);
+        // All four fields are indexed so `searchSymbols` can match signatures
+        // and docstrings, but the DEFAULT search options pin `fields` to
+        // name+fqn — `suggest` (did-you-mean) must not surface doc-only hits.
+        // BM25 stats are per-field, so suggest's scores are unchanged by the
+        // extra indexed fields.
+        this.searchIndex = new MiniSearch({
+            fields: ['name', 'fqn', 'signature', 'doc'],
+            idField: 'id',
+            searchOptions: {
+                fields: ['name', 'fqn'],
+                fuzzy: 0.2,
+                prefix: true,
+                boost: { name: 2 },
+            },
+        });
+        this.searchIndex.addAll([...this.symbolById.values()]);
+        this.namesDirty = false;
+    }
+    rebuildCallerCountsIfDirty() {
+        if (!this.callerCountsDirty)
+            return;
+        this.callerCountById.clear();
+        // isCallerOf rejects every UNRESOLVED ref for short names, so the
+        // hot homonym buckets (`get`/`set`/`run` — mostly unresolved member
+        // calls) are pre-filtered to resolved refs ONCE per name instead of
+        // rescanned in full per same-named symbol. The predicate stays
+        // isCallerOf so counts can never desync from find_references' rows.
+        const resolvedShortRefs = new Map();
+        for (const sym of this.symbolById.values()) {
+            let count = 0;
+            if (sym.name.length < SHORT_NAME_THRESHOLD) {
+                let resolved = resolvedShortRefs.get(sym.name);
+                if (!resolved) {
+                    resolved = (this.referencesByTargetName.get(sym.name) ?? []).filter((r) => r.targetId !== null);
+                    resolvedShortRefs.set(sym.name, resolved);
+                }
+                for (const ref of resolved) {
+                    if (isCallerOf(ref, sym))
+                        count++;
+                }
+            }
+            else {
+                const refs = this.getReferencesByNameOrAlias(sym.name, sym.file, isClassMember(sym));
+                for (const ref of refs) {
+                    if (isCallerOf(ref, sym))
+                        count++;
+                }
+            }
+            // Skip zero-count entries — getCallerCount returns `?? 0`, so the
+            // observable behavior is identical and we save one Map slot per
+            // never-called helper (common for leaf utilities).
+            if (count > 0)
+                this.callerCountById.set(sym.id, count);
+        }
+        this.callerCountsDirty = false;
+    }
+    rebuildFilePathsIfDirty() {
+        if (!this.filePathsDirty)
+            return;
+        this.sortedFilePaths = [...this.fileByPath.keys()].sort();
+        this.filePathsDirty = false;
+    }
+    rebuildAliasIndexIfDirty() {
+        if (!this.aliasIndexDirty)
+            return;
+        this.renamingAliasesByName.clear();
+        for (const [filePath, imports] of this.importsByFile) {
+            for (const imp of imports) {
+                for (const named of imp.importedNames) {
+                    if (!named.alias || named.alias === named.name)
+                        continue;
+                    // Renaming type-only aliases (`import type { X as Y }`) are
+                    // erased at runtime; their alias-named call sites can't bind
+                    // through the import.
+                    if (!isValueBinding(named))
+                        continue;
+                    pushOrInit(this.renamingAliasesByName, named.name, {
+                        filePath,
+                        sourceModule: imp.sourceModule,
+                        alias: named.alias,
+                    });
+                }
+            }
+        }
+        this.aliasIndexDirty = false;
+    }
+    resolveIds(ids) {
+        if (!ids)
+            return [];
+        const out = [];
+        for (const id of ids) {
+            const sym = this.symbolById.get(id);
+            if (sym)
+                out.push(sym);
+        }
+        return out;
+    }
+    runLocked(work) {
+        const next = this.writeLock.then(work);
+        // Swallow rejections on the lock chain so one failed save doesn't block
+        // future ones; the original promise still rejects to the caller.
+        this.writeLock = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    // Decides whether a primary ref should be attributed to `targetFile`.
+    // Resolved refs (targetId !== null) always flow through — `isCallerOf`
+    // filters precise mismatches downstream. For unresolved refs the policy
+    // distinguishes four states of the source file's matching imports:
+    //
+    // - resolves to targetFile → include (precise match);
+    // - resolves to a different indexed file → drop (binds elsewhere);
+    // - matches but specifier is unresolvable (TS path alias, workspace
+    //   pkg, Python absolute) → fall through to best-effort include;
+    // - no matching import at all → drop. The bare `name()` call binds
+    //   to a parameter, local, nested-function, or global — attributing
+    //   it to every same-named export is wrong.
+    primaryRefMatchesTarget(ref, name, targetFile, targetIsMember) {
+        if (ref.targetId !== null)
+            return true;
+        if (ref.receiver !== undefined) {
+            return this.memberRefMatchesTarget(ref, ref.receiver, targetFile, targetIsMember);
+        }
+        const importingFile = this.fileByPath.get(ref.file);
+        if (!importingFile)
+            return true;
+        // Go: files of one package call each other's top-level functions with
+        // NO import statement (the no-matching-import drop below would hide
+        // every sibling-file caller — the dominant Go call pattern). One
+        // directory = one package, so a same-directory bare ref is attributed
+        // directly — but only to a top-level Go target: a bare Go identifier
+        // can never bind to a same-named TS/Python symbol that happens to share
+        // the directory, nor to a struct FIELD or other member (members are
+        // reachable only through a receiver). `_test` files share the directory
+        // and slip through; acceptable — they really do call the target.
+        if (!targetIsMember &&
+            importingFile.language === 'go' &&
+            this.fileByPath.get(targetFile)?.language === 'go' &&
+            posix.dirname(ref.file) === posix.dirname(targetFile)) {
+            return true;
+        }
+        const imports = this.importsByFile.get(ref.file) ?? [];
+        let hasUnresolvableMatch = false;
+        for (const imp of imports) {
+            for (const named of imp.importedNames) {
+                if (isWildcardImport(named)) {
+                    const resolved = this.resolveImportTarget(importingFile, imp.sourceModule);
+                    if (resolved === null) {
+                        hasUnresolvableMatch = true;
+                    }
+                    else if (resolved === targetFile) {
+                        return true;
+                    }
+                    continue;
+                }
+                const localName = named.alias ?? named.name;
+                if (localName !== name)
+                    continue;
+                if (!isValueBinding(named))
+                    continue;
+                // The local binding `name` is an alias for a different export.
+                // The alias loop attributes via resolveImportTarget; skip here
+                // so the ref isn't double-attributed to a same-named homonym.
+                if (isRenamingNamedAlias(named))
+                    return false;
+                const resolved = this.resolveImportTarget(importingFile, imp.sourceModule);
+                if (resolved === null) {
+                    hasUnresolvableMatch = true;
+                    continue;
+                }
+                if (resolved === targetFile)
+                    return true;
+                // Specifier resolves to a different indexed file: bare `name`
+                // binds elsewhere. JS/TS forbids duplicate top-level bindings,
+                // so no other matching import can change that.
+                return false;
+            }
+        }
+        return hasUnresolvableMatch;
+    }
+    // Scoping for unresolved member refs (`receiver.name()`). Deliberately
+    // asymmetric with the bare-name policy above: a bare `save()` with no
+    // matching import provably binds locally (drop), but `obj.save()` says
+    // nothing about where obj's class lives — and methods are unreachable
+    // by any other Phase-1 mechanism — so unknown receivers weakly include
+    // (recall over precision; isCallerOf and output labeling counterbalance).
+    // Module/namespace receivers ARE statically resolvable: `utils.foo()`
+    // binds to an export of whatever module `utils` names, so those admit
+    // or drop precisely.
+    memberRefMatchesTarget(ref, receiver, targetFile, targetIsMember) {
+        // An opaque (chained/computed) receiver can never name an import binding,
+        // so the scan below would always fall through to the weak include — skip
+        // it, matching rankRefs and edgeStrength (the sibling classifiers named in
+        // types.ts), which both short-circuit the same guaranteed-false scan for
+        // RECEIVER_OPAQUE. Keeps the three in lockstep on the hot per-call path
+        // (chained capture makes opaque the dominant member-ref shape).
+        if (receiver === RECEIVER_OPAQUE)
+            return true;
+        const importingFile = this.fileByPath.get(ref.file);
+        if (!importingFile)
+            return true;
+        for (const imp of this.importsByFile.get(ref.file) ?? []) {
+            for (const named of imp.importedNames) {
+                if ((named.alias ?? named.name) !== receiver)
+                    continue;
+                if (named.kind === 'namespace' || named.kind === 'module') {
+                    // Module-object access reaches only TOP-LEVEL exports —
+                    // `utils.save()` can never invoke `Cache.prototype.save`, so a
+                    // class-member target is out of reach through this binding.
+                    if (targetIsMember)
+                        return false;
+                    const resolved = this.resolveImportTarget(importingFile, moduleSpecifierFor(imp, named));
+                    if (resolved === null)
+                        return true; // path alias / absolute py — best effort
+                    return resolved === targetFile;
+                }
+                // Type-only bindings are erased at runtime; member access through
+                // them can't be a call into the target.
+                if (named.kind === 'type')
+                    return false;
+                // Value binding: the receiver is an object, and the defining file
+                // of its class is statically unknowable — weak include.
+                return true;
+            }
+        }
+        // Unknown receiver (local, parameter, field) — weak name-grade match.
+        return true;
+    }
+    // Returns the indexed file the specifier resolves to, or null if the
+    // specifier is unrecognized (TS path alias, workspace pkg, Python
+    // absolute import) or if no candidate is indexed. Picks the FIRST
+    // indexed candidate (direct match, then suffix candidates in
+    // language-specific order) — when the same stem is indexed under
+    // multiple extensions (`foo.ts` AND `foo.js`), this disambiguates to
+    // one. The candidate list and order come from `normalizeImportSpecifier`
+    // and depend on the importer's language and the specifier's explicit
+    // extension — see the *_CANDIDATES constants.
+    resolveImportTarget(importingFile, sourceModule) {
+        const norm = normalizeImportSpecifier(importingFile, sourceModule);
+        if (norm === null)
+            return null;
+        const baseDir = posix.dirname(importingFile.path);
+        const resolved = posix.join(baseDir, norm.specifier);
+        if (this.fileByPath.has(resolved))
+            return resolved;
+        for (const suffix of norm.candidates) {
+            const candidate = resolved + suffix;
+            if (this.fileByPath.has(candidate))
+                return candidate;
+        }
+        return null;
+    }
+}
+// Translates a raw import specifier into a POSIX relative path plus the
+// candidate-suffix order that should follow. Returns null for specifiers
+// that can't be resolved without project config (bare specifiers, TS path
+// aliases, Python absolute imports, bare-package Python imports like
+// `from . import x` whose target is reached via the imported NAME).
+function normalizeImportSpecifier(importingFile, sourceModule) {
+    // Python relative imports use dot-prefix syntax with no slashes:
+    // `.utils`, `..pkg.sub`. n leading dots = (n-1) levels up; remaining
+    // dots in the module path are package separators → '/'.
+    if (importingFile.language === 'python') {
+        const m = sourceModule.match(/^(\.+)(.*)$/);
+        if (!m)
+            return null;
+        const [, dots, rest] = m;
+        if (rest.length === 0)
+            return null;
+        const upParts = Array(dots.length - 1).fill('..');
+        return {
+            specifier: posix.join(...upParts, rest.replace(/\./g, '/')),
+            candidates: PY_CANDIDATES,
+        };
+    }
+    if (!sourceModule.startsWith('.'))
+        return null;
+    // JS importers can't resolve to TS source at runtime — keep explicit
+    // extensions exact so the resolution returns the actual JS file. The
+    // JS candidate list still includes `.ts/.tsx` as a fallback for the
+    // extensionless case (`./foo`) under allowJs/checkJs projects.
+    if (importingFile.language === 'javascript') {
+        return { specifier: sourceModule, candidates: JS_CANDIDATES };
+    }
+    // TS/TSX with `.jsx` specifier: Node16/NodeNext emits `.jsx` for `.tsx`
+    // source. Strip and use TS_FROM_JSX_CANDIDATES so `.tsx` wins over
+    // `.ts` at the same stem.
+    if (sourceModule.endsWith('.jsx')) {
+        return {
+            specifier: sourceModule.slice(0, -'.jsx'.length),
+            candidates: TS_FROM_JSX_CANDIDATES,
+        };
+    }
+    // TS/TSX with `.js` specifier: strip and use TS_FROM_JS_CANDIDATES so
+    // explicit `.js` siblings beat `.ts` at the same stem (hand-written JS
+    // in mixed repos), while still falling back to `.ts` when only the
+    // source is indexed (Node16/NodeNext emit case). `.mjs`/`.cjs` are
+    // literal JS targets — `endsWith('.js')` doesn't match them, so they
+    // fall through to direct match. Direct `.ts`/`.tsx` specifiers also
+    // fall through. (Add `.mts`/`.cts` to scanner + candidate lists if
+    // those source kinds are ever supported.)
+    if (sourceModule.endsWith('.js')) {
+        return {
+            specifier: sourceModule.slice(0, -'.js'.length),
+            candidates: TS_FROM_JS_CANDIDATES,
+        };
+    }
+    return { specifier: sourceModule, candidates: TS_CANDIDATES };
+}
+// Resolvable specifier for a module-object binding. Python's bare-dot form
+// (`from . import x`, `from .. import x`) binds the SUBMODULE x — the real
+// specifier is the dots plus the bound name; everything else (TS namespace
+// imports, Python `import a.b`) resolves by sourceModule directly. The
+// kind gate matters: a TS `import * as pkg from '.'` has named.name '*'
+// (the namespace sentinel), which must NOT be appended to the dots.
+function moduleSpecifierFor(imp, named) {
+    return named.kind === 'module' &&
+        /^\.+$/.test(imp.sourceModule) &&
+        named.name !== imp.sourceModule
+        ? `${imp.sourceModule}${named.name}`
+        : imp.sourceModule;
+}
+// `import { X as Y }` where X is a regular identifier (not default or
+// namespace) and X !== Y. The local binding Y points to export X — bare
+// `Y()` calls bind to X, so same-name scoping by Y would misattribute.
+function isRenamingNamedAlias(named) {
+    return (named.alias !== undefined &&
+        named.alias !== named.name &&
+        named.name !== IMPORT_DEFAULT &&
+        named.name !== IMPORT_NAMESPACE);
+}
+// Python `from .x import *` — `alias === undefined` distinguishes it from
+// TS `import * as ns from './x'`, which carries alias='ns' and exposes
+// member access only (bare callees don't bind through it).
+export function isWildcardImport(named) {
+    return named.name === IMPORT_NAMESPACE && named.alias === undefined;
+}
+// Bindings where bare `localName()` is a legitimate value-callable site.
+// kind='type' (TS `import type`), 'namespace' (TS `import * as ns`), and
+// 'module' (Python `import x` / `from . import x`) all bind something
+// that throws TypeError when invoked directly, so they shouldn't be
+// admitted as evidence that a bare call resolves through the import.
+// Absent kind defaults to 'value' for legacy persisted indexes.
+function isValueBinding(named) {
+    return named.kind === undefined || named.kind === 'value';
+}
+// Filters refs to those that should be surfaced as callers of `target`.
+// Used by both find_references's renderCallers and getCallerCount so the
+// rendered list and `References: ~N` always agree.
+export function isCallerOf(ref, target) {
+    // Recursion: target calling itself.
+    if (ref.sourceId === target.id)
+        return false;
+    // Homonym already resolved precisely to a different same-named symbol.
+    if (ref.targetId !== null && ref.targetId !== target.id)
+        return false;
+    if (ref.targetId === null) {
+        const isMember = ref.receiver !== undefined;
+        // Go package scope: a top-level name is unique within a package (one
+        // directory), so same-directory Go refs warrant two exceptions below —
+        // unexported MEMBERS are reachable package-wide, and a bare `Pairs{}`
+        // composite literal / `Pairs(x)` conversion can only mean THE type.
+        // Computed lazily: only the two carve-out branches consult it, and the
+        // dominant refs (exported members, bare function calls, short names)
+        // never reach them, so the dirname work is usually skipped.
+        const goSamePackage = () => target.language === 'go' &&
+            ref.file.endsWith('.go') &&
+            posix.dirname(ref.file) === posix.dirname(target.file);
+        // Self-receiver refs (extractor-determined: TS `this` node, Python
+        // self/cls) that extract-time resolution did NOT bind to a sibling
+        // method can only target an inherited method — LSP territory. An
+        // ordinary receiver merely NAMED `self` is not affected.
+        if (isMember && ref.selfReceiver)
+            return false;
+        // Bare-name matches never bind to method/interface/type — bare
+        // `save()` calls a top-level function, not `C.prototype.save`.
+        // Member matches (`obj.save()`) ARE evidence for methods — the point
+        // of member extraction — but still never for interface/type, which
+        // are never invoked at runtime. Go 'type'-kind symbols are the
+        // exception: a same-package BARE composite literal / conversion
+        // (`Pairs{}`, `Pairs(x)`) does target the type, and extract-time
+        // resolution covers same-file only.
+        if (NON_CALLABLE_KINDS.has(target.kind) &&
+            !(isMember && target.kind === 'method') &&
+            !(!isMember && target.kind === 'type' && goSamePackage())) {
+            return false;
+        }
+        // Short names like `do`/`is` (and `x.get()`/`x.set()`) flood with
+        // cross-file false matches; only count precisely-resolved refs.
+        if (target.name.length < SHORT_NAME_THRESHOLD)
+            return false;
+        // Cross-file member access can only reach exported targets. (Python
+        // exported-ness is the __all__/underscore heuristic, so legal
+        // `utils._helper()` access is filtered — accepted Phase-1 precision.)
+        // Go same-package siblings reach unexported MEMBERS (methods and
+        // func-typed fields) legally — the member analog of the same-package
+        // bare carve-out. Gated on the target actually being a member: a member
+        // ref (`x.foo()`) can never reach a top-level function or variable.
+        if (isMember &&
+            ref.file !== target.file &&
+            !target.exported &&
+            !(isClassMember(target) && goSamePackage())) {
+            return false;
+        }
+    }
+    return true;
+}
+export function isClassMember(s) {
+    return classNameFromFqn(s.fqn) !== null;
+}
+// Distinct transitive callers under a caller-tree root. Walks EVERY emitted
+// node (cycles included — shown once) and dedupes by symbolId, falling back to
+// `m:file:line` for module-level call sites (null symbolId). This is the exact
+// counting impact.ts renders ("N callers across D depths (F files)"), shared so
+// impact and the risk surface never diverge — and deduped, unlike
+// CallerTreeResult.totalNodes which double-counts DAG diamonds.
+export function countDistinctCallers(root) {
+    const callers = new Set();
+    const files = new Set();
+    const depths = new Set();
+    let depthCapped = false;
+    const walk = (node) => {
+        for (const child of node.children) {
+            callers.add(child.symbolId ?? `m:${child.file}:${child.line}`);
+            files.add(child.file);
+            depths.add(child.depth);
+            if (child.depthCapped)
+                depthCapped = true;
+            walk(child);
+        }
+    };
+    walk(root);
+    return { callers: callers.size, files: files.size, depths: depths.size, depthCapped };
+}
+// True when `imports` brings `name` into scope as a value binding the bare
+// call site could resolve to (named import, alias, or wildcard). Shared by
+// getCallerTree's edge classification and find_references' rankRefs so the
+// two stay in lockstep — a one-sided edit would desync impact's edge labels
+// from find_references' caller tiers.
+export function fileImportsName(imports, name) {
+    for (const imp of imports) {
+        for (const named of imp.importedNames) {
+            if (named.name === name || named.alias === name)
+                return true;
+            if (isWildcardImport(named))
+                return true;
+        }
+    }
+    return false;
+}
+// True when `receiver` names a namespace/module import in `imports` — the only
+// receiver bindings whose target module is statically resolvable. Shared with
+// find_references' rankRefs (see fileImportsName).
+export function fileImportsReceiver(imports, receiver) {
+    for (const imp of imports) {
+        for (const named of imp.importedNames) {
+            if (named.kind !== 'namespace' && named.kind !== 'module')
+                continue;
+            if ((named.alias ?? named.name) === receiver)
+                return true;
+        }
+    }
+    return false;
+}
+export function matchesKindScope(s, kind, scope) {
+    if (kind && s.kind !== kind)
+        return false;
+    if (!scope)
+        return true;
+    return scope.endsWith('/') ? s.file.startsWith(scope) : s.file === scope;
+}
+function pushOrInit(map, key, value) {
+    const list = map.get(key);
+    if (list)
+        list.push(value);
+    else
+        map.set(key, [value]);
+}
+function addAdjacency(map, key, value) {
+    let set = map.get(key);
+    if (!set) {
+        set = new Set();
+        map.set(key, set);
+    }
+    set.add(value);
+}
+function pruneAdjacency(map, deleted) {
+    for (const [key, set] of map) {
+        for (const id of deleted)
+            set.delete(id);
+        if (set.size === 0)
+            map.delete(key);
+    }
+}
+function adjacencyToEntries(map) {
+    const out = [];
+    for (const [k, set] of map)
+        out.push([k, [...set]]);
+    return out;
+}
+function lowerBound(arr, target) {
+    let lo = 0;
+    let hi = arr.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (arr[mid] < target)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+function isPersistedReference(ref) {
+    if (typeof ref !== 'object' || ref === null)
+        return false;
+    const r = ref;
+    return ((r.sourceId === null || typeof r.sourceId === 'string') &&
+        (r.targetId === null || typeof r.targetId === 'string') &&
+        typeof r.targetName === 'string' &&
+        typeof r.kind === 'string' &&
+        typeof r.file === 'string' &&
+        typeof r.line === 'number' &&
+        (r.receiver === undefined || typeof r.receiver === 'string') &&
+        (r.selfReceiver === undefined || typeof r.selfReceiver === 'boolean'));
+}
+function isPersistedCoChange(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const c = value;
+    return (typeof c.fileA === 'string' &&
+        typeof c.fileB === 'string' &&
+        typeof c.sharedCommits === 'number' &&
+        typeof c.confidenceAB === 'number' &&
+        typeof c.confidenceBA === 'number' &&
+        typeof c.lastSeen === 'number');
+}
+function isPersistedGitMeta(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const m = value;
+    return (typeof m.head === 'string' &&
+        typeof m.windowDays === 'number' &&
+        typeof m.analyzedAt === 'number');
+}
+function isValidPersisted(data, expectedVersion) {
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const d = data;
+    return (d.version === expectedVersion &&
+        typeof d.createdAt === 'number' &&
+        typeof d.projectRoot === 'string' &&
+        Array.isArray(d.symbols) &&
+        Array.isArray(d.files) &&
+        Array.isArray(d.imports) &&
+        Array.isArray(d.callees) &&
+        Array.isArray(d.callers) &&
+        Array.isArray(d.references) &&
+        Array.isArray(d.cochanges) &&
+        Array.isArray(d.hotspots) &&
+        (d.gitMeta === null || isPersistedGitMeta(d.gitMeta)));
+}