ucn 3.8.26 → 4.0.1

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

@@ -8,6 +8,90 @@
 const { detectLanguage, getParser, getLanguageModule, safeParse, langTraits } = require('../languages');
 const { isTestFile } = require('./discovery');
 const { isFrameworkEntrypoint } = require('./entrypoints');
+const { splitParentList } = require('./graph-build');
+const { isOverrideMarked } = require('./shared');
+
+const _CLASS_KINDS = ['class', 'struct', 'interface', 'trait', 'record'];
+
+/** Strip a base-type expression to its bare name: `Mapping[str, int]`→Mapping, `java.util.List<Foo>`→List, `a::b::C`→C. */
+function _bareBaseName(raw) {
+    return String(raw).replace(/[<[(].*$/s, '').split('.').pop().split('::').pop().trim();
+}
+
+// The universal object root (Python `object`, Java/JS `Object`) has a fixed,
+// known method surface — Object/dunder methods, themselves entry points — so it
+// never dispatches an arbitrary subclass method by name or override. It is NOT
+// an external *dispatching* base: `class Foo(object)` must still report its
+// genuinely-dead inherent methods, exactly like `class Foo`, instead of
+// diverging on a purely cosmetic base declaration. (Java `Object` is the
+// universalSupertype trait; `object` is the Python equivalent — a language
+// convention, rule #9.)
+const _UNIVERSAL_ROOTS = new Set(['object', 'Object']);
+
+/** True when a base name resolves to NO in-project class/struct/interface/trait/record (an out-of-tree type). */
+function _baseIsExternal(index, bare) {
+    if (!bare || _UNIVERSAL_ROOTS.has(bare)) return false;
+    const defs = index.symbols.get(bare);
+    return !(defs && defs.some(d => _CLASS_KINDS.includes(d.type)));
+}
+
+/**
+ * Does the method's enclosing class EXTEND at least one base that is NOT in the
+ * project index? An out-of-tree base is a framework/library type UCN can't see;
+ * via inheritance it may dispatch into a public method of the subclass
+ * polymorphically (Starlette → build_middleware_stack) or by name convention
+ * (Pydantic → bytes_schema). The class def is matched in the method's own file.
+ *
+ * `implements` is deliberately NOT consulted: implementing an external
+ * interface/trait makes only the INTERFACE'S OWN methods a contract (those
+ * carry traitImpl/@Override markers → handled by Rule A), not the class's
+ * unrelated inherent methods. Counting it would wrongly shield, e.g., a Rust
+ * struct's genuinely-dead inherent method just because the struct also
+ * `impl Display for`s.
+ */
+function _classHasExternalBase(index, symbol) {
+    const classDefs = (index.symbols.get(symbol.className) || []).filter(c =>
+        c.file === symbol.file && _CLASS_KINDS.includes(c.type));
+    for (const cd of classDefs) {
+        if (!cd.extends) continue;
+        const supers = Array.isArray(cd.extends) ? cd.extends : splitParentList(cd.extends);
+        for (const raw of supers) {
+            if (_baseIsExternal(index, _bareBaseName(raw))) return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * A method that may be reached through an out-of-tree base class — the deadcode
+ * analog of fix #210's external-contract methods. A zero in-project usage count
+ * is NOT evidence of deadness here; claiming the symbol dead invites deleting a
+ * live framework override (e.g. FastAPI.build_middleware_stack overriding
+ * Starlette, or GenerateJsonSchema.bytes_schema name-dispatched by Pydantic —
+ * the only caller lives in an unindexed dependency).
+ *   (A) explicit override marker (@Override / `override` / typing.@override /
+ *       Rust `impl Trait for X`) AND a single project-wide method owner of the
+ *       name (no in-project supertype defines it → the contract is external —
+ *       the #210 ownerCount===1 rule).
+ *   (B) a public-by-shape method whose class EXTENDS an unresolved base.
+ *       Private/underscore members are never external-contract surface, so a
+ *       genuinely-dead one stays claimable (the fix #211 shape predicate).
+ * Data-driven, not language-keyed: classes without an `extends` clause (Go
+ * embedding, Rust structs / inherent impls) never trip (B), and Rust trait
+ * impls trip (A) via traitImpl — so new languages inherit correct behavior.
+ */
+function overridesOutOfTreeBase(index, symbol) {
+    if (!symbol.className) return false; // standalone function can't override
+    if (isOverrideMarked(symbol)) {
+        const owners = (index.symbols.get(symbol.name) || []).filter(s => s.className);
+        if (owners.length <= 1) return true;
+    }
+    const mods = symbol.modifiers || [];
+    const publicByShape = !mods.includes('private') &&
+        !symbol.name.startsWith('#') && !symbol.name.startsWith('_');
+    if (publicByShape && _classHasExternalBase(index, symbol)) return true;
+    return false;
+}
 
 /** Check if a position in a line is inside a string literal (quotes/backticks) */
 function isInsideString(line, pos) {
@@ -177,6 +261,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
@@ -189,6 +312,7 @@ function deadcode(index, options = {}) {
     const results = [];
     let excludedDecorated = 0;
     let excludedExported = 0;
+    let excludedExternalContract = 0;
 
     // Ensure callee index is built (lazy, reused across operations)
     if (!index.calleeIndex) {
@@ -220,15 +344,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 +376,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 +415,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 +455,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 +518,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 +537,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
@@ -418,6 +573,16 @@ function deadcode(index, options = {}) {
             const totalUsages = nonDefUsages.length;
 
             if (totalUsages === 0) {
+                // External-contract override: the method may be invoked through
+                // an out-of-tree base class UCN can't index (deadcode analog of
+                // fix #210). A zero usage count is not evidence of deadness.
+                // Hidden by default; revealed under --include-exported, since
+                // it is external-reachable surface, not internal dead code.
+                const isExternalContract = overridesOutOfTreeBase(index, symbol);
+                if (isExternalContract && !options.includeExported) {
+                    excludedExternalContract++;
+                    continue;
+                }
                 // Collect decorators/annotations for hint display
                 // Python: symbol.decorators (e.g., ['app.route("/path")', 'login_required'])
                 // Java/Rust/Go: symbol.modifiers may contain annotations (e.g., 'bean', 'scheduled')
@@ -428,6 +593,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 +624,9 @@ function deadcode(index, options = {}) {
                     isExported,
                     usageCount: 0,
                     ...(decorators.length > 0 && { decorators }),
-                    ...(annotations.length > 0 && { annotations })
+                    ...(annotations.length > 0 && { annotations }),
+                    ...(declaredOn && { declaredOn }),
+                    ...(isExternalContract && { externalContract: true })
                 });
             }
         }
@@ -452,6 +641,7 @@ function deadcode(index, options = {}) {
     // Attach exclusion counts as array properties (backwards-compatible)
     results.excludedDecorated = excludedDecorated;
     results.excludedExported = excludedExported;
+    results.excludedExternalContract = excludedExternalContract;
 
     return results;
     } finally { index._endOp(); }

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);
@@ -747,9 +751,10 @@ const HANDLERS = {
         if (limit && limit > 0 && Array.isArray(result) && result.length > limit) {
             note = limitNote(limit, result.length);
             const sliced = result.slice(0, limit);
-            // Preserve custom properties (excludedExported, excludedDecorated) from deadcode()
+            // Preserve custom properties (excludedExported, excludedDecorated, excludedExternalContract) from deadcode()
             if (result.excludedExported != null) sliced.excludedExported = result.excludedExported;
             if (result.excludedDecorated != null) sliced.excludedDecorated = result.excludedDecorated;
+            if (result.excludedExternalContract != null) sliced.excludedExternalContract = result.excludedExternalContract;
             result = sliced;
         }
         const tNote = truncationNote(index);

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) {
     }
 }
 
-module.exports = { buildDirIndex, buildImportGraph, buildInheritanceGraph, _resolveJavaPackageImport };
+/**
+ * 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, splitParentList, _resolveJavaPackageImport };