ucn 4.0.0 → 4.0.1

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/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/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/shared.js

@@ -139,6 +139,26 @@ 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;
+}
+
 module.exports = {
     pickBestDefinition,
     addTestExclusions,
@@ -148,4 +168,5 @@ module.exports = {
     parseSymbolHandle,
     looksLikeHandle,
     isTestPath,
+    isOverrideMarked,
 };

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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "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",