ucn 3.8.23 → 3.8.25

package/cli/index.js

@@ -15,13 +15,132 @@ const { ProjectIndex } = require('../core/project');
 const { expandGlob, findProjectRoot } = require('../core/discovery');
 const output = require('../core/output');
 const { getCliCommandSet, resolveCommand, FLAG_APPLICABILITY, toCliName, FILE_LOCAL_COMMANDS } = require('../core/registry');
+const { looksLikeHandle, parseSymbolHandle } = require('../core/shared');
+
+/**
+ * Convert a CLI argument that may be a stable handle into the symbol name
+ * that's appropriate for headers / "Usages of X" / "find Y" displays.
+ * Plain names pass through unchanged.
+ */
+function nameForDisplay(arg) {
+    if (typeof arg !== 'string') return arg;
+    if (!looksLikeHandle(arg)) return arg;
+    const h = parseSymbolHandle(arg);
+    return h && h.name ? h.name : arg;
+}
 const { execute } = require('../core/execute');
 const { ExpandCache } = require('../core/expand-cache');
 
 // Sentinel error for command failures that have already printed their message.
 // Thrown instead of process.exit(1) so finally blocks can run (cache save).
 class CommandError extends Error { constructor() { super(); } }
-function fail(msg) { console.error(msg); throw new CommandError(); }
+
+// Thrown by validateNumericFlags when a numeric flag has a bad value.
+// The CLI top-level catches this, prints the message, and exits 1. Interactive
+// mode catches it inside its REPL try/catch and continues the session.
+class FlagValidationError extends Error {
+    constructor(msg) { super(msg); this.name = 'FlagValidationError'; }
+}
+
+/**
+ * Validate that a raw flag value is a positive integer. Returns the parsed
+ * number when valid, or throws FlagValidationError. Callers pass `null`/`undefined`
+ * raw values through unchanged (no flag → no validation).
+ *
+ * @param {string|null|undefined} raw - The raw string captured from the CLI/interactive token.
+ * @param {string} flagName - The CLI flag name including dashes (e.g. "--top") for error messages.
+ * @param {object} [opts]
+ * @param {boolean} [opts.allowZero=false] - Whether 0 is a valid value (e.g. depth=0 may be meaningful).
+ * @param {number} [opts.cap=10000000] - Maximum accepted value (rejects 1e100 etc).
+ * @returns {number|undefined} The validated integer, or undefined when raw is null/undefined.
+ */
+function validatePositiveInt(raw, flagName, { allowZero = false, cap = 10000000 } = {}) {
+    if (raw == null) return undefined;
+    const label = allowZero ? 'non-negative integer' : 'positive integer';
+    const trimmed = String(raw).trim();
+    if (trimmed === '') {
+        throw new FlagValidationError(`Invalid ${flagName} value: must be a ${label} (got "${raw}")`);
+    }
+    const n = Number(trimmed);
+    if (!isFinite(n) || isNaN(n)) {
+        throw new FlagValidationError(`Invalid ${flagName} value: must be a ${label} (got "${raw}")`);
+    }
+    if (!Number.isInteger(n)) {
+        throw new FlagValidationError(`Invalid ${flagName} value: must be a ${label} (got ${n})`);
+    }
+    if (allowZero) {
+        if (n < 0) {
+            throw new FlagValidationError(`Invalid ${flagName} value: must be a ${label} (got ${n})`);
+        }
+    } else if (n <= 0) {
+        throw new FlagValidationError(`Invalid ${flagName} value: must be a ${label} (got ${n})`);
+    }
+    if (n > cap) {
+        throw new FlagValidationError(`Invalid ${flagName} value: ${n} exceeds maximum (${cap})`);
+    }
+    return n;
+}
+
+/**
+ * Validate all numeric flags on a parsed flags object. Looks at the *Raw
+ * companion strings preserved by parseFlags so we catch user-supplied bad
+ * values regardless of whether the parsed numeric form happened to be falsy.
+ * Mutates `flags` to hold the validated numeric values.
+ *
+ * Throws FlagValidationError on the first invalid flag.
+ */
+function validateNumericFlags(flags) {
+    // --top: positive integer, no zero. Used by stats/find/context/etc.
+    if (flags.topRaw != null) {
+        flags.top = validatePositiveInt(flags.topRaw, '--top');
+    }
+    // --limit: positive integer, no zero. Reject "0 = no limit" silent coercion.
+    if (flags.limitRaw != null) {
+        flags.limit = validatePositiveInt(flags.limitRaw, '--limit');
+    }
+    // --max-files: positive integer, no zero.
+    if (flags.maxFilesRaw != null) {
+        flags.maxFiles = validatePositiveInt(flags.maxFilesRaw, '--max-files');
+    }
+    // --max-lines: positive integer, no zero. Used by class command.
+    if (flags.maxLinesRaw != null) {
+        flags.maxLines = validatePositiveInt(flags.maxLinesRaw, '--max-lines');
+    }
+    // --depth: non-negative integer (0 is meaningful: "this symbol only").
+    if (flags.depthRaw != null) {
+        flags.depth = validatePositiveInt(flags.depthRaw, '--depth', { allowZero: true });
+    }
+    // --context: non-negative integer (0 = no surrounding lines).
+    if (flags.contextRaw != null) {
+        flags.context = validatePositiveInt(flags.contextRaw, '--context', { allowZero: true });
+    }
+    // --workers: non-negative integer (0 disables parallel build).
+    if (flags.workersRaw != null) {
+        flags.workers = validatePositiveInt(flags.workersRaw, '--workers', { allowZero: true });
+    }
+}
+
+/**
+ * Print an error message and abort. When `--json` is in effect, write a JSON
+ * error envelope to stdout (so JSON-consuming pipelines see structured output)
+ * and write the same plain message to stderr (for humans piping to a TTY).
+ */
+function fail(msg) {
+    // Honor --json by writing a structured envelope to stdout for pipelines.
+    // We use try/catch around symbol lookups because `flags` may not be initialized
+    // yet when fail() is called from the early arg-parsing path (TDZ).
+    let wantsJson = false;
+    try { if (typeof flags !== 'undefined' && flags && flags.json) wantsJson = true; } catch (_) {}
+    if (!wantsJson) {
+        try { if (Array.isArray(process.argv) && process.argv.includes('--json')) wantsJson = true; } catch (_) {}
+    }
+    if (wantsJson) {
+        const env = { meta: { ok: false }, error: typeof msg === 'string' ? msg : String(msg) };
+        try { process.stdout.write(JSON.stringify(env) + '\n'); } catch (_) {}
+    }
+    console.error(msg);
+    throw new CommandError();
+}
 
 // ============================================================================
 // ARGUMENT PARSING
