ucn 3.8.1 → 3.8.3

package/.claude/skills/ucn/SKILL.md

@@ -83,11 +83,23 @@ ucn class MarketDataFetcher
 
 ### 6. `deadcode` — Find unused code
 
-Lists all functions and classes with zero callers across the project.
+Lists all functions and classes with zero callers across the project. Framework entry points (Express routes, Spring controllers, Celery tasks, etc.) are automatically excluded.
 
 ```bash
 ucn deadcode                        # Everything
 ucn deadcode --exclude=test         # Skip test files (most useful)
+ucn deadcode --include-decorated    # Include framework-registered functions
+```
+
+### 7. `entrypoints` — Detect framework entry points
+
+Lists functions registered as framework handlers (HTTP routes, DI beans, job schedulers, etc.). Detects patterns across Express, FastAPI, Flask, Spring, Gin, Actix, Celery, pytest, and more.
+
+```bash
+ucn entrypoints                          # All detected entry points
+ucn entrypoints --type=http              # HTTP routes only
+ucn entrypoints --framework=express      # Specific framework
+ucn entrypoints --file=routes/           # Scoped to files
 ```
 
 ## When to Use the Other Commands
@@ -120,6 +132,7 @@ ucn deadcode --exclude=test         # Skip test files (most useful)
 | Preview a rename or param change | `ucn plan <name> --rename-to=new_name` | Shows what would change without doing it |
 | File-level dependency tree | `ucn graph <file> --depth=1` | Visual import tree. Setting `--depth=N` expands all children. Can be noisy — use depth=1 for large projects. For function-level flow, use `trace` instead |
 | Are there circular dependencies? | `ucn circular-deps` | Detect circular import chains. `--file=<pattern>` filters to cycles involving a file. `--exclude=test` skips test files |
+| What are the framework entry points? | `ucn entrypoints` | Lists all detected routes, DI beans, tasks, etc. Filter: `--type=http`, `--framework=express` |
 | Find which tests cover a function | `ucn tests <name>` | Test files and test function names |
 | Extract specific lines from a file | `ucn lines --file=<file> --range=10-20` | Pull a line range without reading the whole file |
 | Find type definitions | `ucn typedef <name>` | Interfaces, enums, structs, traits, type aliases |
@@ -170,8 +183,11 @@ ucn [target] <command> [name] [--flags]
 | `--case-sensitive` | Case-sensitive text search (default: case-insensitive) |
 | `--exact` | Exact name match only in `find`/`typedef` (no substring) |
 | `--include-uncertain` | Include ambiguous/uncertain matches in `context`/`smart`/`about` |
+| `--show-confidence` | Show confidence scores (0.0–1.0) per caller/callee edge in `context`/`about` |
+| `--min-confidence=N` | Filter edges below confidence threshold (e.g., `--min-confidence=0.7` keeps only high-confidence edges) |
 | `--include-exported` | Include exported symbols in `deadcode` results |
 | `--include-decorated` | Include decorated/annotated symbols in `deadcode` results |
+| `--framework=X` | Filter `entrypoints` by framework (e.g., `express`, `spring`, `celery`) |
 | `--type=<kind>` | Structural search: `function`, `class`, `call`, `method`, `type`. Triggers index query instead of text grep |
 | `--param=<name>` | Structural search: filter by parameter name or type (e.g., `--param=Request`) |
 | `--receiver=<name>` | Structural search: filter calls by receiver (e.g., `--receiver=db` for all db.* calls) |

package/cli/index.js

@@ -112,6 +112,9 @@ function parseFlags(tokens) {
         decorator: getValueFlag('--decorator'),
         exported: tokens.includes('--exported'),
         unused: tokens.includes('--unused'),
+        showConfidence: tokens.includes('--show-confidence'),
+        minConfidence: parseFloat(getValueFlag('--min-confidence') || '0') || 0,
+        framework: getValueFlag('--framework'),
     };
 }
 
