ucn 4.0.1 → 4.1.0

package/core/output/graph.js

@@ -11,9 +11,12 @@ function formatImports(imports, filePath) {
     if (imports?.error) return formatFileError(imports, filePath);
     const lines = [`Imports in ${filePath}:\n`];
 
-    const internal = imports.filter(i => !i.isExternal && !i.isDynamic);
-    const external = imports.filter(i => i.isExternal && !i.isDynamic);
-    const dynamic = imports.filter(i => i.isDynamic);
+    // A string-literal dynamic import that resolved is a project-internal
+    // dependency (isDynamic marks the MECHANISM); only unresolved dynamic
+    // imports belong in the DYNAMIC (unresolved) section.
+    const internal = imports.filter(i => i.resolved);
+    const external = imports.filter(i => !i.resolved && !i.isDynamic);
+    const dynamic = imports.filter(i => !i.resolved && i.isDynamic);
 
     if (internal.length > 0) {
         lines.push('INTERNAL:');
@@ -50,6 +53,10 @@ function formatImports(imports, filePath) {
         }
     }
 
+    if (internal.length === 0 && external.length === 0 && dynamic.length === 0) {
+        lines.push('  (none)');
+    }
+
     return lines.join('\n');
 }
 
@@ -66,7 +73,8 @@ function formatImportsJson(imports, filePath) {
             names: i.names,
             type: i.type,
             resolved: i.resolved || null,
-            isDynamic: !!i.isDynamic
+            isDynamic: !!i.isDynamic,
+            line: i.line ?? null
         }))
     }, null, 2);
 }
