ucn 3.8.0 → 3.8.2

package/core/entrypoints.js

@@ -0,0 +1,416 @@
+/**
+ * core/entrypoints.js - Framework entry point detection
+ *
+ * Detects functions registered as framework handlers (HTTP routes, DI beans,
+ * job schedulers, etc.) that are invoked by the framework at runtime, not by
+ * user code. These functions should never be flagged as dead code.
+ *
+ * Two detection methods:
+ * 1. Decorator/modifier matching (Python, Java, Rust, JS/TS decorators)
+ * 2. Call-pattern matching (Express routes, Gin handlers, Go http.HandleFunc)
+ */
+
+'use strict';
+
+const { getCachedCalls } = require('./callers');
+
+// ============================================================================
+// FRAMEWORK PATTERNS
+// ============================================================================
+
+const JS_LANGS = new Set(['javascript', 'typescript', 'tsx']);
+
+const FRAMEWORK_PATTERNS = [
+    // ── HTTP Routes ─────────────────────────────────────────────────────
+
+    // Express / Fastify / Koa (JS/TS) — call-pattern: app.get('/path', handler)
+    {
+        id: 'express-route',
+        languages: JS_LANGS,
+        type: 'http',
+        framework: 'express',
+        detection: 'callPattern',
+        receiverPattern: /^(app|router|server|fastify)$/i,
+        methodPattern: /^(get|post|put|delete|patch|all|use|options|head)$/,
+    },
+
+    // NestJS (JS/TS) — decorators: @Get(), @Post(), @Controller(), etc.
+    {
+        id: 'nestjs-handler',
+        languages: JS_LANGS,
+        type: 'http',
+        framework: 'nestjs',
+        detection: 'decorator',
+        pattern: /^(Get|Post|Put|Delete|Patch|Options|Head|All|Controller|Injectable|Module)$/,
+    },
+
+    // FastAPI (Python) — decorators: @app.get('/path'), @router.post('/path')
+    {
+        id: 'fastapi-route',
+        languages: new Set(['python']),
+        type: 'http',
+        framework: 'fastapi',
+        detection: 'decorator',
+        pattern: /^(app|router)\.(get|post|put|delete|patch|options|head)/,
+    },
+
+    // Flask (Python) — decorators: @app.route('/path'), @bp.get('/path')
+    {
+        id: 'flask-route',
+        languages: new Set(['python']),
+        type: 'http',
+        framework: 'flask',
+        detection: 'decorator',
+        pattern: /^(app|bp|blueprint)\.(route|get|post|put|delete|patch)/,
+    },
+
+    // Django (Python) — decorators: @api_view, @action, @permission_classes
+    {
+        id: 'django-view',
+        languages: new Set(['python']),
+        type: 'http',
+        framework: 'django',
+        detection: 'decorator',
+        pattern: /^(api_view|action|permission_classes|login_required|csrf_exempt)/,
+    },
+
+    // Spring HTTP (Java) — modifiers (lowercased annotations)
+    {
+        id: 'spring-mapping',
+        languages: new Set(['java']),
+        type: 'http',
+        framework: 'spring',
+        detection: 'modifier',
+        pattern: /^(getmapping|postmapping|putmapping|deletemapping|patchmapping|requestmapping)$/,
+    },
+
+    // Gin (Go) — call-pattern: router.GET('/path', handler)
+    {
+        id: 'gin-route',
+        languages: new Set(['go']),
+        type: 'http',
+        framework: 'gin',
+        detection: 'callPattern',
+        receiverPattern: /^(router|r|g|group|engine|api|v\d+)$/i,
+        methodPattern: /^(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS|Any|Handle)$/,
+    },
+
+    // Go net/http — call-pattern: http.HandleFunc('/path', handler)
+    {
+        id: 'go-http',
+        languages: new Set(['go']),
+        type: 'http',
+        framework: 'net/http',
+        detection: 'callPattern',
+        receiverPattern: /^(http|mux|serveMux)$/i,
+        methodPattern: /^(HandleFunc|Handle)$/,
+    },
+
+    // Actix (Rust) — modifiers from #[get("/path")], #[post("/path")]
+    {
+        id: 'actix-route',
+        languages: new Set(['rust']),
+        type: 'http',
+        framework: 'actix',
+        detection: 'modifier',
+        pattern: /^(get|post|put|delete|patch|actix_web::main|actix_web::test)$/,
+    },
+
+    // ── Dependency Injection ────────────────────────────────────────────
+
+    // Spring DI (Java)
+    {
+        id: 'spring-di',
+        languages: new Set(['java']),
+        type: 'di',
+        framework: 'spring',
+        detection: 'modifier',
+        pattern: /^(bean|component|service|controller|repository|configuration|restcontroller)$/,
+    },
+
+    // ── Job Schedulers ──────────────────────────────────────────────────
+
+    // Spring Scheduled (Java)
+    {
+        id: 'spring-jobs',
+        languages: new Set(['java']),
+        type: 'jobs',
+        framework: 'spring',
+        detection: 'modifier',
+        pattern: /^(scheduled|eventlistener|async)$/,
+    },
+
+    // Celery (Python)
+    {
+        id: 'celery-task',
+        languages: new Set(['python']),
+        type: 'jobs',
+        framework: 'celery',
+        detection: 'decorator',
+        pattern: /^(app\.task|shared_task|celery\.task)/,
+    },
+
+    // ── Test Frameworks ─────────────────────────────────────────────────
+
+    // pytest fixtures (Python)
+    {
+        id: 'pytest-fixture',
+        languages: new Set(['python']),
+        type: 'test',
+        framework: 'pytest',
+        detection: 'decorator',
+        pattern: /^pytest\.fixture/,
+    },
+
+    // ── Runtime ─────────────────────────────────────────────────────────
+
+    // Tokio (Rust)
+    {
+        id: 'tokio-main',
+        languages: new Set(['rust']),
+        type: 'runtime',
+        framework: 'tokio',
+        detection: 'modifier',
+        pattern: /^tokio::main$/,
+    },
+
+    // ── Catch-all fallbacks ─────────────────────────────────────────────
+
+    // Python: any decorator with '.' (attribute access) — framework registration heuristic
+    // Catches @app.route, @router.get, @celery.task, @something.hook, etc.
+    // Placed last so specific patterns match first (for better type/framework labeling).
+    {
+        id: 'python-dotted-decorator',
+        languages: new Set(['python']),
+        type: 'events',
+        framework: 'unknown',
+        detection: 'decorator',
+        pattern: /\./,
+    },
+
+    // Java: any non-standard annotation (not a keyword modifier or standard JDK annotation)
+    // Catches @Bean, @Scheduled, @EventListener, @Transactional, etc.
+    // Placed last so specific patterns match first.
+    {
+        id: 'java-custom-annotation',
+        languages: new Set(['java']),
+        type: 'di',
+        framework: 'unknown',
+        detection: 'modifier',
+        pattern: /^(?!public$|private$|protected$|static$|final$|abstract$|synchronized$|native$|default$|override$|deprecated$|suppresswarnings$|functionalinterface$|safevarargs$)/,
+    },
+];
+
+// ============================================================================
+// DETECTION
+// ============================================================================
+
+/**
+ * Check if a symbol matches any decorator/modifier-based framework pattern.
+ * @param {object} symbol - Symbol from the symbol table
+ * @param {string} language - File language
+ * @returns {{ pattern: object, matchedOn: string }|null}
+ */
+function matchDecoratorOrModifier(symbol, language) {
+    const decorators = symbol.decorators || [];
+    const modifiers = symbol.modifiers || [];
+
+    for (const fp of FRAMEWORK_PATTERNS) {
+        if (!fp.languages.has(language)) continue;
+
+        if (fp.detection === 'decorator') {
+            const matched = decorators.find(d => fp.pattern.test(d));
+            if (matched) return { pattern: fp, matchedOn: `@${matched}` };
+        }
+
+        if (fp.detection === 'modifier') {
+            const matched = modifiers.find(m => fp.pattern.test(m));
+            if (matched) return { pattern: fp, matchedOn: `@${matched}` };
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Build a map of symbol names used as callbacks in framework route-registration calls.
+ * Scans the calls cache for call-pattern-based framework detection.
+ * @param {object} index - ProjectIndex
+ * @returns {Map<string, { framework, type, patternId, method, file, line }>}
+ */
+function buildCallbackEntrypointMap(index) {
+    const callPatterns = FRAMEWORK_PATTERNS.filter(p => p.detection === 'callPattern');
+    if (callPatterns.length === 0) return new Map();
+
+    const result = new Map(); // name -> info
+
+    for (const [filePath, fileEntry] of index.files) {
+        const lang = fileEntry.language;
+        const relevantPatterns = callPatterns.filter(p => p.languages.has(lang));
+        if (relevantPatterns.length === 0) continue;
+
+        const calls = getCachedCalls(index, filePath);
+        if (!calls) continue;
+
+        // Pass 1: find route-registration calls, index by line
+        // Match both method calls (obj.method) and package-qualified calls (pkg.Func)
+        const routeLines = new Map(); // line -> { pattern, call }
+        for (const call of calls) {
+            if (!call.receiver) continue;
+            for (const pattern of relevantPatterns) {
+                if (pattern.receiverPattern.test(call.receiver) &&
+                    pattern.methodPattern.test(call.name)) {
+                    routeLines.set(call.line, { pattern, call });
+                    break;
+                }
+            }
+        }
+
+        if (routeLines.size === 0) continue;
+
+        // Pass 2: find callbacks on route-registration lines
+        for (const call of calls) {
+            if (!call.isFunctionReference && !call.isPotentialCallback) continue;
+            const route = routeLines.get(call.line);
+            if (!route) continue;
+
+            // This callback is registered as a framework handler
+            if (!result.has(call.name)) {
+                result.set(call.name, {
+                    framework: route.pattern.framework,
+                    type: route.pattern.type,
+                    patternId: route.pattern.id,
+                    method: route.call.name.toUpperCase(),
+                    file: filePath,
+                    line: call.line,
+                });
+            }
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Detect all framework entry points in the project.
+ *
+ * @param {object} index - ProjectIndex
+ * @param {object} [options]
+ * @param {string} [options.type] - Filter by type (http, jobs, di, test, runtime)
+ * @param {string} [options.framework] - Filter by framework name(s), comma-separated
+ * @param {string} [options.file] - Filter by file path pattern
+ * @returns {Array<{ name, file, line, type, framework, patternId, evidence, confidence }>}
+ */
+function detectEntrypoints(index, options = {}) {
+    // Build callback entrypoint map (call-pattern detection)
+    const callbackMap = buildCallbackEntrypointMap(index);
+
+    const results = [];
+    const seen = new Set(); // file:line:name dedup key
+
+    // 1. Scan all symbols for decorator/modifier-based patterns
+    for (const [name, symbols] of index.symbols) {
+        for (const symbol of symbols) {
+            const fileEntry = index.files.get(symbol.file);
+            if (!fileEntry) continue;
+
+            const match = matchDecoratorOrModifier(symbol, fileEntry.language);
+            if (match) {
+                const key = `${symbol.file}:${symbol.startLine}:${name}`;
+                if (seen.has(key)) continue;
+                seen.add(key);
+
+                results.push({
+                    name,
+                    file: symbol.relativePath || symbol.file,
+                    absoluteFile: symbol.file,
+                    line: symbol.startLine,
+                    type: match.pattern.type,
+                    framework: match.pattern.framework,
+                    patternId: match.pattern.id,
+                    evidence: [match.matchedOn],
+                    confidence: 0.95,
+                });
+            }
+        }
+    }
+
+    // 2. Add call-pattern-based entry points (route handlers)
+    for (const [name, info] of callbackMap) {
+        const fileEntry = index.files.get(info.file);
+        const relPath = fileEntry?.relativePath || info.file;
+        const key = `${info.file}:${info.line}:${name}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+
+        results.push({
+            name,
+            file: relPath,
+            absoluteFile: info.file,
+            line: info.line,
+            type: info.type,
+            framework: info.framework,
+            patternId: info.patternId,
+            evidence: [`${info.method} route handler`],
+            confidence: 0.90,
+        });
+    }
+
+    // Apply filters
+    let filtered = results;
+
+    if (options.type) {
+        filtered = filtered.filter(e => e.type === options.type);
+    }
+
+    if (options.framework) {
+        const frameworks = new Set(options.framework.split(',').map(s => s.trim().toLowerCase()));
+        filtered = filtered.filter(e => frameworks.has(e.framework.toLowerCase()));
+    }
+
+    if (options.file) {
+        filtered = filtered.filter(e => e.file.includes(options.file));
+    }
+
+    // Sort by file, then line
+    filtered.sort((a, b) => {
+        if (a.file !== b.file) return a.file.localeCompare(b.file);
+        return a.line - b.line;
+    });
+
+    return filtered;
+}
+
+/**
+ * Check if a specific symbol is a framework entry point.
+ * Used by deadcode to exclude framework-registered functions.
+ *
+ * @param {object} symbol - Symbol from the symbol table
+ * @param {object} index - ProjectIndex
+ * @returns {boolean}
+ */
+function isFrameworkEntrypoint(symbol, index) {
+    const fileEntry = index.files.get(symbol.file);
+    if (!fileEntry) return false;
+
+    // Fast path: check decorator/modifier patterns (no index scan needed)
+    if (matchDecoratorOrModifier(symbol, fileEntry.language)) {
+        return true;
+    }
+
+    // Slow path: check call-pattern patterns (needs callback map)
+    // Build and cache on first use
+    if (!index._callbackEntrypointMap) {
+        index._callbackEntrypointMap = buildCallbackEntrypointMap(index);
+    }
+
+    return index._callbackEntrypointMap.has(symbol.name);
+}
+
+module.exports = {
+    FRAMEWORK_PATTERNS,
+    detectEntrypoints,
+    isFrameworkEntrypoint,
+    matchDecoratorOrModifier,
+    buildCallbackEntrypointMap,
+};

package/core/execute.js

@@ -182,6 +182,7 @@ const HANDLERS = {
             exclude: toExcludeArray(p.exclude),
             maxCallers: num(p.top, undefined),
             maxCallees: num(p.top, undefined),
+            minConfidence: num(p.minConfidence, 0),
         });
         if (!result) {
             // Give better error if file/className filter is the problem
@@ -201,7 +202,7 @@ const HANDLERS = {
             }
             return { ok: false, error: `Symbol "${p.name}" not found.` };
         }
-        return { ok: true, result };
+        return { ok: true, result, showConfidence: !!p.showConfidence };
     },
 
     context: (index, p) => {
@@ -218,9 +219,10 @@ const HANDLERS = {
             file: p.file,
             className: p.className,
             exclude: toExcludeArray(p.exclude),
+            minConfidence: num(p.minConfidence, 0),
         });
         if (!result) return { ok: false, error: `Symbol "${p.name}" not found.` };
-        return { ok: true, result };
+        return { ok: true, result, showConfidence: !!p.showConfidence };
     },
 
     impact: (index, p) => {
@@ -568,6 +570,18 @@ const HANDLERS = {
         return { ok: true, result, note };
     },
 
+    entrypoints: (index, p) => {
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
+        const { detectEntrypoints } = require('./entrypoints');
+        const result = detectEntrypoints(index, {
+            type: p.type,
+            framework: p.framework,
+            file: p.file,
+        });
+        return { ok: true, result };
+    },
+
     // ── Extracting Code ─────────────────────────────────────────────────
 
     fn: (index, p) => {

package/core/output.js

@@ -348,7 +348,8 @@ function formatContextJson(context) {
                 file: c.relativePath || c.file,
                 line: c.line,
                 expression: c.content,  // FULL expression
-                callerName: c.callerName
+                callerName: c.callerName,
+                ...(c.confidence != null && { confidence: c.confidence, resolution: c.resolution }),
             })),
             callees: callees.map(c => ({
                 name: c.name,
@@ -356,7 +357,8 @@ function formatContextJson(context) {
                 file: c.relativePath || c.file,
                 line: c.startLine,
                 params: c.params,  // FULL params
-                weight: c.weight || 'normal'  // Dependency weight: core, setup, utility
+                weight: c.weight || 'normal',  // Dependency weight: core, setup, utility
+                ...(c.confidence != null && { confidence: c.confidence, resolution: c.resolution }),
             })),
             ...(context.warnings && { warnings: context.warnings })
         }
@@ -1512,6 +1514,9 @@ function formatAbout(about, options = {}) {
             lines.push(`  Note: ${w.message}`);
         }
     }
+    if (about.confidenceFiltered) {
+        lines.push(`  Note: ${about.confidenceFiltered} edge(s) below confidence threshold hidden`);
+    }
 
     // Usage summary
     lines.push('');
@@ -1519,6 +1524,7 @@ function formatAbout(about, options = {}) {
     lines.push(`  ${about.usages.calls} calls, ${about.usages.imports} imports, ${about.usages.references} references`);
 
     // Callers
+    const showConf = options.showConfidence || false;
     let aboutTruncated = false;
     if (about.callers.total > 0) {
         lines.push('');
@@ -1532,6 +1538,9 @@ function formatAbout(about, options = {}) {
             const caller = c.callerName ? `[${c.callerName}]` : '';
             lines.push(`  ${c.file}:${c.line} ${caller}`);
             lines.push(`    ${c.expression}`);
+            if (showConf && c.confidence != null) {
+                lines.push(`    confidence: ${c.confidence.toFixed(2)} (${c.resolution})`);
+            }
         }
     }
 
@@ -1547,6 +1556,9 @@ function formatAbout(about, options = {}) {
         for (const c of about.callees.top) {
             const weight = c.weight && c.weight !== 'normal' ? ` [${c.weight}]` : '';
             lines.push(`  ${c.name}${weight} - ${c.file}:${c.line} (${c.callCount}x)`);
+            if (showConf && c.confidence != null) {
+                lines.push(`    confidence: ${c.confidence.toFixed(2)} (${c.resolution})`);
+            }
 
             // Inline expansion: show first 3 lines of callee code
             if (expand && root && c.file && c.startLine) {
@@ -1954,6 +1966,7 @@ function formatContext(ctx, options = {}) {
         const notes = [];
         if (ctx.meta.dynamicImports) { const dn = dynamicImportsNote(ctx.meta.dynamicImports, ctx.meta); if (dn) notes.push(dn); }
         if (ctx.meta.uncertain) notes.push(`${ctx.meta.uncertain} uncertain call(s) skipped`);
+        if (ctx.meta.confidenceFiltered) notes.push(`${ctx.meta.confidenceFiltered} edge(s) below confidence threshold hidden`);
         if (notes.length) {
             const uncertainSuffix = ctx.meta.uncertain && options.uncertainHint ? ` — ${options.uncertainHint}` : '';
             lines.push(`  Note: ${notes.join(', ')}${uncertainSuffix}`);
@@ -1970,12 +1983,16 @@ function formatContext(ctx, options = {}) {
         }
     }
 
+    const showConf = options.showConfidence || false;
     const callers = ctx.callers || [];
     lines.push(`\nCALLERS (${callers.length}):`);
     for (const c of callers) {
         const callerName = c.callerName ? ` [${c.callerName}]` : '';
         lines.push(`  [${itemNum}] ${c.relativePath}:${c.line}${callerName}`);
         lines.push(`    ${c.content.trim()}`);
+        if (showConf && c.confidence != null) {
+            lines.push(`    confidence: ${c.confidence.toFixed(2)} (${c.resolution})`);
+        }
         expandable.push({
             num: itemNum++,
             type: 'caller',
@@ -1999,6 +2016,9 @@ function formatContext(ctx, options = {}) {
     for (const c of callees) {
         const weight = c.weight && c.weight !== 'normal' ? ` [${c.weight}]` : '';
         lines.push(`  [${itemNum}] ${c.name}${weight} - ${c.relativePath}:${c.startLine}`);
+        if (showConf && c.confidence != null) {
+            lines.push(`    confidence: ${c.confidence.toFixed(2)} (${c.resolution})`);
+        }
         expandable.push({
             num: itemNum++,
             type: 'callee',
@@ -2302,10 +2322,12 @@ function formatCircularDeps(result) {
         lines.push(`Filtered to cycles involving: ${result.fileFilter}`);
     }
 
+    const scannedCount = result.filesWithImports || result.totalFiles;
+
     if (result.cycles.length === 0) {
         lines.push('');
         lines.push('No circular dependencies found.');
-        lines.push(`Scanned ${result.totalFiles} files.`);
+        lines.push(`Scanned ${scannedCount} files with import relationships.`);
         return lines.join('\n');
     }
 
@@ -2318,7 +2340,7 @@ function formatCircularDeps(result) {
 
     lines.push('');
     const { totalCycles, filesInCycles } = result.summary;
-    lines.push(`Summary: ${totalCycles} circular dependency chain${totalCycles !== 1 ? 's' : ''} involving ${filesInCycles} file${filesInCycles !== 1 ? 's' : ''} out of ${result.totalFiles} total.`);
+    lines.push(`Summary: ${totalCycles} circular dependency chain${totalCycles !== 1 ? 's' : ''} involving ${filesInCycles} file${filesInCycles !== 1 ? 's' : ''} (${scannedCount} files with imports scanned).`);
 
     return lines.join('\n');
 }
@@ -3063,6 +3085,80 @@ function formatLinesJson(result) {
     }, null, 2);
 }
 
+// ============================================================================
+// Entrypoints command formatters
+// ============================================================================
+
+/**
+ * Format entrypoints command output (text)
+ */
+function formatEntrypoints(results, options = {}) {
+    if (!results || results.length === 0) {
+        return 'No framework entry points detected.';
+    }
+
+    const lines = [];
+    lines.push(`Framework Entry Points: ${results.length} detected\n`);
+
+    // Group by type
+    const byType = new Map();
+    for (const ep of results) {
+        if (!byType.has(ep.type)) byType.set(ep.type, []);
+        byType.get(ep.type).push(ep);
+    }
+
+    const typeLabels = {
+        http: 'HTTP Routes',
+        di: 'Dependency Injection',
+        jobs: 'Job Schedulers',
+        test: 'Test Fixtures',
+        runtime: 'Runtime Entry Points',
+        ui: 'UI Handlers',
+        events: 'Event Handlers',
+    };
+
+    let itemNum = 0;
+    for (const [type, entries] of byType) {
+        const label = typeLabels[type] || type;
+        lines.push(`${label} (${entries.length}):`);
+
+        let currentFile = null;
+        for (const ep of entries) {
+            if (ep.file !== currentFile) {
+                currentFile = ep.file;
+                lines.push(`  ${ep.file}`);
+            }
+            itemNum++;
+            const evidence = ep.evidence.join(', ');
+            lines.push(`    [${itemNum}] ${ep.name} (${ep.framework}) — ${evidence}${' '.repeat(Math.max(0, 40 - ep.name.length - ep.framework.length - evidence.length))}:${ep.line}`);
+        }
+        lines.push('');
+    }
+
+    return lines.join('\n').trimEnd();
+}
+
+/**
+ * Format entrypoints command output (JSON)
+ */
+function formatEntrypointsJson(results) {
+    return JSON.stringify({
+        meta: { total: results.length },
+        data: {
+            entrypoints: results.map(ep => ({
+                name: ep.name,
+                file: ep.file,
+                line: ep.line,
+                type: ep.type,
+                framework: ep.framework,
+                patternId: ep.patternId,
+                evidence: ep.evidence,
+                confidence: ep.confidence,
+            }))
+        }
+    }, null, 2);
+}
+
 module.exports = {
     // Utilities
     normalizeParams,
@@ -3182,5 +3278,9 @@ module.exports = {
     formatClassResult,
     formatClassResultJson,
     formatLines,
-    formatLinesJson
+    formatLinesJson,
+
+    // Entrypoints command
+    formatEntrypoints,
+    formatEntrypointsJson,
 };