ucn 3.8.12 → 3.8.14

package/core/output/reporting.js

@@ -0,0 +1,331 @@
+/**
+ * core/output/reporting.js - Stats/TOC/deadcode/entrypoints formatters
+ */
+
+const {
+    lineRange,
+    dynamicImportsNote,
+    formatFunctionSignature,
+    formatClassSignature,
+} = require('./shared');
+
+/**
+ * Format toc command output
+ * @param {object} toc - TOC data
+ * @param {object} [options] - Formatting options
+ * @param {string} [options.detailedHint] - Custom hint text for non-detailed mode
+ * @param {string} [options.uncertainHint] - Custom hint text for uncertain references
+ */
+function formatToc(toc, options = {}) {
+    const lines = [];
+    const t = toc.totals;
+    lines.push(`PROJECT: ${t.files} files, ${t.lines} lines`);
+    lines.push(`  ${t.functions} functions, ${t.classes} types (classes/interfaces/enums), ${t.state} state objects`);
+
+    const meta = toc.meta || {};
+    if (meta.filteredBy) {
+        lines.push(`  Filtered by: --file=${meta.filteredBy} (${meta.matchedFiles} files matched)`);
+        if (meta.emptyFiles) {
+            lines.push(`  Note: ${meta.emptyFiles} file(s) have no detected symbols (may be generated or data files)`);
+        }
+    }
+    const warnings = [];
+    if (meta.dynamicImports) { const dn = dynamicImportsNote(meta.dynamicImports, meta); if (dn) warnings.push(dn); }
+    if (meta.uncertain) warnings.push(`${meta.uncertain} uncertain reference(s)`);
+    if (warnings.length) {
+        const uncertainSuffix = meta.uncertain && options.uncertainHint ? ` — ${options.uncertainHint}` : '';
+        lines.push(`  Note: ${warnings.join(', ')}${uncertainSuffix}`);
+    }
+
+    if (toc.summary) {
+        if (toc.summary.topFunctionFiles?.length) {
+            const hint = toc.summary.topFunctionFiles.map(f => `${f.file} (${f.functions})`).join(', ');
+            lines.push(`  Most functions: ${hint}`);
+        }
+        if (toc.summary.topLineFiles?.length) {
+            const hint = toc.summary.topLineFiles.map(f => `${f.file} (${f.lines})`).join(', ');
+            lines.push(`  Largest files: ${hint}`);
+        }
+        if (toc.summary.entryFiles?.length) {
+            lines.push(`  Entry points: ${toc.summary.entryFiles.join(', ')}`);
+        }
+    }
+
+    lines.push('═'.repeat(60));
+    const hasDetail = toc.files.some(f => f.symbols);
+    for (const file of toc.files) {
+        const parts = [`${file.lines} lines`];
+        if (file.functions) parts.push(`${file.functions} fn`);
+        if (file.classes) parts.push(`${file.classes} types`);
+        if (file.state) parts.push(`${file.state} state`);
+
+        if (hasDetail) {
+            lines.push(`\n${file.file} (${parts.join(', ')})`);
+            if (file.symbols) {
+                for (const fn of file.symbols.functions) {
+                    lines.push(`  ${lineRange(fn.startLine, fn.endLine)} ${formatFunctionSignature(fn)}`);
+                }
+                for (const cls of file.symbols.classes) {
+                    lines.push(`  ${lineRange(cls.startLine, cls.endLine)} ${formatClassSignature(cls)}`);
+                }
+            }
+        } else {
+            lines.push(`  ${file.file} — ${parts.join(', ')}`);
+        }
+    }
+
+    if (!hasDetail) {
+        const hint = options.detailedHint || 'Use detailed=true to list all functions and classes.';
+        lines.push(`\n${hint}`);
+    }
+
+    if (toc.hiddenFiles > 0) {
+        const topHint = options.topHint || 'Use --top=N or --all to show more.';
+        lines.push(`\n... and ${toc.hiddenFiles} more files. ${topHint}`);
+    }
+
+    return lines.join('\n');
+}
+
+/**
+ * Format TOC data as JSON
+ */
+function formatTocJson(data) {
+    const obj = {
+        meta: data.meta || { complete: true, skipped: 0, dynamicImports: 0, uncertain: 0 },
+        totals: data.totals,
+        summary: data.summary,
+        files: data.files
+    };
+    if (data.hiddenFiles > 0) obj.hiddenFiles = data.hiddenFiles;
+    return JSON.stringify(obj);
+}
+
+/**
+ * Format stats command output
+ */
+function formatStats(stats, options = {}) {
+    const lines = [];
+    lines.push('PROJECT STATISTICS');
+    lines.push('═'.repeat(60));
+    lines.push(`Root: ${stats.root}`);
+    if (stats.truncated) {
+        lines.push(`Files: ${stats.files} (truncated at ${stats.truncated.maxFiles} — use --max-files to increase)`);
+    } else {
+        lines.push(`Files: ${stats.files}`);
+    }
+    lines.push(`Symbols: ${stats.symbols}`);
+    lines.push(`Build time: ${stats.buildTime}ms`);
+
+    lines.push('\nBy Language:');
+    for (const [lang, info] of Object.entries(stats.byLanguage)) {
+        lines.push(`  ${lang}: ${info.files} files, ${info.lines} lines, ${info.symbols} symbols`);
+    }
+
+    lines.push('\nBy Type:');
+    for (const [type, count] of Object.entries(stats.byType)) {
+        lines.push(`  ${type}: ${count}`);
+    }
+
+    if (stats.warnings) {
+        lines.push(`\nWarnings: ${stats.warnings.count} file(s) failed to parse:`);
+        for (const f of stats.warnings.failedFiles.slice(0, 10)) {
+            lines.push(`  ${f}`);
+        }
+        if (stats.warnings.count > 10) {
+            lines.push(`  ... and ${stats.warnings.count - 10} more`);
+        }
+    }
+
+    if (stats.functions) {
+        const top = options.top || 30;
+        const shown = stats.functions.slice(0, top);
+        lines.push(`\nFunctions by line count (top ${shown.length} of ${stats.functions.length}):`);
+        for (const fn of shown) {
+            const loc = `${fn.file}:${fn.startLine}`;
+            lines.push(`  ${String(fn.lines).padStart(5)} lines  ${fn.name}  (${loc})`);
+        }
+        if (stats.functions.length > top) {
+            lines.push(`  ... ${stats.functions.length - top} more (use --top=N to show more)`);
+        }
+    }
+
+    return lines.join('\n');
+}
+
+/**
+ * Format project stats as JSON
+ */
+function formatStatsJson(stats) {
+    return JSON.stringify(stats, null, 2);
+}
+
+/**
+ * Format deadcode command output
+ * @param {Array} results - Dead code results
+ * @param {object} [options] - Formatting options
+ * @param {string} [options.exportedHint] - Hint about exported symbols exclusion
+ */
+function formatDeadcode(results, options = {}) {
+    if (results.length === 0 && !results.excludedDecorated && !results.excludedExported) {
+        return 'No dead code found.';
+    }
+
+    const lines = [];
+    const top = options.top > 0 ? options.top : 0;
+    const showing = top > 0 ? results.slice(0, top) : results;
+    const hidden = results.length - showing.length;
+
+    if (results.length > 0) {
+        if (hidden > 0) {
+            lines.push(`Dead code: ${results.length} unused symbol(s) (showing ${showing.length})\n`);
+        } else {
+            lines.push(`Dead code: ${results.length} unused symbol(s)\n`);
+        }
+    }
+
+    let currentFile = null;
+    for (const item of showing) {
+        if (item.file !== currentFile) {
+            currentFile = item.file;
+            lines.push(item.file);
+        }
+        const exported = item.isExported ? ' [exported]' : '';
+        // Surface decorators/annotations — structural hint that a framework may invoke this
+        const hints = [];
+        if (item.decorators && item.decorators.length > 0) {
+            hints.push(...item.decorators.map(d => `@${d}`));
+        }
+        if (item.annotations && item.annotations.length > 0) {
+            hints.push(...item.annotations.map(a => `@${a}`));
+        }
+        const hintStr = hints.length > 0 ? ` [has ${hints.join(', ')}]` : '';
+        lines.push(`  ${lineRange(item.startLine, item.endLine)} ${item.name} (${item.type})${exported}${hintStr}`);
+    }
+
+    if (hidden > 0) {
+        lines.push(`\n${hidden} more result(s) not shown. Use --top=${results.length} or --all to see all.`);
+    }
+
+    // Show counts of excluded items with expansion hints
+    if (results.length === 0) {
+        lines.push('No dead code found.');
+    }
+    if (results.excludedDecorated > 0) {
+        const decoratedHint = options.decoratedHint || `${results.excludedDecorated} decorated/annotated symbol(s) hidden (framework-registered). Use --include-decorated to include them.`;
+        lines.push(`\n${decoratedHint}`);
+    }
+    if (results.excludedExported > 0) {
+        const exportedHint = options.exportedHint || `${results.excludedExported} exported symbol(s) excluded (all have callers). Use --include-exported to audit them.`;
+        lines.push(`\n${exportedHint}`);
+    }
+
+    if (lines.length === 0) {
+        return 'No dead code found.';
+    }
+
+    return lines.join('\n');
+}
+
+/**
+ * Format deadcode command output - JSON
+ */
+function formatDeadcodeJson(results) {
+    return JSON.stringify({
+        count: results.length,
+        ...(results.excludedExported > 0 && { excludedExported: results.excludedExported }),
+        ...(results.excludedDecorated > 0 && { excludedDecorated: results.excludedDecorated }),
+        symbols: results.map(item => ({
+            name: item.name,
+            type: item.type,
+            file: item.file,
+            startLine: item.startLine,
+            endLine: item.endLine,
+            ...(item.isExported && { isExported: true }),
+            ...(item.decorators && item.decorators.length > 0 && { decorators: item.decorators }),
+            ...(item.annotations && item.annotations.length > 0 && { annotations: item.annotations })
+        }))
+    }, null, 2);
+}
+
+/**
+ * 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',
+        cli: 'CLI Handlers',
+        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 = {
+    formatToc,
+    formatTocJson,
+    formatStats,
+    formatStatsJson,
+    formatDeadcode,
+    formatDeadcodeJson,
+    formatEntrypoints,
+    formatEntrypointsJson,
+};

package/core/output/search.js

@@ -0,0 +1,307 @@
+/**
+ * core/output/search.js - Text search, structural search, example, typedef, tests formatters
+ */
+
+const { detectDoubleEscaping } = require('./shared');
+
+/**
+ * Format search command output
+ */
+function formatSearch(results, term) {
+    const meta = results.meta;
+    const fallbackNote = meta && meta.regexFallback
+        ? `\nNote: Invalid regex (${meta.regexFallback}). Fell back to plain text search.`
+        : '';
+
+    const totalMatches = results.reduce((sum, r) => sum + r.matches.length, 0);
+    if (totalMatches === 0) {
+        if (meta) {
+            const scope = meta.filesSkipped > 0
+                ? `Searched ${meta.filesScanned} of ${meta.totalFiles} file${meta.totalFiles === 1 ? '' : 's'} (${meta.filesSkipped} excluded by filters).`
+                : `Searched ${meta.filesScanned} file${meta.filesScanned === 1 ? '' : 's'}.`;
+            const escapingHint = detectDoubleEscaping(term);
+            return `No matches found for "${term}". ${scope}${fallbackNote}${escapingHint}`;
+        }
+        return `No matches found for "${term}"${fallbackNote}`;
+    }
+
+    const lines = [];
+    const fileWord = results.length === 1 ? 'file' : 'files';
+    lines.push(`Found ${totalMatches} match${totalMatches === 1 ? '' : 'es'} for "${term}" in ${results.length} ${fileWord}:`);
+    if (fallbackNote) lines.push(fallbackNote.trim());
+    lines.push('═'.repeat(60));
+
+    for (const result of results) {
+        lines.push(`\n${result.file}`);
+        for (const m of result.matches) {
+            if (m.before && m.before.length > 0) {
+                for (const line of m.before) {
+                    lines.push(`      ... ${line.trim()}`);
+                }
+            }
+            lines.push(`  ${m.line}: ${m.content.trim()}`);
+            if (m.after && m.after.length > 0) {
+                for (const line of m.after) {
+                    lines.push(`      ... ${line.trim()}`);
+                }
+            }
+        }
+    }
+
+    if (meta && meta.truncatedMatches > 0) {
+        lines.push(`\n${results.reduce((s, r) => s + r.matches.length, 0)} shown of ${meta.totalMatches} total matches. Use top= to see more.`);
+    }
+
+    if (meta && meta.testsExcluded && meta.filesSkipped > 0) {
+        lines.push(`\nNote: ${meta.filesSkipped} test file${meta.filesSkipped === 1 ? '' : 's'} hidden by default (use include_tests=true to include).`);
+    }
+
+    return lines.join('\n');
+}
+
+/**
+ * Format search results as JSON
+ */
+function formatSearchJson(results, term) {
+    const meta = results.meta;
+    const obj = {
+        term,
+        totalMatches: (meta && meta.totalMatches != null) ? meta.totalMatches : results.reduce((sum, r) => sum + r.matches.length, 0),
+        files: results.map(r => ({
+            file: r.file,
+            matchCount: r.matches.length,
+            matches: r.matches.map(m => ({
+                line: m.line,
+                content: m.content  // FULL content
+            }))
+        }))
+    };
+    if (meta) {
+        obj.filesScanned = meta.filesScanned;
+        obj.filesSkipped = meta.filesSkipped;
+        obj.totalFiles = meta.totalFiles;
+        if (meta.regexFallback) obj.regexFallback = meta.regexFallback;
+        if (meta.truncatedMatches > 0) obj.truncatedMatches = meta.truncatedMatches;
+    }
+    return JSON.stringify(obj, null, 2);
+}
+
+/**
+ * Format structural search results (index-based queries)
+ */
+function formatStructuralSearch(result) {
+    const { results, meta } = result;
+    const lines = [];
+
+    // Build query description
+    const parts = [];
+    if (meta.query.type) parts.push(`type=${meta.query.type}`);
+    if (meta.query.term) parts.push(`name="${meta.query.term}"`);
+    if (meta.query.param) parts.push(`param="${meta.query.param}"`);
+    if (meta.query.receiver) parts.push(`receiver="${meta.query.receiver}"`);
+    if (meta.query.returns) parts.push(`returns="${meta.query.returns}"`);
+    if (meta.query.decorator) parts.push(`decorator="${meta.query.decorator}"`);
+    if (meta.query.exported) parts.push('exported');
+    if (meta.query.unused) parts.push('unused');
+    const queryStr = parts.join(', ');
+
+    lines.push(`Structural search: ${queryStr}`);
+    lines.push('═'.repeat(60));
+
+    if (results.length === 0) {
+        lines.push('No matches found.');
+        return lines.join('\n');
+    }
+
+    lines.push(`Found ${meta.totalMatched} match${meta.totalMatched === 1 ? '' : 'es'}${meta.shown < meta.totalMatched ? ` (showing ${meta.shown})` : ''}:`);
+    lines.push('');
+
+    // Group by file
+    let currentFile = null;
+    for (const r of results) {
+        if (r.file !== currentFile) {
+            currentFile = r.file;
+            lines.push(`${r.file}`);
+        }
+
+        if (r.kind === 'call') {
+            lines.push(`  ${r.line}: ${r.name}()${r.isMethod ? ' [method]' : ''}`);
+        } else {
+            let sig = `  ${r.line}: ${r.kind} ${r.name}`;
+            if (r.params) sig += `(${r.params})`;
+            if (r.returnType) sig += ` → ${r.returnType}`;
+            if (r.className) sig += ` [${r.className}]`;
+            if (r.decorators) sig += ` @${r.decorators.join(', @')}`;
+            lines.push(sig);
+        }
+    }
+
+    if (meta.shown < meta.totalMatched) {
+        lines.push(`\n${meta.shown} of ${meta.totalMatched} shown. Use top= to see more.`);
+    }
+
+    return lines.join('\n');
+}
+
+function formatStructuralSearchJson(result) {
+    return JSON.stringify(result, null, 2);
+}
+
+/**
+ * Format example result as text
+ */
+function formatExample(result, name) {
+    if (!result || !result.best) return `No call examples found for "${name}"`;
+
+    const best = result.best;
+    const lines = [];
+    lines.push(`Best example of "${name}":`);
+    lines.push('═'.repeat(60));
+    lines.push(`${best.relativePath}:${best.line}`);
+    lines.push('');
+
+    if (best.before) {
+        for (let i = 0; i < best.before.length; i++) {
+            const ln = best.line - best.before.length + i;
+            lines.push(`${ln.toString().padStart(4)}| ${best.before[i]}`);
+        }
+    }
+
+    lines.push(`${best.line.toString().padStart(4)}| ${best.content}  <--`);
+
+    if (best.after) {
+        for (let i = 0; i < best.after.length; i++) {
+            const ln = best.line + i + 1;
+            lines.push(`${ln.toString().padStart(4)}| ${best.after[i]}`);
+        }
+    }
+
+    lines.push('');
+    lines.push(`Score: ${best.score} (${result.totalCalls} total calls)`);
+    lines.push(`Why: ${best.reasons.length > 0 ? best.reasons.join(', ') : 'first available call'}`);
+
+    return lines.join('\n');
+}
+
+/**
+ * Format example command output - JSON
+ */
+function formatExampleJson(result, name) {
+    if (!result || !result.best) {
+        return JSON.stringify({ found: false, query: name, error: `No call examples found for "${name}"` }, null, 2);
+    }
+
+    const best = result.best;
+    return JSON.stringify({
+        found: true,
+        query: name,
+        totalCalls: result.totalCalls,
+        best: {
+            file: best.relativePath || best.file,
+            line: best.line,
+            content: best.content,
+            score: best.score,
+            reasons: best.reasons || [],
+            ...(best.before && best.before.length > 0 && { before: best.before }),
+            ...(best.after && best.after.length > 0 && { after: best.after })
+        }
+    }, null, 2);
+}
+
+/**
+ * Format typedef command output - text
+ */
+function formatTypedef(types, name) {
+    const lines = [`Type definitions for "${name}":\n`];
+
+    if (types.length === 0) {
+        lines.push('  (none found)');
+    } else {
+        for (const t of types) {
+            lines.push(`${t.relativePath}:${t.startLine}  ${t.type} ${t.name}`);
+            if (t.usageCount !== undefined) {
+                lines.push(`  (${t.usageCount} usages)`);
+            }
+            if (t.code) {
+                lines.push('');
+                lines.push('─── CODE ───');
+                lines.push(t.code);
+                lines.push('');
+            }
+        }
+    }
+
+    return lines.join('\n');
+}
+
+/**
+ * Format typedef as JSON
+ */
+function formatTypedefJson(types, name) {
+    return JSON.stringify({
+        query: name,
+        count: types.length,
+        types: types.map(t => ({
+            name: t.name,
+            type: t.type,
+            file: t.relativePath || t.file,
+            startLine: t.startLine,
+            endLine: t.endLine,
+            ...(t.usageCount !== undefined && { usageCount: t.usageCount }),
+            ...(t.code && { code: t.code })
+        }))
+    }, null, 2);
+}
+
+/**
+ * Format tests command output - text
+ */
+function formatTests(tests, name) {
+    const lines = [`Tests for "${name}":\n`];
+
+    if (tests.length === 0) {
+        lines.push('  (no tests found)');
+    } else {
+        const totalMatches = tests.reduce((sum, t) => sum + t.matches.length, 0);
+        lines.push(`Found ${totalMatches} matches in ${tests.length} test file(s):\n`);
+
+        for (const testFile of tests) {
+            lines.push(testFile.file);
+            for (const match of testFile.matches) {
+                const typeLabel = match.matchType === 'test-case' ? '[test]' :
+                    match.matchType === 'import' ? '[import]' :
+                    match.matchType === 'call' ? '[call]' :
+                    match.matchType === 'string-ref' ? '[string]' : '[ref]';
+                lines.push(`  ${match.line}: ${typeLabel} ${match.content}`);
+            }
+            lines.push('');
+        }
+    }
+
+    return lines.join('\n');
+}
+
+/**
+ * Format tests as JSON
+ */
+function formatTestsJson(tests, name) {
+    return JSON.stringify({
+        query: name,
+        testFileCount: tests.length,
+        totalMatches: tests.reduce((sum, t) => sum + t.matches.length, 0),
+        testFiles: tests
+    }, null, 2);
+}
+
+module.exports = {
+    formatSearch,
+    formatSearchJson,
+    formatStructuralSearch,
+    formatStructuralSearchJson,
+    formatExample,
+    formatExampleJson,
+    formatTypedef,
+    formatTypedefJson,
+    formatTests,
+    formatTestsJson,
+};