@@ -74,10 +193,11 @@ function parseFlags(tokens) {
         exclude: parseExclude(),
         in: getValueFlag('--in'),
         includeTests: tokens.includes('--include-tests') ? true : undefined,
+        excludeTests: tokens.includes('--exclude-tests') ? true : undefined,
         includeExported: tokens.includes('--include-exported') || undefined,
         includeDecorated: tokens.includes('--include-decorated') || undefined,
         includeUncertain: tokens.includes('--include-uncertain') || undefined,
-        includeMethods: tokens.some(a => a === '--include-methods=false') ? false : tokens.some(a => a === '--include-methods' || (a.startsWith('--include-methods=') && a !== '--include-methods=false')) ? true : undefined,
+        includeMethods: tokens.some(a => a === '--include-methods=false' || a === '--no-include-methods') ? false : tokens.some(a => a === '--include-methods' || (a.startsWith('--include-methods=') && a !== '--include-methods=false')) ? true : undefined,
         detailed: tokens.includes('--detailed') || undefined,
         topLevel: tokens.includes('--top-level') || undefined,
         all: tokens.includes('--all') || undefined,
@@ -88,8 +208,14 @@ function parseFlags(tokens) {
         withTypes: tokens.includes('--with-types') || undefined,
         expand: tokens.includes('--expand') || undefined,
         depth: getValueFlag('--depth'),
+        depthRaw: getValueFlag('--depth'),
+        // `top` is the parsed numeric value (NaN/0 default → falsy). `topRaw`
+        // preserves the original string so downstream validators can produce
+        // helpful errors for "abc"/"-1"/"0" instead of silently defaulting.
         top: parseInt(getValueFlag('--top') || '0'),
+        topRaw: getValueFlag('--top'),
         context: parseInt(getValueFlag('--context') || '0'),
+        contextRaw: getValueFlag('--context'),
         direction: getValueFlag('--direction'),
         addParam: getValueFlag('--add-param'),
         removeParam: getValueFlag('--remove-param'),
@@ -97,12 +223,20 @@ function parseFlags(tokens) {
         defaultValue: getValueFlag('--default'),
         base: getValueFlag('--base'),
         staged: tokens.includes('--staged') || undefined,
+        deep: tokens.includes('--deep') || undefined,
+        compact: tokens.includes('--compact') || undefined,
         maxLines: getValueFlag('--max-lines') || null,
+        maxLinesRaw: getValueFlag('--max-lines'),
         regex: tokens.includes('--no-regex') ? false : undefined,
         functions: tokens.includes('--functions') || undefined,
+        hot: tokens.includes('--hot') || undefined,
+        diverse: tokens.includes('--diverse') || undefined,
+        git: tokens.includes('--git') || undefined,
         className: getValueFlag('--class-name'),
         limit: parseInt(getValueFlag('--limit') || '0') || undefined,
+        limitRaw: getValueFlag('--limit'),
         maxFiles: parseInt(getValueFlag('--max-files') || '0') || undefined,
+        maxFilesRaw: getValueFlag('--max-files'),
         // Structural search flags
         type: getValueFlag('--type'),
         param: getValueFlag('--param'),
@@ -111,10 +245,20 @@ function parseFlags(tokens) {
         decorator: getValueFlag('--decorator'),
         exported: tokens.includes('--exported') || undefined,
         unused: tokens.includes('--unused') || undefined,
-        showConfidence: tokens.includes('--no-confidence') ? false : undefined,
+        showConfidence: (tokens.includes('--hide-confidence') || tokens.includes('--no-confidence')) ? false : undefined,
         minConfidence: parseFloat(getValueFlag('--min-confidence') || '0') || 0,
+        unreachableOnly: tokens.includes('--unreachable-only') || undefined,
         framework: getValueFlag('--framework'),
+        // endpoints command flags
+        bridge: tokens.includes('--bridge') || undefined,
+        serverOnly: tokens.includes('--server-only') || undefined,
+        clientOnly: tokens.includes('--client-only') || undefined,
+        unmatched: tokens.includes('--unmatched') || undefined,
+        method: getValueFlag('--method'),
+        prefix: getValueFlag('--prefix'),
+        hideUncertain: tokens.includes('--hide-uncertain') || tokens.includes('--no-uncertain') || undefined,
         stack: getValueFlag('--stack'),
+        workersRaw: getValueFlag('--workers'),
         workers: (() => {
             const v = getValueFlag('--workers');
             if (v === null) return undefined;
@@ -138,17 +282,19 @@ const knownFlags = new Set([
     '--help', '-h', '--mcp',
     '--json', '--verbose', '--no-quiet', '--quiet',
     '--code-only', '--with-types', '--top-level', '--exact', '--case-sensitive',
-    '--no-cache', '--clear-cache', '--include-tests',
-    '--include-exported', '--include-decorated', '--expand', '--interactive', '-i', '--all', '--include-methods', '--include-uncertain', '--detailed', '--calls-only',
+    '--no-cache', '--clear-cache', '--include-tests', '--exclude-tests',
+    '--include-exported', '--include-decorated', '--expand', '--interactive', '-i', '--all', '--include-methods', '--no-include-methods', '--include-uncertain', '--detailed', '--calls-only',
     '--file', '--context', '--exclude', '--not', '--in',
     '--depth', '--direction', '--add-param', '--remove-param', '--rename-to',
     '--default', '--top', '--no-follow-symlinks',
     '--base', '--staged', '--stack',
-    '--regex', '--no-regex', '--functions',
+    '--regex', '--no-regex', '--functions', '--hot', '--diverse', '--git',
     '--max-lines', '--class-name', '--limit', '--max-files',
     '--type', '--param', '--receiver', '--returns', '--decorator', '--exported', '--unused',
-    '--show-confidence', '--no-confidence', '--min-confidence',
-    '--framework', '--workers'
+    '--hide-confidence', '--no-confidence', '--min-confidence', '--unreachable-only',
+    '--framework', '--workers', '--deep', '--compact',
+    '--bridge', '--server-only', '--client-only', '--unmatched',
+    '--method', '--prefix', '--hide-uncertain', '--no-uncertain'
 ]);
 
 // Handle help flag
@@ -171,6 +317,23 @@ if (unknownFlags.length > 0) {
     process.exit(1);
 }
 
+// Validate numeric flag values up front so bad input fails before we build
+// any indexes. Applies to --top, --limit, --max-files, --max-lines, --depth,
+// --context, --workers. Throws FlagValidationError with a helpful message.
+try {
+    validateNumericFlags(flags);
+} catch (e) {
+    if (e instanceof FlagValidationError) {
+        if (flags.json) {
+            const env = { meta: { ok: false }, error: e.message };
+            try { process.stdout.write(JSON.stringify(env) + '\n'); } catch (_) {}
+        }
+        console.error(e.message);
+        process.exit(1);
+    }
+    throw e;
+}
+
 // Value flags that consume the next token (space form: --flag value)
 const VALUE_FLAGS = new Set([
     '--file', '--depth', '--top', '--context', '--direction',
@@ -178,7 +341,7 @@ const VALUE_FLAGS = new Set([
     '--base', '--exclude', '--not', '--in', '--max-lines', '--class-name',
     '--type', '--param', '--receiver', '--returns', '--decorator',
     '--limit', '--max-files', '--min-confidence', '--stack', '--framework',
-    '--workers'
+    '--workers', '--method', '--prefix'
 ]);
 
 // Remove flags from args, then add args after -- (which are all positional)
@@ -479,7 +642,7 @@ function runProjectCommand(rootDir, command, arg) {
         // Map from camelCase flag name to CLI flag string
         const flagToCli = (f) => '--' + f.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
         // Flags that are global (not command-specific) — skip warning for these
-        const globalFlags = new Set(['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles', 'verbose', 'expand', 'interactive', '_fileFromFileMode']);
+        const globalFlags = new Set(['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles', 'verbose', 'expand', 'interactive', '_fileFromFileMode', 'topRaw', 'limitRaw', 'maxFilesRaw', 'maxLinesRaw', 'depthRaw', 'contextRaw', 'workersRaw']);
         for (const [key, value] of Object.entries(flags)) {
             if (globalFlags.has(key)) continue;
             // Skip unset values (undefined, null, 0, empty array) — but NOT false (explicit negation)
@@ -512,7 +675,7 @@ function runProjectCommand(rootDir, command, arg) {
             if (note) console.error(note);
             printOutput(result,
                 r => output.formatSymbolJson(r, arg),
-                r => output.formatFindDetailed(r, arg, { depth: flags.depth, top: flags.top, all: flags.all })
+                r => output.formatFindDetailed(r, arg, { depth: flags.depth, top: flags.top, all: flags.all, compact: flags.compact })
             );
             break;
         }
@@ -521,19 +684,29 @@ function runProjectCommand(rootDir, command, arg) {
             const { ok, result, error, note } = execute(index, 'usages', { name: arg, ...flags });
             if (!ok) fail(error);
             if (note) console.error(note);
+            const displayName = nameForDisplay(arg);
             printOutput(result,
-                r => output.formatUsagesJson(r, arg),
-                r => output.formatUsages(r, arg)
+                r => output.formatUsagesJson(r, displayName),
+                r => output.formatUsages(r, displayName, { compact: flags.compact })
             );
             break;
         }
 
         case 'example': {
-            const { ok, result, error } = execute(index, 'example', { name: arg, file: flags.file, className: flags.className });
+            const { ok, result, error, note } = execute(index, 'example', {
+                name: arg,
+                file: flags.file,
+                className: flags.className,
+                diverse: flags.diverse,
+                top: flags.top || undefined,
+                includeTests: flags.includeTests,
+            });
             if (!ok) fail(error);
+            if (note) console.error(note);
+            const displayName = nameForDisplay(arg);
             printOutput(result,
-                r => output.formatExampleJson(r, arg),
-                r => output.formatExample(r, arg)
+                r => output.formatExampleJson(r, displayName),
+                r => output.formatExample(r, displayName)
             );
             break;
         }
@@ -549,6 +722,7 @@ function runProjectCommand(rootDir, command, arg) {
                     expandHint: 'Use "expand <N>" or --expand to see code for items',
                     uncertainHint: 'use --include-uncertain to include all',
                     showConfidence: flags.showConfidence !== false,
+                    compact: !!flags.compact,
                 });
                 console.log(text);
 
@@ -577,7 +751,29 @@ function runProjectCommand(rootDir, command, arg) {
                 match, itemNum: expandNum, itemCount: items.length, validateRoot: true
             });
             if (!ok) fail(error);
-            console.log(result.text);
+            if (flags.json) {
+                // Honor --json: structured output with the expanded code + metadata.
+                const env = {
+                    meta: { command: 'expand', item: expandNum },
+                    data: {
+                        item: expandNum,
+                        ...(match && {
+                            name: match.name,
+                            type: match.type,
+                            file: match.relativePath || match.file,
+                            startLine: match.startLine,
+                            endLine: match.endLine,
+                            handle: match.relativePath && match.startLine && match.name
+                                ? `${match.relativePath}:${match.startLine}:${match.name}`
+                                : null,
+                        }),
+                        text: result.text,
+                    },
+                };
+                console.log(JSON.stringify(env, null, 2));
+            } else {
+                console.log(result.text);
+            }
             break;
         }
 
@@ -596,7 +792,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, showConfidence: flags.showConfidence !== false })
+                r => output.formatAbout(r, { expand: flags.expand, root: index.root, depth: flags.depth, showConfidence: flags.showConfidence !== false, compact: !!flags.compact, git: !!flags.git })
             );
             if (note) console.error(note);
             break;
@@ -605,7 +801,7 @@ function runProjectCommand(rootDir, command, arg) {
         case 'impact': {
             const { ok, result, error, note } = execute(index, 'impact', { name: arg, ...flags });
             if (!ok) fail(error);
-            printOutput(result, output.formatImpactJson, output.formatImpact);
+            printOutput(result, output.formatImpactJson, r => output.formatImpact(r, { compact: flags.compact }));
             if (note) console.error(note);
             break;
         }
@@ -663,6 +859,34 @@ function runProjectCommand(rootDir, command, arg) {
             break;
         }
 
+        case 'brief': {
+            requireArg(arg, 'Usage: ucn . brief <name>');
+            const { ok, result, error } = execute(index, 'brief', { name: arg, file: flags.file, className: flags.className, git: flags.git });
+            if (!ok) fail(error);
+            printOutput(result, output.formatBriefJson, output.formatBrief);
+            break;
+        }
+
+        case 'doctor': {
+            const { ok, result, error } = execute(index, 'doctor', {
+                file: flags.file, in: flags.in,
+                limit: flags.limit, deep: flags.deep,
+            });
+            if (!ok) fail(error);
+            printOutput(result, output.formatDoctorJson, output.formatDoctor);
+            break;
+        }
+
+        case 'check': {
+            const { ok, result, error } = execute(index, 'check', {
+                base: flags.base, staged: flags.staged,
+                file: flags.file, limit: flags.limit,
+            });
+            if (!ok) fail(error);
+            printOutput(result, output.formatCheckJson, output.formatCheck);
+            break;
+        }
+
         // ── Extraction commands (via execute) ────────────────────────────
 
         case 'fn': {
@@ -760,9 +984,10 @@ function runProjectCommand(rootDir, command, arg) {
         case 'tests': {
             const { ok, result, error } = execute(index, 'tests', { name: arg, callsOnly: flags.callsOnly, className: flags.className, file: flags.file, exclude: flags.exclude });
             if (!ok) fail(error);
+            const displayName = nameForDisplay(arg);
             printOutput(result,
-                r => output.formatTestsJson(r, arg),
-                r => output.formatTests(r, arg)
+                r => output.formatTestsJson(r, displayName),
+                r => output.formatTests(r, displayName)
             );
             break;
         }
@@ -817,7 +1042,7 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'entrypoints': {
-            const { ok, result, error, note } = execute(index, 'entrypoints', { type: flags.type, framework: flags.framework, file: flags.file, exclude: flags.exclude, includeTests: flags.includeTests, limit: flags.limit });
+            const { ok, result, error, note } = execute(index, 'entrypoints', { type: flags.type, framework: flags.framework, file: flags.file, exclude: flags.exclude, includeTests: flags.includeTests, excludeTests: flags.excludeTests, limit: flags.limit });
             if (!ok) fail(error);
             if (note) console.error(note);
             printOutput(result,
@@ -827,9 +1052,42 @@ function runProjectCommand(rootDir, command, arg) {
             break;
         }
 
+        case 'endpoints': {
+            const { ok, result, error, note } = execute(index, 'endpoints', {
+                file: flags.file,
+                exclude: flags.exclude,
+                limit: flags.limit,
+                framework: flags.framework,
+                bridge: flags.bridge,
+                serverOnly: flags.serverOnly,
+                clientOnly: flags.clientOnly,
+                unmatched: flags.unmatched,
+                method: flags.method,
+                prefix: flags.prefix,
+                hideUncertain: flags.hideUncertain,
+            });
+            if (!ok) fail(error);
+            if (note) console.error(note);
+            printOutput(result,
+                output.formatEndpointsJson,
+                r => output.formatEndpoints(r, { bridge: r._bridge, unmatched: r._unmatched })
+            );
+            break;
+        }
+
         case 'stats': {
-            const { ok, result, error } = execute(index, 'stats', { functions: flags.functions });
+            // MEDIUM-7: pass the raw --top value when present so the executor
+            // can validate it and surface "Invalid --top" errors. Without
+            // this, --top=abc is silently coerced to NaN → undefined and
+            // the user gets the default (10) with no warning.
+            const topVal = flags.topRaw != null ? flags.topRaw : (flags.top || undefined);
+            const { ok, result, error, note } = execute(index, 'stats', {
+                functions: flags.functions,
+                hot: flags.hot,
+                top: topVal,
+            });
             if (!ok) fail(error);
+            if (note) console.error(note);
             printOutput(result,
                 output.formatStatsJson,
                 r => output.formatStats(r, { top: flags.top })
@@ -845,6 +1103,18 @@ function runProjectCommand(rootDir, command, arg) {
             break;
         }
 
+        case 'auditAsync': {
+            const { ok, result, error, note } = execute(index, 'auditAsync', {
+                file: flags.file,
+                exclude: flags.exclude,
+                limit: flags.limit,
+            });
+            if (!ok) fail(error);
+            if (note) console.error(note);
+            printOutput(result, output.formatAuditAsyncJson, output.formatAuditAsync);
+            break;
+        }
+
         default:
             console.error(`Unknown command: ${canonical}`);
             printUsage();
@@ -858,8 +1128,10 @@ function runProjectCommand(rootDir, command, arg) {
     } finally {
         // Save cache after command execution so callsCache populated
         // by findCallers/findCallees gets persisted to disk.
-        // On cache-hit runs, only re-save if callsCache was mutated.
-        if (flags.cache && (needsCacheSave || index.callsCacheDirty)) {
+        // On cache-hit runs, only re-save if callsCache was mutated OR
+        // reachability was computed (MED-1: persists the BFS result so
+        // subsequent cold invocations don't repeat the 7-11s tax).
+        if (flags.cache && (needsCacheSave || index.callsCacheDirty || index.reachabilityDirty)) {
             try { index.saveCache(); } catch (e) { /* best-effort */ }
         }
     }
@@ -966,7 +1238,7 @@ function runGlobCommand(pattern, command, arg) {
     const applicableFlags = FLAG_APPLICABILITY[canonical];
     if (applicableFlags) {
         const flagToCli = (f) => '--' + f.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
-        const globalFlags = new Set(['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles', 'verbose', 'expand', 'interactive', '_fileFromFileMode']);
+        const globalFlags = new Set(['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles', 'verbose', 'expand', 'interactive', '_fileFromFileMode', 'topRaw', 'limitRaw', 'maxFilesRaw', 'maxLinesRaw', 'depthRaw', 'contextRaw', 'workersRaw']);
         for (const [key, value] of Object.entries(flags)) {
             if (globalFlags.has(key)) continue;
             if (value === undefined || value === null || value === 0 || (Array.isArray(value) && value.length === 0)) continue;
@@ -1032,7 +1304,7 @@ function runGlobCommand(pattern, command, arg) {
             break;
         case 'about':
             printOutput(result, output.formatAboutJson,
-                r => output.formatAbout(r, { expand: flags.expand, root: index.root, depth: flags.depth, showConfidence: flags.showConfidence !== false }));
+                r => output.formatAbout(r, { expand: flags.expand, root: index.root, depth: flags.depth, showConfidence: flags.showConfidence !== false, compact: !!flags.compact }));
             break;
         case 'context':
             if (flags.json) {
@@ -1043,6 +1315,7 @@ function runGlobCommand(pattern, command, arg) {
                     uncertainHint: 'use --include-uncertain to include all',
                     expandHint: 'Use --expand to see inline callee previews',
                     showConfidence: flags.showConfidence !== false,
+                    compact: !!flags.compact,
                 });
                 console.log(text);
                 if (flags.expand) {
@@ -1060,6 +1333,15 @@ function runGlobCommand(pattern, command, arg) {
             printOutput(result, output.formatRelatedJson,
                 r => output.formatRelated(r, { all: flags.all, top: flags.top }));
             break;
+        case 'brief':
+            printOutput(result, output.formatBriefJson, output.formatBrief);
+            break;
+        case 'doctor':
+            printOutput(result, output.formatDoctorJson, output.formatDoctor);
+            break;
+        case 'check':
+            printOutput(result, output.formatCheckJson, output.formatCheck);
+            break;
         case 'trace':
             printOutput(result, output.formatTraceJson, output.formatTrace);
             break;
@@ -1115,9 +1397,15 @@ function runGlobCommand(pattern, command, arg) {
         case 'entrypoints':
             printOutput(result, output.formatEntrypointsJson, output.formatEntrypoints);
             break;
+        case 'endpoints':
+            printOutput(result, output.formatEndpointsJson, r => output.formatEndpoints(r, { bridge: r._bridge, unmatched: r._unmatched }));
+            break;
         case 'diffImpact':
             printOutput(result, output.formatDiffImpactJson, output.formatDiffImpact);
             break;
+        case 'auditAsync':
+            printOutput(result, output.formatAuditAsyncJson, output.formatAuditAsync);
+            break;
         case 'stacktrace':
             printOutput(result, output.formatStackTraceJson, output.formatStackTrace);
             break;
@@ -1141,6 +1429,8 @@ function runGlobCommand(pattern, command, arg) {
 // ============================================================================
 
 
+// Single source of truth for the public CLI help. README points here ("Run `ucn --help`")
+// rather than carrying a copy — keep it that way.
 function printUsage() {
     console.log(`UCN - Universal Code Navigator
 
@@ -1157,6 +1447,7 @@ Usage:
 UNDERSTAND CODE
 ═══════════════════════════════════════════════════════════════════════════════
   about <name>        Full picture (definition, callers, callees, tests, code)
+  brief <name>        One-screen summary (signature, docstring, side effects, complexity)
   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)
@@ -1200,16 +1491,22 @@ REFACTORING HELPERS
   plan <name>         Preview refactoring (--add-param, --remove-param, --rename-to)
   verify <name>       Check all call sites match signature
   diff-impact         What changed in git diff and who calls it (--base, --staged)
+  check               Pre-commit summary: diff-impact + verify + affected-tests in one shot
   deadcode            Find unused functions/classes
   entrypoints         Detect framework entry points (routes, DI, tasks)
+  endpoints           HTTP API: list server routes + client requests; --bridge to match
+                        --bridge --server-only --client-only --unmatched
+                        --method=GET --prefix=/api --hide-uncertain
 
 ═══════════════════════════════════════════════════════════════════════════════
 OTHER
 ═══════════════════════════════════════════════════════════════════════════════
   api                 Show exported/public symbols
   typedef <name>      Find type definitions
-  stats               Project statistics (--functions for per-function line counts)
+  stats               Project statistics (--functions for per-function line counts, --hot for top callers)
+  doctor              Project trust report (counts, blind spots, parse failures, verdict; --deep for resolution coverage)
   stacktrace <text>   Parse stack trace, show code at each frame (alias: stack)
+  audit-async         Find calls in async functions that are likely missing await (JS/TS/Python)
 
 Common Flags:
   --file <pattern>    Filter by file path (e.g., --file=routes)
@@ -1228,18 +1525,30 @@ Common Flags:
   --with-types        Include type definitions (about, smart)
   --detailed          Show all symbols in toc (not just counts)
   --include-tests     Include test files in usage counts (about) and results (find, usages, deadcode)
+  --exclude-tests     Exclude test files (entrypoints — tests are included by default)
   --class-name=X      Scope to specific class (e.g., --class-name=Repository)
   --include-methods   Include method calls (obj.fn) in caller/callee analysis
   --include-uncertain Include ambiguous/uncertain matches
-  --no-confidence     Hide confidence scores (shown by default in about, context)
+  --hide-confidence   Hide confidence scores (shown by default in about, context)
   --min-confidence=N  Filter low-confidence edges (about, context, blast, trace,
                         reverse-trace, smart, affected-tests)
-  --show-confidence   Show confidence scores on caller/callee edges (about, context)
+  --unreachable-only  Show only callers/callees that are unreachable from entry points (about, context, impact)
   --include-exported  Include exported symbols in deadcode
   --no-regex          Force plain text search (regex is default)
   --functions         Show per-function line counts (stats command)
+  --hot               Show top N most-called functions (stats command, pair with --top=N)
+  --diverse           Cluster call sites by argument shape (example command, pair with --top=N)
+  --git               Attach git enrichment (last modified, author, recent commits) to about/brief
   --include-decorated Include decorated/annotated symbols in deadcode
   --framework=X       Filter entrypoints by framework (e.g., --framework=express,spring)
+  --bridge            Match server routes to client requests (endpoints command).
+                        Confidence tiers: EXACT, PARTIAL, UNCERTAIN
+  --server-only       Only list server routes (endpoints command)
+  --client-only       Only list client requests (endpoints command)
+  --unmatched         Only show routes/requests with no match (endpoints, pair with --bridge)
+  --method=X          Filter by HTTP method (endpoints, e.g., --method=POST)
+  --prefix=X          Filter routes/requests by path prefix (endpoints, e.g., --prefix=/api)
+  --hide-uncertain    Hide UNCERTAIN-confidence bridges (endpoints command)
   --exact             Exact name match only (find, typedef)
   --calls-only        Only show call/test-case matches (tests)
   --case-sensitive    Case-sensitive text search (search)
@@ -1357,7 +1666,7 @@ Flags can be added per-command: context myFunc --include-methods
         const tokens = input.split(/\s+/);
         const command = tokens[0];
         // Flags that take a space-separated value (--flag value)
-        const valueFlagNames = new Set(['--file', '--in', '--base', '--add-param', '--remove-param', '--rename-to', '--default', '--depth', '--top', '--context', '--max-lines', '--direction', '--exclude', '--not', '--stack', '--type', '--param', '--receiver', '--returns', '--decorator', '--limit', '--max-files', '--min-confidence', '--class-name', '--framework']);
+        const valueFlagNames = new Set(['--file', '--in', '--base', '--add-param', '--remove-param', '--rename-to', '--default', '--depth', '--top', '--context', '--max-lines', '--direction', '--exclude', '--not', '--stack', '--type', '--param', '--receiver', '--returns', '--decorator', '--limit', '--max-files', '--min-confidence', '--class-name', '--framework', '--method', '--prefix']);
         const flagTokens = [];
         const argTokens = [];
         const skipNext = new Set();
@@ -1378,10 +1687,18 @@ Flags can be added per-command: context myFunc --include-methods
         const iflags = parseFlags(flagTokens);
 
         try {
+            // Validate numeric flags (--top, --limit, etc) — same rules as
+            // global CLI mode. MED-2/MED-3/MED-5: bad values are rejected with
+            // a helpful message instead of being silently coerced.
+            validateNumericFlags(iflags);
             const iCanonical = resolveCommand(command, 'cli') || command;
             executeInteractiveCommand(index, iCanonical, arg, iflags, iExpandCache);
         } catch (e) {
-            console.error(`Error: ${e.message}`);
+            if (e instanceof FlagValidationError) {
+                console.log(e.message);
+            } else {
+                console.error(`Error: ${e.message}`);
+            }
         }
 
         rl.prompt();
@@ -1406,14 +1723,15 @@ Flags can be added per-command: context myFunc --include-methods
 
 const INTERACTIVE_DISPATCH = {
     // ── Understanding Code ───────────────────────────────────────────
-    about:        { params: 'name', format: (r, _a, f, idx) => output.formatAbout(r, { expand: f.expand, root: idx.root, showAll: f.all, depth: f.depth, showConfidence: f.showConfidence !== false }) },
+    about:        { params: 'name', format: (r, _a, f, idx) => output.formatAbout(r, { expand: f.expand, root: idx.root, showAll: f.all, depth: f.depth, showConfidence: f.showConfidence !== false, git: !!f.git }) },
     smart:        { params: 'name', format: (r) => output.formatSmart(r, { uncertainHint: 'use --include-uncertain to include all' }) },
     impact:       { params: 'name', format: (r) => output.formatImpact(r) },
     blast:        { params: 'name', format: (r) => output.formatBlast(r) },
     trace:        { params: 'name', format: (r) => output.formatTrace(r) },
     reverseTrace: { params: 'name', format: (r) => output.formatReverseTrace(r) },
     related:      { params: 'name', format: (r, _a, f) => output.formatRelated(r, { all: f.all, top: f.top }) },
-    example:      { params: 'name', format: (r, a) => output.formatExample(r, a) },
+    example:      { params: (a, f) => ({ name: a, file: f.file, className: f.className, diverse: f.diverse, top: f.top || undefined, includeTests: f.includeTests }), format: (r, a) => output.formatExample(r, a) },
+    brief:        { params: 'name', format: (r) => output.formatBrief(r) },
 
     // ── Finding Code ─────────────────────────────────────────────────
     find:          { params: 'name', format: (r, a, f) => output.formatFindDetailed(r, a, { depth: f.depth, top: f.top, all: f.all }) },
@@ -1434,12 +1752,20 @@ const INTERACTIVE_DISPATCH = {
     plan:         { params: 'name', format: (r) => output.formatPlan(r) },
     verify:       { params: 'name', format: (r) => output.formatVerify(r) },
     diffImpact:   { params: (a, f) => ({ base: f.base, staged: f.staged, file: f.file, limit: f.limit, all: f.all }), format: (r, _a, f) => output.formatDiffImpact(r, { all: f.all }) },
-    entrypoints:  { params: (a, f) => ({ type: f.type, framework: f.framework, file: f.file, exclude: f.exclude, includeTests: f.includeTests, limit: f.limit }), format: (r) => output.formatEntrypoints(r) },
+    check:        { params: (a, f) => ({ base: f.base, staged: f.staged, file: f.file, limit: f.limit }), format: (r) => output.formatCheck(r) },
+    entrypoints:  { params: (a, f) => ({ type: f.type, framework: f.framework, file: f.file, exclude: f.exclude, includeTests: f.includeTests, excludeTests: f.excludeTests, limit: f.limit }), format: (r) => output.formatEntrypoints(r) },
+    endpoints:    { params: (a, f) => ({ file: f.file, exclude: f.exclude, limit: f.limit, framework: f.framework, bridge: f.bridge, serverOnly: f.serverOnly, clientOnly: f.clientOnly, unmatched: f.unmatched, method: f.method, prefix: f.prefix, hideUncertain: f.hideUncertain }), format: (r) => output.formatEndpoints(r, { bridge: r._bridge, unmatched: r._unmatched }) },
 
     // ── Other ────────────────────────────────────────────────────────
     api:          { params: (a, f) => ({ file: a || f.file, limit: f.limit }), format: (r, a, f) => output.formatApi(r, a || f.file || '.') },
     stacktrace:   { params: (a, f) => ({ stack: f.stack || a }), format: (r) => output.formatStackTrace(r) },
-    stats:        { params: 'flags', format: (r, _a, f) => output.formatStats(r, { top: f.top }) },
+    doctor:       { params: (a, f) => ({ file: f.file, in: f.in, limit: f.limit, deep: f.deep }), format: (r) => output.formatDoctor(r) },
+    // MED-2: stats handler in execute.js rejects top<=0; without explicit
+    // coercion, parseFlags's `top: 0` default would surface as
+    // "Invalid --top value" on bare `stats`. Mirror the project-mode top
+    // coercion (topRaw when present, else undefined for default-10).
+    stats:        { params: (a, f) => ({ functions: f.functions, hot: f.hot, top: f.topRaw != null ? f.topRaw : (f.top || undefined) }), format: (r, _a, f) => output.formatStats(r, { top: f.top }) },
+    auditAsync:   { params: (a, f) => ({ file: f.file, exclude: f.exclude, limit: f.limit }), format: (r) => output.formatAuditAsync(r) },
 };
 
 /**
@@ -1464,7 +1790,7 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
     const applicableFlags = FLAG_APPLICABILITY[command];
     if (applicableFlags) {
         const flagToCli = (f) => '--' + f.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
-        const globalFlags = new Set(['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles', 'verbose', 'expand', 'interactive', '_fileFromFileMode']);
+        const globalFlags = new Set(['json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles', 'verbose', 'expand', 'interactive', '_fileFromFileMode', 'topRaw', 'limitRaw', 'maxFilesRaw', 'maxLinesRaw', 'depthRaw', 'contextRaw', 'workersRaw']);
         for (const [key, value] of Object.entries(iflags)) {
             if (globalFlags.has(key)) continue;
             if (value === undefined || value === null || value === 0 || (Array.isArray(value) && value.length === 0)) continue;