ucn 3.8.23 → 3.8.26

package/core/output/refactoring.js

@@ -102,6 +102,22 @@ function formatPlanJson(plan) {
     }, null, 2);
 }
 
+/**
+ * Render the per-site pattern flags as a compact suffix.
+ * Returns "" when no flags are set, or " [loop, try, callback, test, awaited]"
+ * with only the active flags.
+ */
+function _formatPatternFlags(p) {
+    if (!p) return '';
+    const flags = [];
+    if (p.inLoop) flags.push('loop');
+    if (p.inTry) flags.push('try');
+    if (p.inCallback) flags.push('callback');
+    if (p.inTestCase) flags.push('test');
+    if (p.awaited) flags.push('awaited');
+    return flags.length ? `  [${flags.join(', ')}]` : '';
+}
+
 /**
  * Format verify command output - text
  * Shows call site validation results
@@ -130,7 +146,19 @@ function formatVerify(result, options = {}) {
     lines.push('');
 
     // Summary
-    const status = result.mismatches === 0 ? '✓ All calls valid' : '✗ Mismatches found';
+    // BUG M1: don't claim "All calls valid" when 0 valid + N uncertain.
+    // Status precedence: mismatches > 0 → fail; total === 0 → empty;
+    // valid === 0 && uncertain > 0 → all-uncertain; valid > 0 && mismatches === 0 → ok.
+    let status;
+    if (result.mismatches > 0) {
+        status = `✗ ${result.mismatches} mismatch${result.mismatches === 1 ? '' : 'es'}`;
+    } else if (result.totalCalls === 0) {
+        status = 'ℹ No calls found';
+    } else if (result.valid === 0 && result.uncertain > 0) {
+        status = '⚠ All calls uncertain (no resolved sites)';
+    } else {
+        status = '✓ All calls valid';
+    }
     lines.push(`STATUS: ${status}`);
     lines.push(`  Total calls: ${result.totalCalls}`);
     lines.push(`  Valid: ${result.valid}`);
@@ -140,12 +168,27 @@ function formatVerify(result, options = {}) {
         lines.push(`  Note: ${result.scopeWarning.hint}`);
     }
 
+    // Feature A/B: show aggregate patterns counts when any are present.
+    const p = result.patterns;
+    if (p) {
+        const parts = [];
+        if (p.inLoop > 0) parts.push(`${p.inLoop} in loop`);
+        if (p.inTry > 0) parts.push(`${p.inTry} in try`);
+        if (p.inCallback > 0) parts.push(`${p.inCallback} in callback`);
+        if (p.inTestCase > 0) parts.push(`${p.inTestCase} in test`);
+        if (p.awaitedCalls > 0) parts.push(`${p.awaitedCalls} awaited`);
+        if (parts.length > 0) {
+            lines.push(`  Patterns: ${parts.join(', ')}`);
+        }
+    }
+
     // Show mismatches
     if (result.mismatchDetails.length > 0) {
         lines.push('');
         lines.push('MISMATCHES:');
         for (const m of result.mismatchDetails) {
-            lines.push(`  ${m.file}:${m.line}`);
+            const flags = _formatPatternFlags(m.patterns);
+            lines.push(`  ${m.file}:${m.line}${flags}`);
             lines.push(`    ${m.expression}`);
             lines.push(`    Expected ${m.expected}, got ${m.actual}: [${m.args?.join(', ') || ''}]`);
         }
@@ -156,7 +199,8 @@ function formatVerify(result, options = {}) {
         lines.push('');
         lines.push('UNCERTAIN (manual check needed):');
         for (const u of result.uncertainDetails) {
-            lines.push(`  ${u.file}:${u.line}`);
+            const flags = _formatPatternFlags(u.patterns);
+            lines.push(`  ${u.file}:${u.line}${flags}`);
             lines.push(`    ${u.expression}`);
             lines.push(`    Reason: ${u.reason}`);
         }
@@ -187,19 +231,23 @@ function formatVerifyJson(result) {
         valid: result.valid,
         mismatches: result.mismatches,
         uncertain: result.uncertain,
+        // Feature A/B: surface aggregate patterns and per-site flags.
+        patterns: result.patterns,
         mismatchDetails: result.mismatchDetails.map(m => ({
             file: m.file,
             line: m.line,
             expression: m.expression,
             expected: m.expected,
             actual: m.actual,
-            args: m.args || []
+            args: m.args || [],
+            patterns: m.patterns,
         })),
         uncertainDetails: result.uncertainDetails.map(u => ({
             file: u.file,
             line: u.line,
             expression: u.expression,
-            reason: u.reason
+            reason: u.reason,
+            patterns: u.patterns,
         }))
     }, null, 2);
 }
@@ -283,6 +331,54 @@ function formatStackTraceJson(result) {
     }, null, 2);
 }
 
+/**
+ * Format audit-async command output - text.
+ * Lists likely missing-await call sites grouped by file.
+ */
+function formatAuditAsync(result) {
+    if (!result) return 'No async audit data.';
+    const issues = Array.isArray(result.issues) ? result.issues : [];
+    if (issues.length === 0) {
+        return 'Async audit: no missing-await issues found.';
+    }
+    const lines = [];
+    lines.push(`Async audit: ${result.totalIssues} likely missing-await call site(s) across ${result.filesAffected} file(s)`);
+    lines.push('═'.repeat(60));
+
+    // Group by file (issues are already sorted by file then line).
+    const byFile = new Map();
+    for (const issue of issues) {
+        if (!byFile.has(issue.file)) byFile.set(issue.file, []);
+        byFile.get(issue.file).push(issue);
+    }
+    for (const [file, fileIssues] of byFile) {
+        lines.push('');
+        lines.push(`${file} (${fileIssues.length})`);
+        for (const issue of fileIssues) {
+            const caller = issue.callerName ? ` [${issue.callerName}]` : '';
+            lines.push(`  :${issue.line}${caller}  ${issue.calleeName}() — async, not awaited`);
+        }
+    }
+    return lines.join('\n');
+}
+
+/**
+ * Format audit-async command output - JSON.
+ */
+function formatAuditAsyncJson(result) {
+    if (!result) return JSON.stringify({ issues: [] }, null, 2);
+    return JSON.stringify({
+        totalIssues: result.totalIssues || 0,
+        filesAffected: result.filesAffected || 0,
+        issues: (result.issues || []).map(i => ({
+            file: i.file,
+            line: i.line,
+            callerName: i.callerName,
+            calleeName: i.calleeName,
+        })),
+    }, null, 2);
+}
+
 module.exports = {
     formatPlan,
     formatPlanJson,
@@ -290,4 +386,6 @@ module.exports = {
     formatVerifyJson,
     formatStackTrace,
     formatStackTraceJson,
+    formatAuditAsync,
+    formatAuditAsyncJson,
 };

package/core/output/reporting.js

@@ -150,6 +150,33 @@ function formatStats(stats, options = {}) {
         }
     }
 