@@ -137,7 +140,9 @@ const knownFlags = new Set([
     '--base', '--staged', '--stack',
     '--regex', '--no-regex', '--functions',
     '--max-lines', '--class-name', '--limit', '--max-files',
-    '--type', '--param', '--receiver', '--returns', '--decorator', '--exported', '--unused'
+    '--type', '--param', '--receiver', '--returns', '--decorator', '--exported', '--unused',
+    '--show-confidence', '--min-confidence',
+    '--framework'
 ]);
 
 // Handle help flag
@@ -476,7 +481,8 @@ function runProjectCommand(rootDir, command, arg) {
                 const { text, expandable } = output.formatContext(ctx, {
                     methodsHint: 'Note: obj.method() calls excluded — use --include-methods to include them',
                     expandHint: 'Use "ucn . expand <N>" to see code for item N',
-                    uncertainHint: 'use --include-uncertain to include all'
+                    uncertainHint: 'use --include-uncertain to include all',
+                    showConfidence: flags.showConfidence,
                 });
                 console.log(text);
 
@@ -540,7 +546,7 @@ function runProjectCommand(rootDir, command, arg) {
             if (!ok) fail(error);
             printOutput(result,
                 output.formatAboutJson,
-                r => output.formatAbout(r, { expand: flags.expand, root: index.root, depth: flags.depth })
+                r => output.formatAbout(r, { expand: flags.expand, root: index.root, depth: flags.depth, showConfidence: flags.showConfidence })
             );
             break;
         }
@@ -751,6 +757,16 @@ function runProjectCommand(rootDir, command, arg) {
             break;
         }
 
+        case 'entrypoints': {
+            const { ok, result, error } = execute(index, 'entrypoints', { type: flags.type, framework: flags.framework, file: flags.file });
+            if (!ok) fail(error);
+            printOutput(result,
+                output.formatEntrypointsJson,
+                r => output.formatEntrypoints(r)
+            );
+            break;
+        }
+
         case 'stats': {
             const { ok, result, error } = execute(index, 'stats', { functions: flags.functions });
             if (!ok) fail(error);
@@ -1036,7 +1052,7 @@ Usage:
 ═══════════════════════════════════════════════════════════════════════════════
 UNDERSTAND CODE
 ═══════════════════════════════════════════════════════════════════════════════
-  about <name>        RECOMMENDED: Full picture (definition, callers, callees, tests, code)
+  about <name>        Full picture (definition, callers, callees, tests, code)
   context <name>      Who calls this + what it calls (numbered for expand)
   smart <name>        Function + all dependencies inline
   impact <name>       What breaks if changed (call sites grouped by file)
@@ -1081,6 +1097,7 @@ REFACTORING HELPERS
   verify <name>       Check all call sites match signature
   diff-impact         What changed in git diff and who calls it (--base, --staged)
   deadcode            Find unused functions/classes
+  entrypoints         Detect framework entry points (routes, DI, tasks)
 
 ═══════════════════════════════════════════════════════════════════════════════
 OTHER
@@ -1107,10 +1124,13 @@ Common Flags:
   --include-tests     Include test files
   --include-methods   Include method calls (obj.fn) in caller/callee analysis
   --include-uncertain Include ambiguous/uncertain matches
+  --show-confidence   Show confidence scores per caller/callee edge
+  --min-confidence=N  Filter edges below confidence threshold (0.0-1.0)
   --include-exported  Include exported symbols in deadcode
   --no-regex          Force plain text search (regex is default)
   --functions         Show per-function line counts (stats command)
   --include-decorated Include decorated/annotated symbols in deadcode
+  --framework=X       Filter entrypoints by framework (e.g., --framework=express,spring)
   --exact             Exact name match only (find)
   --calls-only        Only show call/test-case matches (tests)
   --case-sensitive    Case-sensitive text search (search)
@@ -1340,7 +1360,8 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
             const { text, expandable } = output.formatContext(result, {
                 methodsHint: 'Note: obj.method() calls excluded — use --include-methods to include them',
                 expandHint: 'Use "expand <N>" to see code for item N',
-                uncertainHint: 'use --include-uncertain to include all'
+                uncertainHint: 'use --include-uncertain to include all',
+                showConfidence: iflags.showConfidence,
             });
             console.log(text);
             if (cache) {
@@ -1364,6 +1385,13 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
             break;
         }
 
+        case 'entrypoints': {
+            const { ok, result, error } = execute(index, 'entrypoints', { type: iflags.type, framework: iflags.framework, file: iflags.file });
+            if (!ok) { console.log(error); return; }
+            console.log(output.formatEntrypoints(result));
+            break;
+        }
+
         // ── Standard commands routed through execute() ───────────────────
 
         case 'toc': {
@@ -1379,7 +1407,7 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
         case 'about': {
             const { ok, result, error } = execute(index, 'about', { name: arg, ...iflags });
             if (!ok) { console.log(error); return; }
-            console.log(output.formatAbout(result, { expand: iflags.expand, root: index.root, showAll: iflags.all, depth: iflags.depth }));
+            console.log(output.formatAbout(result, { expand: iflags.expand, root: index.root, showAll: iflags.all, depth: iflags.depth, showConfidence: iflags.showConfidence }));
             break;
         }
 

package/core/callers.js

@@ -11,6 +11,7 @@ const crypto = require('crypto');
 const { detectLanguage, getParser, getLanguageModule } = require('../languages');
 const { isTestFile } = require('./discovery');
 const { NON_CALLABLE_TYPES } = require('./shared');
+const { scoreEdge } = require('./confidence');
 
 /**
  * Extract a single line from content without splitting the entire string.
@@ -191,7 +192,8 @@ function findCallers(index, name, options = {}) {
                     if (!pendingByFile.has(filePath)) pendingByFile.set(filePath, []);
                     pendingByFile.get(filePath).push({
                         call, fileEntry, callerSymbol,
-                        isMethod: false, isFunctionReference: true, receiver: undefined
+                        isMethod: false, isFunctionReference: true, receiver: undefined,
+                        _evidence: { isFunctionReference: true }
                     });
                     pendingCount++;
                     continue;
@@ -422,12 +424,13 @@ function findCallers(index, name, options = {}) {
                     }
                 }
 
-                // Java/Go/Rust receiver-class disambiguation:
+                // Receiver-class disambiguation:
                 // When the target definition has a class/receiver type, filter callers
                 // whose receiverType is known to be a different type.
-                // Go uses inferred receiverType; Java/Rust fall back to variable name matching.
+                // All languages use receiverType when available (constructor/annotation inference).
+                // Go/Java/Rust additionally fall back to variable name matching.
                 if (call.isMethod && call.receiver && !resolvedBySameClass && !bindingId &&
-                    (fileEntry.language === 'java' || fileEntry.language === 'go' || fileEntry.language === 'rust')) {
+                    (call.receiverType || fileEntry.language === 'java' || fileEntry.language === 'go' || fileEntry.language === 'rust')) {
                     // Build target type set from both className (Java) and receiver (Go/Rust)
                     const targetTypes = new Set();
                     for (const td of targetDefs) {
@@ -474,12 +477,43 @@ function findCallers(index, name, options = {}) {
                 // Find the enclosing function (get full symbol info)
                 const callerSymbol = index.findEnclosingFunction(filePath, call.line, true);
 
+                // Check import graph evidence: does this file import from the target definition's file?
+                const targetDefs2 = options.targetDefinitions || definitions;
+                const targetFiles2 = new Set(targetDefs2.map(d => d.file).filter(Boolean));
+                const callerImports = index.importGraph.get(filePath) || [];
+                let hasImportLink = targetFiles2.has(filePath) || callerImports.some(imp => targetFiles2.has(imp));
+                // Check one level of re-exports (barrel files) for import evidence
+                if (!hasImportLink) {
+                    for (const imp of callerImports) {
+                        const transImports = index.importGraph.get(imp) || [];
+                        if (transImports.some(ti => targetFiles2.has(ti))) {
+                            hasImportLink = true;
+                            break;
+                        }
+                    }
+                }
+
                 if (!pendingByFile.has(filePath)) pendingByFile.set(filePath, []);
                 pendingByFile.get(filePath).push({
                     call, fileEntry, callerSymbol,
                     isMethod: call.isMethod || false, isFunctionReference: false,
                     receiver: call.receiver,
-                    receiverType: call.receiverType
+                    receiverType: call.receiverType,
+                    _evidence: {
+                        hasBindingId: !!bindingId,
+                        resolvedBySameClass: !!resolvedBySameClass,
+                        isUncertain: !!isUncertain || (
+                            // Method calls where binding resolution was skipped (non-self receiver)
+                            // and the receiver has no binding evidence → uncertain (JS/TS/Python only)
+                            skipLocalBinding && call.isMethod && !resolvedBySameClass &&
+                            fileEntry.language !== 'go' && fileEntry.language !== 'java' && fileEntry.language !== 'rust' &&
+                            !(call.receiver && (fileEntry.bindings || []).some(b => b.name === call.receiver))
+                        ),
+                        hasReceiverType: !!call.receiverType,
+                        hasReceiverEvidence: !!(call.receiver &&
+                            (fileEntry.bindings || []).some(b => b.name === call.receiver)),
+                        hasImportEvidence: !!bindingId || hasImportLink,
+                    }
                 });
                 pendingCount++;
             }
@@ -493,7 +527,8 @@ function findCallers(index, name, options = {}) {
     for (const [filePath, pending] of pendingByFile) {
         try {
             const content = fs.readFileSync(filePath, 'utf-8');
-            for (const { call, fileEntry, callerSymbol, isMethod, isFunctionReference, receiver, receiverType } of pending) {
+            for (const { call, fileEntry, callerSymbol, isMethod, isFunctionReference, receiver, receiverType, _evidence } of pending) {
+                const scored = scoreEdge(_evidence || {});
                 callers.push({
                     file: filePath,
                     relativePath: fileEntry.relativePath,
@@ -506,7 +541,9 @@ function findCallers(index, name, options = {}) {
                     isMethod,
                     ...(isFunctionReference && { isFunctionReference: true }),
                     ...(receiver !== undefined && { receiver }),
-                    ...(receiverType && { receiverType })
+                    ...(receiverType && { receiverType }),
+                    confidence: scored.confidence,
+                    resolution: scored.resolution,
                 });
             }
         } catch (e) {
@@ -612,9 +649,11 @@ function findCallees(index, def, options = {}) {
                         }
                     }
                     continue;
-                } else if (call.receiverType && (language === 'go' || language === 'java' || language === 'rust')) {
+                } else if (call.receiverType) {
                     // Use parser-inferred receiverType for method resolution
-                    // e.g., f.RunFilter() where f is *Framework → resolve to Framework.RunFilter
+                    // Go/Java/Rust: from param/receiver type declarations
+                    // JS/TS: from `new Foo()` assignments or TypeScript type annotations
+                    // Python: from constructor calls or type annotations
                     const typeName = call.receiverType;
                     const symbols = index.symbols.get(call.name);
                     const isCallableRT = (s) => !NON_CALLABLE_TYPES.has(s.type) ||
@@ -981,6 +1020,8 @@ function findCallees(index, def, options = {}) {
         const defReceiver = def.receiver;
         const defFileEntry = fileEntry;
         const callerIsTest = defFileEntry && isTestFile(defFileEntry.relativePath, defFileEntry.language);
+        // Pre-compute import graph for callee confidence scoring
+        const callerImportSet = new Set(index.importGraph.get(def.file) || []);
 
         for (const { name: calleeName, bindingId, count } of callees.values()) {
             const symbols = index.symbols.get(calleeName);
@@ -1009,9 +1050,7 @@ function findCallees(index, def, options = {}) {
                         } else {
                             // Priority 2.5: Imported file — check if the caller's file imports
                             // from any of the candidate callee files (using importGraph)
-                            const callerImportedFiles = index.importGraph.get(def.file) || [];
-                            const importedFileSet = new Set(callerImportedFiles);
-                            const importedCallee = symbols.find(s => importedFileSet.has(s.file));
+                            const importedCallee = symbols.find(s => callerImportSet.has(s.file));
                             if (importedCallee) {
                                 callee = importedCallee;
                             } else if (defReceiver) {
@@ -1095,10 +1134,18 @@ function findCallees(index, def, options = {}) {
                     }
                 }
 
+                const calleeScored = scoreEdge({
+                    hasBindingId: !!bindingId,
+                    hasImportEvidence: !!bindingId || (symbols && symbols.length === 1) ||
+                        (callee.file === def.file) || callerImportSet.has(callee.file),
+                    isUncertain: false, // uncertain callees already filtered above
+                });
                 result.push({
                     ...callee,
                     callCount: count,
-                    weight: index.calculateWeight(count)
+                    weight: index.calculateWeight(count),
+                    confidence: calleeScored.confidence,
+                    resolution: calleeScored.resolution,
                 });
             }
         }

package/core/confidence.js

@@ -0,0 +1,116 @@
+/**
+ * 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.
+ */
+
+'use strict';
+
+// Resolution types ordered from most to least confident
+const RESOLUTION = {
+    EXACT_BINDING:  'exact-binding',
+    SAME_CLASS:     'same-class',
+    RECEIVER_HINT:  'receiver-hint',
+    SCOPE_MATCH:    'scope-match',
+    NAME_ONLY:      'name-only',
+    UNCERTAIN:      'uncertain',
+};
+
+// Seed scores per resolution type (tunable)
+const SCORES = {
+    [RESOLUTION.EXACT_BINDING]:  0.98,
+    [RESOLUTION.SAME_CLASS]:     0.92,
+    [RESOLUTION.RECEIVER_HINT]:  0.80,
+    [RESOLUTION.SCOPE_MATCH]:    0.65,
+    [RESOLUTION.NAME_ONLY]:      0.40,
+    [RESOLUTION.UNCERTAIN]:      0.25,
+};
+
+/**
+ * Score a caller/callee edge based on resolution evidence.
+ *
+ * @param {object} evidence - Resolution evidence collected during call resolution
+ * @param {boolean} [evidence.hasBindingId] - Call resolved to a specific bindingId
+ * @param {boolean} [evidence.resolvedBySameClass] - Resolved via self/this/super/cls
+ * @param {boolean} [evidence.resolvedByReceiverHint] - Receiver type narrowed via local hints
+ * @param {boolean} [evidence.hasImportEvidence] - File imports the target definition
+ * @param {boolean} [evidence.hasReceiverEvidence] - Receiver variable has binding in file scope
+ * @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[] }}
+ */
+function scoreEdge(evidence) {
+    const 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 };
+    }
+
+    // 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 };
+    }
+
+    // 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 };
+    }
+
+    // Scope/import-supported match
+    if (evidence.hasImportEvidence || evidence.hasReceiverEvidence) {
+        if (evidence.hasImportEvidence) reasons.push('import-supported');
+        if (evidence.hasReceiverEvidence) reasons.push('receiver binding in scope');
+        return { confidence: SCORES[RESOLUTION.SCOPE_MATCH], resolution: RESOLUTION.SCOPE_MATCH, evidence: reasons };
+    }
+
+    // Function reference (callback)
+    if (evidence.isFunctionReference) {
+        reasons.push('function reference');
+        return { confidence: SCORES[RESOLUTION.SCOPE_MATCH], resolution: RESOLUTION.SCOPE_MATCH, evidence: reasons };
+    }
+
+    // Uncertain
+    if (evidence.isUncertain) {
+        reasons.push('ambiguous resolution');
+        return { confidence: SCORES[RESOLUTION.UNCERTAIN], resolution: RESOLUTION.UNCERTAIN, evidence: reasons };
+    }
+
+    // Name-only match (no additional evidence)
+    reasons.push('name match only');
+    return { confidence: SCORES[RESOLUTION.NAME_ONLY], resolution: RESOLUTION.NAME_ONLY, evidence: reasons };
+}
+
+/**
+ * Filter edges by minimum confidence threshold.
+ * @param {Array} edges - Array of objects with .confidence property
+ * @param {number} minConfidence - Minimum confidence (0.0-1.0)
+ * @returns {{ kept: Array, filtered: number }}
+ */
+function filterByConfidence(edges, minConfidence) {
+    if (!minConfidence || minConfidence <= 0) return { kept: edges, filtered: 0 };
+    const kept = [];
+    let filtered = 0;
+    for (const edge of edges) {
+        if ((edge.confidence || 0) >= minConfidence) {
+            kept.push(edge);
+        } else {
+            filtered++;
+        }
+    }
+    return { kept, filtered };
+}
+
+module.exports = {
+    RESOLUTION,
+    SCORES,
+    scoreEdge,
+    filterByConfidence,
+};

