codegraph-java 0.1.0

package/dist/resolution/import-resolver.js

@@ -0,0 +1,2240 @@
+"use strict";
+/**
+ * Import Resolver
+ *
+ * Resolves import paths to actual files and symbols.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNixPathImportRef = isNixPathImportRef;
+exports.clearImportResolverMemos = clearImportResolverMemos;
+exports.resolveImportPath = resolveImportPath;
+exports.clearCppIncludeDirCache = clearCppIncludeDirCache;
+exports.loadCppIncludeDirs = loadCppIncludeDirs;
+exports.isPhpIncludePathRef = isPhpIncludePathRef;
+exports.isCobolCopybookRef = isCobolCopybookRef;
+exports.extractImportMappings = extractImportMappings;
+exports.clearImportMappingCache = clearImportMappingCache;
+exports.extractReExports = extractReExports;
+exports.resolveJvmImport = resolveJvmImport;
+exports.resolveViaImport = resolveViaImport;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const path_aliases_1 = require("./path-aliases");
+const workspace_packages_1 = require("./workspace-packages");
+const name_matcher_1 = require("./name-matcher");
+/**
+ * Extension resolution order by language
+ */
+const EXTENSION_RESOLUTION = {
+    typescript: ['.ts', '.tsx', '.d.ts', '.js', '.jsx', '/index.ts', '/index.tsx', '/index.js'],
+    // ArkTS imports both `.ets` components and plain `.ts` logic modules —
+    // HarmonyOS projects are always a mix. `/Index.ets` (capital I) is ohpm's
+    // module-entry convention, hit when a bare workspace import ("data") is
+    // rewritten to the member's directory; lowercase variants for safety.
+    arkts: ['.ets', '.ts', '.d.ts', '.js', '/Index.ets', '/index.ets', '/index.ts', '/index.js'],
+    javascript: ['.js', '.jsx', '.mjs', '.cjs', '.xsjs', '.xsjslib', '/index.js', '/index.jsx'],
+    tsx: ['.tsx', '.ts', '.d.ts', '.js', '.jsx', '/index.tsx', '/index.ts', '/index.js'],
+    jsx: ['.jsx', '.js', '/index.jsx', '/index.js'],
+    // SFC consumers import plain TS/JS, sibling components, and barrels
+    // (`./lib` → `./lib/index.ts`). Without a list, relative imports from a
+    // `.svelte`/`.vue` file resolve to nothing, so barrel callers vanish (#629).
+    svelte: ['.ts', '.js', '.svelte', '.tsx', '.jsx', '/index.ts', '/index.js', '/index.svelte'],
+    vue: ['.ts', '.js', '.vue', '.tsx', '.jsx', '/index.ts', '/index.js', '/index.vue'],
+    astro: ['.ts', '.js', '.astro', '.tsx', '.jsx', '/index.ts', '/index.js', '/index.astro'],
+    python: ['.py', '/__init__.py'],
+    go: ['.go'],
+    rust: ['.rs', '/mod.rs'],
+    java: ['.java'],
+    c: ['.h', '.c'],
+    cpp: ['.h', '.hpp', '.hxx', '.cpp', '.cc', '.cxx'],
+    csharp: ['.cs'],
+    php: ['.php'],
+    ruby: ['.rb'],
+    objc: ['.h', '.m', '.mm'],
+    nix: ['.nix', '/default.nix'],
+};
+function isNixPathImportRef(ref) {
+    return (ref.language === 'nix' &&
+        ref.referenceKind === 'imports' &&
+        (ref.referenceName.startsWith('./') || ref.referenceName.startsWith('../')) &&
+        !/[\s{}()[\];"'<>$]/.test(ref.referenceName));
+}
+/**
+ * Resolve an import path to an actual file
+ */
+// Per-context memos for the two hottest pure lookups on the resolution path:
+// import-specifier → file resolution and exported-symbol lookup. Both are pure
+// given a stable file set + node table, which is exactly the window between
+// ReferenceResolver.clearCaches() calls — clearImportResolverMemos() is invoked
+// there, so the staleness discipline matches the resolver's own caches.
+const importPathMemos = new WeakMap();
+const exportedSymbolMemos = new WeakMap();
+const DEFAULT_BINDING_KINDS = new Set(['function', 'class', 'component', 'constant', 'variable']);
+const DEFAULT_EXPORT_BINDING_RE = /^[ \t]*export\s+default\s+([A-Za-z_$][\w$]*)\s*;?[ \t]*$/m;
+const JS_FAMILY_FILE = /\.(?:[cm]?[jt]sx?)$/;
+/** The identifier `export default NAME` names in a JS-family file, or null. */
+function defaultExportBinding(filePath, context) {
+    if (!JS_FAMILY_FILE.test(filePath))
+        return null;
+    const source = context.readFile(filePath);
+    if (!source || !source.includes('export default'))
+        return null;
+    return source.match(DEFAULT_EXPORT_BINDING_RE)?.[1] ?? null;
+}
+const fileExportIndexes = new WeakMap();
+function getFileExportIndex(filePath, context) {
+    let perFile = fileExportIndexes.get(context);
+    if (!perFile) {
+        perFile = new Map();
+        fileExportIndexes.set(context, perFile);
+    }
+    let idx = perFile.get(filePath);
+    if (!idx) {
+        idx = { byName: new Map(), defaultComponent: undefined, defaultFnClass: undefined, defaultBinding: undefined };
+        const nodesInFile = context.getNodesInFile(filePath);
+        for (const n of nodesInFile) {
+            if (!n.isExported)
+                continue;
+            if (!idx.byName.has(n.name))
+                idx.byName.set(n.name, n);
+            if (idx.defaultComponent === undefined && n.kind === 'component')
+                idx.defaultComponent = n;
+            if (idx.defaultFnClass === undefined && (n.kind === 'function' || n.kind === 'class'))
+                idx.defaultFnClass = n;
+        }
+        const bound = defaultExportBinding(filePath, context);
+        if (bound !== null) {
+            idx.defaultBinding = nodesInFile
+                .filter((n) => n.name === bound && DEFAULT_BINDING_KINDS.has(n.kind))
+                .sort((a, b) => a.startLine - b.startLine || a.startColumn - b.startColumn)[0];
+        }
+        perFile.set(filePath, idx);
+    }
+    return idx;
+}
+/** Drop the per-context memo tables (see ReferenceResolver.clearCaches). */
+function clearImportResolverMemos(context) {
+    importPathMemos.delete(context);
+    exportedSymbolMemos.delete(context);
+    fileExportIndexes.delete(context);
+    luaFileBasenameIndexes.delete(context);
+    cobolCopybookIndexes.delete(context);
+}
+function resolveImportPath(importPath, fromFile, language, context) {
+    let memo = importPathMemos.get(context);
+    if (!memo) {
+        memo = new Map();
+        importPathMemos.set(context, memo);
+    }
+    const key = `${language}\0${fromFile}\0${importPath}`;
+    const hit = memo.get(key);
+    if (hit !== undefined || memo.has(key))
+        return hit ?? null;
+    const resolved = resolveImportPathUncached(importPath, fromFile, language, context);
+    memo.set(key, resolved);
+    return resolved;
+}
+function resolveImportPathUncached(importPath, fromFile, language, context) {
+    // COBOL COPY/EXEC SQL INCLUDE names a copybook member, not a path — the
+    // compiler searches a library, so we match against indexed file basenames.
+    // Must run before isExternalImport: a bare member name would otherwise be
+    // misclassified as an external package.
+    if (language === 'cobol') {
+        return resolveCobolCopybook(importPath, fromFile, context);
+    }
+    // Skip external/npm packages — but pass the context so the
+    // bare-specifier heuristic can consult the project's tsconfig
+    // alias map first (custom prefixes like `@components/*` would
+    // otherwise be misclassified as npm).
+    if (isExternalImport(importPath, language, context)) {
+        return null;
+    }
+    const projectRoot = context.getProjectRoot();
+    const fromDir = path.dirname(path.join(projectRoot, fromFile));
+    // Handle relative imports
+    if (importPath.startsWith('.')) {
+        return resolveRelativeImport(importPath, fromDir, language, context);
+    }
+    // Handle absolute/aliased imports (like @/ or src/)
+    const aliased = resolveAliasedImport(importPath, projectRoot, language, context);
+    if (aliased)
+        return aliased;
+    // C/C++ include directory search: when neither relative nor aliased
+    // resolution found a match, search -I directories from
+    // compile_commands.json or heuristic probing.
+    if (language === 'c' || language === 'cpp') {
+        return resolveCppIncludePath(importPath, language, context);
+    }
+    return null;
+}
+/**
+ * COBOL copybook lookup: `COPY CVACT01Y` (or `EXEC SQL INCLUDE X`) names a
+ * library member resolved by the compiler's copybook search path, so we match
+ * the member against indexed file basenames, case-insensitively. `.cpy` wins
+ * over a same-named program; a same-directory hit wins within a tier. The
+ * stem index is built once per resolution context (a per-ref scan of every
+ * file node would go quadratic on copybook-heavy repos).
+ */
+const cobolCopybookIndexes = new WeakMap();
+/**
+ * Per-context basename → file-paths index for Lua/Luau require resolution
+ * (cobolCopybookIndexes pattern). resolveLuaRequire previously ran
+ * `getAllFiles().filter(endsWith)` FOUR times per require ref — ~7.5k string
+ * suffix scans each, measured at ~0.9ms/ref (2.7s combined on kong's 3k
+ * requires). Buckets preserve getAllFiles() iteration order so the per-suffix
+ * candidate list filters to exactly the array the full scan produced —
+ * identical matches, identical stable sort, identical winner.
+ */
+const luaFileBasenameIndexes = new WeakMap();
+function luaBasenameIndex(context) {
+    let index = luaFileBasenameIndexes.get(context);
+    if (!index) {
+        index = new Map();
+        for (const f of context.getAllFiles()) {
+            const base = f.split('/').pop() ?? '';
+            const paths = index.get(base);
+            if (paths)
+                paths.push(f);
+            else
+                index.set(base, [f]);
+        }
+        luaFileBasenameIndexes.set(context, index);
+    }
+    return index;
+}
+function resolveCobolCopybook(member, fromFile, context) {
+    let index = cobolCopybookIndexes.get(context);
+    if (!index) {
+        index = new Map();
+        for (const fileNode of context.getNodesByKind('file')) {
+            const normalized = fileNode.filePath.replace(/\\/g, '/');
+            const base = normalized.split('/').pop() ?? '';
+            const dot = base.lastIndexOf('.');
+            const stem = (dot > 0 ? base.slice(0, dot) : base).toLowerCase();
+            const paths = index.get(stem);
+            if (paths)
+                paths.push(fileNode.filePath);
+            else
+                index.set(stem, [fileNode.filePath]);
+        }
+        cobolCopybookIndexes.set(context, index);
+    }
+    const candidates = index.get(member.toLowerCase());
+    if (!candidates || candidates.length === 0)
+        return null;
+    const fromDir = fromFile.replace(/\\/g, '/').split('/').slice(0, -1).join('/');
+    let best = null;
+    let bestScore = -1;
+    for (const candidate of candidates) {
+        const normalized = candidate.replace(/\\/g, '/');
+        const ext = normalized.slice(normalized.lastIndexOf('.')).toLowerCase();
+        let score = 0;
+        if (ext === '.cpy')
+            score += 4;
+        else if (ext === '.cbl' || ext === '.cob' || ext === '.cobol')
+            score += 2;
+        if (normalized.split('/').slice(0, -1).join('/') === fromDir)
+            score += 1;
+        if (score > bestScore) {
+            bestScore = score;
+            best = candidate;
+        }
+    }
+    return best;
+}
+/**
+ * C and C++ standard library header names (without delimiters).
+ * Used by isExternalImport to filter system includes from resolution.
+ */
+const C_CPP_STDLIB_HEADERS = new Set([
+    // C standard library headers
+    'assert.h', 'complex.h', 'ctype.h', 'errno.h', 'fenv.h', 'float.h',
+    'inttypes.h', 'iso646.h', 'limits.h', 'locale.h', 'math.h', 'setjmp.h',
+    'signal.h', 'stdalign.h', 'stdarg.h', 'stdatomic.h', 'stdbool.h',
+    'stddef.h', 'stdint.h', 'stdio.h', 'stdlib.h', 'stdnoreturn.h',
+    'string.h', 'tgmath.h', 'threads.h', 'time.h', 'uchar.h', 'wchar.h',
+    'wctype.h',
+    // C++ C-library wrappers (cname form)
+    'cassert', 'ccomplex', 'cctype', 'cerrno', 'cfenv', 'cfloat',
+    'cinttypes', 'ciso646', 'climits', 'clocale', 'cmath', 'csetjmp',
+    'csignal', 'cstdalign', 'cstdarg', 'cstdbool', 'cstddef', 'cstdint',
+    'cstdio', 'cstdlib', 'cstring', 'ctgmath', 'ctime', 'cuchar',
+    'cwchar', 'cwctype',
+    // C++ STL headers
+    'algorithm', 'any', 'array', 'atomic', 'barrier', 'bit', 'bitset',
+    'charconv', 'chrono', 'codecvt', 'compare', 'complex', 'concepts',
+    'condition_variable', 'coroutine', 'deque', 'exception', 'execution',
+    'expected', 'filesystem', 'format', 'forward_list', 'fstream',
+    'functional', 'future', 'generator', 'initializer_list', 'iomanip',
+    'ios', 'iosfwd', 'iostream', 'istream', 'iterator', 'latch',
+    'limits', 'list', 'locale', 'map', 'mdspan', 'memory', 'memory_resource',
+    'mutex', 'new', 'numbers', 'numeric', 'optional', 'ostream', 'print',
+    'queue', 'random', 'ranges', 'ratio', 'regex', 'scoped_allocator',
+    'semaphore', 'set', 'shared_mutex', 'source_location', 'span',
+    'spanstream', 'sstream', 'stack', 'stacktrace', 'stdexcept',
+    'stdfloat', 'stop_token', 'streambuf', 'string', 'string_view',
+    'strstream', 'syncstream', 'system_error', 'thread', 'tuple',
+    'type_traits', 'typeindex', 'typeinfo', 'unordered_map',
+    'unordered_set', 'utility', 'valarray', 'variant', 'vector',
+    'version',
+]);
+/**
+ * Check if an import is external (npm package, etc.)
+ *
+ * `context` is consulted for project-defined path aliases
+ * (tsconfig/jsconfig `paths`). Without that check, custom prefixes
+ * like `@components/*` would fail the bare-specifier heuristic and
+ * be classified as external before alias resolution can run.
+ */
+function isExternalImport(importPath, language, context) {
+    // Relative imports are not external
+    if (importPath.startsWith('.')) {
+        return false;
+    }
+    // Workspace-member imports (`@scope/ui`, `@scope/ui/widgets`) are LOCAL to
+    // a monorepo even though they look like bare npm specifiers. Consult the
+    // workspace map first so they aren't misclassified as external (#629). The
+    // map is null for single-package repos, so this is a no-op there.
+    const workspaces = context?.getWorkspacePackages?.();
+    if (workspaces && (0, workspace_packages_1.resolveWorkspaceImport)(importPath, workspaces)) {
+        return false;
+    }
+    // Common external patterns
+    if (language === 'typescript' || language === 'javascript' || language === 'tsx' || language === 'jsx' || language === 'arkts') {
+        // Node built-ins
+        if (['fs', 'path', 'os', 'crypto', 'http', 'https', 'url', 'util', 'events', 'stream', 'child_process', 'buffer'].includes(importPath)) {
+            return true;
+        }
+        // Project-defined alias prefix? Treat as local.
+        const aliases = context?.getProjectAliases?.();
+        if (aliases) {
+            for (const pat of aliases.patterns) {
+                if (importPath.startsWith(pat.prefix))
+                    return false;
+            }
+        }
+        // Scoped packages or bare specifiers that don't start with aliases
+        if (!importPath.startsWith('@/') && !importPath.startsWith('~/') && !importPath.startsWith('src/')) {
+            // Likely an npm package
+            return true;
+        }
+    }
+    if (language === 'python') {
+        // Standard library modules
+        const stdLibs = ['os', 'sys', 'json', 're', 'math', 'datetime', 'collections', 'typing', 'pathlib', 'logging'];
+        if (stdLibs.includes(importPath.split('.')[0])) {
+            return true;
+        }
+    }
+    if (language === 'go') {
+        // Relative imports (rare in idiomatic Go but the grammar allows them).
+        if (importPath.startsWith('.')) {
+            return false;
+        }
+        // In-module imports look like `<module-path>/sub/pkg` — local to
+        // this project. Without the module-path check we'd flag every
+        // cross-package call in a Go monorepo as external (issue #388).
+        const mod = context?.getGoModule?.();
+        if (mod && (importPath === mod.modulePath || importPath.startsWith(mod.modulePath + '/'))) {
+            return false;
+        }
+        // `internal/` packages stay local even when go.mod is missing —
+        // preserves the pre-#388 escape hatch for repos without a parsed module path.
+        if (importPath.includes('/internal/')) {
+            return false;
+        }
+        // Anything else is the Go standard library or a third-party module.
+        return true;
+    }
+    if (language === 'c' || language === 'cpp') {
+        // C/C++ standard library headers — both C-style (<stdio.h>) and
+        // C++-style (<cstdio>, <vector>) forms. Checked against the import
+        // path (which the extractor strips of <> or "" delimiters).
+        if (C_CPP_STDLIB_HEADERS.has(importPath))
+            return true;
+        // C++ headers without .h extension (e.g. "vector", "string")
+        const withoutExt = importPath.replace(/\.h$/, '');
+        if (C_CPP_STDLIB_HEADERS.has(withoutExt))
+            return true;
+    }
+    return false;
+}
+/**
+ * Resolve a relative import
+ */
+function resolveRelativeImport(importPath, fromDir, language, context) {
+    const projectRoot = context.getProjectRoot();
+    const extensions = EXTENSION_RESOLUTION[language] || [];
+    // Python dotted-relative imports (`from .certs import x`, `from ..pkg.mod
+    // import y`): leading dots are PACKAGE levels (1 = current package), and the
+    // remainder is a dotted submodule path. `path.resolve(dir, '.certs')` would
+    // treat `.certs` as a literal hidden filename, so translate the Python form
+    // to a real filesystem-relative path before resolving.
+    if (language === 'python' && importPath.startsWith('.')) {
+        const dots = importPath.length - importPath.replace(/^\.+/, '').length;
+        const up = '../'.repeat(Math.max(0, dots - 1)); // 1 dot = current dir
+        const rest = importPath.slice(dots).replace(/\./g, '/'); // 'sub.mod' -> 'sub/mod'
+        const pyBase = path.resolve(fromDir, up + rest);
+        const pyRel = path.relative(projectRoot, pyBase).replace(/\\/g, '/');
+        for (const ext of extensions) {
+            if (context.fileExists(pyRel + ext))
+                return pyRel + ext;
+        }
+        if (pyRel && context.fileExists(pyRel))
+            return pyRel;
+        return null;
+    }
+    // Try the path as-is first
+    const basePath = path.resolve(fromDir, importPath);
+    const relativePath = path.relative(projectRoot, basePath).replace(/\\/g, '/');
+    // Try each extension
+    for (const ext of extensions) {
+        const candidatePath = relativePath + ext;
+        if (context.fileExists(candidatePath)) {
+            return candidatePath;
+        }
+    }
+    // Try without extension (might already have one)
+    if (context.fileExists(relativePath)) {
+        return relativePath;
+    }
+    return null;
+}
+/**
+ * Resolve an aliased/absolute import.
+ *
+ * Tries, in order:
+ *   1. Project-defined `compilerOptions.paths` (tsconfig/jsconfig).
+ *      Each pattern can have multiple replacements; tried in tsconfig
+ *      priority order with extension permutations.
+ *   2. The legacy hard-coded fallback list (`@/`, `~/`, `src/`, ...)
+ *      for projects that have aliases but no tsconfig paths block.
+ *   3. Direct path lookup (with extensions).
+ */
+function resolveAliasedImport(importPath, projectRoot, language, context) {
+    const extensions = EXTENSION_RESOLUTION[language] || [];
+    const tryWithExt = (basePath) => {
+        for (const ext of extensions) {
+            const candidate = basePath + ext;
+            if (context.fileExists(candidate))
+                return candidate;
+        }
+        if (context.fileExists(basePath))
+            return basePath;
+        return null;
+    };
+    // 1. Project tsconfig/jsconfig paths.
+    const aliasMap = context.getProjectAliases?.();
+    if (aliasMap) {
+        const candidates = (0, path_aliases_1.applyAliases)(importPath, aliasMap, projectRoot);
+        for (const c of candidates) {
+            const hit = tryWithExt(c);
+            if (hit)
+                return hit;
+        }
+    }
+    // 1.5 Workspace packages (`@scope/ui/widgets` → `packages/ui/widgets`).
+    //     Resolves a monorepo member import to the member's directory; the
+    //     extension/index permutations below then find its barrel (#629).
+    const workspaces = context.getWorkspacePackages?.();
+    if (workspaces) {
+        const base = (0, workspace_packages_1.resolveWorkspaceImport)(importPath, workspaces);
+        if (base) {
+            const hit = tryWithExt(base);
+            if (hit)
+                return hit;
+        }
+    }
+    // 2. Hard-coded fallback list. Kept for projects that use these
+    //    conventional aliases without declaring them in tsconfig.
+    const fallbackAliases = {
+        '@/': 'src/',
+        '~/': 'src/',
+        '@src/': 'src/',
+        'src/': 'src/',
+        '@app/': 'app/',
+        'app/': 'app/',
+    };
+    for (const [alias, replacement] of Object.entries(fallbackAliases)) {
+        if (importPath.startsWith(alias)) {
+            const hit = tryWithExt(importPath.replace(alias, replacement));
+            if (hit)
+                return hit;
+        }
+    }
+    // 3. Direct path.
+    return tryWithExt(importPath);
+}
+/**
+ * C/C++ include directory cache (keyed by project root).
+ * Loaded once per resolver instance, shared across calls.
+ */
+const cppIncludeDirCache = new Map();
+/**
+ * Clear the C/C++ include directory cache (call between indexing runs)
+ */
+function clearCppIncludeDirCache() {
+    cppIncludeDirCache.clear();
+}
+/**
+ * Discover C/C++ include search directories for a project.
+ *
+ * Strategy:
+ * 1. Look for compile_commands.json (Clang compilation database) in the
+ *    project root and common build subdirectories. Parse -I and -isystem
+ *    flags from compiler commands.
+ * 2. If no compilation database is found, probe for common convention
+ *    directories (include/, src/, lib/, api/) and top-level directories
+ *    containing .h/.hpp files.
+ *
+ * Returns paths relative to projectRoot.
+ */
+function loadCppIncludeDirs(projectRoot) {
+    const cached = cppIncludeDirCache.get(projectRoot);
+    if (cached !== undefined)
+        return cached;
+    const dirs = loadCppIncludeDirsFromCompileDB(projectRoot)
+        || loadCppIncludeDirsHeuristic(projectRoot);
+    cppIncludeDirCache.set(projectRoot, dirs);
+    return dirs;
+}
+/**
+ * Try to load include directories from compile_commands.json.
+ * Returns null if no compilation database is found (so the heuristic
+ * fallback can run). Returns an array (possibly empty) otherwise.
+ */
+function loadCppIncludeDirsFromCompileDB(projectRoot) {
+    const candidates = [
+        path.join(projectRoot, 'compile_commands.json'),
+        path.join(projectRoot, 'build', 'compile_commands.json'),
+        path.join(projectRoot, 'cmake-build-debug', 'compile_commands.json'),
+        path.join(projectRoot, 'cmake-build-release', 'compile_commands.json'),
+        path.join(projectRoot, 'out', 'compile_commands.json'),
+    ];
+    let dbPath;
+    for (const c of candidates) {
+        try {
+            if (fs.existsSync(c)) {
+                dbPath = c;
+                break;
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    if (!dbPath)
+        return null;
+    try {
+        const content = fs.readFileSync(dbPath, 'utf-8');
+        const entries = JSON.parse(content);
+        if (!Array.isArray(entries))
+            return null;
+        const dirSet = new Set();
+        for (const entry of entries) {
+            const dir = entry.directory || projectRoot;
+            const args = entry.arguments || (entry.command ? shlexSplit(entry.command) : []);
+            for (let i = 0; i < args.length; i++) {
+                const arg = args[i];
+                let includeDir;
+                // -I<dir> (no space)
+                if (arg.startsWith('-I') && arg.length > 2) {
+                    includeDir = arg.substring(2);
+                }
+                // -isystem <dir> (space-separated)
+                else if ((arg === '-isystem' || arg === '-I') && i + 1 < args.length) {
+                    includeDir = args[i + 1];
+                    i++; // skip next arg
+                }
+                if (includeDir) {
+                    // Normalize: resolve relative to the compilation directory
+                    const absPath = path.isAbsolute(includeDir)
+                        ? includeDir
+                        : path.resolve(dir, includeDir);
+                    const relPath = path.relative(projectRoot, absPath).replace(/\\/g, '/');
+                    // Skip system directories and paths outside the project
+                    // (relative paths starting with .. or absolute paths like
+                    // /usr/include or C:\usr on Windows)
+                    if (!relPath.startsWith('..') && relPath.length > 0 && !path.isAbsolute(relPath)) {
+                        dirSet.add(relPath);
+                    }
+                }
+            }
+        }
+        return Array.from(dirSet);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Minimal shlex-style split for compiler command strings.
+ * Handles double-quoted and single-quoted arguments.
+ */
+function shlexSplit(cmd) {
+    const result = [];
+    let i = 0;
+    while (i < cmd.length) {
+        // Skip whitespace
+        while (i < cmd.length && /\s/.test(cmd[i]))
+            i++;
+        if (i >= cmd.length)
+            break;
+        const ch = cmd[i];
+        if (ch === '"') {
+            i++;
+            let arg = '';
+            while (i < cmd.length && cmd[i] !== '"') {
+                if (cmd[i] === '\\' && i + 1 < cmd.length) {
+                    i++;
+                    arg += cmd[i];
+                }
+                else {
+                    arg += cmd[i];
+                }
+                i++;
+            }
+            i++; // closing quote
+            result.push(arg);
+        }
+        else if (ch === "'") {
+            i++;
+            let arg = '';
+            while (i < cmd.length && cmd[i] !== "'") {
+                arg += cmd[i];
+                i++;
+            }
+            i++; // closing quote
+            result.push(arg);
+        }
+        else {
+            let arg = '';
+            while (i < cmd.length && !/\s/.test(cmd[i])) {
+                arg += cmd[i];
+                i++;
+            }
+            result.push(arg);
+        }
+    }
+    return result;
+}
+/**
+ * Heuristic include directory discovery when no compile_commands.json exists.
+ * Checks common convention directories and scans top-level dirs for headers.
+ */
+function loadCppIncludeDirsHeuristic(projectRoot) {
+    const dirs = [];
+    const conventionDirs = ['include', 'src', 'lib', 'api', 'inc'];
+    try {
+        const entries = fs.readdirSync(projectRoot, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const name = entry.name;
+            // Convention directories
+            if (conventionDirs.includes(name.toLowerCase())) {
+                dirs.push(name);
+                continue;
+            }
+            // Any top-level directory containing .h or .hpp files
+            try {
+                const subFiles = fs.readdirSync(path.join(projectRoot, name));
+                if (subFiles.some(f => /\.(h|hpp|hxx|hh)$/i.test(f))) {
+                    dirs.push(name);
+                }
+            }
+            catch {
+                // ignore permission errors
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return dirs;
+}
+/**
+ * Resolve a C/C++ include path by searching include directories.
+ * Called as a fallback after relative and aliased resolution fail.
+ */
+function resolveCppIncludePath(importPath, language, context) {
+    const includeDirs = context.getCppIncludeDirs?.() ?? [];
+    const extensions = EXTENSION_RESOLUTION[language] ?? [];
+    for (const dir of includeDirs) {
+        const normalizedDir = dir.replace(/\\/g, '/');
+        for (const ext of extensions) {
+            const candidate = normalizedDir + '/' + importPath + ext;
+            if (context.fileExists(candidate))
+                return candidate;
+        }
+        // Try as-is (already has extension)
+        const candidate = normalizedDir + '/' + importPath;
+        if (context.fileExists(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Is this reference a PHP include/require PATH (vs a namespace `use` symbol)?
+ *
+ * include/require emit a file path ("lib.php", "inc/db.php", "../x.php"),
+ * whereas namespace use is an FQN (App\Foo\Bar) or a bare class symbol
+ * (Closure). PHP identifiers contain neither '/' nor '.', so a slash or dot
+ * marks a path-shaped include. Such references resolve to files only — never
+ * to a same-named symbol — so callers must not fall back to the name-matcher.
+ */
+function isPhpIncludePathRef(ref) {
+    return (ref.language === 'php' &&
+        ref.referenceKind === 'imports' &&
+        (ref.referenceName.includes('/') || ref.referenceName.includes('.')));
+}
+/**
+ * Is this a COBOL COPY / EXEC SQL INCLUDE copybook reference? These resolve
+ * to files only (or stay unresolved for compiler-supplied members) — never
+ * to a same-named symbol via the name-matcher.
+ */
+function isCobolCopybookRef(ref) {
+    return ref.language === 'cobol' && ref.referenceKind === 'imports';
+}
+/**
+ * Resolve a PHP include/require path to a project-relative file path.
+ *
+ * PHP resolves includes relative to the including file's directory (the
+ * common case for procedural codebases); php.ini `include_path` is not
+ * modeled. Callers pass an already-extracted static literal path.
+ */
+function resolvePhpIncludePath(includePath, fromFile, context) {
+    const projectRoot = context.getProjectRoot();
+    const fromDir = path.dirname(path.join(projectRoot, fromFile));
+    const basePath = path.resolve(fromDir, includePath);
+    const relativePath = path.relative(projectRoot, basePath).replace(/\\/g, '/');
+    if (context.fileExists(relativePath))
+        return relativePath;
+    // The literal may omit the .php extension (e.g. include "config").
+    for (const ext of EXTENSION_RESOLUTION.php ?? []) {
+        if (context.fileExists(relativePath + ext))
+            return relativePath + ext;
+    }
+    return null;
+}
+/**
+ * Extract import mappings from a file
+ */
+function extractImportMappings(_filePath, content, language) {
+    const mappings = [];
+    if (language === 'typescript' || language === 'javascript' || language === 'tsx' || language === 'jsx' || language === 'arkts') {
+        mappings.push(...extractJSImports(content));
+    }
+    else if (language === 'svelte' || language === 'vue' || language === 'astro') {
+        // Svelte/Vue single-file components import via plain ES6 inside their
+        // `<script>` block (Astro: the `---` frontmatter). Without this, a
+        // `.svelte`/`.vue`/`.astro` consumer produces
+        // zero import mappings, so `resolveViaImport` can't run and a barrel
+        // import (`import { Foo } from './lib'`) falls back to name-matching —
+        // which silently fails whenever the re-export alias differs from the
+        // component's real name, yielding a false 0 callers (#629). The ES6
+        // import regex only matches `import … from '…'`, so running it over the
+        // whole SFC (markup + styles included) is safe.
+        mappings.push(...extractJSImports(content));
+    }
+    else if (language === 'python') {
+        mappings.push(...extractPythonImports(content));
+    }
+    else if (language === 'go') {
+        mappings.push(...extractGoImports(content));
+    }
+    else if (language === 'java' || language === 'kotlin') {
+        mappings.push(...extractJavaImports(content));
+    }
+    else if (language === 'php') {
+        mappings.push(...extractPHPImports(content));
+    }
+    else if (language === 'c' || language === 'cpp') {
+        mappings.push(...extractCppImports(content));
+    }
+    return mappings;
+}
+/**
+ * Extract JS/TS import mappings
+ */
+function extractJSImports(content) {
+    const mappings = [];
+    // ES6 imports
+    const importRegex = /import\s+(?:(\w+)\s*,?\s*)?(?:\{([^}]+)\})?\s*(?:(\*)\s+as\s+(\w+))?\s*from\s*['"]([^'"]+)['"]/g;
+    let match;
+    while ((match = importRegex.exec(content)) !== null) {
+        const [, defaultImport, namedImports, star, namespaceAlias, source] = match;
+        // Default import
+        if (defaultImport) {
+            mappings.push({
+                localName: defaultImport,
+                exportedName: 'default',
+                source: source,
+                isDefault: true,
+                isNamespace: false,
+            });
+        }
+        // Named imports
+        if (namedImports) {
+            const names = namedImports.split(',').map((s) => s.trim());
+            for (const name of names) {
+                const aliasMatch = name.match(/(\w+)\s+as\s+(\w+)/);
+                if (aliasMatch) {
+                    mappings.push({
+                        localName: aliasMatch[2],
+                        exportedName: aliasMatch[1],
+                        source: source,
+                        isDefault: false,
+                        isNamespace: false,
+                    });
+                }
+                else if (name) {
+                    mappings.push({
+                        localName: name,
+                        exportedName: name,
+                        source: source,
+                        isDefault: false,
+                        isNamespace: false,
+                    });
+                }
+            }
+        }
+        // Namespace import
+        if (star && namespaceAlias) {
+            mappings.push({
+                localName: namespaceAlias,
+                exportedName: '*',
+                source: source,
+                isDefault: false,
+                isNamespace: true,
+            });
+        }
+    }
+    // Require statements
+    const requireRegex = /(?:const|let|var)\s+(?:(\w+)|{([^}]+)})\s*=\s*require\(['"]([^'"]+)['"]\)/g;
+    while ((match = requireRegex.exec(content)) !== null) {
+        const [, defaultName, destructured, source] = match;
+        if (defaultName) {
+            mappings.push({
+                localName: defaultName,
+                exportedName: 'default',
+                source: source,
+                isDefault: true,
+                isNamespace: false,
+            });
+        }
+        if (destructured) {
+            const names = destructured.split(',').map((s) => s.trim());
+            for (const name of names) {
+                const aliasMatch = name.match(/(\w+)\s*:\s*(\w+)/);
+                if (aliasMatch) {
+                    mappings.push({
+                        localName: aliasMatch[2],
+                        exportedName: aliasMatch[1],
+                        source: source,
+                        isDefault: false,
+                        isNamespace: false,
+                    });
+                }
+                else if (name) {
+                    mappings.push({
+                        localName: name,
+                        exportedName: name,
+                        source: source,
+                        isDefault: false,
+                        isNamespace: false,
+                    });
+                }
+            }
+        }
+    }
+    return mappings;
+}
+/**
+ * Extract Python import mappings
+ */
+function extractPythonImports(content) {
+    const mappings = [];
+    // from X import Y
+    const fromImportRegex = /from\s+([\w.]+)\s+import\s+([^#\n]+)/g;
+    let match;
+    while ((match = fromImportRegex.exec(content)) !== null) {
+        const [, source, imports] = match;
+        const names = imports.split(',').map((s) => s.trim());
+        for (const name of names) {
+            const aliasMatch = name.match(/(\w+)\s+as\s+(\w+)/);
+            if (aliasMatch) {
+                mappings.push({
+                    localName: aliasMatch[2],
+                    exportedName: aliasMatch[1],
+                    source: source,
+                    isDefault: false,
+                    isNamespace: false,
+                });
+            }
+            else if (name && name !== '*') {
+                mappings.push({
+                    localName: name,
+                    exportedName: name,
+                    source: source,
+                    isDefault: false,
+                    isNamespace: false,
+                });
+            }
+        }
+    }
+    // import X
+    const importRegex = /^import\s+([\w.]+)(?:\s+as\s+(\w+))?/gm;
+    while ((match = importRegex.exec(content)) !== null) {
+        const [, source, alias] = match;
+        const localName = alias || source.split('.').pop();
+        mappings.push({
+            localName,
+            exportedName: '*',
+            source: source,
+            isDefault: false,
+            isNamespace: true,
+        });
+    }
+    return mappings;
+}
+/**
+ * Extract Go import mappings
+ */
+function extractGoImports(content) {
+    const mappings = [];
+    // import "path" or import alias "path"
+    const singleImportRegex = /import\s+(?:(\w+)\s+)?["']([^"']+)["']/g;
+    let match;
+    while ((match = singleImportRegex.exec(content)) !== null) {
+        const [, alias, source] = match;
+        const packageName = source.split('/').pop();
+        mappings.push({
+            localName: alias || packageName,
+            exportedName: '*',
+            source: source,
+            isDefault: false,
+            isNamespace: true,
+        });
+    }
+    // import ( ... ) block
+    const blockImportRegex = /import\s*\(\s*([^)]+)\s*\)/gs;
+    while ((match = blockImportRegex.exec(content)) !== null) {
+        const block = match[1];
+        const lineRegex = /(?:(\w+)\s+)?["']([^"']+)["']/g;
+        let lineMatch;
+        while ((lineMatch = lineRegex.exec(block)) !== null) {
+            const [, alias, source] = lineMatch;
+            const packageName = source.split('/').pop();
+            mappings.push({
+                localName: alias || packageName,
+                exportedName: '*',
+                source: source,
+                isDefault: false,
+                isNamespace: true,
+            });
+        }
+    }
+    return mappings;
+}
+/**
+ * Extract Java / Kotlin import mappings.
+ *
+ * Java/Kotlin imports carry the full qualified name of the imported
+ * symbol — `import com.example.dao.converter.FooConverter;` — which is
+ * exactly the disambiguation signal we need when two packages both
+ * declare a `FooConverter`. Pre-#314 the resolver had no Java branch
+ * here at all, so this mapping was empty and cross-module name
+ * collisions were resolved by file-path proximity (often wrongly).
+ *
+ * `import static com.example.Foo.bar;` is parsed as a local-name `bar`
+ * pointing at FQN `com.example.Foo.bar` so static-method call sites
+ * (`bar(...)`) can resolve through the same import lookup.
+ */
+function extractJavaImports(content) {
+    const mappings = [];
+    // Strip line and block comments so `// import foo;` doesn't false-match.
+    const stripped = content
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .replace(/\/\/[^\n]*/g, '');
+    // `import [static] <fqn>[.*];`
+    const re = /^\s*import\s+(static\s+)?([\w.]+(?:\.\*)?)\s*;/gm;
+    let match;
+    while ((match = re.exec(stripped)) !== null) {
+        const fqn = match[2];
+        // `import com.example.*;` — wildcard. We can't materialize a single
+        // local name; skip and let name-matching handle members reachable
+        // through the wildcard. (Future enhancement: enumerate package files.)
+        if (fqn.endsWith('.*'))
+            continue;
+        const parts = fqn.split('.');
+        const localName = parts[parts.length - 1];
+        if (!localName)
+            continue;
+        mappings.push({
+            localName,
+            exportedName: localName,
+            source: fqn,
+            isDefault: false,
+            isNamespace: false,
+        });
+    }
+    return mappings;
+}
+/**
+ * Extract PHP import mappings (use statements)
+ */
+function extractPHPImports(content) {
+    const mappings = [];
+    // use Namespace\Class; or use Namespace\Class as Alias;
+    const useRegex = /use\s+([\w\\]+)(?:\s+as\s+(\w+))?;/g;
+    let match;
+    while ((match = useRegex.exec(content)) !== null) {
+        const [, fullPath, alias] = match;
+        const className = fullPath.split('\\').pop();
+        mappings.push({
+            localName: alias || className,
+            exportedName: className,
+            source: fullPath,
+            isDefault: false,
+            isNamespace: false,
+        });
+    }
+    return mappings;
+}
+/**
+ * Extract C/C++ import mappings from #include directives.
+ *
+ * #include brings all symbols from the included header into scope
+ * (namespace import), so each mapping uses isNamespace: true and
+ * exportedName: '*'. The localName is set to the header's basename
+ * without extension so that symbol references like `MyClass` can
+ * match against any include that might provide it.
+ */
+function extractCppImports(content) {
+    const mappings = [];
+    // Match both #include <...> and #include "..."
+    const includeRegex = /^\s*#\s*include\s+[<"]([^>"]+)[>"]/gm;
+    let match;
+    while ((match = includeRegex.exec(content)) !== null) {
+        const modulePath = match[1];
+        // Basename without extension for localName matching
+        const basename = modulePath.split('/').pop().replace(/\.(h|hpp|hxx|hh|inl|ipp|cxx|cc|cpp)$/, '');
+        mappings.push({
+            localName: basename || modulePath,
+            exportedName: '*',
+            source: modulePath,
+            isDefault: false,
+            isNamespace: true,
+        });
+    }
+    return mappings;
+}
+// Cache import mappings per file to avoid re-reading and re-parsing
+const importMappingCache = new Map();
+/**
+ * Clear the import mapping cache (call between indexing runs)
+ */
+function clearImportMappingCache() {
+    importMappingCache.clear();
+    cppIncludeDirCache.clear();
+}
+/**
+ * Strip JS line + block comments from `content` while preserving
+ * string literals (so `"//"` inside a string stays intact). Used by
+ * {@link extractReExports} so commented-out export-from statements
+ * don't generate phantom re-export edges.
+ *
+ * Scanner is deliberately small: it only tracks the three contexts
+ * relevant for JS/TS — single-quote string, double-quote string, and
+ * template literal. Comment recognition is the JS spec subset, no
+ * regex-literal awareness (which is fine for our use case: we don't
+ * apply this to function bodies, only to top-level files).
+ */
+function stripJsComments(content) {
+    let out = '';
+    let i = 0;
+    let str = null;
+    while (i < content.length) {
+        const ch = content[i];
+        if (str !== null) {
+            out += ch;
+            if (ch === '\\' && i + 1 < content.length) {
+                out += content[i + 1];
+                i += 2;
+                continue;
+            }
+            if (ch === str)
+                str = null;
+            i++;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === '`') {
+            str = ch;
+            out += ch;
+            i++;
+            continue;
+        }
+        if (ch === '/' && content[i + 1] === '/') {
+            while (i < content.length && content[i] !== '\n')
+                i++;
+            continue;
+        }
+        if (ch === '/' && content[i + 1] === '*') {
+            i += 2;
+            while (i < content.length && !(content[i] === '*' && content[i + 1] === '/'))
+                i++;
+            i += 2;
+            continue;
+        }
+        out += ch;
+        i++;
+    }
+    return out;
+}
+/**
+ * Extract JS/TS re-export declarations from `content`.
+ *
+ * Recognised forms:
+ *   export { foo } from './a';
+ *   export { foo as bar } from './a';
+ *   export * from './a';
+ *   export * as ns from './a';   (treated as wildcard for chasing)
+ *   export { default as Foo } from './a';
+ *
+ * The walker intentionally stays regex-based — the import-resolver
+ * elsewhere in this file already chooses regex over a fresh
+ * tree-sitter pass, and this function shares that trade-off. Errors
+ * fall through silently; resolution simply skips the broken file.
+ */
+function extractReExports(content, language) {
+    if (language !== 'typescript' &&
+        language !== 'javascript' &&
+        language !== 'tsx' &&
+        language !== 'jsx' &&
+        language !== 'arkts') {
+        return [];
+    }
+    const out = [];
+    // Pre-strip block comments + line comments so a commented-out
+    // `// export { x } from '...'` doesn't produce a phantom edge.
+    // (Template literals are still a possible source of false positives;
+    // a project that builds export statements as runtime strings is
+    // out of scope.)
+    const cleaned = stripJsComments(content);
+    // Wildcard: `export * from '...'` or `export * as ns from '...'`
+    const wildcardRe = /export\s*\*(?:\s+as\s+\w+)?\s*from\s*['"]([^'"]+)['"]/g;
+    let m;
+    while ((m = wildcardRe.exec(cleaned)) !== null) {
+        out.push({ kind: 'wildcard', source: m[1] });
+    }
+    // Named: `export { a, b as c } from '...'`
+    const namedRe = /export\s*\{([^}]+)\}\s*from\s*['"]([^'"]+)['"]/g;
+    while ((m = namedRe.exec(cleaned)) !== null) {
+        const inner = m[1];
+        const source = m[2];
+        for (const raw of inner.split(',')) {
+            const item = raw.trim();
+            if (!item)
+                continue;
+            const aliasMatch = item.match(/^(\w+)\s+as\s+(\w+)$/);
+            if (aliasMatch) {
+                out.push({
+                    kind: 'named',
+                    exportedName: aliasMatch[2],
+                    originalName: aliasMatch[1],
+                    source,
+                });
+            }
+            else if (/^\w+$/.test(item)) {
+                out.push({
+                    kind: 'named',
+                    exportedName: item,
+                    originalName: item,
+                    source,
+                });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Resolve a reference using import mappings
+ */
+/**
+ * JVM (Java / Kotlin) imports use fully-qualified names (`import
+ * com.example.foo.Bar`) decoupled from filenames, so the JS/Python
+ * style filesystem path lookup misses them whenever the file isn't
+ * named after its primary symbol (Kotlin `Utils.kt` exporting `Bar`,
+ * top-level fns, extension fns). Resolve them through the
+ * `qualifiedName` index instead — populated by the package_header /
+ * package_declaration namespace wrappers in the extractor.
+ */
+function resolveJvmImport(ref, context) {
+    if (ref.referenceKind !== 'imports')
+        return null;
+    if (ref.language !== 'java' && ref.language !== 'kotlin')
+        return null;
+    const fqn = ref.referenceName;
+    const lastDot = fqn.lastIndexOf('.');
+    if (lastDot <= 0)
+        return null;
+    const pkg = fqn.substring(0, lastDot);
+    const sym = fqn.substring(lastDot + 1);
+    // Wildcard imports (`com.example.*`) deliberately punt to name-matcher.
+    if (sym === '*')
+        return null;
+    const candidates = context.getNodesByQualifiedName(`${pkg}::${sym}`);
+    if (candidates.length === 0)
+        return null;
+    // Kotlin Multiplatform: an `expect` declaration and its `actual`s share one
+    // FQN across source sets (commonMain / androidMain / appleMain). Taking the
+    // first candidate let a single platform `actual` absorb every common-side
+    // import, so the `expect` (the canonical API a commonMain file imports)
+    // looked unused. Prefer the candidate CLOSEST to the importing file by
+    // directory proximity — a commonMain import resolves to the commonMain
+    // declaration — with the `expect` side as a tiebreak.
+    const best = candidates.length === 1 ? candidates[0] : pickClosestJvmCandidate(candidates, ref.filePath);
+    return {
+        original: ref,
+        targetNodeId: best.id,
+        confidence: 0.95,
+        resolvedBy: 'import',
+    };
+}
+/**
+ * Pick the same-FQN candidate closest to `fromPath` by shared directory
+ * prefix, preferring an `expect` declaration on a tie. Used to keep a Kotlin
+ * Multiplatform `expect`/`actual` import resolving within the importer's own
+ * source set instead of an arbitrary platform `actual`.
+ */
+function pickClosestJvmCandidate(candidates, fromPath) {
+    const fromDirs = fromPath.split('/').slice(0, -1);
+    const sharedPrefix = (p) => {
+        const d = p.split('/').slice(0, -1);
+        let shared = 0;
+        for (let i = 0; i < Math.min(fromDirs.length, d.length); i++) {
+            if (fromDirs[i] === d[i])
+                shared++;
+            else
+                break;
+        }
+        return shared;
+    };
+    const isExpect = (n) => Array.isArray(n.decorators) && n.decorators.includes('expect');
+    let best = candidates[0];
+    let bestProx = sharedPrefix(best.filePath);
+    for (let i = 1; i < candidates.length; i++) {
+        const c = candidates[i];
+        const prox = sharedPrefix(c.filePath);
+        if (prox > bestProx || (prox === bestProx && isExpect(c) && !isExpect(best))) {
+            best = c;
+            bestProx = prox;
+        }
+    }
+    return best;
+}
+function resolveViaImport(ref, context) {
+    // C/C++ #include references — resolve directly to the included file
+    // (file→file edge), bypassing symbol lookup. The extractor emits these
+    // with `referenceKind: 'imports'` and `referenceName: <include path>`
+    // (e.g. "uint256.h" or "common/args.h"). Without this branch the
+    // include-dir scan path inside resolveImportPath never produces an
+    // edge — resolveViaImport's symbol lookup below would search the
+    // resolved file for a symbol named like the file extension and fail.
+    if ((ref.language === 'c' || ref.language === 'cpp') && ref.referenceKind === 'imports') {
+        // C/C++ quoted includes (`#include "X.h"`) resolve relative to the
+        // INCLUDING file's own directory first (the C standard's quoted-include
+        // search order). Prefer a same-directory header over an -I directory or a
+        // same-named header on another platform (windows/code/RNCAsyncStorage.h vs
+        // apple/.../RNCAsyncStorage.h) — the include-dir heuristic below would
+        // otherwise pick an arbitrary same-named header, leaving the real local one
+        // with no dependents.
+        const slash = ref.filePath.lastIndexOf('/');
+        const fromDir = slash >= 0 ? ref.filePath.slice(0, slash) : '';
+        const siblingPath = path.posix.normalize(fromDir ? `${fromDir}/${ref.referenceName}` : ref.referenceName);
+        const siblingBase = siblingPath.split('/').pop();
+        const sibling = context
+            .getNodesByName(siblingBase)
+            .find((n) => n.kind === 'file' && n.filePath === siblingPath);
+        if (sibling) {
+            return { original: ref, targetNodeId: sibling.id, confidence: 0.92, resolvedBy: 'import' };
+        }
+        const resolvedPath = resolveImportPath(ref.referenceName, ref.filePath, ref.language, context);
+        if (!resolvedPath)
+            return null;
+        const basename = resolvedPath.split('/').pop();
+        const fileNodes = context.getNodesByName(basename).filter((n) => n.kind === 'file');
+        const fileNode = fileNodes.find((n) => n.filePath === resolvedPath);
+        if (fileNode) {
+            return {
+                original: ref,
+                targetNodeId: fileNode.id,
+                confidence: 0.9,
+                resolvedBy: 'import',
+            };
+        }
+        return null;
+    }
+    // COBOL COPY / EXEC SQL INCLUDE — resolve the copybook member to a
+    // file→file edge, mirroring the C/C++ include branch above. A member that
+    // matches no indexed file (compiler-supplied copybooks like SQLCA/DFHAID)
+    // stays unresolved — callers must not fall back to the symbol name-matcher,
+    // which would connect it to a same-named import symbol elsewhere.
+    if (isCobolCopybookRef(ref)) {
+        const resolvedPath = resolveImportPath(ref.referenceName, ref.filePath, ref.language, context);
+        if (!resolvedPath)
+            return null;
+        const basename = resolvedPath.split('/').pop();
+        const fileNode = context
+            .getNodesByName(basename)
+            .find((n) => n.kind === 'file' && n.filePath === resolvedPath);
+        if (fileNode) {
+            return {
+                original: ref,
+                targetNodeId: fileNode.id,
+                confidence: 0.9,
+                resolvedBy: 'import',
+            };
+        }
+        return null;
+    }
+    // PHP include/require — resolve the static string path to a file→file
+    // edge, mirroring the C/C++ branch above. Distinguish include PATHS from
+    // namespace `use` symbols by shape: an include path contains a slash or a
+    // file extension ("lib.php", "inc/db.php", "../x.php"), whereas a namespace
+    // use is an FQN (App\Foo\Bar) or a bare class symbol (Closure) — PHP
+    // identifiers contain neither '/' nor '.'. Only path-shaped references are
+    // includes; symbol references fall through to the namespace resolution.
+    if (isPhpIncludePathRef(ref)) {
+        const resolvedPath = resolvePhpIncludePath(ref.referenceName, ref.filePath, context);
+        if (resolvedPath) {
+            const basename = resolvedPath.split('/').pop();
+            const fileNode = context
+                .getNodesByName(basename)
+                .find((n) => n.kind === 'file' && n.filePath === resolvedPath);
+            if (fileNode) {
+                return {
+                    original: ref,
+                    targetNodeId: fileNode.id,
+                    confidence: 0.9,
+                    resolvedBy: 'import',
+                };
+            }
+        }
+        // A path-shaped include that doesn't resolve to a known project file is a
+        // dead end. Return unresolved rather than falling through to the symbol
+        // name-matcher, which would mis-connect e.g. "inc/db.php" to an unrelated
+        // db.php elsewhere in the tree — a wrong edge is worse than a missing one.
+        return null;
+    }
+    // Nix static project-path imports (`import ./x.nix`, `builtins.import ./dir`,
+    // `import ./x.nix {}`) resolve to file nodes only. Do not resolve
+    // angle-bracket channels, attribute expressions, variables, or other dynamic
+    // expressions as project files.
+    if (isNixPathImportRef(ref)) {
+        const resolvedPath = resolveImportPath(ref.referenceName, ref.filePath, ref.language, context);
+        if (!resolvedPath)
+            return null;
+        const basename = resolvedPath.split('/').pop();
+        const fileNode = context
+            .getNodesByName(basename)
+            .find((n) => n.kind === 'file' && n.filePath === resolvedPath);
+        if (fileNode) {
+            return {
+                original: ref,
+                targetNodeId: fileNode.id,
+                confidence: 0.9,
+                resolvedBy: 'import',
+            };
+        }
+        return null;
+    }
+    // Use cached import mappings (avoids re-reading and re-parsing per ref)
+    const imports = context.getImportMappings(ref.filePath, ref.language);
+    if (imports.length === 0 && !context.readFile(ref.filePath)) {
+        return null;
+    }
+    // Go cross-package calls: `pkga.FuncX(...)` extracts to referenceName
+    // `pkga.FuncX` and the import `github.com/example/myproject/pkga`
+    // maps to a *package directory* containing one or more .go files.
+    // The generic file-based lookup below can't follow that — issue #388.
+    if (ref.language === 'go') {
+        const goResult = resolveGoCrossPackageReference(ref, imports, context);
+        if (goResult)
+            return goResult;
+    }
+    // Java / Kotlin: imports are FQNs (`import com.example.Foo;`) — no
+    // resolvable file path the JS/TS-style chain below could follow. Look
+    // up the symbol by name and filter to the candidate whose file path
+    // matches the imported FQN. This is the disambiguation signal that
+    // breaks the same-name class collision the path-proximity matcher
+    // can't resolve (issue #314).
+    if (ref.language === 'java' || ref.language === 'kotlin') {
+        const javaResult = resolveJavaImportedReference(ref, imports, context);
+        if (javaResult)
+            return javaResult;
+    }
+    // Python qualified access through an imported MODULE: `certs.where()` after
+    // `from . import certs`, `mod.func()` after `import mod`. The receiver names a
+    // submodule (a file), not a symbol, so the generic symbol lookup below would
+    // search the *package* for `certs` instead of looking inside the module.
+    if (ref.language === 'python') {
+        const pyResult = resolvePythonModuleMember(ref, imports, context);
+        if (pyResult)
+            return pyResult;
+        // Absolute dotted module import: `import conduit.apps.articles.signals`
+        // (the standard Django AppConfig.ready() signal-registration pattern, and
+        // any side-effect `import pkg.mod`). Map the dotted path to its file.
+        const pyModResult = resolvePythonAbsoluteModule(ref, context);
+        if (pyModResult)
+            return pyModResult;
+    }
+    // Rust qualified path: resolve the module prefix of `crate::m::Item` /
+    // `self::sub::Item` / `super::m::func` to a file, then find the leaf symbol in
+    // it. Disambiguates common-name `pub use self::read::read` re-exports that
+    // name-matching would land on the wrong same-named symbol.
+    if (ref.language === 'rust' && ref.referenceName.includes('::')) {
+        const rustResult = resolveRustPathReference(ref, context);
+        if (rustResult)
+            return rustResult;
+    }
+    // Lua / Luau `require(...)`: a dotted module path (`a.b.c` from
+    // `require("a.b.c")`) or an instance-path leaf (`Signal` from
+    // `require(script.Parent.Signal)`) — map it to a module file. There's no static
+    // import statement, so the generic path-matcher can't bridge the dot↔slash /
+    // leaf↔basename gap; resolve it explicitly to the module file.
+    if ((ref.language === 'lua' || ref.language === 'luau') && ref.referenceKind === 'imports') {
+        const luaResult = resolveLuaRequire(ref, context);
+        if (luaResult)
+            return luaResult;
+    }
+    // Whole-module / namespace imports → link the importing file to the module
+    // file. Python `from . import certs` / `import mod`, and TS/JS `import * as ns
+    // from './x'` (so a namespace touched only via a value-member read still
+    // records the dependency). A named TS/JS import returns null here and falls
+    // through to symbol resolution below.
+    if (ref.language === 'python' ||
+        ref.language === 'typescript' ||
+        ref.language === 'tsx' ||
+        ref.language === 'javascript' ||
+        ref.language === 'jsx' ||
+        ref.language === 'arkts') {
+        const moduleFile = resolveModuleImportToFile(ref, imports, context);
+        if (moduleFile)
+            return moduleFile;
+    }
+    // Check if the reference name matches any import
+    for (const imp of imports) {
+        if (imp.localName === ref.referenceName || ref.referenceName.startsWith(imp.localName + '.')) {
+            // Resolve the import path
+            const resolvedPath = resolveImportPath(imp.source, ref.filePath, ref.language, context);
+            if (resolvedPath) {
+                const exportedName = imp.isDefault ? 'default' : imp.exportedName;
+                const memberName = imp.isNamespace
+                    ? ref.referenceName.replace(imp.localName + '.', '')
+                    : null;
+                const targetNode = findExportedSymbol(resolvedPath, { isDefault: imp.isDefault, isNamespace: imp.isNamespace, exportedName, memberName }, ref.language, context, new Set());
+                if (targetNode) {
+                    // `Foo.bar()` / `Foo.CONST` — a NAMED (non-namespace) class import
+                    // accessed through a member. `findExportedSymbol` resolved `Foo` to
+                    // the class itself; descend into it so the reference links to the
+                    // member `bar`, not the class. Without this the edge points at the
+                    // class and `createEdges` then mis-promotes the call to an
+                    // `instantiates` edge, so the static method shows zero callers and a
+                    // hollow impact radius. (#825)
+                    if (!imp.isNamespace && ref.referenceName.startsWith(imp.localName + '.')) {
+                        const memberNode = resolveStaticMember(targetNode, ref, imp.localName, context);
+                        if (memberNode) {
+                            return {
+                                original: ref,
+                                targetNodeId: memberNode.id,
+                                confidence: 0.9,
+                                resolvedBy: 'import',
+                            };
+                        }
+                        // An imported object literal used as a namespace (#1573):
+                        // `api.call()` after `import { api } from './api'` where `api` is
+                        // `export const api = { call() {…} }`. Its members have bare
+                        // qualified names inside the constant's extent, so the
+                        // `Container::member` lookup above can't see them and the edge
+                        // landed on the constant — every cross-file caller of the method
+                        // went missing. Resolve the member by containment instead.
+                        if (targetNode.kind === 'constant' || targetNode.kind === 'variable') {
+                            const member = ref.referenceName.slice(imp.localName.length + 1).split('.')[0];
+                            if (member) {
+                                const literalMember = (0, name_matcher_1.resolveObjectLiteralMember)(targetNode, member, ref, context, 0.9, 'import');
+                                if (literalMember)
+                                    return literalMember;
+                                const aliasMember = resolveObjectLiteralAlias(targetNode, member, ref, context);
+                                if (aliasMember)
+                                    return aliasMember;
+                            }
+                        }
+                        // An imported VALUE (singleton constant / shared instance) called
+                        // through a member: `reproStore.notifyJoinGuildStatus()` after
+                        // `import { reproStore } from './store'`. findExportedSymbol
+                        // resolved the CONSTANT itself; linking the CALL there hides the
+                        // real callee — callers of the method miss every cross-file use
+                        // and the method can look unused (#1292). Infer the value's type
+                        // from its own declaration in the exporting file and resolve the
+                        // member on that type. resolveMethodOnType VALIDATES the type
+                        // declares the method, so a mis-inference falls through to the
+                        // constant edge below rather than fabricating a wrong one.
+                        const instanceMember = resolveImportedInstanceMember(targetNode, ref, imp.localName, context);
+                        if (instanceMember)
+                            return instanceMember;
+                    }
+                    return {
+                        original: ref,
+                        targetNodeId: targetNode.id,
+                        confidence: 0.9,
+                        resolvedBy: 'import',
+                    };
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Resolve a Python qualified reference whose receiver is an imported MODULE:
+ * `certs.where()` after `from . import certs`, `mod.func()` after `import mod`
+ * or `from pkg import mod`. The receiver names a submodule (a file), not a
+ * symbol, so the generic symbol lookup in `resolveViaImport` can't follow it —
+ * it would search the *package* for `certs`/`mod` instead of looking inside the
+ * module. This is the Python half of the cross-package qualified-call problem
+ * (cf. `resolveGoCrossPackageReference` for Go's `pkg.Func`, issue #388).
+ *
+ * Builds the module's dotted import path from the binding — `from . import
+ * certs` → `.certs`; `from pkg import mod` → `pkg.mod`; `import mod` → `mod` —
+ * resolves it to the module file, and finds the member defined there. Returns
+ * null when no module file exists at that path, so attribute access on an
+ * imported *value* (`helper.attr` where `helper` is a function) falls through
+ * to the other strategies untouched.
+ */
+function resolvePythonModuleMember(ref, imports, context) {
+    const dotIdx = ref.referenceName.indexOf('.');
+    if (dotIdx <= 0)
+        return null;
+    const receiver = ref.referenceName.substring(0, dotIdx);
+    // The immediate member of the module (first segment after the receiver).
+    const member = ref.referenceName.substring(dotIdx + 1).split('.')[0];
+    if (!member)
+        return null;
+    for (const imp of imports) {
+        if (imp.localName !== receiver)
+            continue;
+        // `import mod` / `import numpy as np` bind the module at `source` itself;
+        // `from . import certs` / `from pkg import mod` bind a SUBMODULE whose
+        // dotted path is the source joined with the imported name.
+        const modulePath = imp.isNamespace
+            ? imp.source
+            : imp.source.endsWith('.')
+                ? imp.source + imp.localName
+                : imp.source + '.' + imp.localName;
+        // resolveImportPath only maps RELATIVE dotted paths (`.mod`, `..pkg.mod`); an
+        // ABSOLUTE package path (`pkg.module` from `from pkg import module`, or a bare
+        // `import pkg.mod`) resolves to null there, so fall back to the dotted-module
+        // file lookup — the same asymmetry resolveModuleImportToFile already handles
+        // for the file→file import edge. Without this, a `module.func()` call after
+        // `from pkg import module` dropped its `calls` edge even though the import
+        // edge resolved (#578).
+        let resolvedPath = resolveImportPath(modulePath, ref.filePath, ref.language, context);
+        if (!resolvedPath) {
+            resolvedPath = findPythonModuleFile(modulePath, context, ref.filePath)?.filePath ?? null;
+        }
+        if (!resolvedPath || resolvedPath === ref.filePath)
+            continue;
+        // Find the member as a top-level definition in the module file. Exclude
+        // `method` so `mod.foo` never lands on a same-named class method.
+        const target = context.getNodesInFile(resolvedPath).find((n) => n.name === member &&
+            (n.kind === 'function' ||
+                n.kind === 'class' ||
+                n.kind === 'variable' ||
+                n.kind === 'constant'));
+        if (target) {
+            return { original: ref, targetNodeId: target.id, confidence: 0.85, resolvedBy: 'import' };
+        }
+    }
+    return null;
+}
+/**
+ * Resolve a whole-MODULE import to that module's file (a file→file dependency).
+ * The imported name is a module, not a symbol, so there's nothing to resolve to
+ * — but importing a module IS a dependency on it. Covers:
+ *   - Python submodule imports — `from . import certs`, `from pkg import sub`;
+ *   - namespace imports — Python `import mod` / `import numpy as np`, and
+ *     TS/JS `import * as ns from './x'`.
+ *
+ * It is also the robust backstop for {@link resolvePythonModuleMember} and for
+ * TS namespace usage: it records the dependency even when the used member is
+ * re-exported elsewhere (requests' `certs.where`, re-exported from `certifi`),
+ * the usage is module-level code that isn't extracted as a call, or a TS
+ * namespace is touched only via a value-member read (`ns.SOME_CONST`).
+ *
+ * Only fires for dot-free `imports`-kind refs whose module path resolves to a
+ * real file. A NAMED TS/JS import (`import { widget }`) is not a module, so it
+ * returns null and normal symbol resolution handles it.
+ */
+/**
+ * Resolve a Lua/Luau `require(...)` to its module file. The reference name is
+ * either a dotted module path (`telescope.config` → `telescope/config.lua`) or a
+ * Roblox instance-path leaf (`Signal` from `require(script.Parent.Signal)` →
+ * `Signal.luau`). We try `<path>.lua|.luau` and `<path>/init.lua|.luau`, matched
+ * by path suffix (the module root — `lua/`, `src/`, … — is project-specific).
+ * Among suffix matches, the one sharing the longest directory prefix with the
+ * requiring file wins (instance-path requires resolve within the same package).
+ */
+function resolveLuaRequire(ref, context) {
+    const name = ref.referenceName;
+    if (!name)
+        return null;
+    const base = name.includes('.') ? name.replace(/\./g, '/') : name;
+    const suffixes = [`${base}.lua`, `${base}.luau`, `${base}/init.lua`, `${base}/init.luau`];
+    const byBasename = luaBasenameIndex(context);
+    const shared = (a, b) => {
+        let i = 0;
+        while (i < a.length && i < b.length && a[i] === b[i])
+            i++;
+        return i;
+    };
+    for (const suffix of suffixes) {
+        // Only files sharing the suffix's basename can match — the bucket is in
+        // getAllFiles() order, so this filter yields exactly what the full-list
+        // scan did.
+        const candidates = byBasename.get(suffix.split('/').pop() ?? '') ?? [];
+        const matches = candidates.filter((f) => f === suffix || f.endsWith('/' + suffix));
+        if (matches.length === 0)
+            continue;
+        matches.sort((x, y) => shared(y, ref.filePath) - shared(x, ref.filePath));
+        const best = matches[0];
+        if (best === ref.filePath)
+            continue;
+        const fileNode = context.getNodesInFile(best).find((n) => n.kind === 'file');
+        if (fileNode) {
+            // Confidence ≥ 0.9 so this deterministic path/suffix match wins over
+            // name-matching, which otherwise resolves the require to the import node
+            // itself (a same-name self-match).
+            return { original: ref, targetNodeId: fileNode.id, confidence: 0.9, resolvedBy: 'import' };
+        }
+    }
+    return null;
+}
+/**
+ * `UploadApi.uploadARCapture()` where `UploadApi` is a NAMESPACE OBJECT — the
+ * default-export façade most React Native API layers are written as:
+ *
+ *   import { uploadARCapture } from './frames'
+ *   const UploadApi = { uploadARCapture, createFolder }
+ *   export default UploadApi
+ *
+ * The member is a shorthand (or `key: ident`) property whose value is a
+ * binding of the object's file, not a function defined inside the literal,
+ * so containment (`resolveObjectLiteralMember`) finds nothing and the call
+ * landed on the constant — every cross-file caller of the API function went
+ * missing. Read the literal's source, take the binding the member names, and
+ * resolve it where the object's file would: a symbol declared there, else
+ * through its own imports. Calls accept callable targets only.
+ */
+function resolveObjectLiteralAlias(container, member, ref, context) {
+    if (container.kind !== 'constant' && container.kind !== 'variable')
+        return null;
+    if (!JS_FAMILY_FILE.test(container.filePath))
+        return null;
+    if (!/^[A-Za-z_$][\w$]*$/.test(member))
+        return null;
+    const lines = context.getFileLines?.(container.filePath) ?? context.readFile(container.filePath)?.split('\n');
+    if (!lines)
+        return null;
+    const extent = lines.slice(container.startLine - 1, container.endLine).join('\n');
+    const brace = extent.indexOf('{');
+    if (brace < 0)
+        return null;
+    const body = extent.slice(brace);
+    const keyed = new RegExp(`[{,\\s]${member}\\s*:\\s*([A-Za-z_$][\\w$]*)\\s*[,}]`);
+    const shorthand = new RegExp(`[{,\\s]${member}\\s*[,}]`);
+    const k = body.match(keyed);
+    const binding = k ? k[1] : shorthand.test(body) ? member : null;
+    if (binding === null)
+        return null;
+    const callable = (n) => n.kind === 'function' || n.kind === 'method' || n.kind === 'class';
+    const accepts = ref.referenceKind === 'calls'
+        ? callable
+        : (n) => callable(n) || n.kind === 'constant' || n.kind === 'variable' || n.kind === 'component';
+    // Declared in the object's own file, outside the literal.
+    const local = context
+        .getNodesInFile(container.filePath)
+        .filter((n) => n.name === binding && n.id !== container.id && accepts(n))
+        .sort((a, b) => a.startLine - b.startLine || a.startColumn - b.startColumn)[0];
+    if (local)
+        return { original: ref, targetNodeId: local.id, confidence: 0.9, resolvedBy: 'import' };
+    // Imported into the object's file.
+    for (const imp of context.getImportMappings(container.filePath, container.language)) {
+        if (imp.localName !== binding || imp.isNamespace)
+            continue;
+        const resolvedPath = resolveImportPath(imp.source, container.filePath, container.language, context);
+        if (!resolvedPath)
+            continue;
+        const target = findExportedSymbol(resolvedPath, {
+            isDefault: imp.isDefault,
+            isNamespace: false,
+            exportedName: imp.isDefault ? 'default' : imp.exportedName,
+            memberName: null,
+        }, container.language, context, new Set());
+        if (target && accepts(target)) {
+            return { original: ref, targetNodeId: target.id, confidence: 0.9, resolvedBy: 'import' };
+        }
+    }
+    return null;
+}
+function resolveModuleImportToFile(ref, imports, context) {
+    if (ref.referenceKind !== 'imports')
+        return null;
+    if (ref.referenceName.includes('.'))
+        return null;
+    for (const imp of imports) {
+        if (imp.localName !== ref.referenceName)
+            continue;
+        let modulePath;
+        if (imp.isNamespace || imp.isDefault) {
+            // `import * as ns from './x'` (namespace) or `import x from './x'`
+            // (default) — the dependency is on the MODULE FILE. A default import binds
+            // a (possibly renamed) local to whatever the module's default export is
+            // (`import articlesController from './article.controller'` ← `export
+            // default router`), so the binding name can't be found as a symbol — link
+            // the file the import resolves to instead. External modules don't resolve
+            // (no file), so `import React from 'react'` creates no edge.
+            modulePath = imp.source;
+        }
+        else if (ref.language === 'python') {
+            // `from . import certs` — the imported NAME is a submodule of the source.
+            modulePath = imp.source.endsWith('.')
+                ? imp.source + imp.localName
+                : imp.source + '.' + imp.localName;
+        }
+        else {
+            // A named TS/JS import binds a symbol, not a module — leave it alone.
+            continue;
+        }
+        const resolvedPath = resolveImportPath(modulePath, ref.filePath, ref.language, context);
+        if (resolvedPath && resolvedPath !== ref.filePath) {
+            const fileNode = context.getNodesInFile(resolvedPath).find((n) => n.kind === 'file');
+            if (fileNode) {
+                return { original: ref, targetNodeId: fileNode.id, confidence: 0.9, resolvedBy: 'import' };
+            }
+        }
+        // Python absolute `from a.b import submodule` (a FastAPI router aggregator's
+        // `from app.api.routes import authentication`): resolveImportPath only maps
+        // RELATIVE dotted paths to a file, so resolve the absolute dotted module
+        // directly to its file node.
+        if (ref.language === 'python') {
+            const modFile = findPythonModuleFile(modulePath, context, ref.filePath);
+            if (modFile) {
+                return { original: ref, targetNodeId: modFile.id, confidence: 0.9, resolvedBy: 'import' };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Find the file node for a Python dotted module path `a.b.c` — a module file
+ * ending in `a/b/c.py`, or a package `a/b/c/__init__.py` (suffix-matched, so a
+ * package rooted under `src/` etc. still resolves). Returns null for
+ * stdlib/external modules (no matching repo file node), so `import os` creates
+ * no edge. Shared by absolute `import a.b.c` and absolute `from a.b import c`
+ * (where `c` is a submodule) resolution.
+ */
+function findPythonModuleFile(mod, context, excludeFilePath) {
+    if (!mod || mod.startsWith('.'))
+        return null; // relative imports handled elsewhere
+    const rel = mod.replace(/\./g, '/');
+    const lastSeg = mod.split('.').pop();
+    const endsWith = (p, want) => p === want || p.endsWith('/' + want);
+    const moduleFile = context
+        .getNodesByName(`${lastSeg}.py`)
+        .find((n) => n.kind === 'file' && n.filePath !== excludeFilePath && endsWith(n.filePath, `${rel}.py`));
+    if (moduleFile)
+        return moduleFile;
+    const pkgFile = context
+        .getNodesByName('__init__.py')
+        .find((n) => n.kind === 'file' && n.filePath !== excludeFilePath && endsWith(n.filePath, `${rel}/__init__.py`));
+    return pkgFile ?? null;
+}
+/**
+ * Resolve a Python ABSOLUTE dotted module import (`import a.b.c`) to its file —
+ * the Django `AppConfig.ready(): import myapp.signals` pattern and any
+ * side-effect module import.
+ */
+function resolvePythonAbsoluteModule(ref, context) {
+    if (ref.referenceKind !== 'imports')
+        return null;
+    // Only a DOTTED `import a.b.c` ref carries its full module path. A bare leaf
+    // (`from app.api.routes import authentication`) is ambiguous on its own — three
+    // `authentication.py` files may exist — so leave it to resolveModuleImportToFile,
+    // which uses the import's source (`app.api.routes`) to build the full path.
+    if (!ref.referenceName.includes('.'))
+        return null;
+    const hit = findPythonModuleFile(ref.referenceName, context, ref.filePath);
+    return hit ? { original: ref, targetNodeId: hit.id, confidence: 0.9, resolvedBy: 'import' } : null;
+}
+/**
+ * Resolve a Rust qualified reference `A::B::C` by mapping the MODULE prefix
+ * (`A::B`) to a file and finding the leaf symbol (`C`) in it. This is the Rust
+ * analog of {@link resolvePythonModuleMember} / {@link resolveGoCrossPackageReference}
+ * and the precise answer to common-name re-exports (`pub use self::read::read`)
+ * that name-matching can't disambiguate. Returns null when the prefix isn't a
+ * real module path (e.g. `Widget::new` — `Widget` is a struct, not a module),
+ * so associated-function calls and enum-variant paths fall through untouched.
+ */
+function resolveRustPathReference(ref, context) {
+    const segments = ref.referenceName.split('::').filter((s) => s.length > 0);
+    if (segments.length < 2)
+        return null;
+    const leaf = segments[segments.length - 1];
+    const modSegs = segments.slice(0, -1);
+    const file = resolveRustModuleFile(modSegs, ref.filePath, context);
+    if (!file || file === ref.filePath)
+        return null;
+    const target = context.getNodesInFile(file).find((n) => n.name === leaf &&
+        (n.kind === 'function' ||
+            n.kind === 'struct' ||
+            n.kind === 'union' ||
+            n.kind === 'enum' ||
+            n.kind === 'trait' ||
+            n.kind === 'type_alias' ||
+            n.kind === 'constant' ||
+            n.kind === 'method' ||
+            n.kind === 'class' ||
+            n.kind === 'interface'));
+    if (target) {
+        return { original: ref, targetNodeId: target.id, confidence: 0.9, resolvedBy: 'import' };
+    }
+    return null;
+}
+/** The crate-root directory (holds `lib.rs`/`main.rs`), walking up from a file. */
+function rustCrateRootDir(fromFileAbs, context) {
+    const projectRoot = context.getProjectRoot();
+    const toRel = (p) => path.relative(projectRoot, p).replace(/\\/g, '/');
+    let dir = path.dirname(fromFileAbs);
+    for (let i = 0; i < 64; i++) {
+        if (context.fileExists(toRel(path.join(dir, 'lib.rs'))) ||
+            context.fileExists(toRel(path.join(dir, 'main.rs')))) {
+            return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+/** Directory under which the current file's module declares its SUBMODULES. */
+function rustSelfModuleDir(fromFileAbs) {
+    const base = path.basename(fromFileAbs);
+    const dir = path.dirname(fromFileAbs);
+    // mod.rs / lib.rs / main.rs own their directory; `foo.rs`'s submodules live in `foo/`.
+    if (base === 'mod.rs' || base === 'lib.rs' || base === 'main.rs')
+        return dir;
+    return path.join(dir, base.replace(/\.rs$/, ''));
+}
+/**
+ * Resolve a Rust module path (segments WITHOUT the leaf symbol) to the file of
+ * the last module segment — `crate::a::b` → `<crate>/a/b.rs` (or `.../b/mod.rs`).
+ * Anchors on `crate` / `self` / `super`; a bare path is tried crate-relative.
+ */
+function resolveRustModuleFile(segments, fromFile, context) {
+    if (segments.length === 0)
+        return null;
+    const projectRoot = context.getProjectRoot();
+    const fromAbs = path.join(projectRoot, fromFile);
+    const toRel = (p) => path.relative(projectRoot, p).replace(/\\/g, '/');
+    // Walk a sequence of module segments down from `startDir`, mapping each to a
+    // `<seg>.rs` or `<seg>/mod.rs` file. Returns the leaf module's file, or null
+    // if `startDir` is null or any segment has no file on disk.
+    const resolveUnder = (startDir, rest) => {
+        if (!startDir)
+            return null;
+        let dir = startDir;
+        let targetFile = null;
+        for (const seg of rest) {
+            if (seg === 'self' || seg === 'crate' || seg === 'super')
+                continue;
+            const asFile = toRel(path.join(dir, seg + '.rs'));
+            const asMod = toRel(path.join(dir, seg, 'mod.rs'));
+            if (context.fileExists(asFile))
+                targetFile = asFile;
+            else if (context.fileExists(asMod))
+                targetFile = asMod;
+            else
+                return null;
+            dir = path.join(dir, seg);
+        }
+        return targetFile;
+    };
+    const first = segments[0];
+    if (first === 'crate') {
+        return resolveUnder(rustCrateRootDir(fromAbs, context), segments.slice(1));
+    }
+    if (first === 'self') {
+        return resolveUnder(rustSelfModuleDir(fromAbs), segments.slice(1));
+    }
+    if (first === 'super') {
+        let supers = 0;
+        while (segments[supers] === 'super')
+            supers++;
+        let dir = rustSelfModuleDir(fromAbs);
+        for (let s = 0; s < supers && dir; s++)
+            dir = path.dirname(dir);
+        return resolveUnder(dir, segments.slice(supers));
+    }
+    // Bare path. In expression position (`submodule::item()` — the router-assembly
+    // and general cross-module-call pattern) the prefix is a SUBMODULE of the
+    // current module, i.e. 2018 `self::`-relative — so try self-relative FIRST.
+    // Fall back to crate-relative for 2015-edition / crate-root items. External
+    // crate paths (`serde::de::Error`) miss both and fall through to name-matching.
+    return (resolveUnder(rustSelfModuleDir(fromAbs), segments) ??
+        resolveUnder(rustCrateRootDir(fromAbs, context), segments));
+}
+/**
+ * Resolve a Java/Kotlin reference whose receiver is the simple name of
+ * an imported FQN: `Foo.bar(...)` where `import com.example.Foo;`. The
+ * imported FQN converts to a file-path suffix (`com/example/Foo.java`
+ * or `.kt`) which uniquely identifies the right symbol when multiple
+ * classes share the same simple name.
+ *
+ * Also handles bare references to the imported class itself
+ * (`new Foo()` extraction emits `Foo` as a `references`/`instantiates`
+ * ref) and `import static <Foo>.bar` style imports of a single member.
+ */
+function resolveJavaImportedReference(ref, imports, context) {
+    if (imports.length === 0)
+        return null;
+    const ext = ref.language === 'kotlin' ? '.kt' : '.java';
+    for (const imp of imports) {
+        const matchesBare = imp.localName === ref.referenceName;
+        const matchesQualified = ref.referenceName.startsWith(imp.localName + '.');
+        if (!matchesBare && !matchesQualified)
+            continue;
+        // Convert FQN to a file-path suffix. `com.example.Foo` ->
+        // `com/example/Foo.java` (or `.kt`). The actual file may live
+        // under any source root (`src/main/java/`, `src/`, etc.), so match
+        // by suffix rather than exact path.
+        const fqnPath = imp.source.replace(/\./g, '/') + ext;
+        // Which symbol name to look up: the class itself, or a member.
+        const memberName = matchesBare
+            ? imp.localName
+            : ref.referenceName.substring(imp.localName.length + 1);
+        const candidates = context.getNodesByName(memberName);
+        for (const node of candidates) {
+            if (node.language !== ref.language)
+                continue;
+            const fp = node.filePath.replace(/\\/g, '/');
+            if (fp.endsWith(fqnPath) || fp.endsWith('/' + fqnPath)) {
+                return {
+                    original: ref,
+                    targetNodeId: node.id,
+                    confidence: 0.9,
+                    resolvedBy: 'import',
+                };
+            }
+        }
+        // `import static com.example.Foo.bar;` — the FQN's tail is the
+        // member name, the part before is the owner class. Look up the
+        // member named `<imp.localName>` (e.g. `bar`) and prefer the
+        // candidate whose file matches the parent FQN's path.
+        if (matchesBare) {
+            const dot = imp.source.lastIndexOf('.');
+            if (dot > 0) {
+                const ownerFqn = imp.source.substring(0, dot);
+                const ownerPath = ownerFqn.replace(/\./g, '/') + ext;
+                for (const node of candidates) {
+                    if (node.language !== ref.language)
+                        continue;
+                    const fp = node.filePath.replace(/\\/g, '/');
+                    if (fp.endsWith(ownerPath) || fp.endsWith('/' + ownerPath)) {
+                        return {
+                            original: ref,
+                            targetNodeId: node.id,
+                            confidence: 0.9,
+                            resolvedBy: 'import',
+                        };
+                    }
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Resolve a Go cross-package qualified reference (`pkga.FuncX`) by matching
+ * the package alias against an in-module import, stripping the module prefix
+ * to a project-relative directory, and locating the exported symbol in any
+ * `.go` file under that directory. Returns `null` for stdlib / third-party
+ * imports (no `go.mod`-relative match) so the rest of `resolveViaImport`
+ * can still try the file-based path.
+ */
+function resolveGoCrossPackageReference(ref, imports, context) {
+    const mod = context.getGoModule?.();
+    if (!mod)
+        return null;
+    // Qualified call: receiver before `.`, member after. A bare reference
+    // (no dot) is a same-file/in-package call — handled elsewhere.
+    const dotIdx = ref.referenceName.indexOf('.');
+    if (dotIdx <= 0)
+        return null;
+    const receiver = ref.referenceName.substring(0, dotIdx);
+    const memberName = ref.referenceName.substring(dotIdx + 1);
+    if (!memberName)
+        return null;
+    for (const imp of imports) {
+        if (imp.localName !== receiver)
+            continue;
+        // Only in-module imports map to a known directory.
+        if (imp.source !== mod.modulePath && !imp.source.startsWith(mod.modulePath + '/')) {
+            continue;
+        }
+        const pkgDir = imp.source === mod.modulePath
+            ? ''
+            : imp.source.substring(mod.modulePath.length + 1);
+        // Look up the member by name and pick the candidate whose file lives
+        // directly in the package directory. Match the immediate parent dir
+        // exactly so a call to `pkga.FuncX` doesn't accidentally land on a
+        // `FuncX` declared in `pkga/subpkg/`.
+        const candidates = context.getNodesByName(memberName);
+        for (const node of candidates) {
+            if (node.language !== 'go')
+                continue;
+            if (!node.isExported)
+                continue;
+            const fp = node.filePath.replace(/\\/g, '/');
+            const lastSlash = fp.lastIndexOf('/');
+            const fileDir = lastSlash >= 0 ? fp.substring(0, lastSlash) : '';
+            if (fileDir === pkgDir) {
+                return {
+                    original: ref,
+                    targetNodeId: node.id,
+                    confidence: 0.9,
+                    resolvedBy: 'import',
+                };
+            }
+        }
+    }
+    return null;
+}
+/** Recursive depth cap for re-export chain following. Real codebases
+ *  rarely chain barrels more than 2–3 deep; 8 is a generous safety
+ *  net that still bounds worst-case work. */
+const REEXPORT_MAX_DEPTH = 8;
+/**
+ * Find an exported symbol in `filePath`, following `export { x } from
+ * './other'` and `export * from './other'` chains until the original
+ * declaration is reached. Cycle-safe via the `visited` set.
+ *
+ * Without this, every barrel-style import (`import { Foo } from
+ * './index'` where `index.ts` only re-exports) used to resolve to
+ * nothing — the existing code only looked for declarations IN the
+ * resolved file, not declarations the file forwarded.
+ */
+function findExportedSymbol(filePath, want, language, context, visited, depth = 0) {
+    // Memoize fresh (top-level) lookups only: recursive re-export steps carry a
+    // populated `visited` set, whose contents change the reachable answer.
+    // Every ref to the same imported symbol repeats this exact walk, so the
+    // top-level memo removes the re-export chase + per-file linear scans from
+    // all but the first occurrence.
+    if (depth === 0 && visited.size === 0) {
+        let memo = exportedSymbolMemos.get(context);
+        if (!memo) {
+            memo = new Map();
+            exportedSymbolMemos.set(context, memo);
+        }
+        const key = `${filePath}\0${want.isDefault ? 1 : 0}${want.isNamespace ? 1 : 0}\0${want.exportedName}\0${want.memberName ?? ''}\0${language}`;
+        if (memo.has(key))
+            return memo.get(key);
+        const result = findExportedSymbolWalk(filePath, want, language, context, visited, depth);
+        memo.set(key, result);
+        return result;
+    }
+    return findExportedSymbolWalk(filePath, want, language, context, visited, depth);
+}
+function findExportedSymbolWalk(filePath, want, language, context, visited, depth) {
+    if (depth > REEXPORT_MAX_DEPTH)
+        return undefined;
+    if (visited.has(filePath))
+        return undefined;
+    visited.add(filePath);
+    const exportIndex = getFileExportIndex(filePath, context);
+    // 1. Direct hit: the symbol is declared in this file.
+    if (want.isDefault) {
+        // Svelte/Vue single-file components ARE the module's default export,
+        // but are extracted as kind 'component' (not function/class). Prefer
+        // the component node; fall back to an exported function/class for the
+        // `.ts`/`.tsx` `export default fn`/`class` case. Without the component
+        // branch, an `export { default as X } from './X.svelte'` barrel never
+        // resolves and the component shows a false 0 callers (#629).
+        // A component file IS its default export; otherwise the statement that
+        // names the binding beats the first-exported-function guess.
+        const direct = exportIndex.defaultComponent ?? exportIndex.defaultBinding ?? exportIndex.defaultFnClass;
+        if (direct)
+            return direct;
+    }
+    else if (want.isNamespace && want.memberName) {
+        const direct = exportIndex.byName.get(want.memberName);
+        if (direct)
+            return direct;
+    }
+    else {
+        const direct = exportIndex.byName.get(want.exportedName);
+        if (direct)
+            return direct;
+    }
+    // 2. Re-export hit: the file forwards the symbol to another module.
+    const reExports = context.getReExports?.(filePath, language) ?? [];
+    if (reExports.length === 0)
+        return undefined;
+    // Look for explicit `export { want } from './other'` (with optional rename).
+    const targetName = want.isDefault ? 'default' : want.exportedName;
+    for (const rex of reExports) {
+        if (rex.kind === 'named' && rex.exportedName === targetName) {
+            const next = resolveImportPath(rex.source, filePath, language, context);
+            if (!next)
+                continue;
+            // After rename: `export { foo as bar } from './x'` — to chase
+            // `bar`, we look for `foo` in `./x`.
+            const chained = findExportedSymbol(next, {
+                isDefault: rex.originalName === 'default',
+                isNamespace: false,
+                exportedName: rex.originalName,
+                memberName: null,
+            }, language, context, visited, depth + 1);
+            if (chained)
+                return chained;
+        }
+    }
+    // 3. Wildcard re-export: `export * from './other'` — try every
+    //    forwarding source. This is the barrel-of-barrels case.
+    for (const rex of reExports) {
+        if (rex.kind === 'wildcard') {
+            const next = resolveImportPath(rex.source, filePath, language, context);
+            if (!next)
+                continue;
+            const chained = findExportedSymbol(next, want, language, context, visited, depth + 1);
+            if (chained)
+                return chained;
+        }
+    }
+    return undefined;
+}
+/** Node kinds that own static members reachable as `Container.member`. */
+const STATIC_MEMBER_CONTAINERS = new Set([
+    'class', 'struct', 'union', 'interface', 'enum', 'trait', 'protocol',
+]);
+/**
+ * Resolve `Container.member` — a static method/property access on a NAMED class
+ * import (`import { Foo } …; Foo.bar()`) — to the member node, given the
+ * already-resolved container class.
+ *
+ * Members carry a `Container::member` qualifiedName, so we look up
+ * `${container.qualifiedName}::${member}` within the container's own file (the
+ * file filter disambiguates same-named classes in other modules). Returns
+ * undefined when the container isn't a member-owning kind or the member isn't
+ * found, so the caller falls back to the container itself (prior behavior) —
+ * languages whose members aren't `::`-qualified, and genuine class references,
+ * are unaffected. See #825.
+ */
+/**
+ * Resolve a CALL through an imported value to the method on the value's own
+ * type: `reproStore.notifyJoinGuildStatus()` where `reproStore` is
+ * `export const reproStore = new ReproStore()` in the imported file (#1292).
+ * The same-file form of this call already resolves via local-variable
+ * receiver inference (#1108); this is the cross-file/import half. The type is
+ * recovered from the VALUE'S OWN declaration lines in the exporting file
+ * (initializer `= new T(...)` or a type annotation, per the shared #1108
+ * pattern table), then the member is resolved AND VALIDATED on that type by
+ * resolveMethodOnType — a failed inference or validation returns null so the
+ * caller keeps its existing constant-edge behavior.
+ */
+function resolveImportedInstanceMember(value, ref, localName, context) {
+    if (ref.referenceKind !== 'calls')
+        return null;
+    if (value.kind !== 'constant' && value.kind !== 'variable')
+        return null;
+    const member = ref.referenceName.slice(localName.length + 1).split('.')[0];
+    if (!member)
+        return null;
+    const source = context.readFile(value.filePath);
+    if (!source)
+        return null;
+    // Only the value's own declaration lines — never the whole file, so a
+    // same-named identifier elsewhere can't donate a type.
+    const lines = source.split('\n');
+    const declSlice = lines.slice(Math.max(0, value.startLine - 1), value.endLine).join('\n');
+    const receiver = value.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    for (const pattern of (0, name_matcher_1.localReceiverTypePatterns)(value.language, receiver)) {
+        const m = declSlice.match(pattern);
+        if (!m || !m[1])
+            continue;
+        const typeName = (0, name_matcher_1.normalizeInferredTypeName)(m[1]);
+        if (!typeName)
+            continue;
+        const resolved = (0, name_matcher_1.resolveMethodOnType)(typeName, member, ref, context, 0.85, 'instance-method');
+        if (resolved)
+            return resolved;
+    }
+    return null;
+}
+function resolveStaticMember(container, ref, localName, context) {
+    if (!STATIC_MEMBER_CONTAINERS.has(container.kind))
+        return undefined;
+    // First segment after the receiver: `Foo.bar.baz` → `bar`.
+    const member = ref.referenceName.slice(localName.length + 1).split('.')[0];
+    if (!member)
+        return undefined;
+    const candidates = context
+        .getNodesByQualifiedName(`${container.qualifiedName}::${member}`)
+        .filter((n) => n.filePath === container.filePath);
+    if (candidates.length === 0)
+        return undefined;
+    // When the reference is a call, prefer a callable member if several nodes
+    // share the qualifiedName (e.g. a static property and a method).
+    if (ref.referenceKind === 'calls') {
+        const callable = candidates.find((n) => n.kind === 'method' || n.kind === 'function');
+        if (callable)
+            return callable;
+    }
+    return candidates[0];
+}
+//# sourceMappingURL=import-resolver.js.map