ucn 3.8.25 → 4.0.0

package/core/confidence.js

@@ -9,24 +9,56 @@
 
 // Resolution types ordered from most to least confident
 const RESOLUTION = {
-    EXACT_BINDING:  'exact-binding',
-    SAME_CLASS:     'same-class',
-    RECEIVER_HINT:  'receiver-hint',
-    SCOPE_MATCH:    'scope-match',
-    NAME_ONLY:      'name-only',
-    UNCERTAIN:      'uncertain',
+    EXACT_BINDING:    'exact-binding',
+    SAME_CLASS:       'same-class',
+    RECEIVER_HINT:    'receiver-hint',
+    SCOPE_MATCH:      'scope-match',
+    POSSIBLE_DISPATCH: 'possible-dispatch',
+    NAME_ONLY:        'name-only',
+    METHOD_AMBIGUOUS: 'method-ambiguous',
+    UNCERTAIN:        'uncertain',
 };
 
 // Seed scores per resolution type (tunable)
 const SCORES = {
-    [RESOLUTION.EXACT_BINDING]:  0.98,
-    [RESOLUTION.SAME_CLASS]:     0.92,
-    [RESOLUTION.RECEIVER_HINT]:  0.80,
-    [RESOLUTION.SCOPE_MATCH]:    0.65,
-    [RESOLUTION.NAME_ONLY]:      0.40,
-    [RESOLUTION.UNCERTAIN]:      0.25,
+    [RESOLUTION.EXACT_BINDING]:    0.98,
+    [RESOLUTION.SAME_CLASS]:       0.92,
+    [RESOLUTION.RECEIVER_HINT]:    0.80,
+    [RESOLUTION.SCOPE_MATCH]:      0.65,
+    [RESOLUTION.POSSIBLE_DISPATCH]: 0.50,
+    [RESOLUTION.NAME_ONLY]:        0.40,
+    [RESOLUTION.METHOD_AMBIGUOUS]: 0.35,
+    [RESOLUTION.UNCERTAIN]:        0.25,
 };
 
