ucn 4.2.3 → 5.0.2

package/core/output/analysis.js

@@ -88,17 +88,34 @@ function formatAccountLines(account) {
         `${account.confirmed} confirmed, ${account.unverified} unverified, ` +
         `${nc.total} non-call (${nc.imports} import, ${nc.definitions} definition, ${nc.references} reference, ${nc.unclassifiedText} other-text), ` +
         `${account.excluded ? account.excluded.total : 0} other-target, ` +
+        `${account.unsupported && account.unsupported.lines > 0 ? `${account.unsupported.lines} unsupported-language, ` : ''}` +
         `${account.unaccounted} unaccounted`;
     if (account.beyondText && account.beyondText.count > 0) {
         line += ` (+${account.beyondText.count} beyond-text caller${account.beyondText.count === 1 ? '' : 's'})`;
     }
     lines.push(line);
     const contract = account.contract || {};
+    const unsupported = account.unsupported ||
+        { fileCount: 0, lines: 0, files: [], languages: {}, sites: [], sitesTruncated: false };
     const textComplete = contract.textComplete !== undefined
         ? contract.textComplete
         : Boolean(account.conserved) && !(account.unparsed && account.unparsed.fileCount > 0) &&
+            unsupported.lines === 0 &&
             !(account.unreadableFiles && account.unreadableFiles.length > 0);
-    if (!textComplete) {
+    // When the ONLY gap is unsupported-language occurrences, say exactly that
+    // instead of the generic DEGRADED sentence: the partition over supported
+    // languages is still conserved, and the gap is enumerated below.
+    const unsupportedOnly = !textComplete && unsupported.lines > 0 &&
+        Boolean(account.conserved) &&
+        !(account.unparsed && account.unparsed.fileCount > 0) &&
+        !(account.unreadableFiles && account.unreadableFiles.length > 0);
+    if (unsupportedOnly) {
+        const langs = Object.keys(unsupported.languages).join(', ');
+        lines.push(`CONTRACT: literal-name text partition complete over SUPPORTED languages only — ` +
+            `${unsupported.lines} line${unsupported.lines === 1 ? '' : 's'} in unsupported-language file${unsupported.fileCount === 1 ? '' : 's'}` +
+            `${langs ? ` (${langs})` : ''} NOT analyzed (see WARNING; verify with grep/ripgrep). ` +
+            'Semantic completeness is not claimed.');
+    } else if (!textComplete) {
         lines.push('CONTRACT: literal-name text partition is DEGRADED; review WARNING and unaccounted lines before acting. Semantic completeness is not claimed.');
     } else if (contract.observedTextZero) {
         lines.push('CONTRACT: observed-text zero only; every literal-name line was classified, but aliases, indirect calls, generated code, and runtime dispatch may exist. Not safe-delete proof.');
@@ -111,8 +128,31 @@ function formatAccountLines(account) {
             `(${account.unparsed.lines} line${account.unparsed.lines === 1 ? '' : 's'}, NOT analyzed): ` +
             account.unparsed.files.join(', '));
     }
+    if (unsupported.lines > 0) {
+        const langParts = Object.entries(unsupported.languages)
+            .map(([lang, count]) => `${lang}: ${count}`).join(', ');
+        lines.push(`WARNING: ${unsupported.lines} line${unsupported.lines === 1 ? '' : 's'} in ` +
+            `${unsupported.fileCount} unsupported-language file${unsupported.fileCount === 1 ? '' : 's'} ` +
+            `contain${unsupported.lines === 1 ? 's' : ''} "${account.symbol}"` +
+            `${langParts ? ` (${langParts})` : ''} — NOT analyzed; verify with grep/ripgrep:`);
+        const shown = unsupported.sites.slice(0, 5);
+        for (const site of shown) {
+            lines.push(`  ${site.file}:${site.line}  ${site.text}`);
+        }
+        if (unsupported.lines > shown.length) {
+            lines.push(`  ... and ${unsupported.lines - shown.length} more line${unsupported.lines - shown.length === 1 ? '' : 's'}`);
+        }
+    }
     if (account.unreadableFiles && account.unreadableFiles.length > 0) {
-        lines.push(`WARNING: ${account.unreadableFiles.length} indexed-but-unreadable file(s) skipped: ${account.unreadableFiles.join(', ')}`);
+        lines.push(`WARNING: ${account.unreadableFiles.length} unreadable file(s) skipped: ${account.unreadableFiles.join(', ')}`);
+    }
+    if (account.skippedSources && account.skippedSources.length > 0) {
+        const shown = account.skippedSources.slice(0, 5)
+            .map(issue => `${issue.relativePath} (${issue.reason})`);
+        lines.push(`WARNING: ${account.skippedSources.length} source discovery gap(s) make this index partial: ${shown.join(', ')}`);
+        if (account.skippedSources.length > shown.length) {
+            lines.push(`  ... and ${account.skippedSources.length - shown.length} more; run repo --sections=health for the full reason set.`);
+        }
     }
     if (account.filtered && account.filtered.total > 0) {
         const parts = [];
@@ -156,11 +196,18 @@ function unverifiedCalleeLines(entries, compact) {
 }
 
 /** "NON-CALL OCCURRENCES" summary line from the account. */
-function formatNonCallLine(account, hintName) {
+function formatNonCallLine(account, hintName, usagesHint) {
     if (!account || !account.nonCall || account.nonCall.total === 0) return null;
     const nc = account.nonCall;
+    const hint = usagesHint || `ucn usages ${hintName}`;
+    // Classification differs across the two surfaces by contract: these
+    // counts are engine-adjudicated (a method reference that resolves to
+    // this target is a confirmed caller, not a reference), while `usages`
+    // classifies each line by syntax alone — the breakdowns can
+    // legitimately differ.
     return `NON-CALL OCCURRENCES: ${nc.total} (${nc.imports} imports, ${nc.definitions} definitions, ` +
-        `${nc.references} references, ${nc.unclassifiedText} other-text) — counts only; see: ucn usages ${hintName}`;
+        `${nc.references} references, ${nc.unclassifiedText} other-text) — engine-adjudicated counts; ` +
+        `syntax-classified line records: ${hint}`;
 }
 
 /** Format context (callers + callees) as JSON */
@@ -191,6 +238,7 @@ function formatContextJson(context) {
                 usages: callers.map(c => ({
                     file: c.relativePath || c.file,
                     line: c.line,
+                    ...(Number.isInteger(c.column) && { column: c.column }),
                     expression: c.content,
                     callerName: c.callerName,
                     ...(c.calledAs && { calledAs: c.calledAs }),
@@ -206,6 +254,7 @@ function formatContextJson(context) {
                 unverifiedCallers: (context.unverifiedCallers || []).map(c => ({
                     file: c.relativePath || c.file,
                     line: c.line,
+                    ...(Number.isInteger(c.column) && { column: c.column }),
                     expression: c.content,
                     callerName: c.callerName ?? null,
                     ...(c.calledAs && { calledAs: c.calledAs }),
@@ -219,6 +268,10 @@ function formatContextJson(context) {
                     ...(c.dispatchVia && { dispatchVia: c.dispatchVia }),
                     ...(c.dispatchCandidates != null && { dispatchCandidates: c.dispatchCandidates }),
                     ...(c.externalContract && { externalContract: true }),
+                    uncertaintyClass: c.uncertaintyClass ||
+                        (c.reason === 'possible-dispatch' && c.dispatchVia
+                            ? 'runtime-dispatch' : 'actionable-ambiguity'),
+                    ...(c.dispatchFamily && { dispatchFamily: c.dispatchFamily }),
                 })),
                 ...(context.warnings && { warnings: context.warnings })
             }
@@ -242,6 +295,7 @@ function formatContextJson(context) {
             callers: callers.map(c => ({
                 file: c.relativePath || c.file,
                 line: c.line,
+                ...(Number.isInteger(c.column) && { column: c.column }),
                 expression: c.content,  // FULL expression
                 callerName: c.callerName,
                 ...(c.calledAs && { calledAs: c.calledAs }),
@@ -255,6 +309,7 @@ function formatContextJson(context) {
             unverifiedCallers: unverifiedCallers.map(c => ({
                 file: c.relativePath || c.file,
                 line: c.line,
+                ...(Number.isInteger(c.column) && { column: c.column }),
                 expression: c.content,  // FULL expression
                 callerName: c.callerName ?? null,
                 ...(c.calledAs && { calledAs: c.calledAs }),
@@ -267,6 +322,10 @@ function formatContextJson(context) {
                 ...(c.dispatchVia && { dispatchVia: c.dispatchVia }),
                 ...(c.dispatchCandidates != null && { dispatchCandidates: c.dispatchCandidates }),
                 ...(c.externalContract && { externalContract: true }),
+                uncertaintyClass: c.uncertaintyClass ||
+                    (c.reason === 'possible-dispatch' && c.dispatchVia
+                        ? 'runtime-dispatch' : 'actionable-ambiguity'),
+                ...(c.dispatchFamily && { dispatchFamily: c.dispatchFamily }),
             })),
             callees: callees.map(c => ({
                 name: c.name,
@@ -299,13 +358,14 @@ function formatContext(ctx, options = {}) {
     if (!ctx) return { text: 'Symbol not found.', expandable: [] };
 
     const expandHint = options.expandHint != null ? options.expandHint : 'Use ucn_expand with item number to see code for any item.';
+    const allHint = options.allHint || 'use --all';
 
     const lines = [];
     const expandable = [];
     let itemNum = 1;
 
     // Handle struct/interface types
-    if (ctx.type && ['class', 'struct', 'interface', 'type'].includes(ctx.type)) {
+    if (ctx.type && ['class', 'struct', 'interface', 'type', 'enum', 'record', 'trait', 'namespace'].includes(ctx.type)) {
         lines.push(`Context for ${ctx.type} ${ctx.name}:`);
         lines.push('═'.repeat(60));
 
@@ -334,8 +394,20 @@ function formatContext(ctx, options = {}) {
             });
         }
 
+        const members = ctx.members || [];
+        if (members.length > 0) {
+            lines.push(`\nMEMBERS (${members.length}):`);
+            for (const member of members) {
+                lines.push(`  ${member.name} (${member.type})`);
+                lines.push(`    ${member.file}:${member.line}`);
+            }
+        }
+
         const callers = ctx.callers || [];
-        lines.push(`\nCALLERS — CONFIRMED (${callers.length}):`);
+        const typeCallerTotal = ctx.meta?.callerTotal ?? callers.length;
+        const typeCallerLabel = typeCallerTotal > callers.length
+            ? `${callers.length} shown of ${typeCallerTotal}` : `${callers.length}`;
+        lines.push(`\nCALLERS — CONFIRMED (${typeCallerLabel}):`);
         for (const c of callers) {
             const callerName = c.callerName ? ` [${c.callerName}]` : '';
             lines.push(`  [${itemNum}] ${c.relativePath}:${c.line}${callerName}`);
@@ -376,7 +448,7 @@ function formatContext(ctx, options = {}) {
                 shown++;
             }
             if (typeUnverified.length > shown) {
-                lines.push(`  (+${typeUnverified.length - shown} more unverified — use --all)`);
+                lines.push(`  (+${typeUnverified.length - shown} more unverified — ${allHint})`);
             }
         }
 
@@ -424,9 +496,12 @@ function formatContext(ctx, options = {}) {
     const callers = ctx.callers || [];
     const prodCallers = callers.filter(c => !isTestEntry(c));
     const testCallers = callers.filter(c => isTestEntry(c));
-    const tierHeader = testCallers.length > 0
-        ? `CALLERS — CONFIRMED (${callers.length}, ${prodCallers.length} prod + ${testCallers.length} test):`
-        : `CALLERS — CONFIRMED (${callers.length}):`;
+    const callerTotal = ctx.meta?.callerTotal ?? callers.length;
+    const tierHeader = callerTotal > callers.length
+        ? `CALLERS — CONFIRMED (${callers.length} shown of ${callerTotal}):`
+        : testCallers.length > 0
+            ? `CALLERS — CONFIRMED (${callers.length}, ${prodCallers.length} prod + ${testCallers.length} test):`
+            : `CALLERS — CONFIRMED (${callers.length}):`;
     lines.push(`${compact ? '' : '\n'}${tierHeader}`);
     const callerEvidence = options.showConfidence !== false ? formatEvidenceLine(callers) : null;
     if (callerEvidence) lines.push(callerEvidence);
@@ -464,15 +539,123 @@ function formatContext(ctx, options = {}) {
     // candidates ARE analyzed — they render in the unverified band with
     // reasons, and the ACCOUNT line reconciles every text occurrence.
 
-    // UNVERIFIED tier: call-syntax matches without binding/receiver evidence.
-    // Always visible (the contract: never silently hide an occurrence), capped
-    // at 10 one-liners unless --all.
+    // Runtime dispatch has a known boundary (trait/interface/supertype or a
+    // capability guard), but the concrete implementation is selected at
+    // runtime. Present repeated sites as one decision family with samples:
+    // the raw sites remain in JSON/accounting and --all expands every one.
+    // This separates unavoidable language semantics from ambiguity the agent
+    // can investigate.
     const unverified = ctx.unverifiedCallers || [];
-    if (unverified.length > 0) {
-        lines.push(`${compact ? '' : '\n'}CALLERS — UNVERIFIED (${unverified.length}) — call syntax, no binding/receiver evidence:`);
+    const runtimeDispatch = unverified.filter(u =>
+        u.uncertaintyClass === 'runtime-dispatch' ||
+        (u.reason === 'possible-dispatch' && u.dispatchVia));
+    const compileTimeDispatch = unverified.filter(u =>
+        u.uncertaintyClass === 'compile-time-dispatch');
+    const actionableUnverified = unverified.filter(u =>
+        u.uncertaintyClass !== 'compile-time-dispatch' &&
+        !(u.uncertaintyClass === 'runtime-dispatch' ||
+          (u.reason === 'possible-dispatch' && u.dispatchVia)));
+    if (runtimeDispatch.length > 0) {
+        const groups = new Map();
+        for (const site of runtimeDispatch) {
+            const key = `${site.dispatchVia}\0${site.dispatchCandidates ?? ''}\0` +
+                `${site.externalContract ? 'external' : 'project'}`;
+            if (!groups.has(key)) groups.set(key, []);
+            groups.get(key).push(site);
+        }
+        lines.push(`${compact ? '' : '\n'}CALLERS — RUNTIME DISPATCH ` +
+            `(${runtimeDispatch.length} site${runtimeDispatch.length === 1 ? '' : 's'}, ` +
+            `${groups.size} ${groups.size === 1 ? 'family' : 'families'}) — ` +
+            'implementation selected at runtime:');
+        const showAll = !!ctx.meta?.all;
+        let summarized = 0;
+        for (const sites of groups.values()) {
+            const first = sites[0];
+            const implementation = first.dispatchCandidates > 1
+                ? `; 1 of ${first.dispatchCandidates} implementations`
+                : first.externalContract ? '; open external implementation set' : '';
+            lines.push(`  via ${first.dispatchVia}: ${sites.length} ` +
+                `site${sites.length === 1 ? '' : 's'}${implementation}`);
+            const samples = showAll ? sites : sites.slice(0, 2);
+            for (const u of samples) {
+                const callerName = u.callerName ? ` [${u.callerName}]` : '';
+                const expr = u.content
+                    ? `: ${u.content.trim().replace(/\s+/g, ' ').slice(0, 100)}` : '';
+                lines.push(`    [${itemNum}] ${u.relativePath}:${u.line}${callerName}${expr}`);
+                expandable.push({
+                    num: itemNum++,
+                    type: 'caller',
+                    name: u.callerName || '(module level)',
+                    file: u.callerFile || u.file,
+                    relativePath: u.relativePath,
+                    line: u.line,
+                    startLine: u.callerStartLine || u.line,
+                    endLine: u.callerEndLine || u.line
+                });
+            }
+            summarized += sites.length - samples.length;
+        }
+        if (summarized > 0) {
+            lines.push(`  (+${summarized} more runtime-dispatch sites — ${allHint})`);
+        }
+    }
+
+    // Template substitution, constraints, and dependent calls are selected by
+    // the C++ compiler. Repeating every source site as generic actionable
+    // ambiguity makes an agent inspect code it cannot settle statically. Keep
+    // every raw site in JSON/accounting and group the text view by the exact
+    // overload family that needs a compiler handoff.
+    if (compileTimeDispatch.length > 0) {
+        const groups = new Map();
+        for (const site of compileTimeDispatch) {
+            const key = `${site.dispatchFamily || 'template overload set'}\0` +
+                `${site.dispatchCandidates ?? ''}`;
+            if (!groups.has(key)) groups.set(key, []);
+            groups.get(key).push(site);
+        }
+        lines.push(`${compact ? '' : '\n'}CALLERS — COMPILE-TIME DISPATCH ` +
+            `(${compileTimeDispatch.length} site${compileTimeDispatch.length === 1 ? '' : 's'}, ` +
+            `${groups.size} ${groups.size === 1 ? 'family' : 'families'}) — ` +
+            'exact overload depends on template substitution or constraints:');
+        const showAll = !!ctx.meta?.all;
+        let summarized = 0;
+        for (const sites of groups.values()) {
+            const first = sites[0];
+            const candidates = first.dispatchCandidates > 1
+                ? `; ${first.dispatchCandidates} candidate overloads` : '';
+            lines.push(`  ${first.dispatchFamily || 'template overload set'}: ` +
+                `${sites.length} site${sites.length === 1 ? '' : 's'}${candidates}`);
+            const samples = showAll ? sites : sites.slice(0, 2);
+            for (const u of samples) {
+                const callerName = u.callerName ? ` [${u.callerName}]` : '';
+                const expr = u.content
+                    ? `: ${u.content.trim().replace(/\s+/g, ' ').slice(0, 100)}` : '';
+                lines.push(`    [${itemNum}] ${u.relativePath}:${u.line}${callerName}${expr}`);
+                expandable.push({
+                    num: itemNum++,
+                    type: 'caller',
+                    name: u.callerName || '(module level)',
+                    file: u.callerFile || u.file,
+                    relativePath: u.relativePath,
+                    line: u.line,
+                    startLine: u.callerStartLine || u.line,
+                    endLine: u.callerEndLine || u.line
+                });
+            }
+            summarized += sites.length - samples.length;
+        }
+        if (summarized > 0) {
+            lines.push(`  (+${summarized} more compile-time-dispatch sites — ${allHint})`);
+        }
+    }
+
+    // Actionable ambiguity: call syntax without enough identity evidence.
+    // Always visible and capped at 10 one-liners unless --all.
+    if (actionableUnverified.length > 0) {
+        lines.push(`${compact ? '' : '\n'}CALLERS — UNVERIFIED (${actionableUnverified.length}) — call syntax, no binding/receiver evidence:`);
         const cap = (ctx.meta && ctx.meta.all) ? Infinity : 10;
         let shown = 0;
-        for (const u of unverified) {
+        for (const u of actionableUnverified) {
             if (shown >= cap) break;
             const callerName = u.callerName ? ` [${u.callerName}]` : '';
             const reason = u.reason ? ` (${unverifiedReasonLabel(u)})` : '';
@@ -490,13 +673,16 @@ function formatContext(ctx, options = {}) {
             });
             shown++;
         }
-        if (unverified.length > shown) {
-            lines.push(`  (+${unverified.length - shown} more unverified — use --all)`);
+        if (actionableUnverified.length > shown) {
+            lines.push(`  (+${actionableUnverified.length - shown} more unverified — ${allHint})`);
         }
     }
 
     const callees = ctx.callees || [];
-    lines.push(`${compact ? '' : '\n'}CALLEES (${callees.length}):`);
+    const calleeTotal = ctx.meta?.calleeTotal ?? callees.length;
+    const calleeLabel = calleeTotal > callees.length
+        ? `${callees.length} shown of ${calleeTotal}` : `${callees.length}`;
+    lines.push(`${compact ? '' : '\n'}CALLEES (${calleeLabel}):`);
     const calleeEvidence = options.showConfidence !== false ? formatEvidenceLine(callees) : null;
     if (calleeEvidence) lines.push(calleeEvidence);
     const calleeReach = reachabilityDisplay(callees, hasEntrypoints, 'callee');
@@ -535,7 +721,7 @@ function formatContext(ctx, options = {}) {
     // Conservation contract lines: non-call summary + ACCOUNT/WARNING/FILTERED
     const account = ctx.meta && ctx.meta.account;
     if (account) {
-        const nonCallLine = formatNonCallLine(account, ctx.function);
+        const nonCallLine = formatNonCallLine(account, ctx.function, options.usagesHint);
         if (nonCallLine) lines.push(`${compact ? '' : '\n'}${nonCallLine}`);
         const accountLines = formatAccountLines(account);
         if (accountLines.length > 0) {
@@ -567,6 +753,9 @@ function formatImpact(impact, options = {}) {
     if (!compact) lines.push('═'.repeat(60));
     lines.push(`${impact.file}:${impact.startLine}`);
     if (!compact) lines.push(impact.signature);
+    for (const warning of impact.warnings || []) {
+        lines.push(`Note: ${warning.message}`);
+    }
     if (!compact) lines.push('');
 
     // Summary (confirmed + unverified tiers reported separately)
@@ -693,6 +882,7 @@ function formatAbout(about, options = {}) {
     }
 
     const lines = [];
+    const allHint = options.allHint || 'use --all';
     const sym = about.symbol;
     const { expand, root, depth } = options;
 
@@ -809,7 +999,7 @@ function formatAbout(about, options = {}) {
             lines.push(`  ${u.file}:${u.line}${caller}${expr}${reason}`);
         }
         if (aboutUnverified.total > aboutUnverified.top.length) {
-            lines.push(`  (+${aboutUnverified.total - aboutUnverified.top.length} more unverified — use --all)`);
+            lines.push(`  (+${aboutUnverified.total - aboutUnverified.top.length} more unverified — ${allHint})`);
         }
     }
 
@@ -927,7 +1117,7 @@ function formatAbout(about, options = {}) {
         lines.push(about.code);
     } else if (about.code && compact) {
         lines.push('');
-        lines.push(`SOURCE: omitted in compact mode; use fn ${sym.handle || sym.name} to extract it.`);
+        lines.push(`SOURCE: omitted in compact mode; use source ${sym.handle || sym.name} to extract it.`);
     }
 
     if (aboutTruncated) {

package/core/output/brief.js

@@ -14,6 +14,18 @@ function signatureLine(sym) {
     const parts = [];
     if (sym.modifiers && sym.modifiers.length) parts.push(sym.modifiers.join(' '));
     let sig = sym.name;
+    if (sym.generics) sig += String(sym.generics).replace(/\s+/g, ' ').trim();
+    if (sym.type === 'field' || sym.type === 'state' ||
+        sym.memberType === 'field' || sym.memberType === 'property') {
+        const declaredType = sym.fieldType || sym.returnType;
+        if (declaredType) sig += `: ${String(declaredType).replace(/\s+/g, ' ').trim()}`;
+        parts.push(sig);
+        return parts.join(' ');
+    }
+    if (sym.type === 'macro' && sym.functionLike === false) {
+        parts.push(sig);
+        return parts.join(' ');
+    }
     const typed = renderTypedParams(sym);
     // If we have a structured-params array of length 0, the function has no params.
     // Render `()` rather than the legacy `(...)` placeholder.
@@ -57,6 +69,17 @@ function formatBrief(result) {
         return lines.join('\n');
     }
 
+    if (result.kind === 'data') {
+        lines.push(signatureLine(sym));
+        lines.push(`  ${sym.file}:${sym.startLine}-${sym.endLine}  (${result.lineCount || 0} line${result.lineCount === 1 ? '' : 's'})`);
+        if (sym.handle) lines.push(`  handle: ${sym.handle}`);
+        if (sym.docstring) lines.push(`  "${sym.docstring}"`);
+        if (sym.className) lines.push(`  in class ${sym.className}`);
+        const gitLineData = formatGitLine(result.git);
+        if (gitLineData) lines.push(`  ${gitLineData}`);
+        return lines.join('\n');
+    }
+
     // Header line: signature
     lines.push(signatureLine(sym));
     // Location + line count

package/core/output/check.js

@@ -6,6 +6,10 @@
 
 function formatCheck(result) {
     if (!result) return 'No check result.';
+    if (result.ok === false) {
+        // The gate could not run — never render this like a clean tree.
+        return `Pre-commit Check (${result.base}${result.staged ? ', staged' : ''})\n${'═'.repeat(60)}\nCHECK DID NOT RUN [${result.status || 'diff-failed'}] — ${result.error || 'git diff failed'}\nThis is not a pass. Fix the git context (run inside a git repository with a valid base ref) and rerun.`;
+    }
     if (result.empty) {
         return `Pre-commit Check (${result.base}${result.staged ? ', staged' : ''})\n${'═'.repeat(60)}\nNo changes to analyze${result.reason ? ` (${result.reason})` : ''}.`;
     }

package/core/output/doctor.js

@@ -4,7 +4,9 @@
 
 'use strict';
 
-function formatDoctor(result) {
+const { langTraits } = require('../../languages');
+
+function formatDoctor(result, options = {}) {
     if (!result) return 'No project to analyze.';
     const lines = [];
     lines.push(`UCN Trust Report — ${result.root}`);
@@ -12,14 +14,20 @@ function formatDoctor(result) {
     if (result.version) lines.push(`Version: ucn ${result.version}`);
     lines.push(`Index: ${result.files.scanned} file${result.files.scanned === 1 ? '' : 's'}, ${result.symbols} symbol${result.symbols === 1 ? '' : 's'}`);
 
-    if (result.filter) lines.push(`Filter: ${result.filter}`);
+    if (result.filter) {
+        const parts = [];
+        if (result.filter.file) parts.push(`file=${result.filter.file}`);
+        if (result.filter.in) parts.push(`in=${result.filter.in}`);
+        if (result.filter.exclude?.length) parts.push(`exclude=${result.filter.exclude.join(',')}`);
+        if (parts.length > 0) lines.push(`Filter: ${parts.join(' · ')}`);
+    }
 
     // Languages
     const langEntries = Object.entries(result.languages || {}).sort((a, b) => b[1].files - a[1].files);
     if (langEntries.length) {
         const totalFiles = langEntries.reduce((s, [, v]) => s + v.files, 0) || 1;
         const langStr = langEntries.map(([name, v]) => `${name} (${Math.round(v.files / totalFiles * 100)}%)`).join(', ');
-        lines.push(`Languages: ${langStr}`);
+        lines.push(`Languages (by indexed files): ${langStr}`);
     }
 
     // Cache state
@@ -52,23 +60,35 @@ function formatDoctor(result) {
         lines.push('Resolution evidence profile: no caller edges in the stratified sample.');
     } else {
         lines.push('');
-        lines.push('Resolution evidence profile: not computed (use --deep)');
+        lines.push(`Resolution evidence profile: not computed (${options.deepHint || 'use --deep'})`);
     }
 
     // Blind spots
     lines.push('');
     lines.push('Blind spots:');
     const bs = result.blindSpots || {};
+    const staticSpecialImports = result.projectLanguage &&
+        !langTraits(result.projectLanguage)?.hasDynamicImports;
+    const importLabel = staticSpecialImports
+        ? (result.projectLanguage === 'rust' ? 'Glob imports' : 'Blank/dot imports')
+        : 'Dynamic imports';
     const bsLines = [
-        ['Dynamic imports', bs.dynamicImports],
+        [importLabel, bs.dynamicImports],
         ['Eval/exec calls', bs.evalCalls],
         ['Reflection',      bs.reflection],
+        ['Computed dispatch', bs.computedDispatch],
         ['Parse failures',  bs.parseFailures],
         ['Parser recovery', bs.parseRecoveries],
+        ['Unsupported source', bs.unsupportedSources],
+        ['Skipped source', bs.skippedSources],
     ];
     const unitFor = {
-        'Dynamic imports': 'import', 'Eval/exec calls': 'use', Reflection: 'use',
+        'Dynamic imports': 'import', 'Blank/dot imports': 'import',
+        'Glob imports': 'import', 'Eval/exec calls': 'use', Reflection: 'use',
+        'Computed dispatch': 'call',
         'Parse failures': 'failure',
+        'Unsupported source': 'file',
+        'Skipped source': 'path',
     };
     let anyBlindSpot = false;
     for (const [label, info] of bsLines) {
@@ -82,6 +102,17 @@ function formatDoctor(result) {
             const unit = unitFor[label] || 'use';
             if (label === 'Parser recovery') {
                 lines.push(`  ${label}: ${fileCount} recovered file${fileCount === 1 ? '' : 's'} (results may be partial)`);
+            } else if (label === 'Unsupported source') {
+                const languages = Object.entries(info.languages || {})
+                    .map(([language, count]) => `${language} ${count}`)
+                    .join(', ');
+                lines.push(`  ${label}: ${fileCount} file${fileCount === 1 ? '' : 's'} skipped${languages ? ` (${languages})` : ''}`);
+                lines.push('    Handoff: use grep/ripgrep and a language-native analyzer for these files.');
+            } else if (label === 'Skipped source') {
+                const reasons = Object.entries(info.reasons || {})
+                    .map(([reason, count]) => `${reason} ${count}`).join(', ');
+                lines.push(`  ${label}: ${fileCount} path${fileCount === 1 ? '' : 's'} not indexed${reasons ? ` (${reasons})` : ''}`);
+                lines.push('    The index is partial; adjust .ucn.json or discovery limits before relying on completeness-sensitive commands.');
             } else {
                 lines.push(`  ${label}: ${info.count} ${unit}${info.count === 1 ? '' : 's'} in ${fileCount} file${fileCount === 1 ? '' : 's'}`);
             }

package/core/output/endpoints.js

@@ -26,7 +26,7 @@ function formatEndpoints(result, options = {}) {
     const showBridge = options.bridge;
 
     if (!showBridge) {
-        return formatRoutesAndRequests(routes, requests, meta, options);
+        return formatRoutesAndRequests(routes, requests, meta, options, result.advisory);
     }
     return formatBridges(bridges, unmatchedRoutes, unmatchedRequests, meta, options, result.advisory);
 }
@@ -48,7 +48,7 @@ function uniqueMatchPercent(bridges, totalRequests) {
     return Math.min(100, Math.max(0, pct));
 }
 
-function formatRoutesAndRequests(routes, requests, meta, options) {
+function formatRoutesAndRequests(routes, requests, meta, options, advisory = null) {
     const lines = [];
     const showServer = !options.clientOnly;
     const showClient = !options.serverOnly;
@@ -109,6 +109,8 @@ function formatRoutesAndRequests(routes, requests, meta, options) {
         }
     }
 
+    const routeAdvisory = advisoryLine(advisory);
+    if (routeAdvisory) lines.push('', routeAdvisory);
     return lines.join('\n').trimEnd();
 }
 
@@ -220,6 +222,7 @@ function formatEndpointsJson(result, options = {}) {
         meta: {
             ok: true,
             ...meta,
+            ...(result.advisory && { advisory: result.advisory }),
             // HIGH-2: signal to consumers that bridges array was suppressed
             // because the user filtered to unmatched-only.
             ...(unmatchedOnly && { filterMode: 'unmatched' }),

package/core/output/extraction.js

@@ -17,11 +17,11 @@ function formatFn(match, fnCode) {
     lines.push(`${match.relativePath}:${match.startLine}`);
     // Class attribution: three same-name `clear` methods under --all were
     // indistinguishable without their owning class (fix #248).
-    const sig = formatFunctionSignature(match);
-    const attributed = match.className && !sig.includes(`${match.className}.`)
-        ? `${match.className}.${sig}`
-        : sig;
-    lines.push(`${lineRange(match.startLine, match.endLine)} ${attributed}`);
+    const signatureTarget = match.className
+        ? { ...match, name: `${match.className}.${match.name}` }
+        : match;
+    const sig = formatFunctionSignature(signatureTarget);
+    lines.push(`${lineRange(match.startLine, match.endLine)} ${sig}`);
     lines.push('─'.repeat(60));
     lines.push(fnCode);
     return lines.join('\n');
@@ -69,10 +69,14 @@ function formatFunctionJson(fn, code) {
  * Notes are NOT included — surfaces render those separately (e.g. stderr for CLI).
  * @param {{ entries: Array<{match, code}>, notes: string[] }} result
  */
-function formatFnResult(result) {
+function formatFnResult(result, options = {}) {
     const parts = [];
-    for (const { match, code } of result.entries) {
-        parts.push(formatFn(match, code));
+    for (const { match, code, truncated, shownLines, totalLines } of result.entries) {
+        let text = formatFn(match, code);
+        if (truncated) {
+            text += `\n... showing ${shownLines} of ${totalLines} lines (${options.maxLinesHint || 'use --max-lines=N or omit it for the full function'})`;
+        }
+        parts.push(text);
     }
     const separator = result.entries.length > 1 ? '\n\n' + '═'.repeat(60) + '\n\n' : '';
     return parts.join(separator);
@@ -83,9 +87,16 @@ function formatFnResult(result) {
  */
 function formatFnResultJson(result) {
     if (result.entries.length === 1) {
-        return formatFunctionJson(result.entries[0].match, result.entries[0].code);
+        const entry = result.entries[0];
+        const value = JSON.parse(formatFunctionJson(entry.match, entry.code));
+        if (entry.truncated) {
+            value.truncated = true;
+            value.shownLines = entry.shownLines;
+            value.totalLines = entry.totalLines;
+        }
+        return JSON.stringify(value, null, 2);
     }
-    const arr = result.entries.map(({ match, code }) => ({
+    const arr = result.entries.map(({ match, code, truncated, shownLines, totalLines }) => ({
         name: match.name,
         params: match.params,
         paramsStructured: match.paramsStructured || [],
@@ -101,6 +112,7 @@ function formatFnResultJson(result) {
         ...(match.isGenerator && { isGenerator: true }),
         file: match.relativePath || match.file,
         code,
+        ...(truncated && { truncated: true, shownLines, totalLines }),
     }));
     return JSON.stringify(arr, null, 2);
 }
@@ -109,7 +121,7 @@ function formatFnResultJson(result) {
  * Format class handler result (from execute.js).
  * @param {{ entries: Array<{match, code, methods?, summaryMode, truncated, totalLines, maxLines?}>, notes: string[] }} result
  */
-function formatClassResult(result) {
+function formatClassResult(result, options = {}) {
     const parts = [];
     for (const entry of result.entries) {
         if (entry.summaryMode) {
@@ -124,7 +136,7 @@ function formatClassResult(result) {
                     lines.push(`  ${formatFunctionSignature(m)}  [line ${m.startLine}]`);
                 }
             }
-            lines.push(`\nClass is ${entry.totalLines} lines. Use --max-lines=N to see source, or "fn <method>" for individual methods.`);
+            lines.push(`\nClass is ${entry.totalLines} lines. ${options.classSourceHint || 'Use --max-lines=N to see source, or "source <method-handle>" for an individual method.'}`);
             parts.push(lines.join('\n'));
         } else if (entry.truncated) {
             parts.push(formatClass(entry.match, entry.code) + `\n\n... showing ${entry.maxLines} of ${entry.totalLines} lines`);