+    if (stats.hot) {
+        const items = stats.hot.items || [];
+        const total = stats.hot.total || items.length;
+        lines.push(`\nHottest functions (top ${items.length} of ${total} called):`);
+        if (items.length === 0) {
+            lines.push('  (no inbound calls detected)');
+        } else {
+            for (const fn of items) {
+                const loc = `${fn.file}:${fn.startLine}`;
+                lines.push(`  ${String(fn.callCount).padStart(5)} calls  ${fn.name}  (${loc})`);
+                // MEDIUM-6: when the same name has multiple definitions across
+                // files (e.g. test helpers vs. test fixtures both named `tmp`),
+                // list the additional locations indented so the user knows
+                // the count covers ambiguous resolution.
+                if (Array.isArray(fn.locations) && fn.locations.length > 1) {
+                    for (let i = 1; i < fn.locations.length; i++) {
+                        const l = fn.locations[i];
+                        lines.push(`         ↳ also defined at ${l.file}:${l.startLine}`);
+                    }
+                }
+            }
+            if (total > items.length) {
+                lines.push(`  ... ${total - items.length} more (use --top=N to show more)`);
+            }
+        }
+    }
+
     return lines.join('\n');
 }
 
@@ -231,20 +258,29 @@ function formatDeadcode(results, options = {}) {
  * Format deadcode command output - JSON
  */
 function formatDeadcodeJson(results) {
+    const { formatSymbolHandle } = require('../shared');
     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 })
