ucn 4.0.0 → 4.0.2

package/cli/index.js

@@ -1052,7 +1052,8 @@ function runProjectCommand(rootDir, command, arg) {
                 r => output.formatDeadcode(r, {
                     top: flags.top,
                     decoratedHint: !flags.includeDecorated && result.excludedDecorated > 0 ? `${result.excludedDecorated} decorated/annotated symbol(s) hidden (framework-registered). Use --include-decorated to include them.` : undefined,
-                    exportedHint: !flags.includeExported && result.excludedExported > 0 ? `${result.excludedExported} exported symbol(s) excluded (all have callers). Use --include-exported to audit them.` : undefined
+                    exportedHint: !flags.includeExported && result.excludedExported > 0 ? `${result.excludedExported} exported symbol(s) excluded (all have callers). Use --include-exported to audit them.` : undefined,
+                    externalContractHint: !flags.includeExported && result.excludedExternalContract > 0 ? `${result.excludedExternalContract} symbol(s) hidden (override an out-of-tree base class — reachable via external contract, not dead). Use --include-exported to include them.` : undefined
                 })
             );
             break;
@@ -1911,7 +1912,8 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
             console.log(output.formatDeadcode(result, {
                 top: iflags.top,
                 decoratedHint: !iflags.includeDecorated && result.excludedDecorated > 0 ? `${result.excludedDecorated} decorated/annotated symbol(s) hidden (framework-registered). Use --include-decorated to include them.` : undefined,
-                exportedHint: !iflags.includeExported && result.excludedExported > 0 ? `${result.excludedExported} exported symbol(s) excluded (all have callers). Use --include-exported to audit them.` : undefined
+                exportedHint: !iflags.includeExported && result.excludedExported > 0 ? `${result.excludedExported} exported symbol(s) excluded (all have callers). Use --include-exported to audit them.` : undefined,
+                externalContractHint: !iflags.includeExported && result.excludedExternalContract > 0 ? `${result.excludedExternalContract} symbol(s) hidden (override an out-of-tree base class — reachable via external contract, not dead). Use --include-exported to include them.` : undefined
             }));
             break;
         }

package/core/analysis.js

@@ -12,7 +12,7 @@ const path = require('path');
 const { execFileSync } = require('child_process');
 const { parse } = require('./parser');
 const { detectLanguage, langTraits } = require('../languages');
-const { NON_CALLABLE_TYPES, addTestExclusions } = require('./shared');
+const { NON_CALLABLE_TYPES, addTestExclusions, countTextBlindspots } = require('./shared');
 const { computeReachability, symbolKey } = require('./entrypoints');
 const { getLanguageModule } = require('../languages');
 
