ucn 4.1.2 → 4.2.1

package/core/check.js

@@ -11,7 +11,33 @@
 
 'use strict';
 
-const { diffImpact } = require('./analysis');
+const { diffImpact, composeAccount, callNotResolvedEntries } = require('./analysis');
+
+function summarizeAccount(account) {
+    if (!account) {
+        return {
+            available: false,
+            textComplete: false,
+            semanticComplete: false,
+            safeToDelete: false,
+        };
+    }
+    const contract = account.contract || {};
+    return {
+        available: true,
+        conserved: account.conserved === true,
+        textComplete: contract.textComplete === true,
+        observedTextZero: contract.observedTextZero === true,
+        semanticComplete: false,
+        safeToDelete: false,
+        unparsedFiles: account.unparsed ? account.unparsed.fileCount || 0 : 0,
+        unreadableFiles: Array.isArray(account.unreadableFiles) ? account.unreadableFiles.length : 0,
+        unaccounted: account.unaccounted || 0,
+        filtered: account.filtered ? account.filtered.total || 0 : 0,
+        beyondTextCallers: account.beyondText ? account.beyondText.count || 0 : 0,
+        requiresUsageReview: contract.requiresUsageReview === true,
+    };
+}
 
 /**
  * Run the pre-commit check.
@@ -61,12 +87,11 @@ function check(index, options = {}) {
     const changed = limit ? allChanged.slice(0, limit) : allChanged;
 
     const items = [];
-    const reachable = computeReachableSet(index);
 
     // For each changed function, run verify and gather caller summary
     for (const fn of changed) {
         const filePath = fn.relativePath || fn.file || '';
-        let verifyResult = null;
+        let verifyResult;
         try {
             verifyResult = index.verify(fn.name, { file: filePath });
         } catch (e) {
@@ -81,12 +106,22 @@ function check(index, options = {}) {
         // bands already (confirmed `callers` + visible `unverifiedCallers`).
         let callers = Array.isArray(fn.callers) ? fn.callers : [];
         let unverifiedCallers = Array.isArray(fn.unverifiedCallers) ? fn.unverifiedCallers : [];
+        let account = fn.account || null;
         if (callers.length === 0 && fn._kind === 'added') {
             try {
-                const raw = index.findCallers(fn.name, { includeMethods: true, collectAccount: true }) || [];
+                const definitions = (index.symbols.get(fn.name) || []).filter(d =>
+                    (d.relativePath === filePath || d.file === fn.filePath) &&
+                    (!fn.startLine || d.startLine === fn.startLine));
+                const raw = index.findCallers(fn.name, {
+                    includeMethods: true,
+                    collectAccount: true,
+                    targetDefinitions: definitions.length > 0 ? definitions : undefined,
+                }) || [];
                 callers = raw.filter(c => c.tier !== 'unverified');
                 unverifiedCallers = raw.filter(c => c.tier === 'unverified')
                     .concat(raw.unverifiedEntries || []);
+                account = composeAccount(index, fn.name, raw);
+                unverifiedCallers = unverifiedCallers.concat(callNotResolvedEntries(index, account));
             } catch (e) { /* skip */ }
         }
 
@@ -98,6 +133,7 @@ function check(index, options = {}) {
             callerCount: callers.length,
             unverifiedCallerCount: unverifiedCallers.length,
             signatureMismatches: mismatches.length,
+            account: summarizeAccount(account),
             ...(mismatches.length > 0 && { mismatches: mismatches.slice(0, 5) }),
         };
 
@@ -134,6 +170,13 @@ function check(index, options = {}) {
             callerCount: 0,
             unverifiedCallerCount: (d.remainingCallSites || []).length,
             signatureMismatches: 0,
+            account: {
+                available: false,
+                reason: 'deleted-target-cannot-be-reconciled-against-the-current-index',
+                textComplete: false,
+                semanticComplete: false,
+                safeToDelete: false,
+            },
         });
     }
 