-        }))
+        meta: { command: 'deadcode', count: results.length },
+        data: {
+            count: results.length,
+            ...(results.excludedExported > 0 && { excludedExported: results.excludedExported }),
+            ...(results.excludedDecorated > 0 && { excludedDecorated: results.excludedDecorated }),
+            symbols: results.map(item => {
+                const handleSym = { ...item, relativePath: item.relativePath || item.file };
+                const handle = formatSymbolHandle(handleSym);
+                return {
+                    name: item.name,
+                    type: item.type,
+                    file: item.file,
+                    startLine: item.startLine,
+                    endLine: item.endLine,
+                    ...(handle && { handle }),
+                    ...(item.isExported && { isExported: true }),
+                    ...(item.decorators && item.decorators.length > 0 && { decorators: item.decorators }),
+                    ...(item.annotations && item.annotations.length > 0 && { annotations: item.annotations })
+                };
+            }),
+        },
     }, null, 2);
 }
 
@@ -305,16 +341,20 @@ 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,
-            }))
+            entrypoints: results.map(ep => {
+                const handle = ep.line && ep.name ? `${ep.file}:${ep.line}:${ep.name}` : null;
+                return {
+                    name: ep.name,
+                    file: ep.file,
+                    line: ep.line,
+                    ...(handle && { handle }),
+                    type: ep.type,
+                    framework: ep.framework,
+                    patternId: ep.patternId,
+                    evidence: ep.evidence,
+                    confidence: ep.confidence,
+                };
+            }),
         }
     }, null, 2);
 }

package/core/output/search.js

@@ -151,8 +151,20 @@ function formatStructuralSearchJson(result) {
  * Format example result as text
  */
 function formatExample(result, name) {
+    // MEDIUM-8: when only test-file callers exist and the user didn't ask
+    // for them, surface that fact explicitly instead of saying nothing was
+    // found.
+    if (result && !result.best && result.excludedTestCalls > 0) {
+        const n = result.excludedTestCalls;
+        return `No call examples found for "${name}" (excluded ${n} test-file usage${n === 1 ? '' : 's'} — pass --include-tests to include them)`;
+    }
     if (!result || !result.best) return `No call examples found for "${name}"`;
 
+    // Diverse mode: render one block per cluster representative.
+    if (result.clusters && result.clusters.length > 0) {
+        return formatExampleDiverse(result, name);
+    }
+
     const best = result.best;
     const lines = [];
     lines.push(`Best example of "${name}":`);
@@ -183,6 +195,55 @@ function formatExample(result, name) {
     return lines.join('\n');
 }
 
+/**
+ * Render `example --diverse` output: one representative per call-shape cluster.
+ * Each block shows the shape signature, cluster size, and the representative
+ * with code context — so an agent can see "calls fall into N distinct shapes,
+ * here's an example of each".
+ */
+function formatExampleDiverse(result, name) {
+    const lines = [];
+    const total = result.totalClusters || result.clusters.length;
+    lines.push(`Diverse examples of "${name}" — ${result.clusters.length} of ${total} cluster(s), ${result.totalCalls} total calls:`);
+    lines.push('═'.repeat(60));
+
+    for (let i = 0; i < result.clusters.length; i++) {
+        const c = result.clusters[i];
+        const rep = c.representative;
+        const shape = c.argKinds == null
+            ? 'unknown shape'
+            : c.argKinds.length === 0
+                ? 'no arguments'
+                : `args: (${c.argKinds.join(', ')})`;
+
+        lines.push('');
+        lines.push(`[${i + 1}] ${shape}  — ${c.count} call${c.count === 1 ? '' : 's'} in this cluster`);
+        if (!rep) continue;
+        lines.push(`    ${rep.relativePath || rep.file}:${rep.line}`);
+
+        if (rep.before) {
+            for (let j = 0; j < rep.before.length; j++) {
+                const ln = rep.line - rep.before.length + j;
+                lines.push(`    ${ln.toString().padStart(4)}| ${rep.before[j]}`);
+            }
+        }
+        lines.push(`    ${rep.line.toString().padStart(4)}| ${rep.content}  <--`);
+        if (rep.after) {
+            for (let j = 0; j < rep.after.length; j++) {
+                const ln = rep.line + j + 1;
+                lines.push(`    ${ln.toString().padStart(4)}| ${rep.after[j]}`);
+            }
+        }
+    }
+
+    if (total > result.clusters.length) {
+        lines.push('');
+        lines.push(`... ${total - result.clusters.length} more cluster(s) (use --top=N to show more)`);
+    }
+
+    return lines.join('\n');
+}
+
 /**
  * Format example command output - JSON
  */
@@ -192,7 +253,7 @@ function formatExampleJson(result, name) {
     }
 
     const best = result.best;
-    return JSON.stringify({
+    const env = {
         found: true,
         query: name,
         totalCalls: result.totalCalls,
@@ -205,7 +266,29 @@ function formatExampleJson(result, name) {
             ...(best.before && best.before.length > 0 && { before: best.before }),
             ...(best.after && best.after.length > 0 && { after: best.after })
         }
-    }, null, 2);
+    };
+
+    if (result.clusters && result.clusters.length > 0) {
+        env.totalClusters = result.totalClusters;
+        env.clusters = result.clusters.map(c => ({
+            shapeKey: c.shapeKey,
+            argCount: c.argCount,
+            argKinds: c.argKinds,
+            count: c.count,
+            representative: c.representative ? {
+                file: c.representative.relativePath || c.representative.file,
+                line: c.representative.line,
+                content: c.representative.content,
+                score: c.representative.score,
+                reasons: c.representative.reasons || [],
+                ...(c.representative._argTexts && { argTexts: c.representative._argTexts }),
+                ...(c.representative.before && c.representative.before.length > 0 && { before: c.representative.before }),
+                ...(c.representative.after && c.representative.after.length > 0 && { after: c.representative.after }),
+            } : null,
+        }));
+    }
+
+    return JSON.stringify(env, null, 2);
 }
 
 /**
@@ -238,18 +321,27 @@ function formatTypedef(types, name) {
  * Format typedef as JSON
  */
 function formatTypedefJson(types, name) {
+    const { formatSymbolHandle } = require('../shared');
     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 })