+// Trust tiers for the tiered caller contract. CONFIRMED = the resolution
+// rests on binding/receiver/import evidence; UNVERIFIED = name match without
+// evidence. The mapping is resolution-based, never language-based — evidence
+// flags already come from langTraits dispatch in callers.js, so every
+// language gets correct tiers automatically.
+const TIER = { CONFIRMED: 'confirmed', UNVERIFIED: 'unverified' };
+const RESOLUTION_TIER = {
+    [RESOLUTION.EXACT_BINDING]: TIER.CONFIRMED,
+    [RESOLUTION.SAME_CLASS]:    TIER.CONFIRMED,
+    [RESOLUTION.RECEIVER_HINT]: TIER.CONFIRMED,
+    // scope-match is only assigned with import/receiver/callback evidence
+    // (see scoreEdge below) — that satisfies the contract's evidence clause.
+    [RESOLUTION.SCOPE_MATCH]:   TIER.CONFIRMED,
+    // Nominal dispatch tiering: a call that CAN reach the target through
+    // virtual dispatch (interface/supertype-typed receiver) or whose untyped
+    // receiver faces multiple same-name owners is evidence a call happens —
+    // not evidence it reaches THIS definition. Unverified by construction.
+    [RESOLUTION.POSSIBLE_DISPATCH]: TIER.UNVERIFIED,
+    [RESOLUTION.NAME_ONLY]:     TIER.UNVERIFIED,
+    [RESOLUTION.METHOD_AMBIGUOUS]: TIER.UNVERIFIED,
+    [RESOLUTION.UNCERTAIN]:     TIER.UNVERIFIED,
+};
+
+/** Map a RESOLUTION value to its trust tier (unknown values are unverified). */
+function tierForResolution(resolution) {
+    return RESOLUTION_TIER[resolution] || TIER.UNVERIFIED;
+}
+
 /**
  * Score a caller/callee edge based on resolution evidence.
  *
@@ -44,6 +76,25 @@ const SCORES = {
 function scoreEdge(evidence) {
     const reasons = [];
 
+    // Known receiver/path type mismatch — checked FIRST: positive evidence the
+    // call targets a different symbol overrides any receiver-type signal
+    // (without this, a known mismatch would score receiver-hint 0.80).
+    if (evidence.typeMismatch) {
+        reasons.push('receiver type mismatch');
+        return { confidence: SCORES[RESOLUTION.UNCERTAIN], resolution: RESOLUTION.UNCERTAIN, evidence: reasons };
+    }
+
+    // Nominal dispatch tiering (contract surface only — callers.js sets these
+    // flags exclusively under collectAccount, so legacy paths never see them).
+    if (evidence.possibleDispatch) {
+        reasons.push('interface/supertype dispatch');
+        return { confidence: SCORES[RESOLUTION.POSSIBLE_DISPATCH], resolution: RESOLUTION.POSSIBLE_DISPATCH, evidence: reasons };
+    }
+    if (evidence.methodAmbiguous) {
+        reasons.push('untyped receiver, multiple same-name definitions');
+        return { confidence: SCORES[RESOLUTION.METHOD_AMBIGUOUS], resolution: RESOLUTION.METHOD_AMBIGUOUS, evidence: reasons };
+    }
+
     // Exact binding match (highest confidence)
     if (evidence.hasBindingId) {
         reasons.push('binding-id match');
@@ -64,16 +115,25 @@ function scoreEdge(evidence) {
         return { confidence: SCORES[RESOLUTION.RECEIVER_HINT], resolution: RESOLUTION.RECEIVER_HINT, evidence: reasons };
     }
 
+    // Function reference (callback / passed-as-argument). Argument position is
+    // only confirming when the name demonstrably reaches the target (same file,
+    // same package, or an import edge) — otherwise it's a bare name match: a
+    // local variable or an unrelated same-name symbol shadows it invisibly.
+    if (evidence.isFunctionReference) {
+        reasons.push('function reference');
+        if (evidence.hasImportEvidence || evidence.hasSamePackageEvidence) {
+            reasons.push(evidence.hasImportEvidence ? 'import-supported' : 'same package/module');
+            return { confidence: SCORES[RESOLUTION.SCOPE_MATCH], resolution: RESOLUTION.SCOPE_MATCH, evidence: reasons };
+        }
+        reasons.push('no import evidence');
+        return { confidence: SCORES[RESOLUTION.NAME_ONLY], resolution: RESOLUTION.NAME_ONLY, evidence: reasons };
+    }
+
     // Scope/import-supported match
-    if (evidence.hasImportEvidence || evidence.hasReceiverEvidence) {
+    if (evidence.hasImportEvidence || evidence.hasReceiverEvidence || evidence.hasSamePackageEvidence) {
         if (evidence.hasImportEvidence) reasons.push('import-supported');
         if (evidence.hasReceiverEvidence) reasons.push('receiver binding in scope');
-        return { confidence: SCORES[RESOLUTION.SCOPE_MATCH], resolution: RESOLUTION.SCOPE_MATCH, evidence: reasons };
-    }
-
-    // Function reference (callback)
-    if (evidence.isFunctionReference) {
-        reasons.push('function reference');
+        if (evidence.hasSamePackageEvidence) reasons.push('same package/module');
         return { confidence: SCORES[RESOLUTION.SCOPE_MATCH], resolution: RESOLUTION.SCOPE_MATCH, evidence: reasons };
     }
 
@@ -111,6 +171,9 @@ function filterByConfidence(edges, minConfidence) {
 module.exports = {
     RESOLUTION,
     SCORES,
+    TIER,
+    RESOLUTION_TIER,
+    tierForResolution,
     scoreEdge,
     filterByConfidence,
 };

package/core/deadcode.js

@@ -177,6 +177,45 @@ function buildUsageIndex(index, filterNames) {
     return usageIndex;
 }
 
+/**
+ * Is a symbol part of the public/exported API surface?
+ *
+ * Beyond direct evidence (export list, export/public modifiers, Go
+ * capitalization), methods of an exported class count as exported in
+ * languages where class members are public by default (implicitlyPublicMembers
+ * trait — JS/TS/Python): they are reachable through the class from outside
+ * the project, so claiming them dead invites deleting public API (fix #211 —
+ * zod's `strictImplement` is called by zero project files but is documented
+ * public API). Private-by-shape members (#name, _name, `private` modifier)
+ * stay claimable.
+ */
+function symbolIsExported(index, symbol, fileEntry) {
+    if (!fileEntry) return false;
+    const name = symbol.name;
+    const mods = symbol.modifiers || [];
+    if (fileEntry.exports.includes(name) || mods.includes('export') || mods.includes('public')) {
+        return true;
+    }
+    const traits = langTraits(fileEntry.language);
+    if (traits?.exportVisibility === 'capitalization') {
+        return /^[A-Z]/.test(name);
+    }
+    if (traits?.implicitlyPublicMembers && symbol.className &&
+        !mods.includes('private') && !name.startsWith('#') && !name.startsWith('_')) {
+        const classSyms = index.symbols.get(symbol.className) || [];
+        const cls = classSyms.find(c => c.file === symbol.file &&
+            (c.type === 'class' || c.type === 'interface'));
+        if (cls) {
+            const cmods = cls.modifiers || [];
+            if (fileEntry.exports.includes(symbol.className) ||
+                cmods.includes('export') || cmods.includes('public')) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
 /**
  * Find dead code (unused functions/classes)
  * @param {object} index - ProjectIndex instance
@@ -220,15 +259,7 @@ function deadcode(index, options = {}) {
         for (const name of potentiallyDeadNames) {
             const syms = index.symbols.get(name) || [];
             // Keep the name only if at least one definition is NOT exported
-            const allExported = syms.every(s => {
-                const fe = index.files.get(s.file);
-                const lang = fe?.language;
-                if (!fe) return false;
-                return fe.exports.includes(name) ||
-                    (s.modifiers || []).includes('export') ||
-                    (s.modifiers || []).includes('public') ||
-                    (langTraits(lang)?.exportVisibility === 'capitalization' && /^[A-Z]/.test(name));
-            });
+            const allExported = syms.every(s => symbolIsExported(index, s, index.files.get(s.file)));
             if (!allExported) narrowed.add(name);
         }
         potentiallyDeadNames = narrowed;
@@ -260,10 +291,18 @@ function deadcode(index, options = {}) {
                 const content = index._readFile(filePath);
                 // Fast pre-filter: extract identifiers from file, intersect with target names.
                 // One regex pass over content (O(content)) vs O(names × content) substring searches.
+                // Names the identifier regex can never produce — quoted member names
+                // (zod's `"~validate"`), $-containing JS names — fall back to a substring
+                // check, or they would scan as zero-usage and be falsely claimed dead
+                // (fix #211: `this["~validate"](data)` is a real usage; the quotes in
+                // the symbol name make the substring search self-delimiting).
                 const fileIdentifiers = new Set(content.match(/\b[a-zA-Z_]\w*\b/g));
                 const namesInFile = [];
                 for (const name of potentiallyDeadNames) {
-                    if (fileIdentifiers.has(name)) namesInFile.push(name);
+                    const present = /^[a-zA-Z_]\w*$/.test(name)
+                        ? fileIdentifiers.has(name)
+                        : content.includes(name);
+                    if (present) namesInFile.push(name);
                 }
                 if (namesInFile.length === 0) continue;
                 const lines = content.split('\n');
@@ -291,9 +330,37 @@ function deadcode(index, options = {}) {
                                 (hashIdx === 0 || /\s/.test(line[hashIdx - 1]))) continue;
                             // Skip if inside a string literal
                             if (isInsideString(line, pos)) continue;
-                            // Skip property/field access: preceded by '.' unless followed by '(' (method call)
+                            // Property/field access (preceded by '.'), not a
+                            // call: resolve the RECEIVER (fix #216, express-
+                            // measured false-dead — `app.all(route, user.load)`
+                            // is a callback reference to user.js's load, and
+                            // deleting it breaks the route).
+                            //   - import-bound module receiver → usage scoped
+                            //     to the module's resolved file
+                            //   - this/self/cls receiver → usage scoped to the
+                            //     same file (same-class member reference)
+                            //   - any other receiver (local object literal,
+                            //     instance) → NOT a usage of a standalone
+                            //     symbol (fix #123: `Primitives.Separator` has
+                            //     its own key; must not keep the export alive)
+                            let dottedScope;
                             if (pos > 0 && line[pos - 1] === '.' &&
-                                (pos + nameLen >= line.length || line[pos + nameLen] !== '(')) continue;
+                                (pos + nameLen >= line.length || line[pos + nameLen] !== '(')) {
+                                let r = pos - 2;
+                                while (r >= 0 && /[\w$]/.test(line[r])) r--;
+                                const receiver = line.slice(r + 1, pos - 1);
+                                if (!receiver) continue;
+                                if (['this', 'self', 'cls'].includes(receiver)) {
+                                    dottedScope = 'same-file';
+                                } else {
+                                    const binding = (fileEntry.importBindings || [])
+                                        .find(b => b.name === receiver);
+                                    const resolved = binding && fileEntry.moduleResolved &&
+                                        fileEntry.moduleResolved[binding.module];
+                                    if (!resolved) continue;
+                                    dottedScope = resolved;
+                                }
+                            }
                             // Skip object literal key: name followed by ':' (not '::' for Rust paths)
                             const afterChar = pos + nameLen < line.length ? line[pos + nameLen] : '';
                             const afterChar2 = pos + nameLen + 1 < line.length ? line[pos + nameLen + 1] : '';
@@ -303,7 +370,8 @@ function deadcode(index, options = {}) {
                             usageIndex.get(name).push({
                                 file: filePath,
                                 line: i + 1,
-                                relativePath: fileEntry.relativePath
+                                relativePath: fileEntry.relativePath,
+                                ...(dottedScope && { dottedScope })
                             });
                             break; // one match per line is enough for deadcode
                         }
@@ -365,12 +433,7 @@ function deadcode(index, options = {}) {
                 continue;
             }
 
-            const isExported = fileEntry && (
-                fileEntry.exports.includes(name) ||
-                mods.includes('export') ||
-                mods.includes('public') ||
-                (langTraits(lang)?.exportVisibility === 'capitalization' && /^[A-Z]/.test(name))
-            );
+            const isExported = symbolIsExported(index, symbol, fileEntry);
 
             // Skip exported unless requested
             if (isExported && !options.includeExported) {
@@ -389,8 +452,15 @@ function deadcode(index, options = {}) {
             // Filter out usages that are at the definition location
             // nameLine: when decorators/annotations are present, startLine is the decorator line
             // but the name identifier is on a different line (nameLine). Check both.
+            // Dotted usages (fix #216) are scoped to the file their receiver
+            // resolves to — `user.load` keeps user.js's load alive, never an
+            // unrelated module's same-name symbol.
             let nonDefUsages = allUsages.filter(u =>
-                !(u.file === symbol.file && (u.line === symbol.startLine || u.line === symbol.nameLine))
+                !(u.file === symbol.file && (u.line === symbol.startLine || u.line === symbol.nameLine)) &&
+                (!u.dottedScope ||
+                    (u.dottedScope === 'same-file'
+                        ? u.file === symbol.file
+                        : u.dottedScope === symbol.relativePath))
             );
 
             // For exported symbols in --include-exported mode, also filter out export-site
@@ -428,6 +498,28 @@ function deadcode(index, options = {}) {
                     ? mods.filter(m => !javaKw.has(m))
                     : [];
 
+                // Interface/trait member declarations are contract surface, not
+                // executable code: "unreferenced" is true, but deleting one
+                // changes the API contract rather than removing dead logic (Go
+                // marker interfaces exist SOLELY as uncallable declarations —
+                // grpc-go-measured: its entire default deadcode output was this
+                // family). Label so the claim self-explains (fix #211). Only
+                // body-less declarations qualify — Java `default` and Rust
+                // default-bodied trait methods are executable code, detected
+                // generically by a brace in the member's source range.
+                const declaredOn = (() => {
+                    if (!symbol.className) return null;
+                    const enclosing = (index.symbols.get(symbol.className) || []).find(c =>
+                        c.file === symbol.file && (c.type === 'interface' || c.type === 'trait'));
+                    if (!enclosing) return null;
+                    try {
+                        const content = index._readFile(symbol.file);
+                        const range = content.split('\n').slice(symbol.startLine - 1, symbol.endLine).join('\n');
+                        if (range.includes('{')) return null;
+                    } catch { return null; }
+                    return { kind: enclosing.type, name: symbol.className };
+                })();
+
                 results.push({
                     name: symbol.name,
                     type: symbol.type,
@@ -437,7 +529,8 @@ function deadcode(index, options = {}) {
                     isExported,
                     usageCount: 0,
                     ...(decorators.length > 0 && { decorators }),
-                    ...(annotations.length > 0 && { annotations })
+                    ...(annotations.length > 0 && { annotations }),
+                    ...(declaredOn && { declaredOn })
                 });
             }
         }

package/core/execute.js

@@ -292,6 +292,7 @@ const HANDLERS = {
         const result = index.context(p.name, {
             ...buildCallerOptions(p),
             unreachableOnly: !!p.unreachableOnly,
+            all: !!p.all,
         });
         if (!result) return { ok: false, error: `Symbol "${p.name}" not found.` };
         const tNote = truncationNote(index);
@@ -337,6 +338,7 @@ const HANDLERS = {
             ...buildCallerOptions(p),
             depth: depthVal ?? 3,
             all: p.all || depthVal !== undefined,
+            expandUnverified: !!p.expandUnverified,
         });
         if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
         const note = treeNote(result);
@@ -358,6 +360,7 @@ const HANDLERS = {
             ...buildCallerOptions(p),
             depth: depthVal ?? 5,
             all: p.all || depthVal !== undefined,
+            expandUnverified: !!p.expandUnverified,
         });
         if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
         const note = treeNote(result);
@@ -396,6 +399,7 @@ const HANDLERS = {
             ...buildCallerOptions(p),
             depth: depthVal ?? 3,
             all: p.all || depthVal !== undefined,
+            expandUnverified: !!p.expandUnverified,
         });
         if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
         const note = treeNote(result);

package/core/graph-build.js

@@ -105,6 +105,13 @@ function buildImportGraph(index) {
     for (const [filePath, fileEntry] of index.files) {
         const importedFiles = new Set();
         const seenModules = new Set();
+        // Per-module resolution map (fix #209): module string → resolved
+        // project file (ROOT-RELATIVE — fileEntry persists in the cache, so
+        // paths must stay portable). Lets query-time code answer "which FILE
+        // does the module behind this import binding live in" — file-level
+        // importGraph edges can't (a file importing the target for OTHER
+        // names is not evidence about THIS name's module).
+        const moduleResolved = {};
 
         for (const importModule of fileEntry.imports) {
             // Skip null modules (e.g., dynamic include! macros in Rust)
@@ -128,6 +135,7 @@ function buildImportGraph(index) {
             }
 
             if (resolved && index.files.has(resolved)) {
+                moduleResolved[importModule] = path.relative(index.root, resolved);
                 // For Go, a package import means all files in that directory are dependencies
                 // (Go packages span multiple files in the same directory)
                 const filesToLink = [resolved];
@@ -154,6 +162,7 @@ function buildImportGraph(index) {
         }
 
         index.importGraph.set(filePath, importedFiles);
+        fileEntry.moduleResolved = moduleResolved;
     }
 }
 
@@ -181,8 +190,15 @@ function buildInheritanceGraph(index) {
             }
 
             if (symbol.extends) {
-                // Parse comma-separated parents (Python MRO: "Flyable, Swimmable")
-                const parents = symbol.extends.split(',').map(s => s.trim()).filter(Boolean);
+                // Parse comma-separated parents (Python MRO: "Flyable, Swimmable").
+                // Commas inside type arguments do NOT separate parents:
+                // `extends Base<string, object>` is ONE parent `Base`, and
+                // `class C(Mapping[str, int], Base)` is `Mapping` + `Base`.
+                // The naive split made every generically-extended class
+                // parentless (fix #214 — zod's whole ZodType hierarchy had no
+                // ancestor edges, measured: 12 true base-class dispatch edges
+                // demoted because `Base<string` never equals `Base`).
+                const parents = splitParentList(symbol.extends);
 
                 // Resolve aliased parent names via import aliases
                 // e.g., const { BaseHandler: Handler } = require('./base')
@@ -221,4 +237,30 @@ function buildInheritanceGraph(index) {
     }
 }
 
+/**
+ * Split an extends/bases clause on TOP-LEVEL commas only and strip each
+ * parent's trailing type-argument suffix: `Base<string, object>` → `Base`,
+ * `Mapping[str, int], Flyable` → `Mapping`, `Flyable`. Depth-tracks <>, [],
+ * and () so argument commas never split (fix #214).
+ */
+function splitParentList(clause) {
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (const ch of String(clause)) {
+        if (ch === '<' || ch === '[' || ch === '(') depth++;
+        else if (ch === '>' || ch === ']' || ch === ')') depth = Math.max(0, depth - 1);
+        if (ch === ',' && depth === 0) {
+            parts.push(current);
+            current = '';
+        } else {
+            current += ch;
+        }
+    }
+    parts.push(current);
+    return parts
+        .map(s => s.trim().replace(/[<[(].*$/s, '').trim())
+        .filter(Boolean);
+}
+
 module.exports = { buildDirIndex, buildImportGraph, buildInheritanceGraph, _resolveJavaPackageImport };

package/core/imports.js

@@ -120,6 +120,10 @@ function resolveImport(importPath, fromFile, config = {}) {
                     if (result) return result;
                 }
             }
+
+            // Package self-reference (import own package by name)
+            const selfResolved = resolveSelfReference(importPath, fromDir, config);
+            if (selfResolved) return selfResolved;
         }
 
         // Check Go module imports
@@ -412,12 +416,124 @@ function resolveRustImport(importPath, fromFile, projectRoot) {
 /**
  * Try to resolve a path with various extensions
  */
+// package.json lookup cache for self-reference resolution (dir -> info|null).
+// Process-lifetime cache: package.json name/exports churn is rare enough that
+// long-lived servers (MCP) tolerate it.
+const _pkgCache = new Map();
+
+function _findPackageJson(fromDir, stopDir) {
+    let current = fromDir;
+    for (let i = 0; i < 8; i++) {
+        let info;
+        if (_pkgCache.has(current)) {
+            info = _pkgCache.get(current);
+        } else {
+            info = null;
+            const candidate = path.join(current, 'package.json');
+            try {
+                if (fs.existsSync(candidate)) {
+                    const pkg = JSON.parse(fs.readFileSync(candidate, 'utf-8'));
+                    info = { dir: current, name: pkg.name, exports: pkg.exports, main: pkg.main };
+                }
+            } catch { /* unreadable or invalid JSON */ }
+            _pkgCache.set(current, info);
+        }
+        if (info) return info;
+        if (stopDir && current === stopDir) break;
+        const parent = path.dirname(current);
+        if (parent === current) break;
+        current = parent;
+    }
+    return null;
+}
+
+/** Flatten an exports-map entry to candidate targets (condition objects in
+ *  insertion order, arrays in order). 'types' conditions are skipped — they
+ *  name declaration files, not runtime sources. */
+function _collectExportTargets(entry, out = []) {
+    if (typeof entry === 'string') {
+        out.push(entry);
+    } else if (Array.isArray(entry)) {
+        for (const e of entry) _collectExportTargets(e, out);
+    } else if (entry && typeof entry === 'object') {
+        for (const [cond, v] of Object.entries(entry)) {
+            if (cond === 'types') continue;
+            _collectExportTargets(v, out);
+        }
+    }
+    return out;
+}
+
+/**
+ * Package self-reference: a file importing its own package by name
+ * (`import * as z from "zod/v3"` inside the zod repo) — standard in monorepo
+ * tests and benchmarks. Resolves through package.json "exports" (conditional
+ * objects, arrays, '*' wildcards), accepting the first condition target that
+ * lands on a real file.
+ */
+function resolveSelfReference(importPath, fromDir, config) {
+    const pkg = _findPackageJson(fromDir, config.root ? path.dirname(config.root) : null);
+    if (!pkg || !pkg.name) return null;
+    if (importPath !== pkg.name && !importPath.startsWith(pkg.name + '/')) return null;
+    const subpath = importPath === pkg.name ? '.' : './' + importPath.slice(pkg.name.length + 1);
+    const extensions = config.extensions || getExtensions(config.language);
+    const tryTargets = (entry, wildcard) => {
+        for (const target of _collectExportTargets(entry)) {
+            const concrete = wildcard != null ? target.replace(/\*/g, wildcard) : target;
+            const resolved = resolveFilePath(path.resolve(pkg.dir, concrete), extensions);
+            if (resolved) return resolved;
+        }
+        return null;
+    };
+    const exp = pkg.exports;
+    if (typeof exp === 'string') {
+        return subpath === '.' ? tryTargets(exp, null) : null;
+    }
+    if (exp && typeof exp === 'object') {
+        if (exp[subpath] !== undefined) {
+            const hit = tryTargets(exp[subpath], null);
+            if (hit) return hit;
+        }
+        for (const [key, val] of Object.entries(exp)) {
+            const star = key.indexOf('*');
+            if (star === -1) continue;
+            const pre = key.slice(0, star);
+            const post = key.slice(star + 1);
+            if (subpath.length > pre.length + post.length &&
+                subpath.startsWith(pre) && subpath.endsWith(post)) {
+                const wild = subpath.slice(pre.length, subpath.length - post.length);
+                const hit = tryTargets(val, wild);
+                if (hit) return hit;
+            }
+        }
+        return null;
+    }
+    // No exports map: bare name -> main/index; subpath -> direct file
+    if (subpath === '.') {
+        return (pkg.main && resolveFilePath(path.resolve(pkg.dir, pkg.main), extensions)) ||
+            resolveFilePath(path.resolve(pkg.dir, 'index'), extensions);
+    }
+    return resolveFilePath(path.resolve(pkg.dir, subpath), extensions);
+}
+
 function resolveFilePath(basePath, extensions) {
     // Check exact path
     if (fs.existsSync(basePath) && fs.statSync(basePath).isFile()) {
         return basePath;
     }
 
+    // TS-ESM: explicit '.js'/'.mjs' specifiers refer to '.ts'/'.mts' sources
+    // (import specifiers name the compiled output). Remap before probing.
+    const esmRemap = { '.js': ['.ts', '.tsx'], '.jsx': ['.tsx'], '.mjs': ['.mts'], '.cjs': ['.cts'] };
+    const explicitExt = path.extname(basePath);
+    if (esmRemap[explicitExt]) {
+        const stem = basePath.slice(0, -explicitExt.length);
+        for (const tsExt of esmRemap[explicitExt]) {
+            const candidate = stem + tsExt;
+            try { if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate; } catch { /* skip */ }
+        }
+    }
+
     // Try adding extensions
     for (const ext of extensions) {
         const withExt = basePath + ext;
@@ -633,5 +749,6 @@ module.exports = {
     extractImports,
     extractExports,
     resolveImport,
-    resolveFilePath
+    resolveFilePath,
+    findGoModule
 };