@@ -157,6 +200,34 @@ function check(index, options = {}) {
     // Action items
     const actions = [];
     for (const it of items) {
+        if (!it.account || !it.account.textComplete) {
+            actions.push({
+                severity: 'error',
+                kind: 'incomplete_account',
+                message: `${it.name}: caller evidence is not text-complete; inspect warnings and usages manually`,
+            });
+        }
+        if (it.unverifiedCallerCount > 0) {
+            actions.push({
+                severity: 'warn',
+                kind: 'unverified_callers',
+                message: `${it.name}: review ${it.unverifiedCallerCount} unverified caller candidate(s)`,
+            });
+        }
+        if (it.account && it.account.filtered > 0) {
+            actions.push({
+                severity: 'warn',
+                kind: 'filtered_evidence',
+                message: `${it.name}: ${it.account.filtered} caller edge(s) were hidden by filters`,
+            });
+        }
+        if (it.account && it.account.requiresUsageReview) {
+            actions.push({
+                severity: 'warn',
+                kind: 'non_call_usages',
+                message: `${it.name}: non-call references require a usages review`,
+            });
+        }
         if (it.signatureMismatches > 0) {
             actions.push({
                 severity: 'warn',
@@ -168,10 +239,17 @@ function check(index, options = {}) {
             actions.push({
                 severity: 'warn',
                 kind: 'orphan_new',
-                message: `${it.name} is new but has no callers (confirmed or unverified) and is not an entry point`,
+                message: `${it.name} is new with no observed caller candidates and is not a detected entry point; review usages before treating it as orphaned`,
             });
         }
     }
+    if (limit && allChanged.length > limit) {
+        actions.push({
+            severity: 'error',
+            kind: 'truncated_change_set',
+            message: `${allChanged.length - limit} changed function(s) were not checked; rerun without --limit`,
+        });
+    }
     if (testFiles.length > 0) {
         const filesList = testFiles.slice(0, 5).map(t => t.file).join(' ');
         actions.push({
@@ -181,6 +259,16 @@ function check(index, options = {}) {
         });
     }
 
+    const incompleteAccounts = items.filter(it => !it.account || !it.account.textComplete).length;
+    const unverifiedCallSites = items.reduce((sum, it) => sum + (it.unverifiedCallerCount || 0), 0);
+    const signatureMismatches = items.reduce((sum, it) => sum + (it.signatureMismatches || 0), 0);
+    const filteredEdges = items.reduce((sum, it) => sum + (it.account ? it.account.filtered || 0 : 0), 0);
+    const usageReviewSymbols = items.filter(it => it.account && it.account.requiresUsageReview).length;
+    const reviewRequired = incompleteAccounts > 0 || unverifiedCallSites > 0 ||
+        signatureMismatches > 0 || filteredEdges > 0 || usageReviewSymbols > 0 ||
+        actions.some(a => a.kind === 'orphan_new') ||
+        !!(limit && allChanged.length > limit);
+
     return {
         base: options.base || 'HEAD',
         staged: !!options.staged,
@@ -191,21 +279,21 @@ function check(index, options = {}) {
         totalTestFiles: testFiles.length,
         totalTests: testCount,
         actions,
+        trust: {
+            status: incompleteAccounts > 0 || signatureMismatches > 0
+                ? 'BLOCKED'
+                : reviewRequired ? 'REVIEW_REQUIRED' : 'READY_FOR_TOOLCHAIN',
+            accountsChecked: items.filter(it => it.account && it.account.available).length,
+            incompleteAccounts,
+            unverifiedCallSites,
+            signatureMismatches,
+            filteredEdges,
+            usageReviewSymbols,
+            semanticComplete: false,
+            safeToDelete: false,
+            requiresCompilerAndTests: true,
+        },
     };
 }
 
-function symbolKey(file, line) {
-    return `${file}:${line}`;
-}
-
-function computeReachableSet(index) {
-    try {
-        const ep = require('./entrypoints');
-        if (typeof ep.computeReachability === 'function') {
-            return ep.computeReachability(index);
-        }
-    } catch (e) { /* fall through */ }
-    return null;
-}
-
 module.exports = { check };

package/core/confidence.js

@@ -1,8 +1,9 @@
 /**
  * core/confidence.js - Deterministic edge confidence scoring
  *
- * Assigns a 0.0-1.0 confidence score to each caller/callee edge based on
- * how the call was resolved. Rule-based, no ML.
+ * Assigns an ordinal 0.0-1.0 evidence weight to each caller/callee edge based
+ * on how the call was resolved. Rule-based, no ML. These values rank evidence;
+ * they are NOT probabilities and are NOT calibrated accuracy estimates.
  */
 
 'use strict';
@@ -19,7 +20,8 @@ const RESOLUTION = {
     UNCERTAIN:        'uncertain',
 };
 
-// Seed scores per resolution type (tunable)
+// Ordinal evidence weights per resolution type. The legacy public field is
+// named `confidence` for compatibility; do not interpret 0.98 as "98% likely".
 const SCORES = {
     [RESOLUTION.EXACT_BINDING]:    0.98,
     [RESOLUTION.SAME_CLASS]:       0.92,
@@ -59,6 +61,17 @@ function tierForResolution(resolution) {
     return RESOLUTION_TIER[resolution] || TIER.UNVERIFIED;
 }
 
+function scored(resolution, reasons) {
+    const evidenceScore = SCORES[resolution];
+    return {
+        confidence: evidenceScore,
+        evidenceScore,
+        scoreKind: 'ordinal-evidence-not-probability',
+        resolution,
+        evidence: reasons,
+    };
+}
+
 /**
  * Score a caller/callee edge based on resolution evidence.
  *
@@ -71,7 +84,7 @@ function tierForResolution(resolution) {
  * @param {boolean} [evidence.isUncertain] - Marked uncertain by resolution logic
  * @param {boolean} [evidence.isFunctionReference] - Passed as callback argument
  * @param {boolean} [evidence.hasReceiverType] - Go/Java/Rust parser-inferred receiverType
- * @returns {{ confidence: number, resolution: string, evidence: string[] }}
+ * @returns {{ confidence: number, evidenceScore: number, scoreKind: string, resolution: string, evidence: string[] }}
  */
 function scoreEdge(evidence) {
     const reasons = [];
@@ -81,38 +94,38 @@ function scoreEdge(evidence) {
     // (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 };
+        return scored(RESOLUTION.UNCERTAIN, 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 };
+        return scored(RESOLUTION.POSSIBLE_DISPATCH, reasons);
     }
     if (evidence.methodAmbiguous) {
         reasons.push('untyped receiver, multiple same-name definitions');
-        return { confidence: SCORES[RESOLUTION.METHOD_AMBIGUOUS], resolution: RESOLUTION.METHOD_AMBIGUOUS, evidence: reasons };
+        return scored(RESOLUTION.METHOD_AMBIGUOUS, reasons);
     }
 
     // Exact binding match (highest confidence)
     if (evidence.hasBindingId) {
         reasons.push('binding-id match');
         if (evidence.hasImportEvidence) reasons.push('import-verified');
-        return { confidence: SCORES[RESOLUTION.EXACT_BINDING], resolution: RESOLUTION.EXACT_BINDING, evidence: reasons };
+        return scored(RESOLUTION.EXACT_BINDING, reasons);
     }
 
     // Same-class resolution (self/this/super/cls)
     if (evidence.resolvedBySameClass) {
         reasons.push('same-class method');
         if (evidence.hasInheritanceChain) reasons.push('via inheritance');
-        return { confidence: SCORES[RESOLUTION.SAME_CLASS], resolution: RESOLUTION.SAME_CLASS, evidence: reasons };
+        return scored(RESOLUTION.SAME_CLASS, reasons);
     }
 
     // Receiver hint narrowed to specific type
     if (evidence.resolvedByReceiverHint || evidence.hasReceiverType) {
         reasons.push(evidence.hasReceiverType ? 'parser receiver-type' : 'local type inference');
-        return { confidence: SCORES[RESOLUTION.RECEIVER_HINT], resolution: RESOLUTION.RECEIVER_HINT, evidence: reasons };
+        return scored(RESOLUTION.RECEIVER_HINT, reasons);
     }
 
     // Function reference (callback / passed-as-argument). Argument position is
@@ -123,10 +136,10 @@ function scoreEdge(evidence) {
         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 };
+            return scored(RESOLUTION.SCOPE_MATCH, reasons);
         }
         reasons.push('no import evidence');
-        return { confidence: SCORES[RESOLUTION.NAME_ONLY], resolution: RESOLUTION.NAME_ONLY, evidence: reasons };
+        return scored(RESOLUTION.NAME_ONLY, reasons);
     }
 
     // Scope/import-supported match
@@ -134,22 +147,22 @@ function scoreEdge(evidence) {
         if (evidence.hasImportEvidence) reasons.push('import-supported');
         if (evidence.hasReceiverEvidence) reasons.push('receiver binding in scope');
         if (evidence.hasSamePackageEvidence) reasons.push('same package/module');
-        return { confidence: SCORES[RESOLUTION.SCOPE_MATCH], resolution: RESOLUTION.SCOPE_MATCH, evidence: reasons };
+        return scored(RESOLUTION.SCOPE_MATCH, reasons);
     }
 
     // Uncertain
     if (evidence.isUncertain) {
         reasons.push('ambiguous resolution');
-        return { confidence: SCORES[RESOLUTION.UNCERTAIN], resolution: RESOLUTION.UNCERTAIN, evidence: reasons };
+        return scored(RESOLUTION.UNCERTAIN, reasons);
     }
 
     // Name-only match (no additional evidence)
     reasons.push('name match only');
-    return { confidence: SCORES[RESOLUTION.NAME_ONLY], resolution: RESOLUTION.NAME_ONLY, evidence: reasons };
+    return scored(RESOLUTION.NAME_ONLY, reasons);
 }
 
 /**
- * Filter edges by minimum confidence threshold.
+ * Filter edges by minimum ordinal evidence threshold (legacy name retained).
  * @param {Array} edges - Array of objects with .confidence property
  * @param {number} minConfidence - Minimum confidence (0.0-1.0)
  * @returns {{ kept: Array, filtered: number }}

package/core/deadcode.js

@@ -53,32 +53,90 @@ function _baseIsExternal(index, bare, lang) {
     return !(defs && defs.some(d => _CLASS_KINDS.includes(d.type)));
 }
 
-/** Does this CLASS DEF extend at least one base that is not in the project index? */
-function _classDefHasExternalBase(index, classDef, lang) {
-    if (!classDef.extends) return false;
-    const supers = Array.isArray(classDef.extends) ? classDef.extends : splitParentList(classDef.extends);
-    return supers.some(raw => _baseIsExternal(index, _bareBaseName(raw), lang));
-}
+// Bounded heritage-closure depth (fix #270) — matches the engine's other
+// inheritance walks.
+const _HERITAGE_WALK_DEPTH = 8;
 
 /**
- * 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.
+ * Does this CLASS DEF reach at least one base that is NOT in the project
+ * index, walking `extends` chains transitively THROUGH resolved project types
+ * (fix #270)? One level was not enough — fastify-measured: CustomLoggerImpl
+ * implements CustomLogger (project) extends FastifyBaseLogger (project,
+ * .d.ts) extends Pick<BaseLogger, ...'silent'> (pino — external). The member
+ * surface the class must provide comes from the OUT-OF-TREE end of the chain,
+ * invisible without tsc, so a zero-usage impl member (`silent`) is contract
+ * surface — deleting it breaks the build. Same dispatch physics as one level;
+ * only the verdict moved from "direct parent external" to "heritage closure
+ * reaches external".
  *
- * `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.
+ * `followImplements` additionally walks the def's OWN `implements` clause
+ * (first hop only — the measured family; deeper implements hops are
+ * classified-deferred). Method claims pass true only when the member sits
+ * INSIDE the def's source range: TS/Java members live in the class body, so
+ * the implements contract constrains them. Rust surfaces trait impls as
+ * `implements` on the struct (rust.js), but inherent methods live in separate
+ * `impl X` blocks OUTSIDE the struct's range — an unrelated `impl Display
+ * for X` must never shield a genuinely-dead inherent method (the original
+ * reason implements was not consulted here at all; trait-impl members
+ * themselves carry traitImpl/@Override markers → Rule A). Class-kind claims
+ * pass false: deleting the whole class removes its implements clause with it.
+ */
+function _heritageReachesExternalBase(index, classDef, lang, followImplements) {
+    const seen = new Set();
+    let frontier = [classDef];
+    for (let depth = 0; depth < _HERITAGE_WALK_DEPTH && frontier.length; depth++) {
+        const next = [];
+        for (const def of frontier) {
+            // Copy array-shaped extends — the implements push below must
+            // never mutate the symbol's own heritage data in the index.
+            const parents = def.extends
+                ? (Array.isArray(def.extends) ? [...def.extends] : splitParentList(def.extends))
+                : [];
+            if (depth === 0 && followImplements && Array.isArray(def.implements)) {
+                parents.push(...def.implements);
+            }
+            for (const raw of parents) {
+                const bare = _bareBaseName(raw);
+                if (!bare || seen.has(bare)) continue;
+                seen.add(bare);
+                if (_baseIsExternal(index, bare, lang)) return true;
+                for (const pd of index.symbols.get(bare) || []) {
+                    if (_CLASS_KINDS.includes(pd.type)) next.push(pd);
+                }
+            }
+        }
+        frontier = next;
+    }
+    return false;
+}
+
+/**
+ * Does the method's enclosing class reach at least one base that is NOT in
+ * the project index through its heritage closure? 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), by name convention (Pydantic → bytes_schema), or
+ * REQUIRE the member outright (fastify → CustomLoggerImpl.silent, via an
+ * implements chain ending in pino). The class def is matched in the method's
+ * own file; `implements` is walked only when the member sits inside the class
+ * def's own range (see _heritageReachesExternalBase — the Rust guard).
  */
 function _classHasExternalBase(index, symbol) {
     const lang = index.files.get(symbol.file)?.language;
+    // The implements hop shields only contract-SATISFIABLE members: an
+    // interface implementation must be public, so in explicit-visibility
+    // languages a package-private/non-pub member provably cannot implement
+    // any interface member (javac rejects it) — `implements Runnable` never
+    // shields a package-private helper. Implicit-public languages satisfy
+    // contracts with unmarked members; the caller's public-by-shape check
+    // already screened those. Compiler physics, not a heuristic.
+    const contractSatisfiable = langTraits(lang)?.implicitlyPublicMembers ||
+        (symbol.modifiers || []).includes('public');
     const classDefs = (index.symbols.get(symbol.className) || []).filter(c =>
         c.file === symbol.file && _CLASS_KINDS.includes(c.type));
-    return classDefs.some(cd => _classDefHasExternalBase(index, cd, lang));
+    return classDefs.some(cd => _heritageReachesExternalBase(index, cd, lang,
+        contractSatisfiable &&
+        symbol.startLine >= cd.startLine && symbol.startLine <= cd.endLine));
 }
 
 /**
@@ -92,9 +150,12 @@ function _classHasExternalBase(index, symbol) {
  *       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).
+ *   (B) a public-by-shape method whose class reaches an unresolved base
+ *       through its heritage closure (extends chains walked transitively,
+ *       plus the class's own `implements` clause when the member sits in the
+ *       class body — fix #270). 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.
@@ -147,8 +208,7 @@ function nameOnlySelfRecursive(index, name) {
     }
     const { getCachedCalls } = require('./callers');
     for (const f of files) {
-        let calls;
-        try { calls = getCachedCalls(index, f); } catch { return false; }
+        const calls = getCachedCalls(index, f);
         if (!calls) return false;
         for (const call of calls) {
             if (call.name !== name && call.resolvedName !== name &&
@@ -950,7 +1010,7 @@ function deadcode(index, options = {}) {
                 // by module path, pytest plugins by registration) — zero
                 // in-project references is not evidence of deadness there.
                 const isExternalContract = classAuditSet.has(symbol.type)
-                    ? _classDefHasExternalBase(index, symbol, lang)
+                    ? _heritageReachesExternalBase(index, symbol, lang, false)
                     : overridesOutOfTreeBase(index, symbol);
                 if (isExternalContract && !options.includeExported) {
                     excludedExternalContract++;

package/core/entrypoints.js

@@ -943,29 +943,27 @@ function detectEntrypoints(index, options = {}) {
             // (3) Top-level invocation targets: any non-method call with no
             //     enclosingFunction is module-load-time, so its callee is reachable.
             //     We treat the callee as an entry point (the function being kicked off).
-            try {
-                const calls = getCachedCalls(index, filePath);
-                if (calls && calls.length > 0) {
-                    for (const c of calls) {
-                        if (c.enclosingFunction != null) continue;
-                        if (c.isMethod) continue;
-                        // Resolve callee names (handles aliased imports)
-                        const names = c.resolvedNames || (c.resolvedName ? [c.resolvedName] : [c.name]);
-                        for (const n of names) {
-                            if (index.symbols.has(n)) allowed.add(n);
-                        }
+            const calls = getCachedCalls(index, filePath);
+            if (calls && calls.length > 0) {
+                for (const c of calls) {
+                    if (c.enclosingFunction != null) continue;
+                    if (c.isMethod) continue;
+                    // Resolve callee names (handles aliased imports)
+                    const names = c.resolvedNames || (c.resolvedName ? [c.resolvedName] : [c.name]);
+                    for (const n of names) {
+                        if (index.symbols.has(n)) allowed.add(n);
                     }
-
-                    // (4) Function containing a top-level `if (require.main === module) { ... }`
-                    //     wrapping calls — captured by treating any non-method call whose
-                    //     enclosingFunction body is at top level. The simplest detection:
-                    //     scan calls inside any function whose body contains the require.main
-                    //     guard. We approximate via the same `enclosingFunction` data: if a
-                    //     function contains top-level invocation-style entries, it's typically
-                    //     identified by the (3) check above. Skip explicit (4) detection here —
-                    //     (3) already covers `if (require.main === module) { main(); }`.
                 }
-            } catch (_e) { /* best-effort */ }
+
+                // (4) Function containing a top-level `if (require.main === module) { ... }`
+                //     wrapping calls — captured by treating any non-method call whose
+                //     enclosingFunction body is at top level. The simplest detection:
+                //     scan calls inside any function whose body contains the require.main
+                //     guard. We approximate via the same `enclosingFunction` data: if a
+                //     function contains top-level invocation-style entries, it's typically
+                //     identified by the (3) check above. Skip explicit (4) detection here —
+                //     (3) already covers `if (require.main === module) { main(); }`.
+            }
 
             // If we identified at least one specific entry, use that set.
             // Otherwise fall back to permissive (null) so a CLI file with neither
@@ -1143,6 +1141,18 @@ function computeReachability(index) {
     const langModuleCache = new Map();
     for (const [, symbols] of index.symbols) {
         for (const symbol of symbols) {
+            // JS/TS module-scope object registries are invoked through dynamic
+            // property access (HANDLERS[command](...)). There may be no static
+            // incoming edge to discover. Treat these members as conservative
+            // roots so deadcode never presents a dynamically reachable handler
+            // as safe to remove; callees then flow through the normal BFS.
+            if (symbol.registryMember) {
+                const registryKey = symbolKey(symbol.file, symbol.startLine);
+                if (!reachable.has(registryKey)) {
+                    reachable.add(registryKey);
+                    queue.push(symbol);
+                }
+            }
             const fileEntry = index.files.get(symbol.file);
             if (!fileEntry) continue;
             const lang = fileEntry.language;
@@ -1183,12 +1193,7 @@ function computeReachability(index) {
     for (const [filePath, fileEntry] of index.files) {
         const lang = fileEntry.language;
         if (lang !== 'javascript' && lang !== 'typescript' && lang !== 'tsx') continue;
-        let calls;
-        try {
-            calls = getCachedCalls(index, filePath);
-        } catch (_e) {
-            continue;
-        }
+        const calls = getCachedCalls(index, filePath);
         if (!calls || calls.length === 0) continue;
         for (const call of calls) {
             // Top-level call: AST recorded enclosingFunction === null/undefined.

package/core/execute.js

@@ -241,7 +241,6 @@ function checkFilePatternMatch(index, filePattern) {
         if (fileEntry.relativePath.includes(filePattern)) return null;
     }
     // Suggest similar directories/files to help user refine
-    const patternLower = filePattern.toLowerCase();
     const basename = filePattern.split('/').pop().toLowerCase();
     const suggestions = new Set();
     for (const [, fileEntry] of index.files) {
@@ -493,6 +492,7 @@ const HANDLERS = {
     example: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
+        const targetWasHandle = looksLikeHandle(p.name);
         applyClassMethodSyntax(p);
         const fileErr = checkFilePatternMatch(index, p.file);
         if (fileErr) return { ok: false, error: fileErr };
@@ -501,6 +501,12 @@ const HANDLERS = {
         const result = index.example(p.name, {
             file: p.file,
             className: p.className,
+            line: p.line,
+            // Preserve legacy plain-name `--file` as a call-site scope while
+            // letting a stable handle use its file component purely as exact
+            // target identity. Without this distinction, handles could never
+            // find examples outside the definition file.
+            callSiteFile: !targetWasHandle ? p.file : null,
             diverse: !!p.diverse,
             top: num(p.top, undefined),
             // MEDIUM-8: thread includeTests so test-file callers are included
@@ -583,7 +589,6 @@ const HANDLERS = {
             in: p.in,
             file: p.file,
             deep: !!p.deep,
-            sampleSize: num(p.limit, undefined),
         });
         return { ok: true, result };
     },
@@ -832,10 +837,21 @@ const HANDLERS = {
         // splitting would shear the filename at the dot into
         // className='helper', name='go' and silently return nothing
         // (fix #239, G3-go-measured). Mirror the engine's file-path test.
-        const testsTargetIsFile = typeof p.name === 'string' && (
+        const testsTargetIsHandle = looksLikeHandle(p.name);
+        const testsTargetIsFile = !testsTargetIsHandle && typeof p.name === 'string' && (
             p.name.includes('/') || p.name.includes('\\') ||
             /\.(js|ts|py|go|java|rs)$/.test(p.name));
         if (!testsTargetIsFile) applyClassMethodSyntax(p);
+        if (testsTargetIsHandle && p.line) {
+            const line = Number(p.line);
+            const pinned = (index.symbols.get(p.name) || []).filter(d =>
+                d.startLine === line && (!p.file || d.relativePath?.includes(p.file)));
+            if (pinned.length === 1 && !p.className && pinned[0].className) {
+                p.className = pinned[0].className;
+            }
+            const pinErr = checkDefinitionPin(index, p);
+            if (pinErr) return { ok: false, error: pinErr };
+        }
         if (p.file) {
             const fileErr = checkFilePatternMatch(index, p.file);
             if (fileErr) return { ok: false, error: fileErr };