package/core/deadcode.js

@@ -8,6 +8,7 @@
 const { detectLanguage, getParser, getLanguageModule, safeParse } = require('../languages');
 const { isTestFile } = require('./discovery');
 const { escapeRegExp } = require('./shared');
+const { isFrameworkEntrypoint } = require('./entrypoints');
 
 /** Check if a position in a line is inside a string literal (quotes/backticks) */
 function isInsideString(line, pos) {
@@ -369,23 +370,13 @@ function deadcode(index, options = {}) {
                 continue;
             }
 
-            // Framework registration decorators — excluded by default to reduce noise
-            // Python: decorators with '.' (attribute access) like @router.get, @app.route, @celery.task
-            // Java: non-standard annotations like @Bean, @Scheduled, @GetMapping
-            // These functions are invoked by frameworks, not by user code — AST can't see the call path
-            const javaKeywords = new Set(['public', 'private', 'protected', 'static', 'final', 'abstract', 'synchronized', 'native', 'default']);
-            const hasRegistrationDecorator = (() => {
-                if (lang === 'python') {
-                    const decorators = symbol.decorators || [];
-                    return decorators.some(d => d.includes('.'));
-                }
-                if (lang === 'java') {
-                    return mods.some(m => !javaKeywords.has(m));
-                }
-                return false;
-            })();
+            // Framework entry point detection — excluded by default to reduce noise
+            // Detects decorator/annotation patterns (Python, Java, Rust, JS/TS) and
+            // call-pattern-based registration (Express routes, Gin handlers, etc.)
+            // These functions are invoked by frameworks, not by user code.
+            const hasFrameworkEntrypoint = isFrameworkEntrypoint(symbol, index);
 
-            if (hasRegistrationDecorator && !options.includeDecorated) {
+            if (hasFrameworkEntrypoint && !options.includeDecorated) {
                 excludedDecorated++;
                 continue;
             }
@@ -447,9 +438,10 @@ function deadcode(index, options = {}) {
                 // Python: symbol.decorators (e.g., ['app.route("/path")', 'login_required'])
                 // Java/Rust/Go: symbol.modifiers may contain annotations (e.g., 'bean', 'scheduled')
                 const decorators = symbol.decorators || [];
-                // For Java, extract annotation-like modifiers (javaKeywords defined above)
+                // For Java, extract annotation-like modifiers
+                const javaKw = new Set(['public', 'private', 'protected', 'static', 'final', 'abstract', 'synchronized', 'native', 'default']);
                 const annotations = lang === 'java'
-                    ? mods.filter(m => !javaKeywords.has(m))
+                    ? mods.filter(m => !javaKw.has(m))
                     : [];
 
                 results.push({