ucn 5.5.3 → 5.6.1

package/core/output/check.js

@@ -1,14 +1,77 @@
 /**
  * core/output/check.js — Pre-commit check formatter.
+ *
+ * Items are grouped by verdict, worst first: what broke, what to look at,
+ * what nothing depends on. Every site of a break is listed: a reader who
+ * has to fix thirteen call sites needs thirteen lines.
  */
 
 'use strict';
 
+const SECTIONS = [
+    ['blocked', 'BLOCKED', 'a break was observed'],
+    ['review', 'REVIEW', 'change exposure or call requirements not settled'],
+    ['ready', 'READY', 'no unresolved exposure in the modeled checks'],
+];
+// Occurrences of a name are context, not a worklist: a head is enough.
+const NAME_SITE_LIMIT = 10;
+
+function callersText(it) {
+    if (it.kind === 'module') return '';
+    let callers = it.callerCount != null ? `${it.callerCount} caller${it.callerCount === 1 ? '' : 's'}` : '';
+    if (it.unverifiedCallerCount > 0) callers += ` (+${it.unverifiedCallerCount} unverified)`;
+    return callers;
+}
+
+function itemLines(it) {
+    const tags = [];
+    if (it.kind && it.kind !== 'changed') tags.push(it.kind.toUpperCase());
+    if (it.verdict === 'ready' && it.kind === 'modified') {
+        if (it.change === 'inert') tags.push('contract unchanged');
+        else if (it.noDependents) tags.push('no static dependents');
+    }
+    if (it.verdict !== 'ready') {
+        for (const reason of it.reasons || []) if (reason !== 'signature-mismatch') tags.push(reason);
+    }
+    if (it.signatureMismatches > 0) tags.push(`SIG-DRIFT(${it.signatureMismatches})`);
+    if (it.orphan) tags.push('ORPHAN');
+    if (it.symbolType) tags.push(it.symbolType);
+    // Caller evidence matters where the callers do.
+    if (it.verdict !== 'ready' && it.kind !== 'deleted' && it.account && !it.account.textComplete) {
+        tags.push('ACCOUNT-INCOMPLETE');
+    }
+    const lines = [`  ${it.name} (${it.file}:${it.line})${tags.length ? ` [${tags.join(', ')}]` : ''}  ${callersText(it)}`.trimEnd()];
+    if (it.symbolType) {
+        lines.push(`    Dependencies: ${it.dependencyCount || 0} confirmed, ${it.unverifiedDependencyCount || 0} unverified`);
+    }
+    for (const m of it.mismatches || []) {
+        const problem = m.expected ? `expected ${m.expected}, got ${m.actual}` : (m.reason || 'arity mismatch');
+        const where = m.file ? `${m.file}:${m.line}` : '';
+        const expression = m.expression ? `  ${String(m.expression).trim()}` : '';
+        lines.push(`    ↳ ${where}${expression}  ${problem}${m.unchecked ? '  (not checked by the toolchain)' : ''}`);
+    }
+    for (const site of it.outgoingReview || []) {
+        lines.push(`    ↳ ${site.file}:${site.line}${site.column != null ? `:${site.column + 1}` : ''}  ${site.name}: ${site.reason}`);
+    }
+    const sites = it.sites || [];
+    const definite = it.verdict === 'blocked';
+    const shown = definite ? sites : sites.slice(0, NAME_SITE_LIMIT);
+    for (const site of shown) {
+        lines.push(`    ↳ ${site.file}${site.line ? `:${site.line}` : ''}${site.kind ? `  ${site.kind}` : ''}` +
+            `${site.unchecked ? '  (not checked by the toolchain)' : ''}`);
+    }
+    if (sites.length > shown.length) lines.push(`    (+${sites.length - shown.length} more occurrence(s))`);
+    return lines;
+}
+
 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.`;
+        const advice = result.status === 'staged-snapshot-unavailable'
+            ? 'This is not a pass, and says nothing about the worktree. Resolve what keeps the git index from being exported (unmerged paths, a missing object) and rerun.'
+            : 'This is not a pass. Fix the git context (run inside a git repository with a valid base ref) and rerun.';
+        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'}\n${advice}`;
     }
     const pathNotes = [];
     if (result.nonSourcePaths > 0) pathNotes.push(`Note: ${result.nonSourcePaths} changed path(s) outside supported source files not analyzed.`);
