ucn 3.8.12 → 3.8.14

package/core/registry.js

@@ -84,8 +84,65 @@ const PARAM_MAP = {
     top_level:         'topLevel',
     max_files:         'maxFiles',
     max_chars:         'maxChars',
+    follow_symlinks:   'followSymlinks',
 };
 
+// ============================================================================
+// FLAG APPLICABILITY MATRIX
+// ============================================================================
+
+// Per-command list of accepted flag names (camelCase). Source of truth for help text,
+// MCP schema validation, and architecture guards.
+// file* = file is the command subject (required), not a filter pattern.
+const FLAG_APPLICABILITY = {
+    // Understanding code
+    about:        ['file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'top', 'all', 'withTypes', 'minConfidence', 'showConfidence'],
+    context:      ['file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'minConfidence', 'showConfidence'],
+    impact:       ['file', 'exclude', 'className', 'top'],
+    blast:        ['file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence'],
+    reverseTrace: ['file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence'],
+    smart:        ['file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'withTypes', 'minConfidence'],
+    trace:        ['file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'all', 'minConfidence'],
+    example:      ['file', 'className'],
+    related:      ['file', 'className', 'top', 'all'],
+    // Finding code
+    find:         ['file', 'exclude', 'className', 'includeTests', 'top', 'limit', 'exact', 'in', 'all'],
+    usages:       ['file', 'exclude', 'className', 'includeTests', 'limit', 'codeOnly', 'context', 'in'],
+    toc:          ['file', 'exclude', 'top', 'limit', 'all', 'detailed', 'topLevel', 'in'],
+    search:       ['file', 'exclude', 'includeTests', 'top', 'limit', 'codeOnly', 'caseSensitive', 'context', 'regex', 'in', 'type', 'param', 'receiver', 'returns', 'decorator', 'exported', 'unused'],
+    tests:        ['className', 'callsOnly'],
+    affectedTests:['file', 'exclude', 'className', 'includeMethods', 'includeUncertain', 'depth', 'minConfidence'],
+    deadcode:     ['file', 'exclude', 'includeTests', 'includeExported', 'includeDecorated', 'limit', 'in'],
+    entrypoints:  ['file', 'exclude', 'includeTests', 'limit', 'type', 'framework'],
+    // Extracting code
+    fn:           ['file', 'className', 'all'],
+    class:        ['file', 'className', 'all', 'maxLines'],
+    lines:        ['file', 'range'],
+    expand:       [],
+    // File dependencies
+    imports:      ['file'],
+    exporters:    ['file'],
+    fileExports:  ['file'],
+    graph:        ['file', 'depth', 'direction'],
+    circularDeps: ['file', 'exclude'],
+    // Refactoring
+    verify:       ['file', 'className'],
+    plan:         ['file', 'className', 'addParam', 'removeParam', 'renameTo', 'defaultValue'],
+    diffImpact:   ['file', 'limit', 'base', 'staged', 'all'],
+    // Other
+    typedef:      ['file', 'className', 'exact'],
+    stacktrace:   ['stack'],
+    api:          ['file', 'limit'],
+    stats:        ['functions', 'top'],
+};
+
+// Commands whose output is project-wide — truncation means you need a filter, not more text.
+// Used by MCP server for tighter default output limits.
+const BROAD_COMMANDS = new Set([
+    'toc', 'entrypoints', 'diffImpact', 'affectedTests',
+    'deadcode', 'usages', 'reverseTrace', 'circularDeps',
+]);
+
 // ============================================================================
 // HELPERS
 // ============================================================================
@@ -172,6 +229,8 @@ module.exports = {
     CLI_ALIASES,
     MCP_ALIASES,
     PARAM_MAP,
+    FLAG_APPLICABILITY,
+    BROAD_COMMANDS,
     resolveCommand,
     normalizeParams,
     getCliCommandSet,

package/core/reporting.js

@@ -0,0 +1,258 @@
+/**
+ * core/reporting.js — Project statistics and table of contents
+ *
+ * Extracted from project.js. All functions take an `index` (ProjectIndex)
+ * as the first argument instead of using `this`.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { isTestFile } = require('./discovery');
+
+/**
+ * Get project statistics: file counts, symbol counts, LOC, language breakdown.
+ *
+ * @param {object} index - ProjectIndex instance
+ * @param {object} options - { functions }
+ * @returns {object}
+ */
+function getStats(index, options = {}) {
+    // Count total symbols (not just unique names)
+    let totalSymbols = 0;
+    for (const [name, symbols] of index.symbols) {
+        totalSymbols += symbols.length;
+    }
+
+    const stats = {
+        root: index.root,
+        files: index.files.size,
+        symbols: totalSymbols,  // Total symbol count, not unique names
+        buildTime: index.buildTime,
+        byLanguage: {},
+        byType: {},
+        ...(index.truncated && { truncated: index.truncated })
+    };
+
+    for (const [filePath, fileEntry] of index.files) {
+        const lang = fileEntry.language;
+        if (!stats.byLanguage[lang]) {
+            stats.byLanguage[lang] = { files: 0, lines: 0, symbols: 0 };
+        }
+        stats.byLanguage[lang].files++;
+        stats.byLanguage[lang].lines += fileEntry.lines;
+        stats.byLanguage[lang].symbols += fileEntry.symbols.length;
+    }
+
+    for (const [name, symbols] of index.symbols) {
+        for (const sym of symbols) {
+            if (!Object.hasOwn(stats.byType, sym.type)) {
+                stats.byType[sym.type] = 0;
+            }
+            stats.byType[sym.type]++;
+        }
+    }
+
+    // Surface build warnings (parse failures, skipped files)
+    if (index.failedFiles && index.failedFiles.size > 0) {
+        stats.warnings = {
+            failedFiles: [...index.failedFiles].map(f => path.relative(index.root, f)),
+            count: index.failedFiles.size
+        };
+    }
+
+    // Per-function line counts for complexity audits
+    if (options.functions) {
+        const functions = [];
+        for (const [name, symbols] of index.symbols) {
+            for (const sym of symbols) {
+                if (sym.type === 'function' || sym.type === 'method' || sym.type === 'static' ||
+                    sym.type === 'constructor' || sym.type === 'public' || sym.type === 'abstract' ||
+                    sym.type === 'classmethod') {
+                    const lineCount = sym.endLine - sym.startLine + 1;
+                    const relativePath = sym.relativePath || (sym.file ? path.relative(index.root, sym.file) : '');
+                    functions.push({
+                        name: sym.className ? `${sym.className}.${sym.name}` : sym.name,
+                        file: relativePath,
+                        startLine: sym.startLine,
+                        lines: lineCount
+                    });
+                }
+            }
+        }
+        functions.sort((a, b) => b.lines - a.lines);
+        stats.functions = functions;
+    }
+
+    return stats;
+}
+
+/**
+ * Get table of contents for all files in the project.
+ *
+ * @param {object} index - ProjectIndex instance
+ * @param {object} options - { file, exclude, in, detailed, topLevel, all, top }
+ * @returns {object}
+ */
+function getToc(index, options = {}) {
+    const files = [];
+    let totalFunctions = 0;
+    let totalClasses = 0;
+    let totalState = 0;
+    let totalLines = 0;
+    let totalDynamic = 0;
+    let totalTests = 0;
+
+    // When file= is specified, scope to matching files only
+    let fileFilter = null;
+    if (options.file) {
+        const resolved = index.findFile(options.file);
+        if (resolved) {
+            fileFilter = new Set([resolved]);
+        } else {
+            // Try substring match for partial paths
+            const matching = [];
+            for (const fp of index.files.keys()) {
+                const rp = path.relative(index.root, fp);
+                if (rp.includes(options.file) || fp.includes(options.file)) {
+                    matching.push(fp);
+                }
+            }
+            if (matching.length > 0) {
+                fileFilter = new Set(matching);
+            } else {
+                return {
+                    meta: { complete: true, skipped: 0, dynamicImports: 0, uncertain: 0 },
+                    totals: { files: 0, lines: 0, functions: 0, classes: 0, state: 0, testFiles: 0 },
+                    summary: { topFunctionFiles: [], topLineFiles: [], entryFiles: [] },
+                    files: [],
+                    hiddenFiles: 0,
+                    error: `File not found in project: ${options.file}`
+                };
+            }
+        }
+    }
+
+    for (const [filePath, fileEntry] of index.files) {
+        if (fileFilter && !fileFilter.has(filePath)) continue;
+        if (options.exclude && options.exclude.length > 0) {
+            if (!index.matchesFilters(fileEntry.relativePath, { exclude: options.exclude })) continue;
+        }
+        if (options.in) {
+            if (!index.matchesFilters(fileEntry.relativePath, { in: options.in })) continue;
+        }
+        let functions = fileEntry.symbols.filter(s =>
+            s.type === 'function' || s.type === 'method' || s.type === 'static' ||
+            s.type === 'constructor' || s.type === 'public' || s.type === 'abstract' ||
+            s.type === 'classmethod'
+        );
+        const classes = fileEntry.symbols.filter(s =>
+            ['class', 'interface', 'type', 'enum', 'struct', 'trait', 'impl', 'record', 'namespace'].includes(s.type)
+        );
+        const state = fileEntry.symbols.filter(s => s.type === 'state');
+
+        if (options.topLevel) {
+            functions = functions.filter(fn => !fn.isNested && (!fn.indent || fn.indent === 0));
+        }
+
+        totalFunctions += functions.length;
+        totalClasses += classes.length;
+        totalState += state.length;
+        totalLines += fileEntry.lines;
+        totalDynamic += fileEntry.dynamicImports || 0;
+        if (isTestFile(fileEntry.relativePath, fileEntry.language)) totalTests += 1;
+
+        const entry = {
+            file: fileEntry.relativePath,
+            language: fileEntry.language,
+            lines: fileEntry.lines,
+            functions: functions.length,
+            classes: classes.length,
+            state: state.length
+        };
+
+        if (options.detailed) {
+            entry.symbols = { functions, classes, state };
+        }
+
+        files.push(entry);
+    }
+
+    // Hints: top files by function count and lines
+    const hintLimit = options.all ? Infinity : 3;
+    const topFunctionFiles = [...files]
+        .sort((a, b) => b.functions - a.functions || b.lines - a.lines)
+        .filter(f => f.functions > 0)
+        .slice(0, hintLimit)
+        .map(f => ({ file: f.file, functions: f.functions }));
+
+    const topLineFiles = [...files]
+        .sort((a, b) => b.lines - a.lines)
+        .slice(0, hintLimit)
+        .map(f => ({ file: f.file, lines: f.lines }));
+
+    // Entry point candidates
+    const entryPattern = /(main|index|server|app)\.(js|jsx|ts|tsx|py|go|rs|java)$/i;
+    const entryFiles = files
+        .filter(f => entryPattern.test(f.file))
+        .slice(0, options.all ? Infinity : 5)
+        .map(f => f.file);
+
+    // Also detect entry points from package.json main/exports fields
+    const pkgJsonPath = path.join(index.root, 'package.json');
+    try {
+        const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+        const mainField = pkgJson.main || pkgJson.module;
+        if (mainField) {
+            const mainFile = path.relative(index.root, path.resolve(index.root, mainField));
+            if (files.some(f => f.file === mainFile) && !entryFiles.includes(mainFile)) {
+                entryFiles.unshift(mainFile);
+            }
+        }
+    } catch {
+        // No package.json or invalid JSON — skip
+    }
+
+    // Apply top limit for detailed mode to avoid massive output
+    const top = options.top > 0 ? options.top : (options.detailed && !options.all ? 50 : Infinity);
+    let hiddenFiles = 0;
+    let displayFiles = files;
+    if (top < files.length) {
+        hiddenFiles = files.length - top;
+        displayFiles = files.slice(0, top);
+    }
+
+    // Count files with no symbols (generated/empty files)
+    const emptyFiles = files.filter(f => f.functions === 0 && f.classes === 0 && f.state === 0).length;
+
+    return {
+        meta: {
+            complete: totalDynamic === 0,
+            skipped: 0,
+            dynamicImports: totalDynamic,
+            uncertain: 0,
+            projectLanguage: index._getPredominantLanguage(),
+            ...(fileFilter && { filteredBy: options.file, matchedFiles: files.length }),
+            ...(options.in && { scopedTo: options.in }),
+            ...(emptyFiles > 0 && fileFilter && { emptyFiles })
+        },
+        totals: {
+            files: files.length,
+            lines: totalLines,
+            functions: totalFunctions,
+            classes: totalClasses,
+            state: totalState,
+            testFiles: totalTests
+        },
+        summary: {
+            topFunctionFiles,
+            topLineFiles,
+            entryFiles
+        },
+        files: displayFiles,
+        hiddenFiles
+    };
+}
+
+module.exports = { getStats, getToc };