-        }))
+        meta: { command: 'typedef', count: types.length },
+        data: {
+            query: name,
+            count: types.length,
+            types: types.map(t => {
+                const handle = formatSymbolHandle(t);
+                return {
+                    name: t.name,
+                    type: t.type,
+                    file: t.relativePath || t.file,
+                    startLine: t.startLine,
+                    endLine: t.endLine,
+                    ...(handle && { handle }),
+                    ...(t.docstring && { docstring: t.docstring }),
+                    ...(t.usageCount !== undefined && { usageCount: t.usageCount }),
+                    ...(t.code && { code: t.code }),
+                };
+            }),
+        },
     }, null, 2);
 }
 
@@ -259,7 +351,7 @@ function formatTypedefJson(types, name) {
 function formatTests(tests, name) {
     const lines = [`Tests for "${name}":\n`];
 
-    if (tests.length === 0) {
+    if (!tests || !Array.isArray(tests) || tests.length === 0) {
         lines.push('  (no tests found)');
     } else {
         const totalMatches = tests.reduce((sum, t) => sum + t.matches.length, 0);
@@ -285,11 +377,12 @@ function formatTests(tests, name) {
  * Format tests as JSON
  */
 function formatTestsJson(tests, name) {
+    const safe = Array.isArray(tests) ? tests : [];
     return JSON.stringify({
         query: name,
-        testFileCount: tests.length,
-        totalMatches: tests.reduce((sum, t) => sum + t.matches.length, 0),
-        testFiles: tests
+        testFileCount: safe.length,
+        totalMatches: safe.reduce((sum, t) => sum + (t.matches?.length || 0), 0),
+        testFiles: safe
     }, null, 2);
 }
 

package/core/output/shared.js

@@ -91,8 +91,17 @@ function formatFunctionSignature(fn) {
     // Name + generics + params (concatenated without spaces)
     let sig = fn.name;
     if (fn.generics) sig += fn.generics;
-    const params = normalizeParams(fn.params);
-    sig += `(${params})`;
+    // If paramsStructured + paramTypes are available, render typed params
+    const typed = renderTypedParams(fn);
+    // When paramsStructured is an empty array, the function has zero params —
+    // render `()` rather than the legacy `(...)` placeholder.
+    const noParams = Array.isArray(fn.paramsStructured) && fn.paramsStructured.length === 0;
+    let paramText;
+    if (typed != null) paramText = typed;
+    else if (noParams) paramText = '';
+    else if (fn.params != null && fn.params !== '...') paramText = normalizeParams(fn.params);
+    else paramText = '...';
+    sig += `(${paramText})`;
 
     // Return type
     if (fn.returnType) sig += `: ${fn.returnType}`;
@@ -106,6 +115,29 @@ function formatFunctionSignature(fn) {
     return sig;
 }
 
+/**
+ * Render parameters with type annotations when available.
+ * Returns null if not enough info — caller falls back to raw params string.
+ */
+function renderTypedParams(fn) {
+    const ps = fn.paramsStructured;
+    if (!Array.isArray(ps) || ps.length === 0) return null;
+    const paramTypes = fn.paramTypes;
+    const hasStructuredTypes = ps.some(p => p && p.type);
+    const hasMappedTypes = paramTypes && Object.keys(paramTypes).length > 0;
+    if (!hasStructuredTypes && !hasMappedTypes) return null;
+    const parts = ps.map(p => {
+        if (!p || !p.name) return '';
+        let s = p.rest ? `...${p.name.replace(/^\.\.\./, '')}` : p.name;
+        const t = p.type || (paramTypes && paramTypes[p.name]);
+        if (t) s += `: ${t}`;
+        if (p.optional && !p.rest && p.default == null) s += '?';
+        if (p.default != null) s += ` = ${p.default}`;
+        return s;
+    });
+    return parts.filter(Boolean).join(', ');
+}
+
 /**
  * Format class/type signature for TOC display
  */
@@ -254,6 +286,26 @@ function computeConfidence(symbol) {
     return { level, reasons };
 }
 
+/**
+ * Render a single human-readable line for git enrichment data.
+ * Format: `Last modified: <ISO> by <author> · <N> commits in last 30d`
+ *
+ * Returns null when input is missing or unavailable so callers can decide
+ * whether to push it. Used by `about` and `brief` formatters.
+ */
+function formatGitLine(git) {
+    if (!git || !git.available) return null;
+    const parts = [];
+    if (git.lastModified) parts.push(`Last modified: ${git.lastModified}`);
+    if (git.author) parts.push(`by ${git.author}`);
+    let line = parts.join(' ');
+    if (git.recentChanges != null) {
+        const tail = `${git.recentChanges} commit${git.recentChanges === 1 ? '' : 's'} in last 30d`;
+        line = line ? `${line} · ${tail}` : tail;
+    }
+    return line;
+}
+
 module.exports = {
     dynamicImportsNote,
     formatFileError,
@@ -262,10 +314,12 @@ module.exports = {
     lineRange,
     lineLoc,
     formatFunctionSignature,
+    renderTypedParams,
     formatClassSignature,
     formatMemberSignature,
     formatLineRanges,
     detectDoubleEscaping,
     countNestedGenerics,
     computeConfidence,
+    formatGitLine,
 };

package/core/output.js

@@ -19,4 +19,8 @@ module.exports = {
     ...require('./output/extraction'),
     ...require('./output/reporting'),
     ...require('./output/refactoring'),
+    ...require('./output/brief'),
+    ...require('./output/doctor'),
+    ...require('./output/check'),
+    ...require('./output/endpoints'),
 };

package/core/parser.js

@@ -274,15 +274,21 @@ function getExportedSymbols(result) {
 /**
  * Strip <script> and </script> tags from extracted code lines for HTML files.
  * Only affects the first and last lines when they contain script tags alongside JS code.
+ * Handles inline cases like `<p>foo</p><script>code</script><p>bar</p>` by stripping
+ * the opening/closing tags wherever they appear on the line, not just at line edges.
  * @param {string[]} lines - Extracted lines
  * @param {string} language - Language name
  * @returns {string[]} Cleaned lines (same array mutated)
  */
 function cleanHtmlScriptTags(lines, language) {
     if (language === 'html' && lines.length > 0) {
-        lines[0] = lines[0].replace(/^(\s*)<script[^>]*>/i, '$1');
+        // Strip opening <script ...> tag wherever it appears on the first line
+        // (may be preceded by other HTML on the same line, e.g. <p>x</p><script>...).
+        lines[0] = lines[0].replace(/<script\b[^>]*>/i, '');
+        // Strip closing </script> tag wherever it appears on the last line
+        // (may be followed by other HTML on the same line, e.g. ...</script><p>x</p>).
         const last = lines.length - 1;
-        lines[last] = lines[last].replace(/<\/script>\s*$/i, '');
+        lines[last] = lines[last].replace(/<\/script\s*>/i, '');
     }
     return lines;
 }