@@ -196,8 +204,15 @@ function formatApi(symbols, filePath) {
 function formatApiJson(symbols, filePath) {
     const { formatSymbolHandle } = require('../shared');
     const deduped = dedupExportSymbols(symbols);
+    // Under --limit the handler slices and attaches the full-set size
+    // (fix #251, the #242/#247 shape) — meta.total describes the FULL set.
+    const li = symbols.limitInfo;
     return JSON.stringify({
-        meta: { command: 'api', count: deduped.length },
+        meta: {
+            command: 'api',
+            count: deduped.length,
+            ...(li && { total: li.total, truncated: true }),
+        },
         ...(filePath && { file: filePath }),
         data: {
             exportCount: deduped.length,
@@ -247,7 +262,11 @@ function formatGraph(graph, options = {}) {
 
     const showAll = options.showAll || false;
     const maxChildren = showAll ? Infinity : 8;
-    const maxDepth = options.maxDepth !== undefined ? options.maxDepth : Infinity;
+    const maxDepth = options.maxDepth !== undefined ? options.maxDepth
+        : (graph.maxDepth !== undefined ? graph.maxDepth : Infinity);
+    // The engine stops traversal at ITS maxDepth, so the data never reaches
+    // the formatter's own depth check — the engine reports the cut instead.
+    const engineTruncated = !!graph.depthTruncated;
 
     function printTree(nodes, edges, rootFile) {
         const visited = new Set();     // all nodes ever printed (for diamond dep detection)
@@ -310,7 +329,7 @@ function formatGraph(graph, options = {}) {
         let totalTruncated = 0;
         let anyDepthLimited = false;
 
-        lines.push(`\nIMPORTS (what this file depends on): ${importCount} files`);
+        lines.push(`\nIMPORTS (what this file depends on): ${importCount} file${importCount === 1 ? '' : 's'}`);
         if (importCount > 0) {
             const r = printTree(graph.imports.nodes, graph.imports.edges, graph.root);
             totalTruncated += r.truncatedNodes;
@@ -319,7 +338,7 @@ function formatGraph(graph, options = {}) {
             lines.push('  (none)');
         }
 
-        lines.push(`\nIMPORTERS (what depends on this file): ${importerCount} files`);
+        lines.push(`\nIMPORTERS (what depends on this file): ${importerCount} file${importerCount === 1 ? '' : 's'}`);
         if (importerCount > 0) {
             const r = printTree(graph.importers.nodes, graph.importers.edges, graph.root);
             totalTruncated += r.truncatedNodes;
@@ -328,6 +347,7 @@ function formatGraph(graph, options = {}) {
             lines.push('  (none)');
         }
 
+        anyDepthLimited = anyDepthLimited || engineTruncated;
         if (anyDepthLimited || totalTruncated > 0) {
             lines.push('\n' + '─'.repeat(60));
             if (anyDepthLimited) {
@@ -343,7 +363,8 @@ function formatGraph(graph, options = {}) {
         lines.push(`Dependency graph for ${rootRelPath}`);
         lines.push('═'.repeat(60));
 
-        const { truncatedNodes, depthLimited } = printTree(graph.nodes, graph.edges, graph.root);
+        const { truncatedNodes, depthLimited: fmtDepthLimited } = printTree(graph.nodes, graph.edges, graph.root);
+        const depthLimited = fmtDepthLimited || engineTruncated;
 
         if (depthLimited || truncatedNodes > 0) {
             lines.push('\n' + '─'.repeat(60));
@@ -372,6 +393,8 @@ function formatGraphJson(graph) {
         nodes: graph.nodes,
         edges: graph.edges
     };
+    if (graph.maxDepth !== undefined) result.maxDepth = graph.maxDepth;
+    if (graph.depthTruncated) result.depthTruncated = true;
     if (graph.imports) result.imports = graph.imports;
     if (graph.importers) result.importers = graph.importers;
     return JSON.stringify(result, null, 2);

package/core/output/refactoring.js

@@ -2,6 +2,30 @@
  * core/output/refactoring.js - Verify/plan/stacktrace formatters
  */
 
+const { unverifiedReasonLabel, advisoryLine } = require('./shared');
+const { formatAccountLines } = require('./analysis');
+
+/**
+ * Render the v4 unverified band shared by verify and plan: capped one-liners
+ * with reasons. Returns [] when the band is empty.
+ */
+function _unverifiedBandLines(sites, cap = 10) {
+    if (!sites || sites.length === 0) return [];
+    const lines = [];
+    lines.push('');
+    lines.push(`UNVERIFIED CALL SITES (${sites.length}) — call syntax, no binding/receiver evidence; review manually:`);
+    for (const u of sites.slice(0, cap)) {
+        const caller = u.callerName ? ` [${u.callerName}]` : '';
+        const reason = u.reason ? ` (${unverifiedReasonLabel(u)})` : '';
+        const expr = u.expression ? `: ${u.expression.replace(/\s+/g, ' ').slice(0, 100)}` : '';
+        lines.push(`  ${u.file}:${u.line}${caller}${expr}${reason}`);
+    }
+    if (sites.length > cap) {
+        lines.push(`  (+${sites.length - cap} more unverified)`);
+    }
+    return lines;
+}
+
 /**
  * Format plan command output - text
  * Shows before/after signatures and all changes needed
@@ -14,7 +38,12 @@ function formatPlan(plan, options = {}) {
         return `Function "${plan.function}" not found.`;
     }
     if (plan.error) {
-        return `Error: ${plan.error}\nCurrent parameters: ${plan.currentParams?.join(', ') || 'none'}`;
+        // Only show the parameter list when the error result carries one —
+        // unrelated errors (multi-op rejection) don't, and "none" would be
+        // wrong for functions that have parameters.
+        return plan.currentParams
+            ? `Error: ${plan.error}\nCurrent parameters: ${plan.currentParams.join(', ') || 'none'}`
+            : `Error: ${plan.error}`;
     }
 
     const lines = [];
@@ -58,6 +87,15 @@ function formatPlan(plan, options = {}) {
         }
     }
 
+    // v4 tiered contract: candidates without evidence are not planned but
+    // stay visible — a rename that misses one of these breaks at runtime.
+    lines.push(..._unverifiedBandLines(plan.unverifiedSites));
+    const planAccountLines = formatAccountLines(plan.account);
+    if (planAccountLines.length > 0) {
+        lines.push('');
+        lines.push(...planAccountLines);
+    }
+
     return lines.join('\n');
 }
 
@@ -83,22 +121,34 @@ function formatPlanJson(plan) {
         }, null, 2);
     }
 
+    // Standard {meta, data} envelope (fix #230 — plan was one of three
+    // commands still emitting a bare result object).
     return JSON.stringify({
-        found: true,
-        function: plan.function,
-        file: plan.file,
-        startLine: plan.startLine,
-        operation: plan.operation,
-        before: { signature: plan.before.signature },
-        after: { signature: plan.after.signature },
-        totalChanges: plan.totalChanges,
-        filesAffected: plan.filesAffected,
-        changes: plan.changes.map(c => ({
-            file: c.file,
-            line: c.line,
-            expression: c.expression,
-            suggestion: c.suggestion
-        }))
+        meta: {
+            complete: (plan.unverifiedCount || 0) === 0,
+            unverified: plan.unverifiedCount || 0,
+            ...(plan.account && { account: plan.account }),
+        },
+        data: {
+            found: true,
+            function: plan.function,
+            file: plan.file,
+            startLine: plan.startLine,
+            operation: plan.operation,
+            before: { signature: plan.before.signature },
+            after: { signature: plan.after.signature },
+            totalChanges: plan.totalChanges,
+            filesAffected: plan.filesAffected,
+            changes: plan.changes.map(c => ({
+                file: c.file,
+                line: c.line,
+                expression: c.expression,
+                suggestion: c.suggestion
+            })),
+            // v4 tiered contract passthrough
+            unverifiedCount: plan.unverifiedCount,
+            unverifiedSites: plan.unverifiedSites,
+        },
     }, null, 2);
 }
 
@@ -139,9 +189,9 @@ function formatVerify(result, options = {}) {
     lines.push(result.signature);
     lines.push('');
 
-    // Expected args
+    // Expected args (max null = unbounded rest param)
     const { min, max } = result.expectedArgs;
-    const expectedStr = min === max ? `${min}` : `${min}-${max}`;
+    const expectedStr = max == null ? `${min}+` : (min === max ? `${min}` : `${min}-${max}`);
     lines.push(`Expected arguments: ${expectedStr}`);
     lines.push('');
 
@@ -164,6 +214,9 @@ function formatVerify(result, options = {}) {
     lines.push(`  Valid: ${result.valid}`);
     lines.push(`  Mismatches: ${result.mismatches}`);
     lines.push(`  Uncertain: ${result.uncertain}`);
+    if (result.unverifiedCount > 0) {
+        lines.push(`  Unverified (not arg-checked): ${result.unverifiedCount}`);
+    }
     if (result.scopeWarning) {
         lines.push(`  Note: ${result.scopeWarning.hint}`);
     }
@@ -206,6 +259,15 @@ function formatVerify(result, options = {}) {
         }
     }
 
+    // v4 tiered contract: unverified band (distinct from UNCERTAIN above,
+    // which is arg-parse uncertainty among CONFIRMED sites).
+    lines.push(..._unverifiedBandLines(result.unverifiedSites));
+    const accountLines = formatAccountLines(result.account);
+    if (accountLines.length > 0) {
+        lines.push('');
+        lines.push(...accountLines);
+    }
+
     return lines.join('\n');
 }
 
@@ -220,35 +282,49 @@ function formatVerifyJson(result) {
         return JSON.stringify({ found: false, error: `Function "${result.function}" not found.` }, null, 2);
     }
 
+    // Standard {meta, data} envelope (fix #230 — verify was one of three
+    // commands still emitting a bare result object). Completeness signals
+    // and the account live in meta, like context/impact/about.
     return JSON.stringify({
-        found: true,
-        function: result.function,
-        file: result.file,
-        startLine: result.startLine,
-        signature: result.signature,
-        expectedArgs: result.expectedArgs,
-        totalCalls: result.totalCalls,
-        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 || [],
-            patterns: m.patterns,
-        })),
-        uncertainDetails: result.uncertainDetails.map(u => ({
-            file: u.file,
-            line: u.line,
-            expression: u.expression,
-            reason: u.reason,
-            patterns: u.patterns,
-        }))
+        meta: {
+            complete: result.uncertain === 0 && (result.unverifiedCount || 0) === 0,
+            uncertain: result.uncertain,
+            unverified: result.unverifiedCount || 0,
+            ...(result.account && { account: result.account }),
+        },
+        data: {
+            found: true,
+            function: result.function,
+            file: result.file,
+            startLine: result.startLine,
+            signature: result.signature,
+            expectedArgs: result.expectedArgs,
+            totalCalls: result.totalCalls,
+            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 || [],
+                patterns: m.patterns,
+            })),
+            uncertainDetails: result.uncertainDetails.map(u => ({
+                file: u.file,
+                line: u.line,
+                expression: u.expression,
+                reason: u.reason,
+                patterns: u.patterns,
+            })),
+            // v4 tiered contract passthrough
+            unverifiedCount: result.unverifiedCount,
+            unverifiedSites: result.unverifiedSites,
+        },
     }, null, 2);
 }
 
@@ -262,8 +338,13 @@ function formatStackTrace(result) {
     }
 
     const lines = [];
-    lines.push(`Stack trace: ${result.frameCount} frames`);
+    lines.push(`Stack trace: ${result.frameCount} frame${result.frameCount === 1 ? '' : 's'}`);
     lines.push('═'.repeat(60));
+    const stAdvisory = advisoryLine(result.advisory);
+    if (stAdvisory) lines.push(stAdvisory);
+    if (result.skippedFrames > 0) {
+        lines.push(`(${result.skippedFrames} frame(s) without file:line — Unknown Source, native — skipped)`);
+    }
 
     for (let i = 0; i < result.frames.length; i++) {
         const frame = result.frames[i];
@@ -289,6 +370,12 @@ function formatStackTrace(result) {
                 lines.push('');
                 lines.push(`  In: ${frame.functionInfo.name}(${frame.functionInfo.params || ''})`);
                 lines.push(`  Range: ${frame.functionInfo.startLine}-${frame.functionInfo.endLine}`);
+                // The engine computed this and both surfaces dropped it —
+                // an out-of-range line got an unqualified attribution
+                // (fix #251).
+                if (frame.functionInfo.lineMismatch) {
+                    lines.push(`  ⚠ line ${frame.line} is outside this range — nearest same-name definition shown`);
+                }
             }
         } else {
             lines.push(`  ${frame.file}:${frame.line} (file not found in project)`);
@@ -304,16 +391,26 @@ function formatStackTrace(result) {
  */
 function formatStackTraceJson(result) {
     if (!result || result.frameCount === 0) {
-        return JSON.stringify({ frameCount: 0, frames: [] }, null, 2);
+        return JSON.stringify({
+            frameCount: 0,
+            frames: [],
+            ...(result && result.advisory && { advisory: result.advisory }),
+        }, null, 2);
     }
 
     return JSON.stringify({
         frameCount: result.frameCount,
+        // The v4 two-tier surface: advisory commands self-label in JSON too
+        // (fix #251 — the result carried this and the text rendered it, but
+        // the JSON rebuild dropped it in every language cell).
+        ...(result.advisory && { advisory: result.advisory }),
+        ...(result.skippedFrames > 0 && { skippedFrames: result.skippedFrames }),
         frames: result.frames.map(f => ({
             function: f.function || null,
             file: f.file,
             line: f.line,
             found: !!f.found,
+            ...(f.confidence !== undefined && { confidence: f.confidence }),
             ...(f.resolvedFile && { resolvedFile: f.resolvedFile }),
             ...(f.context && { context: f.context.map(c => ({
                 line: c.line,
@@ -324,7 +421,8 @@ function formatStackTraceJson(result) {
                 name: f.functionInfo.name,
                 params: f.functionInfo.params || null,
                 startLine: f.functionInfo.startLine,
-                endLine: f.functionInfo.endLine
+                endLine: f.functionInfo.endLine,
+                ...(f.functionInfo.lineMismatch && { lineMismatch: true }),
             } }),
             ...(f.raw && { raw: f.raw })
         }))

package/core/output/reporting.js

@@ -236,7 +236,10 @@ function formatDeadcode(results, options = {}) {
         const extStr = item.externalContract
             ? ' [reachable via out-of-tree base — external contract, not dead]'
             : '';
-        lines.push(`  ${lineRange(item.startLine, item.endLine)} ${item.name} (${item.type})${exported}${hintStr}${declStr}${extStr}`);
+        // The only references are the symbol's own recursion (fix #253c).
+        const recStr = item.selfRecursive ? ' [only self-references — recursive]' : '';
+        const displayName = item.className ? `${item.className}.${item.name}` : item.name;
+        lines.push(`  ${lineRange(item.startLine, item.endLine)} ${displayName} (${item.type})${exported}${hintStr}${declStr}${extStr}${recStr}`);
     }
 
     if (hidden > 0) {
@@ -252,7 +255,7 @@ function formatDeadcode(results, options = {}) {
         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.`;
+        const exportedHint = options.exportedHint || `${results.excludedExported} exported symbol(s) excluded from the audit (public API may have external callers). Use --include-exported to audit them.`;
         lines.push(`\n${exportedHint}`);
     }
     if (results.excludedExternalContract > 0) {
@@ -272,10 +275,18 @@ function formatDeadcode(results, options = {}) {
  */
 function formatDeadcodeJson(results) {
     const { formatSymbolHandle } = require('../shared');
+    // Under --limit the handler slices the array and attaches the full-set
+    // size (fix #242) — the payload itself must say it is truncated.
+    const li = results.limitInfo;
     return JSON.stringify({
-        meta: { command: 'deadcode', count: results.length },
+        meta: {
+            command: 'deadcode',
+            count: results.length,
+            ...(li && { total: li.total, truncated: true }),
+        },
         data: {
             count: results.length,
+            ...(li && { total: li.total, truncated: true }),
             ...(results.excludedExported > 0 && { excludedExported: results.excludedExported }),
             ...(results.excludedDecorated > 0 && { excludedDecorated: results.excludedDecorated }),
             ...(results.excludedExternalContract > 0 && { excludedExternalContract: results.excludedExternalContract }),
@@ -288,12 +299,14 @@ function formatDeadcodeJson(results) {
                     file: item.file,
                     startLine: item.startLine,
                     endLine: item.endLine,
+                    ...(item.className && { className: item.className }),
                     ...(handle && { handle }),
                     ...(item.isExported && { isExported: true }),
                     ...(item.decorators && item.decorators.length > 0 && { decorators: item.decorators }),
                     ...(item.annotations && item.annotations.length > 0 && { annotations: item.annotations }),
                     ...(item.declaredOn && { declaredOn: item.declaredOn }),
-                    ...(item.externalContract && { externalContract: true })
+                    ...(item.externalContract && { externalContract: true }),
+                    ...(item.selfRecursive && { selfRecursive: true })
                 };
             }),
         },
@@ -354,8 +367,16 @@ function formatEntrypoints(results, options = {}) {
  * Format entrypoints command output (JSON)
  */
 function formatEntrypointsJson(results) {
+    // Under --limit the handler slices the array and attaches the full-set
+    // size (fix #247, the deadcode #242 shape) — meta.total must describe
+    // the FULL set, with `truncated` saying the list below is a prefix.
+    const li = results.limitInfo;
     return JSON.stringify({
-        meta: { total: results.length },
+        meta: {
+            count: results.length,
+            total: li ? li.total : results.length,
+            ...(li && { truncated: true }),
+        },
         data: {
             entrypoints: results.map(ep => {
                 const handle = ep.line && ep.name ? `${ep.file}:${ep.line}:${ep.name}` : null;
@@ -368,6 +389,7 @@ function formatEntrypointsJson(results) {
                     framework: ep.framework,
                     patternId: ep.patternId,
                     evidence: ep.evidence,
+                    ...(ep.registeredAt && { registeredAt: ep.registeredAt }),
                     confidence: ep.confidence,
                 };
             }),
@@ -375,9 +397,86 @@ function formatEntrypointsJson(results) {
     }, null, 2);
 }
 
+/**
+ * formatOrient — one-screen cold-repo orientation.
+ */
+function formatOrient(result) {
+    const lines = [];
+    lines.push(`PROJECT ORIENTATION — ${result.root}`);
+    lines.push('═'.repeat(60));
+
+    // Size + language mix (percent by symbols, largest first)
+    const langs = Object.entries(result.byLanguage || {})
+        .map(([lang, v]) => ({ lang, symbols: v.symbols || 0 }))
+        .sort((a, b) => b.symbols - a.symbols || (a.lang < b.lang ? -1 : a.lang > b.lang ? 1 : 0));
+    const totalSym = result.symbols || 1;
+    const langStr = langs
+        .map(l => `${l.lang} ${Math.round((l.symbols / totalSym) * 100)}%`)
+        .join(', ');
+    lines.push(`${result.files} files · ${result.symbols} symbols · ${langStr}`);
+    lines.push('');
+
+    if (result.dirs?.length) {
+        lines.push('TOP DIRS (by symbols):');
+        const width = Math.max(...result.dirs.map(d => d.dir.length));
+        for (const d of result.dirs) {
+            lines.push(`  ${d.dir.padEnd(width)}  ${d.symbols} symbols · ${d.files} file(s)`);
+        }
+        lines.push('');
+    }
+
+    if (result.hot?.items?.length) {
+        const scope = result.hot.production ? 'production functions' : 'functions';
+        lines.push(`HOT (most-called ${scope}, top ${result.hot.items.length} of ${result.hot.total}):`);
+        for (const h of result.hot.items) {
+            const label = h.className ? `${h.className}.${h.name}` : h.name;
+            lines.push(`  ${label} — ${h.callCount} call(s) · ${h.file}:${h.line}`);
+        }
+        lines.push('');
+    }
+
+    if (result.entrypoints) {
+        const byType = result.entrypoints.byType
+            .map(t => `${t.type} ${t.count}`).join(', ');
+        lines.push(`ENTRY POINTS: ${result.entrypoints.total} — ${byType}`);
+    } else {
+        lines.push('ENTRY POINTS: (detection unavailable)');
+    }
+
+    const bs = result.trust?.blindSpots || {};
+    const bsParts = [];
+    if (bs.dynamicImports) bsParts.push(`${bs.dynamicImports} dynamic import(s)`);
+    if (bs.evalCalls) bsParts.push(`${bs.evalCalls} eval`);
+    if (bs.reflection) bsParts.push(`${bs.reflection} reflection`);
+    if (bs.parseFailures) bsParts.push(`${bs.parseFailures} parse failure(s)`);
+    lines.push(`TRUST: ${result.trust?.level || 'UNKNOWN'}${bsParts.length ? ' — ' + bsParts.join(', ') : ''}  (ucn doctor for detail)`);
+    lines.push('');
+
+    const next = [];
+    if (result.suggest) next.push(`ucn about ${result.suggest}`);
+    next.push('ucn toc --detailed', 'ucn stats --hot --top=20', 'ucn doctor --deep');
+    lines.push(`Next: ${next.join(' · ')}`);
+
+    return lines.join('\n');
+}
+
+function formatOrientJson(result) {
+    return JSON.stringify({
+        meta: {
+            command: 'orient',
+            files: result.files,
+            symbols: result.symbols,
+            trust: result.trust?.level ?? null,
+        },
+        data: result,
+    }, null, 2);
+}
+
 module.exports = {
     formatToc,
     formatTocJson,
+    formatOrient,
+    formatOrientJson,
     formatStats,
     formatStatsJson,
     formatDeadcode,

package/core/output/search.js

@@ -2,7 +2,7 @@
  * core/output/search.js - Text search, structural search, example, typedef, tests formatters
  */
 
-const { detectDoubleEscaping } = require('./shared');
+const { detectDoubleEscaping, advisoryLine } = require('./shared');
 
 /**
  * Format search command output
@@ -170,6 +170,8 @@ function formatExample(result, name) {
     lines.push(`Best example of "${name}":`);
     lines.push('═'.repeat(60));
     lines.push(`${best.relativePath}:${best.line}`);
+    const exAdvisory = advisoryLine(result.advisory);
+    if (exAdvisory) lines.push(exAdvisory);
     lines.push('');
 
     if (best.before) {
@@ -206,6 +208,8 @@ function formatExampleDiverse(result, name) {
     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));
+    const divAdvisory = advisoryLine(result.advisory);
+    if (divAdvisory) lines.push(divAdvisory);
 
     for (let i = 0; i < result.clusters.length; i++) {
         const c = result.clusters[i];
@@ -249,13 +253,23 @@ function formatExampleDiverse(result, name) {
  */
 function formatExampleJson(result, name) {
     if (!result || !result.best) {
-        return JSON.stringify({ found: false, query: name, error: `No call examples found for "${name}"` }, null, 2);
+        // Surface the excluded-test-usages count in JSON too (fix #237 — the
+        // handler note that used to carry it duplicated the text body).
+        const excluded = result?.excludedTestCalls || 0;
+        return JSON.stringify({
+            found: false, query: name,
+            ...(excluded > 0 && { excludedTestCalls: excluded }),
+            error: excluded > 0
+                ? `No call examples found for "${name}" (excluded ${excluded} test-file usage${excluded === 1 ? '' : 's'} — pass --include-tests to include them)`
+                : `No call examples found for "${name}"`,
+        }, null, 2);
     }
 
     const best = result.best;
     const env = {
         found: true,
         query: name,
+        ...(result.advisory && { advisory: result.advisory }),
         totalCalls: result.totalCalls,
         best: {
             file: best.relativePath || best.file,
@@ -302,7 +316,20 @@ function formatTypedef(types, name) {
     } else {
         for (const t of types) {
             lines.push(`${t.relativePath}:${t.startLine}  ${t.type} ${t.name}`);
-            if (t.usageCount !== undefined) {
+            // Honest breakdown (fix #251): the fast-path count sees calls/
+            // defs/imports only — for TYPE symbols, reference-kind usage
+            // dominates and is NOT counted here; say what the number is.
+            if (t.usageCounts !== undefined) {
+                const c = t.usageCounts;
+                const parts = [];
+                if (c.calls > 0) parts.push(`${c.calls} calls`);
+                if (c.definitions > 0) parts.push(`${c.definitions} def`);
+                if (c.imports > 0) parts.push(`${c.imports} imports`);
+                if (c.references > 0) parts.push(`${c.references} refs`);
+                lines.push(parts.length > 0
+                    ? `  (${c.total} usages: ${parts.join(', ')} — type references not counted; use \`usages ${t.name}\`)`
+                    : `  (${c.total} usages)`);
+            } else if (t.usageCount !== undefined) {
                 lines.push(`  (${t.usageCount} usages)`);
             }
             if (t.code) {