ucn 4.1.3 → 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

@@ -208,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 &&

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

package/core/graph-build.js

@@ -260,6 +260,39 @@ function buildInheritanceGraph(index) {
                         const alias = fileEntry.importAliases.find(a => a.local === parent);
                         if (alias && classNames.has(alias.original)) return alias.original;
                     }
+                    // Qualified structural parent: `class CustomCommand(
+                    // click.Command)`. The symbol table owns bare class names,
+                    // so keeping `click.Command` makes the subclass invisible
+                    // to dispatch/reachability. Normalize only when the
+                    // qualifier is an actual project module import and its
+                    // bounded import graph reaches exactly one matching class
+                    // definition—never by suffix alone.
+                    if (langTraits(fileEntry.language)?.typeSystem === 'structural' && parent.includes('.')) {
+                        const pieces = parent.split('.');
+                        const localModule = pieces[0];
+                        const className = pieces[pieces.length - 1];
+                        const binding = (fileEntry.importBindings || []).find(b => b.name === localModule);
+                        const rel = binding && fileEntry.moduleResolved?.[binding.module];
+                        if (rel && classNames.has(className)) {
+                            const moduleFile = path.join(index.root, rel);
+                            const candidateFiles = new Set((index.symbols.get(className) || [])
+                                .filter(d => ['class', 'interface', 'struct', 'trait', 'record'].includes(d.type))
+                                .map(d => d.file).filter(Boolean));
+                            const reached = new Set();
+                            const queue = [{ file: moduleFile, depth: 0 }];
+                            const seen = new Set();
+                            while (queue.length > 0) {
+                                const cur = queue.shift();
+                                if (!cur.file || seen.has(cur.file) || cur.depth > 4) continue;
+                                seen.add(cur.file);
+                                if (candidateFiles.has(cur.file)) reached.add(cur.file);
+                                for (const next of index.importGraph.get(cur.file) || []) {
+                                    queue.push({ file: next, depth: cur.depth + 1 });
+                                }
+                            }
+                            if (reached.size === 1) return className;
+                        }
+                    }
                     return parent;
                 });