@@ -600,20 +600,20 @@ function detectCompleteness(index) {
             const content = index._readFile(filePath);
 
             if (langTraits(fileEntry.language)?.hasDynamicImports) {
-                // Dynamic imports: import(), require(variable), __import__
-                dynamicImports += (content.match(/import\s*\([^'"]/g) || []).length;
-                dynamicImports += (content.match(/require\s*\([^'"]/g) || []).length;
-                dynamicImports += (content.match(/__import__\s*\(/g) || []).length;
-
-                // eval, Function constructor
-                evalUsage += (content.match(/(^|[^a-zA-Z_])eval\s*\(/gm) || []).length;
-                evalUsage += (content.match(/new\s+Function\s*\(/g) || []).length;
+                // Dynamic imports: use the parser's structural count — the SAME
+                // source `doctor` uses — instead of a text regex. The old
+                // /import\s*\(/ matched Python grouped imports `from x import
+                // (...)`, flashing a false "N dynamic imports" incompleteness
+                // warning on essentially every Python project (field-report #2,
+                // reviewer-confirmed: doctor and about now agree on one count).
+                dynamicImports += fileEntry.dynamicImports || 0;
             }
 
-            // Reflection: getattr, hasattr, Reflect
-            reflectionUsage += (content.match(/\bgetattr\s*\(/g) || []).length;
-            reflectionUsage += (content.match(/\bhasattr\s*\(/g) || []).length;
-            reflectionUsage += (content.match(/\bReflect\./g) || []).length;
+            // eval/exec and reflection: the SAME shared counter doctor uses, so
+            // the about footer and the trust report never diverge (field-report #2).
+            const bs = countTextBlindspots(content, fileEntry.language);
+            evalUsage += bs.eval;
+            reflectionUsage += bs.reflection;
         } catch (e) {
             // Skip unreadable files
         }

package/core/callers.js

@@ -10,7 +10,7 @@ const path = require('path');
 const crypto = require('crypto');
 const { detectLanguage, getParser, getLanguageModule, langTraits } = require('../languages');
 const { isTestFile } = require('./discovery');
-const { NON_CALLABLE_TYPES } = require('./shared');
+const { NON_CALLABLE_TYPES, isOverrideMarked } = require('./shared');
 const { scoreEdge, tierForResolution, TIER } = require('./confidence');
 const { findGoModule } = require('./imports');
 
@@ -233,7 +233,7 @@ function findCallers(index, name, options = {}) {
             // `some`, not `every`: one marked overload proves the NAME exists
             // on an external contract — receiver identity is then unprovable
             // for every call shape (external signatures are invisible).
-            const marked = tDefs.find(d => _externalContractMarker(d));
+            const marked = tDefs.find(d => isOverrideMarked(d));
             if (marked) _extContract = { via: _externalContractVia(index, marked) };
         }
         return _extContract;
@@ -3838,7 +3838,7 @@ function _nameBindingReaches(index, startAbs, name, targetFiles, maxDepth = 4) {
         const next = [];
         for (const [abs, attr] of frontier) {
             if (targetFiles.has(abs)) return 'yes';
-            const stateKey = `${abs}${attr}`;
+            const stateKey = `${abs}\x00${attr}`;
             if (visited.has(stateKey)) continue;
             visited.add(stateKey);
             const fe = index.files.get(abs);
@@ -4463,22 +4463,8 @@ function _targetAncestryFullyResolved(index, targetDefs) {
     return true;
 }
 
-/**
- * Explicit override marker on a method definition (fix #210). Marker fields
- * are language-disjoint: traitImpl is Rust-only, an 'override' modifier is
- * Java's lowercased @Override annotation, an override-bearing memberType is
- * TS's `override` keyword, and an override decorator is Python's
- * typing.@override. The marker is compiler-checked syntax in all four —
- * never inferred.
- */
-function _externalContractMarker(def) {
-    if (def.traitImpl) return true;
-    if (def.modifiers && def.modifiers.includes('override')) return true;
-    if (def.memberType && /\boverride\b/.test(def.memberType)) return true;
-    if (def.decorators && def.decorators.some(d =>
-        String(d).replace(/\(.*$/, '').split('.').pop() === 'override')) return true;
-    return false;
-}
+// _externalContractMarker moved to core/shared.js as isOverrideMarked (shared
+// with deadcode's out-of-tree override suppression — one source of truth).
 
 /**
  * Name of the external contract a marked method implements, for dispatch

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) {
@@ -228,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) {
@@ -488,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')
@@ -530,7 +625,8 @@ function deadcode(index, options = {}) {
                     usageCount: 0,
                     ...(decorators.length > 0 && { decorators }),
                     ...(annotations.length > 0 && { annotations }),
-                    ...(declaredOn && { declaredOn })
+                    ...(declaredOn && { declaredOn }),
+                    ...(isExternalContract && { externalContract: true })
                 });
             }
         }
@@ -545,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

@@ -751,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

@@ -263,4 +263,4 @@ function splitParentList(clause) {
         .filter(Boolean);
 }
 
-module.exports = { buildDirIndex, buildImportGraph, buildInheritanceGraph, _resolveJavaPackageImport };
+module.exports = { buildDirIndex, buildImportGraph, buildInheritanceGraph, splitParentList, _resolveJavaPackageImport };

package/core/output/analysis.js

@@ -732,6 +732,21 @@ function formatAbout(about, options = {}) {
             for (const c of testTop) renderAboutCaller(c);
         }
         if (aboutCallerReach.note) lines.push(aboutCallerReach.note);
+
+        // Field-report #5: when every CONFIRMED caller is a test and the
+        // production call sites are method-style (landed in UNVERIFIED as
+        // method-ambiguous — e.g. a module function sharing a name with a
+        // method), the bare "0 prod" count reads like dead code. Flag it so the
+        // empty prod count isn't misread; the real calls are listed below.
+        if (prodTop.length === 0 && testTop.length > 0) {
+            const uv = about.callers.unverified;
+            const methodStyle = uv && uv.top
+                ? uv.top.some(u => u.reason === 'method-ambiguous' || u.reason === 'possible-dispatch')
+                : false;
+            if (uv && uv.total > 0 && methodStyle) {
+                lines.push(`  Note: 0 production callers CONFIRMED — the ${uv.total} call site(s) under UNVERIFIED below include method-style calls that may bind to this or a same-name method, so this is not dead code.`);
+            }
+        }
     }
 
     // Callers — UNVERIFIED tier (always visible; the contract forbids hiding)

package/core/output/doctor.js

@@ -13,6 +13,7 @@ function formatDoctor(result) {
     const lines = [];
     lines.push(`UCN Trust Report — ${result.root}`);
     lines.push('═'.repeat(60));
+    if (result.version) lines.push(`Version: ucn ${result.version}`);
     lines.push(`Index: ${result.files.scanned} file${result.files.scanned === 1 ? '' : 's'}, ${result.symbols} symbol${result.symbols === 1 ? '' : 's'}`);
 
     if (result.filter) lines.push(`Filter: ${result.filter}`);
@@ -60,13 +61,22 @@ function formatDoctor(result) {
         ['Reflection',      bs.reflection],
         ['Parse failures',  bs.parseFailures],
     ];
+    const unitFor = { 'Dynamic imports': 'import', 'Eval/exec calls': 'use', 'Reflection': 'use', 'Parse failures': 'failure' };
     let anyBlindSpot = false;
     for (const [label, info] of bsLines) {
         if (info && info.count > 0) {
             anyBlindSpot = true;
-            const sample = info.files.slice(0, 3).map(f => `    - ${f}`).join('\n');
-            const more = info.files.length > 3 ? `\n    ... and ${info.files.length - 3} more` : '';
-            lines.push(`  ${label}: ${info.count} in ${info.files.length} file${info.files.length === 1 ? '' : 's'}`);
+            // fileCount is the TRUE (uncapped) number of files; info.files is a
+            // capped display sample. Show "N use(s) in M file(s)" and, when the
+            // sample is truncated, "... and K more file(s)" against the true M —
+            // never present the display cap as the population (field-report #2).
+            const fileCount = info.fileCount != null ? info.fileCount : info.files.length;
+            const unit = unitFor[label] || 'use';
+            lines.push(`  ${label}: ${info.count} ${unit}${info.count === 1 ? '' : 's'} in ${fileCount} file${fileCount === 1 ? '' : 's'}`);
+            const shownFiles = info.files.slice(0, 3);
+            const sample = shownFiles.map(f => `    - ${f}`).join('\n');
+            const moreFiles = fileCount - shownFiles.length;
+            const more = moreFiles > 0 ? `\n    ... and ${moreFiles} more file${moreFiles === 1 ? '' : 's'}` : '';
             if (sample) lines.push(sample + more);
         }
     }

package/core/output/reporting.js

@@ -194,7 +194,7 @@ function formatStatsJson(stats) {
  * @param {string} [options.exportedHint] - Hint about exported symbols exclusion
  */
 function formatDeadcode(results, options = {}) {
-    if (results.length === 0 && !results.excludedDecorated && !results.excludedExported) {
+    if (results.length === 0 && !results.excludedDecorated && !results.excludedExported && !results.excludedExternalContract) {
         return 'No dead code found.';
     }
 
@@ -232,7 +232,11 @@ function formatDeadcode(results, options = {}) {
         const declStr = item.declaredOn
             ? ` [declared on ${item.declaredOn.kind} ${item.declaredOn.name} — contract surface, not executable code]`
             : '';
-        lines.push(`  ${lineRange(item.startLine, item.endLine)} ${item.name} (${item.type})${exported}${hintStr}${declStr}`);
+        // Revealed under --include-exported: mark as external-reachable, not dead.
+        const extStr = item.externalContract
+            ? ' [reachable via out-of-tree base — external contract, not dead]'
+            : '';
+        lines.push(`  ${lineRange(item.startLine, item.endLine)} ${item.name} (${item.type})${exported}${hintStr}${declStr}${extStr}`);
     }
 
     if (hidden > 0) {
@@ -251,6 +255,10 @@ function formatDeadcode(results, options = {}) {
         const exportedHint = options.exportedHint || `${results.excludedExported} exported symbol(s) excluded (all have callers). Use --include-exported to audit them.`;
         lines.push(`\n${exportedHint}`);
     }
+    if (results.excludedExternalContract > 0) {
+        const extHint = options.externalContractHint || `${results.excludedExternalContract} symbol(s) hidden (override an out-of-tree base class — reachable via external contract, not dead). Use --include-exported to include them.`;
+        lines.push(`\n${extHint}`);
+    }
 
     if (lines.length === 0) {
         return 'No dead code found.';
@@ -270,6 +278,7 @@ function formatDeadcodeJson(results) {
             count: results.length,
             ...(results.excludedExported > 0 && { excludedExported: results.excludedExported }),
             ...(results.excludedDecorated > 0 && { excludedDecorated: results.excludedDecorated }),
+            ...(results.excludedExternalContract > 0 && { excludedExternalContract: results.excludedExternalContract }),
             symbols: results.map(item => {
                 const handleSym = { ...item, relativePath: item.relativePath || item.file };
                 const handle = formatSymbolHandle(handleSym);
@@ -283,7 +292,8 @@ function formatDeadcodeJson(results) {
                     ...(item.isExported && { isExported: true }),
                     ...(item.decorators && item.decorators.length > 0 && { decorators: item.decorators }),
                     ...(item.annotations && item.annotations.length > 0 && { annotations: item.annotations }),
-                    ...(item.declaredOn && { declaredOn: item.declaredOn })
+                    ...(item.declaredOn && { declaredOn: item.declaredOn }),
+                    ...(item.externalContract && { externalContract: true })
                 };
             }),
         },

package/core/reporting.js

@@ -538,28 +538,23 @@ function doctor(index, options = {}) {
     const fileCounts = { total: 0, scanned: 0 };
     const langs = {};
     let totalSymbols = 0;  // counted post-filter for accuracy when --in is set
+    // Each category tracks: count = total OCCURRENCES (uses), fileCount = TRUE
+    // number of files affected (uncapped), files = a capped sample for display.
+    // Keeping count and fileCount distinct is what lets the formatter say
+    // "481 uses in 121 files" instead of mislabeling a file count as uses or
+    // presenting the 10-file display cap as the population (field-report #2).
+    const BLINDSPOT_FILE_CAP = 10;
     const blindSpots = {
-        dynamicImports: { count: 0, files: [] },
-        evalCalls:      { count: 0, files: [] },
-        reflection:     { count: 0, files: [] },
-        parseFailures:  { count: 0, files: [] },
+        dynamicImports: { count: 0, fileCount: 0, files: [] },
+        evalCalls:      { count: 0, fileCount: 0, files: [] },
+        reflection:     { count: 0, fileCount: 0, files: [] },
+        parseFailures:  { count: 0, fileCount: 0, files: [] },
     };
 
-    // Reflection signals per language. These run textually over the source — fast,
-    // and acceptable since UCN already records dynamic-import counts at parse time.
-    const REFLECTION_PATTERNS = {
-        python:     /\b(getattr|hasattr|setattr|__import__|importlib\.import_module)\s*\(/,
-        javascript: /\bnew Function\s*\(|\bReflect\.\w+\s*\(/,
-        typescript: /\bnew Function\s*\(|\bReflect\.\w+\s*\(/,
-        go:         /"reflect"|reflect\.\w+\s*\(/,
-        java:       /\.getDeclaredMethod\b|\.getMethod\b|\.getDeclaredField\b|Class\.forName\b/,
-        rust:       /\bAny::downcast/,
-    };
-    const EVAL_PATTERNS = {
-        python:     /\b(eval|exec)\s*\(/,
-        javascript: /\beval\s*\(/,
-        typescript: /\beval\s*\(/,
-    };
+    // Reflection/eval signals come from the shared text-blind-spot counter
+    // (core/shared.js) — the SAME routine detectCompleteness uses for the about
+    // footer, so the two never drift (field-report #2). Occurrence counts.
+    const { hasTextBlindspots, countTextBlindspots } = require('./shared');
 
     for (const [filePath, fe] of index.files) {
         fileCounts.total++;
@@ -574,29 +569,22 @@ function doctor(index, options = {}) {
         langs[lang].lines += fe.lines || 0;
         totalSymbols += (fe.symbols || []).length;
 
-        if (fe.dynamicImports && fe.dynamicImports > 0) {
-            blindSpots.dynamicImports.count += fe.dynamicImports;
-            if (blindSpots.dynamicImports.files.length < 10) blindSpots.dynamicImports.files.push(rel);
-        }
-        if (fe.parseError) {
-            blindSpots.parseFailures.count++;
-            if (blindSpots.parseFailures.files.length < 10) blindSpots.parseFailures.files.push(rel);
-        }
+        const recordBlind = (cat, occurrences) => {
+            if (occurrences <= 0) return;
+            cat.count += occurrences;
+            cat.fileCount++;
+            if (cat.files.length < BLINDSPOT_FILE_CAP) cat.files.push(rel);
+        };
+
+        if (fe.dynamicImports && fe.dynamicImports > 0) recordBlind(blindSpots.dynamicImports, fe.dynamicImports);
+        if (fe.parseError) recordBlind(blindSpots.parseFailures, 1);
 
-        // Read file once for eval/reflection signals
-        const evalRe = EVAL_PATTERNS[lang];
-        const reflRe = REFLECTION_PATTERNS[lang];
-        if (evalRe || reflRe) {
+        // Read file once for eval/reflection signals (shared counter).
+        if (hasTextBlindspots(lang)) {
             try {
-                const content = fs.readFileSync(filePath, 'utf-8');
-                if (evalRe && evalRe.test(content)) {
-                    blindSpots.evalCalls.count++;
-                    if (blindSpots.evalCalls.files.length < 10) blindSpots.evalCalls.files.push(rel);
-                }
-                if (reflRe && reflRe.test(content)) {
-                    blindSpots.reflection.count++;
-                    if (blindSpots.reflection.files.length < 10) blindSpots.reflection.files.push(rel);
-                }
+                const bs = countTextBlindspots(fs.readFileSync(filePath, 'utf-8'), lang);
+                recordBlind(blindSpots.evalCalls, bs.eval);
+                recordBlind(blindSpots.reflection, bs.reflection);
             } catch (e) { /* ignore read errors */ }
         }
     }
@@ -620,57 +608,87 @@ function doctor(index, options = {}) {
 
     // Compute trust verdict.
     //
-    // 1. If a deep sample produced no edges (empty project, --in matches nothing),
-    //    don't pretend that's "0% confident" — return UNKNOWN.
-    // 2. Coverage gives the headline %, but blind spots (eval/reflection/dynamic
-    //    imports) downgrade the verdict by one tier each — a project that resolves
-    //    99% of edges but is full of `getattr` is not actually "HIGH" trust.
-    // 3. Parse failures always cap at MEDIUM regardless of coverage.
+    // Field-report #1: the old logic dropped the tier by one PER blind-spot
+    // category present, so any non-trivial Python/TS project (all of which have
+    // some getattr/eval/dynamic import) was forced to LOW even when --deep
+    // measured ~99% of edges at confidence ≥ 0.5 — a self-contradicting verdict
+    // ("99.1% ... LOW") that trains agents to distrust a healthy index. The fix:
+    //   - When --deep coverage exists it drives the tier. Coverage measures the
+    //     CONFIDENCE of edges UCN FOUND, NOT completeness — a reflection-hidden
+    //     edge is absent from the sample, never a low-confidence edge dragging
+    //     the % down — so sparse blind spots are a CAVEAT, while PERVASIVE ones
+    //     (a large share of files) can hide edges the sample can't see and cap
+    //     the verdict at MEDIUM (density, not mere presence; see below).
+    //   - Parse failures are a separate exception: a file UCN couldn't parse is
+    //     not in the sample at all, a genuine uncounted hole → cap at MEDIUM.
+    //   - Without --deep there is no measurement, so blind spots are the only
+    //     signal — but bounded to ONE tier total (not one per category), so a
+    //     handful of getattr doesn't read as untrustworthy.
     let trust = 'UNKNOWN';
     let trustReason = '';
-    const reasons = [];
+    const tier = ['HIGH', 'MEDIUM', 'LOW'];
+
+    const blindSignals = [];
+    if (blindSpots.parseFailures.count > 0) blindSignals.push(`${blindSpots.parseFailures.count} parse failure(s)`);
+    if (blindSpots.evalCalls.count > 0) blindSignals.push(`${blindSpots.evalCalls.count} eval/exec use(s) in ${blindSpots.evalCalls.fileCount} file(s)`);
+    if (blindSpots.reflection.count > 0) blindSignals.push(`${blindSpots.reflection.count} reflection use(s) in ${blindSpots.reflection.fileCount} file(s)`);
+    if (blindSpots.dynamicImports.count > 0) blindSignals.push(`${blindSpots.dynamicImports.count} dynamic import(s) in ${blindSpots.dynamicImports.fileCount} file(s)`);
 
     if (coverage && coverage.total > 0) {
         const safe = coverage.high + coverage.medium;
         const safePct = safe / coverage.total;
-        let baseLevel;
-        if (safePct >= 0.85) baseLevel = 'HIGH';
-        else if (safePct >= 0.6) baseLevel = 'MEDIUM';
-        else baseLevel = 'LOW';
-        reasons.push(`${(safePct * 100).toFixed(1)}% of edges have confidence ≥ 0.5`);
-
-        // Blind-spot downgrades — each kind drops one tier.
-        const tier = ['HIGH', 'MEDIUM', 'LOW'];
-        let idx = tier.indexOf(baseLevel);
-        const blindSignals = [];
-        if (blindSpots.parseFailures.count > 0) { idx = Math.max(idx, 1); blindSignals.push(`${blindSpots.parseFailures.count} parse failure(s)`); }
-        if (blindSpots.evalCalls.count > 0) { idx = Math.min(2, idx + 1); blindSignals.push(`${blindSpots.evalCalls.count} eval call(s)`); }
-        if (blindSpots.reflection.count > 0) { idx = Math.min(2, idx + 1); blindSignals.push(`${blindSpots.reflection.count} reflection use(s)`); }
-        if (blindSpots.dynamicImports.count > 0) { idx = Math.min(2, idx + 1); blindSignals.push(`${blindSpots.dynamicImports.count} dynamic import(s)`); }
+        let idx = safePct >= 0.85 ? 0 : safePct >= 0.6 ? 1 : 2;
+        // Parse failures: unparsed files aren't in the sample at all.
+        if (blindSpots.parseFailures.count > 0) idx = Math.max(idx, 1);
+        // Coverage measures the CONFIDENCE of edges UCN found, NOT completeness:
+        // a call hidden behind reflection/dynamic dispatch is simply absent from
+        // findCallers' result, never a low-confidence edge that drags the % down.
+        // So when blind spots are PERVASIVE — affecting a large share of files —
+        // they can hide a real fraction of the call graph that the sample can't
+        // see, and the verdict is capped at MEDIUM. Density, not mere presence:
+        // a handful of getattr stays a caveat (the old code dropped a tier per
+        // category, forcing every project to LOW); reflection across half the
+        // files does cap. Gated on a file-count floor — file share is meaningless
+        // for a handful of files, so small projects ride on coverage alone.
+        const scanned = fileCounts.scanned || 1;
+        const share = (fc) => fc / scanned;
+        const pervasiveBlindSpot = scanned >= 10 && (
+            share(blindSpots.reflection.fileCount) >= 0.5 ||
+            share(blindSpots.dynamicImports.fileCount) >= 0.4 ||
+            share(blindSpots.evalCalls.fileCount) >= 0.15
+        );
+        const baseIdx = idx;
+        if (pervasiveBlindSpot) idx = Math.max(idx, 1);
+        const capped = idx > baseIdx;
         trust = tier[idx];
-        if (blindSignals.length) reasons.push(`blind spots: ${blindSignals.join(', ')}`);
+        const reasons = [`${(safePct * 100).toFixed(1)}% of found edges have confidence ≥ 0.5`];
+        if (blindSignals.length) {
+            reasons.push(capped
+                ? `capped at MEDIUM — pervasive blind spots may hide edges the sample can't see: ${blindSignals.join(', ')}`
+                : `blind spots (caveat — coverage measures found edges, not completeness): ${blindSignals.join(', ')}`);
+        }
         trustReason = reasons.join('; ');
     } else if (coverage) {
         // Sampled but zero edges — can't say anything about confidence.
         trust = 'UNKNOWN';
         trustReason = 'no edges sampled (empty scope or filter matched nothing)';
     } else if (fileCounts.scanned > 0) {
-        // Cheap path (no --deep): use blind-spot signals.
-        const tier = ['HIGH', 'MEDIUM', 'LOW'];
+        // Cheap path (no --deep): no measurement, so blind spots are the only
+        // signal — bounded to one tier total. Run --deep for a measured verdict.
         let idx = 0;
-        const blindSignals = [];
-        if (blindSpots.parseFailures.count > 0) { idx = Math.max(idx, 1); blindSignals.push(`${blindSpots.parseFailures.count} parse failure(s)`); }
-        if (blindSpots.evalCalls.count > 0) { idx = Math.min(2, idx + 1); blindSignals.push(`${blindSpots.evalCalls.count} eval call(s)`); }
-        if (blindSpots.reflection.count > 0) { idx = Math.min(2, idx + 1); blindSignals.push(`${blindSpots.reflection.count} reflection use(s)`); }
-        if (blindSpots.dynamicImports.count > 0) { idx = Math.min(2, idx + 1); blindSignals.push(`${blindSpots.dynamicImports.count} dynamic import(s)`); }
+        if (blindSpots.parseFailures.count > 0) idx = Math.max(idx, 1);
+        if (blindSpots.evalCalls.count + blindSpots.reflection.count + blindSpots.dynamicImports.count > 0) {
+            idx = Math.min(2, idx + 1);
+        }
         trust = tier[idx];
         trustReason = blindSignals.length
-            ? `coverage not deep-checked; blind spots: ${blindSignals.join(', ')}`
-            : 'no parse failures; coverage not deep-checked';
+            ? `coverage not deep-checked (run --deep); blind spots: ${blindSignals.join(', ')}`
+            : 'no parse failures; coverage not deep-checked (run --deep)';
     }
 
     return {
         root: index.root,
+        version: require('../package.json').version,  // running ucn version — surfaces MCP/CLI drift (field-report #3)
         files: fileCounts,
         symbols: totalSymbols,
         languages: langs,

package/core/shared.js

@@ -139,6 +139,69 @@ function looksLikeHandle(input) {
     return /^.+:\d+(?::.+)?$/.test(input);
 }
 
+/**
+ * Explicit override marker on a method definition (fix #210). Marker fields are
+ * language-disjoint and compiler-checked syntax (never inferred): traitImpl is
+ * Rust's `impl Trait`, an 'override' modifier is Java's lowercased @Override, an
+ * override-bearing memberType is TS's `override` keyword, and an override
+ * decorator is Python's typing.@override. Shared by the external-contract
+ * reasoning in both the caller dispatch gate and deadcode (out-of-tree override
+ * suppression) — one source of truth so a new marker is added once, not in two
+ * drifting copies.
+ */
+function isOverrideMarked(def) {
+    if (def.traitImpl) return true;
+    const mods = def.modifiers || [];
+    if (mods.includes('override')) return true;
+    if (def.memberType && /\boverride\b/.test(def.memberType)) return true;
+    if (def.decorators && def.decorators.some(d =>
+        String(d).replace(/\(.*$/, '').split('.').pop() === 'override')) return true;
+    return false;
+}
+
+// Per-language text patterns for the "blind spots" UCN's AST can't follow:
+// eval/exec-style code execution and reflection (dynamic attribute access /
+// dynamic dispatch). ONE source of truth so doctor's trust scan and
+// detectCompleteness's about-footer warning count identically (field-report #2:
+// they used to diverge — doctor 497 reflection vs footer 194, eval 3 vs 2 —
+// because each kept its own regex set). Dynamic imports are NOT here: those are
+// structural (fileEntry.dynamicImports), the AST-accurate count both paths share.
+// `new Function(...)` is categorized as eval (code execution), not reflection.
+const BLINDSPOT_TEXT_PATTERNS = {
+    reflection: {
+        python:     /\b(getattr|hasattr|setattr|__import__|importlib\.import_module)\s*\(/g,
+        javascript: /\bReflect\.\w+\s*\(/g,
+        typescript: /\bReflect\.\w+\s*\(/g,
+        go:         /\breflect\.\w+\s*\(/g,
+        java:       /\.getDeclaredMethod\b|\.getMethod\b|\.getDeclaredField\b|Class\.forName\b/g,
+        rust:       /\bAny::downcast/g,
+    },
+    eval: {
+        python:     /\b(eval|exec)\s*\(/g,
+        javascript: /\beval\s*\(|\bnew\s+Function\s*\(/g,
+        typescript: /\beval\s*\(|\bnew\s+Function\s*\(/g,
+    },
+};
+
+/** True when a language has any text-blind-spot pattern (so callers can skip the file read otherwise). */
+function hasTextBlindspots(language) {
+    return !!(BLINDSPOT_TEXT_PATTERNS.reflection[language] || BLINDSPOT_TEXT_PATTERNS.eval[language]);
+}
+
+/**
+ * Count text-detected blind spots (eval/exec, reflection) in one file's source.
+ * Returns { eval, reflection } OCCURRENCE counts (global match). Shared by doctor
+ * and detectCompleteness so both report the same numbers (field-report #2).
+ */
+function countTextBlindspots(content, language) {
+    const reRe = BLINDSPOT_TEXT_PATTERNS.reflection[language];
+    const evRe = BLINDSPOT_TEXT_PATTERNS.eval[language];
+    return {
+        eval: evRe ? (content.match(evRe) || []).length : 0,
+        reflection: reRe ? (content.match(reRe) || []).length : 0,
+    };
+}
+
 module.exports = {
     pickBestDefinition,
     addTestExclusions,
@@ -148,4 +211,7 @@ module.exports = {
     parseSymbolHandle,
     looksLikeHandle,
     isTestPath,
+    isOverrideMarked,
+    hasTextBlindspots,
+    countTextBlindspots,
 };

package/mcp/server.js

@@ -576,7 +576,8 @@ server.registerTool(
                 let dcText = output.formatDeadcode(result, {
                     top: ep.top || 0,
                     decoratedHint: !ep.includeDecorated && result.excludedDecorated > 0 ? `${result.excludedDecorated} decorated/annotated symbol(s) hidden (framework-registered). Use include_decorated=true to include them.` : undefined,
-                    exportedHint: !ep.includeExported && result.excludedExported > 0 ? `${result.excludedExported} exported symbol(s) excluded (all have callers). Use include_exported=true to audit them.` : undefined
+                    exportedHint: !ep.includeExported && result.excludedExported > 0 ? `${result.excludedExported} exported symbol(s) excluded (all have callers). Use include_exported=true to audit them.` : undefined,
+                    externalContractHint: !ep.includeExported && result.excludedExternalContract > 0 ? `${result.excludedExternalContract} symbol(s) hidden (override an out-of-tree base class — reachable via external contract, not dead). Use include_exported=true to include them.` : undefined
                 });
                 if (dcNote) dcText += '\n\n' + dcNote;
                 return tr(dcText);
@@ -790,7 +791,9 @@ server.registerTool(
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error('UCN MCP server running on stdio');
+    // Print the running version so MCP-vs-CLI drift is visible (field-report #3:
+    // a stale `npx -y ucn` cache can silently run an older engine than the CLI).
+    console.error(`UCN MCP server v${require('../package.json').version} running on stdio`);
 }
 
 main().catch(e => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "mcpName": "io.github.mleoca/ucn",
   "description": "Code intelligence toolkit for AI agents — extract functions, trace call chains, find callers, detect dead code without reading entire files. Works as MCP server, CLI, or agent skill. Supports JS/TS, Python, Go, Rust, Java.",
   "main": "index.js",