@@ -21,20 +84,26 @@ function formatCheck(result) {
     lines.push(`Pre-commit Check vs ${result.base}${result.staged ? ' (staged)' : ''}`);
     lines.push('═'.repeat(60));
     lines.push(...pathNotes);
+    for (const note of result.notes || []) lines.push(`Note: ${note}`);
+    const items = result.changed || [];
     if (result.trust) {
-        lines.push(`TRUST: ${result.trust.status} — UCN evidence is not semantic proof; compiler and tests are required`);
-        const trustDetails = [];
-        if (result.trust.incompleteAccounts) trustDetails.push(`${result.trust.incompleteAccounts} incomplete account(s)`);
-        if (result.trust.unverifiedCallSites) trustDetails.push(`${result.trust.unverifiedCallSites} unverified caller(s)`);
-        if (result.trust.signatureMismatches) trustDetails.push(`${result.trust.signatureMismatches} signature mismatch(es)`);
-        if (result.trust.filteredEdges) trustDetails.push(`${result.trust.filteredEdges} filtered edge(s)`);
-        if (result.trust.usageReviewSymbols) trustDetails.push(`${result.trust.usageReviewSymbols} symbol(s) need usages review`);
-        if (result.trust.unvalidatedDeclarations) trustDetails.push(`${result.trust.unvalidatedDeclarations} declaration change(s) need toolchain validation`);
-        if (trustDetails.length > 0) lines.push(`  ${trustDetails.join(' · ')}`);
+        const trust = result.trust;
+        lines.push(`TRUST: ${trust.status} — UCN evidence is not semantic proof; compiler and tests are required`);
+        const counts = [];
+        if (trust.blocked) counts.push(`${trust.blocked} blocked`);
+        if (trust.review) counts.push(`${trust.review} to review`);
+        if (trust.ready) counts.push(`${trust.ready} ready`);
+        const details = [];
+        if (trust.signatureMismatches) details.push(`${trust.signatureMismatches} signature mismatch(es)`);
+        if (trust.unverifiedCallSites) details.push(`${trust.unverifiedCallSites} unverified caller(s)`);
+        if (trust.incompleteAccounts) details.push(`${trust.incompleteAccounts} incomplete account(s)`);
+        if (trust.filteredEdges) details.push(`${trust.filteredEdges} filtered edge(s)`);
+        if (trust.usageReviewSymbols) details.push(`${trust.usageReviewSymbols} symbol(s) need usages review`);
+        if (trust.unvalidatedDeclarations) details.push(`${trust.unvalidatedDeclarations} declaration change(s) need toolchain validation`);
+        if (trust.strict) details.push('strict: review does not pass');
+        if (counts.length > 0 || details.length > 0) lines.push(`  ${[...counts, ...details].join(' · ')}`);
     }
 
-    // Changed functions section
-    const items = result.changed || [];
     const noun = items.some(it => it.symbolType) ? 'symbol' : 'function';
     if (result.truncated) {
         lines.push(`Changed: ${items.length} of ${result.totalChanged} ${noun}s`);
@@ -44,38 +113,28 @@ function formatCheck(result) {
     if (items.length === 0) {
         lines.push('  (none — only non-function changes)');
     } else {
-        for (const it of items) {
-            const tags = [];
-            if (it.kind && it.kind !== 'changed') tags.push(it.kind.toUpperCase());
-            if (it.signatureMismatches > 0) tags.push(`SIG-DRIFT(${it.signatureMismatches})`);
-            if (it.orphan) tags.push('ORPHAN');
-            if (it.symbolType) tags.push(it.symbolType);
-            if (it.account && !it.account.textComplete) tags.push('ACCOUNT-INCOMPLETE');
-            const tagStr = tags.length ? ' [' + tags.join(', ') + ']' : '';
-            let callers = it.callerCount != null ? `${it.callerCount} caller${it.callerCount === 1 ? '' : 's'}` : '';
-            if (it.unverifiedCallerCount > 0) {
-                callers += ` (+${it.unverifiedCallerCount} unverified)`;
-            }
-            lines.push(`  ${it.name} (${it.file}:${it.line})${tagStr}  ${callers}`);
-            if (it.symbolType) lines.push(`    Dependencies: ${it.dependencyCount || 0} confirmed, ${it.unverifiedDependencyCount || 0} unverified`);
-            if (it.mismatches && it.mismatches.length > 0) {
-                for (const m of it.mismatches.slice(0, 3)) {
-                    const where = m.file ? ` at ${m.file}:${m.line}` : '';
-                    const reason = m.expected
-                        ? `expected ${m.expected}, got ${m.actual}`
-                        : (m.reason || 'arity mismatch');
-                    lines.push(`    ↳ ${reason}${where}`);
-                }
-            }
+        for (const [verdict, title, meaning] of SECTIONS) {
+            const group = items.filter(it => (it.verdict || 'review') === verdict);
+            if (group.length === 0) continue;
+            lines.push(`${title} (${group.length}) — ${meaning}:`);
+            for (const it of group) lines.push(...itemLines(it));
         }
     }
 
     // Tests
     lines.push('');
     if (result.testFiles && result.testFiles.length > 0) {
-        lines.push(`Tests potentially affected: ${result.totalTests || result.testFiles.length} in ${result.testFiles.length} file${result.testFiles.length === 1 ? '' : 's'}`);
+        const files = result.testFiles.length;
+        // A count of tests is printed only when tests were counted: files
+        // whose tests are not read have none to report.
+        // "at least": a file among them holds tests that are not listed.
+        const conditional = result.conditionalTests ? ` (${result.conditionalTests} conditional)` : '';
+        lines.push(result.totalTests > 0
+            ? `Tests potentially affected: ${result.moreTests ? 'at least ' : ''}${result.totalTests} in ${files} file${files === 1 ? '' : 's'}${conditional}`
+            : `Test files potentially affected: ${files}${result.moreTests ? ' (tests not listed)' : ''}`);
         for (const tf of result.testFiles.slice(0, 8)) {
-            const cnt = tf.testCount ? ` (${tf.testCount})` : '';
+            const cnt = tf.testCount ? ` (${tf.moreTests ? 'at least ' : ''}${tf.testCount})`
+                : tf.moreTests ? ' (tests not listed)' : '';
             lines.push(`  ${tf.file}${cnt}`);
         }
         if (result.testFiles.length > 8) {
@@ -84,6 +143,11 @@ function formatCheck(result) {
     } else {
         lines.push('Tests: none detected for changed functions');
     }
+    if (result.supportFiles && result.supportFiles.length > 0) {
+        const names = result.supportFiles.slice(0, 5).map(row => row.file).join(', ');
+        const more = result.supportFiles.length > 5 ? `, +${result.supportFiles.length - 5} more` : '';
+        lines.push(`Test support code reached (declares no test, runs with the tests that load it): ${names}${more}`);
+    }
 
     // Action items
     if (result.actions && result.actions.length > 0) {

package/core/output/doctor.js

@@ -116,7 +116,15 @@ function formatDoctor(result, options = {}) {
                 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.');
+                const unsearchable = info.unsearchable || 0;
+                if (unsearchable > 0) {
+                    lines.push(`    ${unsearchable} could not be searched: no caller account is complete until ` +
+                        'they can be read (fix the path, raise the limit, or declare it in .ucn.json outsideProject).');
+                }
+                if (fileCount > unsearchable) {
+                    lines.push(`    ${unsearchable > 0 ? 'The rest is searched' : 'Searched'} as text for each name: ` +
+                        'an occurrence there is listed, not analyzed.');
+                }
             } else {
                 lines.push(`  ${label}: ${info.count} ${unit}${info.count === 1 ? '' : 's'} in ${fileCount} file${fileCount === 1 ? '' : 's'}`);
             }
@@ -129,6 +137,31 @@ function formatDoctor(result, options = {}) {
     }
     if (!anyBlindSpot) lines.push('  (none detected)');
 
+    // What a completeness claim ranges over and what it never means: said
+    // here once, so an answer only carries its own state.
+    lines.push('');
+    lines.push('Contract scope:');
+    const scope = result.scope;
+    if (scope) {
+        const list = reasons => Object.entries(reasons || {})
+            .map(([reason, count]) => `${reason} ${count}`).join(', ');
+        lines.push(`  Indexed source, plus ${scope.textOnly.count} file${scope.textOnly.count === 1 ? '' : 's'} ` +
+            `searched as text for each name${scope.textOnly.count > 0 ? ` (${list(scope.textOnly.reasons)})` : ''}.`);
+        if (scope.opaque.count > 0) {
+            lines.push(`  Not searchable: ${scope.opaque.count} path${scope.opaque.count === 1 ? '' : 's'} ` +
+                `(${list(scope.opaque.reasons)}); every caller account is degraded until they are.`);
+        }
+        if (scope.outside.count > 0) {
+            const sample = scope.outside.sample.slice(0, 3).map(entry => entry.path).join(', ');
+            lines.push(`  Outside the project: ${scope.outside.count} path${scope.outside.count === 1 ? '' : 's'} ` +
+                `(${list(scope.outside.reasons)}), no part of any claim: ${sample}` +
+                `${scope.outside.count > 3 ? ', ...' : ''}`);
+        }
+    }
+    lines.push('  CONTRACT text-complete: every literal-name line in that scope was classified.');
+    lines.push('  It is never semantic completeness (aliases, indirect calls, generated code and');
+    lines.push('  runtime dispatch may exist), and a zero is never deletion proof.');
+
     // Task-specific readiness. One scalar cannot honestly describe navigation,
     // refactoring, and deletion risk.
     lines.push('');

package/core/output/find.js

@@ -10,9 +10,10 @@ const {
 } = require('./shared');
 
 const { formatSymbolHandle } = require('../shared');
+const { paramFact } = require('../registry');
 
 // Detailed text rows shown by default; the rest are counted.
-const DEFAULT_DISPLAY_LIMIT = 5;
+const DEFAULT_DISPLAY_LIMIT = paramFact('limit', 'findDetail');
 
 /**
  * Trim a docstring to a single short sentence (max 80 chars) for inline display.

package/core/output/lines.js

@@ -15,10 +15,11 @@
 'use strict';
 
 const { CALLABLE_SYMBOL_KINDS } = require('../shared');
-const { formatSurfaceMessage } = require('../registry');
+const { CANONICAL_COMMANDS, FLAG_APPLICABILITY, formatSurfaceMessage } = require('../registry');
 const { formatAccountLines, formatCalleeAccountLine } = require('./analysis');
 
-const LINES_COMMANDS = new Set(['find', 'usages', 'search', 'show', 'impact']);
+// The commands that take `lines`: the registry's applicability.
+const LINES_COMMANDS = new Set(CANONICAL_COMMANDS.filter(command => FLAG_APPLICABILITY[command].includes('lines')));
 
 function record(pathLike, line, text, tag = '') {
     // One record per line is the contract: a multi-line signature or a
@@ -304,4 +305,63 @@ function formatPublicRaw(result, execution = {}) {
     return code;
 }
 
-module.exports = { LINES_COMMANDS, formatPublicLines, formatPublicRaw, commentLines };
+/**
+ * A line listing cut to `limit` characters: the records that fit, in their
+ * order, then every comment line, then one `# truncated` line counting the
+ * records left out. A record is never cut and a comment line is never
+ * dropped: the accounting still describes the whole answer. Null when the
+ * listing has no record to drop or when not one record fits beside the
+ * comment lines. `allowNoRows` may return no rows, but still keeps every
+ * comment; if that cannot fit, it explicitly withholds the whole answer.
+ */
+function budgetLineListing(text, limit, surface = 'cli', { allowNoRows = false } = {}) {
+    const lines = String(text).split('\n').filter(line => line !== '');
+    const records = lines.filter(line => !line.startsWith('# '));
+    const comments = lines.filter(line => line.startsWith('# '));
+    if (records.length === 0 && !allowNoRows) return null;
+    const advice = surface === 'mcp'
+        ? 'raise max_chars or narrow the query'
+        : 'raise --max-chars or omit it';
+    const trailer = omitted => `# truncated: ${omitted} of ${records.length} rows omitted; ${advice}`;
+    // The most records whose text, with every comment line and the trailer
+    // that counts the rest, is within the limit.
+    const fixed = comments.reduce((sum, line) => sum + line.length + 1, 0);
+    const withheld = () => {
+        const flag = surface === 'mcp' ? 'max_chars' : '--max-chars';
+        const needed = Math.min(String(text).length, fixed + trailer(records.length).length);
+        const notices = [
+            `# Answer withheld: accounting does not fit; raise ${flag} to at least ${needed}.`,
+            `# Answer withheld; ${flag}>=${needed}`,
+            `# withheld; >=${needed}`,
+        ];
+        return {
+            text: notices.find(notice => notice.length <= limit) || '',
+            rows: records.length, omitted: records.length, contractMetadataComplete: false,
+        };
+    };
+    if (records.length === 0) return withheld();
+    const prefix = [0];
+    for (const record of records) prefix.push(prefix[prefix.length - 1] + record.length + 1);
+    let kept = 0;
+    for (let count = records.length - 1; count >= 1; count--) {
+        if (prefix[count] + fixed + trailer(records.length - count).length <= limit) { kept = count; break; }
+    }
+    if (kept === 0) {
+        // No row fits. Never present a partial accounting as the complete
+        // answer: all comment lines accompany the row count, or the entire
+        // answer is withheld explicitly.
+        const all = trailer(records.length);
+        if (!allowNoRows) return null;
+        if (fixed + all.length > limit) return withheld();
+        return { text: [...comments, all].join('\n'), rows: records.length, omitted: records.length,
+            contractMetadataComplete: true };
+    }
+    return {
+        text: [...records.slice(0, kept), ...comments, trailer(records.length - kept)].join('\n'),
+        rows: records.length,
+        omitted: records.length - kept,
+        contractMetadataComplete: true,
+    };
+}
+
+module.exports = { LINES_COMMANDS, formatPublicLines, formatPublicRaw, commentLines, budgetLineListing };

package/core/output/public.js

@@ -10,10 +10,12 @@
 
 const { COMMAND_CONTRACTS } = require('../command-contracts');
 const { COMMAND_TRUST_MATRIX } = require('../trust-matrix');
-const { toCliName, toMcpName, formatSurfaceMessage } = require('../registry');
+const { toCliName, toMcpName, formatSurfaceMessage, paramDefault } = require('../registry');
 const { LINES_COMMANDS, formatPublicLines, formatPublicRaw } = require('./lines');
 const { provenanceReplacer } = require('./provenance');
 
+const { summarizeReasons } = require('../evidence-bands');
+
 const legacy = {
     ...require('./analysis'),
     ...require('./analysis-ext'),
@@ -163,11 +165,12 @@ function formatShow(result, params = {}, hints = presentationHints()) {
     if (result.context) {
         const context = { ...result.context };
         const formatted = legacy.formatContext(context, {
-            showConfidence: params.showConfidence !== false,
-            compact: params.compact !== false,
+            showConfidence: params.showConfidence ?? paramDefault('showConfidence'),
+            compact: params.compact ?? paramDefault('compact', 'show'),
             expandHint: hints.source,
             allHint: hints.all,
             usagesHint: hints.usages(context.function || result.target),
+            evidenceBands: hints.evidenceBands,
         });
         parts.push(block('RELATIONSHIPS', projectContextText(formatted.text, selected)));
     }
@@ -227,10 +230,14 @@ function formatTrace(result, params = {}, hints = presentationHints()) {
     });
 }
 
-function formatImpact(result, params = {}) {
+function formatImpact(result, params = {}, hints = presentationHints()) {
+    // `--all` prints every unverified row, `--top` (or `--limit`) that many.
+    const top = Number(params.limit) > 0 ? Number(params.limit) : Number(params.top) > 0 ? Number(params.top) : undefined;
+    const rows = { all: !!params.all, ...(Number.isInteger(top) && { top }), allHint: hints.all,
+        evidenceBands: hints.evidenceBands };
     return modeOf('impact', result) === 'diff'
-        ? legacy.formatDiffImpact(result, { all: params.all })
-        : legacy.formatImpact(result, { compact: params.compact !== false });
+        ? legacy.formatDiffImpact(result, rows)
+        : legacy.formatImpact(result, { compact: params.compact ?? paramDefault('compact', 'impact'), ...rows });
 }
 
 function formatTests(result, params = {}, hints = presentationHints()) {
@@ -299,11 +306,13 @@ function formatPublicText(command, result, params = {}, execution = {}) {
         if (shaped != null) return shaped;
     }
     const hints = presentationHints(execution.surface);
+    // Display only: another band table relabels the reason summaries.
+    if (execution.evidenceBands) hints.evidenceBands = execution.evidenceBands;
     if (result?.scopeWarning?.hint) {
-        result.scopeWarning = {
+        result = { ...result, scopeWarning: {
             ...result.scopeWarning,
             hint: formatSurfaceMessage(result.scopeWarning.hint, execution.surface),
-        };
+        } };
     }
     let text;
     switch (command) {
@@ -312,7 +321,7 @@ function formatPublicText(command, result, params = {}, execution = {}) {
             text = modeOf('find', result) === 'type'
                 ? legacy.formatTypedef(result, params.name)
                 : legacy.formatFindDetailed(result, params.name, {
-                    compact: params.compact,
+                    compact: params.compact ?? paramDefault('compact', 'find'),
                     withSource: params.withSource,
                     top: params.limit,
                     all: !!params.all,
@@ -320,7 +329,7 @@ function formatPublicText(command, result, params = {}, execution = {}) {
                 });
             break;
         case 'usages': text = legacy.formatUsages(result, params.name, {
-            compact: params.compact,
+            compact: params.compact ?? paramDefault('compact', 'usages'),
             all: params.all,
             allHint: hints.all,
         }); break;
@@ -341,7 +350,7 @@ function formatPublicText(command, result, params = {}, execution = {}) {
             break;
         case 'source': text = formatSource(result, hints); break;
         case 'trace': text = formatTrace(result, params, hints); break;
-        case 'impact': text = formatImpact(result, params); break;
+        case 'impact': text = formatImpact(result, params, hints); break;
         case 'tests': text = formatTests(result, params, hints); break;
         case 'deps': text = formatDeps(result, params, hints); break;
         case 'api': text = legacy.formatApi(result, params.file || '.'); break;
@@ -413,6 +422,8 @@ function formatPublicJson(command, result, params = {}, execution = {}) {
         commandMeta.excludedConstructors = result.excludedConstructors || 0;
         commandMeta.pythonImplicitExportFiles = result.pythonImplicitExportFiles || 0;
         commandMeta.excludedDynamicDispatch = result.excludedDynamicDispatch || 0;
+        commandMeta.excludedRequiredSlot = result.excludedRequiredSlot || 0;
+        commandMeta.projectKind = result.projectKind || 'library';
         commandMeta.computedDispatch = result.computedDispatch || { count: 0, names: [] };
         commandMeta.reflection = result.reflection || {
             count: 0, literalCount: 0, dynamicCount: 0,
@@ -468,6 +479,13 @@ function formatPublicJson(command, result, params = {}, execution = {}) {
     if (command === 'usages' && result?.analysisGaps) {
         commandMeta.analysisGaps = result.analysisGaps;
     }
+    // The reasons of the unverified callers with how often each was a real
+    // edge on the release board: labels beside the data, never part of it.
+    const unverifiedCallers = command === 'impact' ? result?.unverifiedSites
+        : command === 'show' ? result?.context?.unverifiedCallers : null;
+    if (Array.isArray(unverifiedCallers) && unverifiedCallers.length > 0) {
+        commandMeta.unverifiedReasons = summarizeReasons(unverifiedCallers, execution.evidenceBands);
+    }
 
     const surfaceCommand = execution.surface === 'mcp'
         ? toMcpName(command)

package/core/output/refactoring.js

@@ -71,10 +71,42 @@ function groupedReviewLines(items, cap = 20) {
  * Format plan command output - text
  * Shows before/after signatures and all changes needed
  */
+/**
+ * A deletion assessment: the verdict, its basis and where the declaration
+ * is. What the verdict never means (a guarantee) is stated once, in the
+ * tool description and the usage guide.
+ */
+function formatDeletion(assessment) {
+    const d = assessment.declaration;
+    const owner = d.className ? `${d.className}.` : '';
+    const lines = [
+        `Deletion assessment: ${owner}${d.name}`,
+        '═'.repeat(60),
+        `${d.file}:${d.startLine}${d.type ? `  (${d.type})` : ''}`,
+        ...(assessment.warnings || []).map(warning => `Note: ${warning.message}`),
+        `VERDICT: ${assessment.verdict}`,
+        `  basis: ${assessment.basis}`,
+    ];
+    if (assessment.site) {
+        const site = assessment.site;
+        lines.push(`  first use: ${site.file}${site.line != null ? `:${site.line}` : ''}`);
+    }
+    if (assessment.projectKind === 'application') {
+        lines.push('  project kind: application (.ucn.json): exported symbols are assessed');
+    }
+    if (assessment.verdict === 'has-static-dependents') {
+        lines.push(`  next: ucn show ${d.file}:${d.startLine}:${d.name} lists the callers; ucn usages ${d.name} lists every occurrence`);
+    } else if (assessment.reason === 'downstream-exposure') {
+        lines.push('  next: declare "kind": "application" in .ucn.json if nothing outside this repository consumes it');
+    }
+    return lines.join('\n');
+}
+
 function formatPlan(plan, options = {}) {
     if (!plan) {
         return 'Function not found.';
     }
+    if (plan.operation === 'delete') return formatDeletion(plan);
     if (!plan.found) {
         return `Function "${plan.function}" not found.`;
     }

package/core/output/reporting.js

@@ -215,8 +215,11 @@ function formatDeadcode(results, options = {}) {
     if (results.length === 0 && !results.excludedDecorated &&
         !results.excludedExported && !results.excludedExternalContract &&
         !results.excludedRuntimeContract && !results.excludedConstructors && !results.pythonImplicitExportFiles &&
-        !results.excludedDynamicDispatch && !results.computedDispatch?.count &&
+        !results.excludedDynamicDispatch && !results.excludedRequiredSlot &&
+        results.projectKind !== 'application' && !results.computedDispatch?.count &&
         !results.reflection?.withheld && !results.reflection?.dynamicCount && !results.reflection?.literalCount &&
+        !results.reflection?.withheldByTable?.length && !results.macroPaste?.withheld &&
+        !results.macroPaste?.blind?.count && !results.macroRulesBlind?.count &&
         results.coverage?.complete !== false) {
         return 'No dead code found.';
     }
@@ -232,6 +235,8 @@ function formatDeadcode(results, options = {}) {
         } else {
             lines.push(`Dead code: ${results.length} unused symbol(s)\n`);
         }
+    } else {
+        lines.push('Dead code: 0 unused symbol(s)\n');
     }
 
     let currentFile = null;
@@ -301,6 +306,12 @@ function formatDeadcode(results, options = {}) {
     if (results.excludedDynamicDispatch > 0) {
         lines.push(`\n${results.excludedDynamicDispatch} registry member(s) hidden because a matching computed dispatch (registry[key]()) may invoke them.`);
     }
+    if (results.excludedRequiredSlot > 0) {
+        lines.push(`\n${results.excludedRequiredSlot} member(s) withheld: required by an interface, abstract class or trait of the project, overridden by a descendant that says so, or matching a project interface or protocol by shape. Removing one can break a type.`);
+    }
+    if (results.projectKind === 'application') {
+        lines.push('\nProject kind: application (.ucn.json). Exported symbols are audited; contracts, registrations and reflection still withhold.');
+    }
     if (results.computedDispatch?.count > 0) {
         lines.push(`\nWARNING: ${results.computedDispatch.count} computed dispatch call(s) in ${results.computedDispatch.fileCount} file(s). Dead-code results are review candidates; runtime-selected members may not have a named static edge.`);
     }
@@ -379,6 +390,8 @@ function formatDeadcodeJson(results) {
             ...(results.excludedConstructors > 0 && { excludedConstructors: results.excludedConstructors }),
             ...(results.pythonImplicitExportFiles > 0 && { pythonImplicitExportFiles: results.pythonImplicitExportFiles }),
             ...(results.excludedDynamicDispatch > 0 && { excludedDynamicDispatch: results.excludedDynamicDispatch }),
+            ...(results.excludedRequiredSlot > 0 && { excludedRequiredSlot: results.excludedRequiredSlot }),
+            ...(results.projectKind === 'application' && { projectKind: results.projectKind }),
             ...(results.computedDispatch?.count > 0 && { computedDispatch: results.computedDispatch }),
             ...(results.reflection?.count > 0 && { reflection: results.reflection }),
             ...(results.macroPaste && { macroPaste: results.macroPaste }),
@@ -573,7 +586,11 @@ function formatOrient(result, options = {}) {
     if (result.skippedSources?.count > 0) {
         const reasons = Object.entries(result.skippedSources.reasons || {})
             .map(([reason, count]) => `${reason} ${count}`).join(', ');
-        lines.push(`SKIPPED SOURCE: ${result.skippedSources.count} path(s) were not indexed${reasons ? ` (${reasons})` : ''} — completeness claims are withdrawn.`);
+        const unsearchable = result.skippedSources.unsearchable || 0;
+        lines.push(`SKIPPED SOURCE: ${result.skippedSources.count} path(s) not indexed${reasons ? ` (${reasons})` : ''} — ` +
+            (unsearchable > 0
+                ? `${unsearchable} could not be searched, so no caller account is complete.`
+                : 'searched as text for each name; an occurrence there is listed, not analyzed.'));
     }
     lines.push('');
 

package/core/output/search.js

@@ -3,6 +3,7 @@
  */
 
 const { detectDoubleEscaping, advisoryLine } = require('./shared');
+const { selectorText, testCountText } = require('../test-units');
 
 /**
  * Format search command output
@@ -419,15 +420,26 @@ function formatTests(tests, name) {
         }
 
         for (const testFile of tests) {
-            lines.push(testFile.file);
+            const counted = testCountText(testFile.tests, testFile.moreTests, testFile.conditionalTests);
+            const facts = testFile.role === 'support' ? '  [support: declares no test]'
+                : counted ? `  (${counted})` : '';
+            lines.push(`${testFile.file}${facts}`);
             for (const match of testFile.matches) {
                 const typeLabel = match.matchType === 'test-case' ? '[test]' :
                     match.matchType === 'import' ? '[import]' :
                     match.matchType === 'call' ? '[call]' :
                     match.matchType === 'unverified-call' ? '[unverified-call]' :
                     match.matchType === 'unverified-reference' ? '[unverified-ref]' :
+                    match.matchType === 'inherited-test' ? '[inherited]' :
                     match.matchType === 'string-ref' ? '[string]' : '[ref]';
-                lines.push(`  ${match.line}: ${typeLabel} ${match.content}`);
+                // A test the class inherits: its name, and where its body is.
+                const origin = match.matchType === 'inherited-test' ? `  ${match.name} (from ${match.from})` : '';
+                lines.push(`  ${match.line}: ${typeLabel} ${match.content}${origin}`);
+            }
+            if (testFile.run) lines.push(`  run: ${selectorText(testFile.run)}`);
+            else if (testFile.role === 'tests' && testFile.runWithheld) lines.push(`  no command: ${testFile.runWithheld}`);
+            for (const unit of testFile.units || []) {
+                if (unit.selector) lines.push(`  run test: ${selectorText(unit.selector)}`);
             }
             lines.push('');
         }