ucn 5.5.2 → 5.6.0

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)
@@ -476,6 +494,7 @@ function formatPublicJson(command, result, params = {}, execution = {}) {
     const envelope = {
         meta: {
             command: surfaceCommand,
+            ...(execution.surface === 'cli' && { maxChars: 'not-applied' }),
             ...(surfaceCommand !== command && { canonicalCommand: command }),
             // A result that self-reports it could not run (check with a bad
             // base ref / outside git) must be machine-distinguishable from a

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,7 +215,8 @@ 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.coverage?.complete !== false) {
         return 'No dead code found.';
@@ -301,6 +302,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.`);
     }
@@ -315,6 +322,12 @@ function formatDeadcode(results, options = {}) {
     if (results.reflection?.dynamicCount > 0) {
         lines.push(`\nWARNING: ${results.reflection.dynamicCount} dynamic reflection use(s) have no static member spelling. Dead-code results remain review candidates because runtime-selected members cannot be attributed.`);
     }
+    if (results.reflection?.withheldByTable?.length > 0) {
+        lines.push('\nConservatively withheld: exact string literals in a file with dynamic reflection (flow to the reflection call is unproven):');
+        for (const site of results.reflection.withheldByTable) {
+            lines.push(`  ${site.name}: named in possible reflection table ${site.file}:${site.line}`);
+        }
+    }
     if (results.macroPaste) {
         const m = results.macroPaste;
         if (m.withheld > 0) {
@@ -373,6 +386,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 }),
@@ -567,7 +582,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,16 +420,24 @@ 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}`);
             lines.push('');
         }
     }

package/core/output/tracing.js

@@ -8,6 +8,7 @@
  * conservation) lines close the arithmetic.
  */
 
+const { testCountText } = require('../test-units');
 const { unverifiedReasonLabel } = require('./shared');
 const { codeUnitCompare } = require('../shared');
 const { formatAccountLines } = require('./analysis');
@@ -562,23 +563,49 @@ function formatAffectedTests(result, options = {}) {
         lines.push('No confirmed static test links found for any affected function.');
     } else {
         const MAX_TEST_FILES = options.all ? Infinity : 30;
-        const displayFiles = result.testFiles.slice(0, MAX_TEST_FILES);
-        const truncatedFiles = result.testFiles.length - displayFiles.length;
-        lines.push(`Test files to run (${summary.totalTestFiles}):`);
+        const runnable = result.testFiles.filter(tf => tf.role !== 'support');
+        const support = result.testFiles.filter(tf => tf.role === 'support');
+        const displayFiles = runnable.slice(0, MAX_TEST_FILES);
+        const truncatedFiles = runnable.length - displayFiles.length;
+        // A count is exact only where every test of the files is listed:
+        // "at least" says a file holds tests that are not.
+        const total = testCountText(summary.totalTests, summary.moreTests, summary.conditionalTests);
+        lines.push(`Test files to run (${runnable.length})${total ? `, ${total}` : ''}:`);
         lines.push('');
         for (const tf of displayFiles) {
-            lines.push(`  ${tf.file} (links: ${linkList(tf.linkedFunctions, options)})`);
+            const counted = testCountText(tf.testCount, tf.moreTests, tf.conditionalTests);
+            const count = counted ? ` · ${counted}` : '';
+            const refusal = tf.runWithheld ? ` · no command: ${tf.runWithheld}` : '';
+            lines.push(`  ${tf.file} (links: ${linkList(tf.linkedFunctions, options)})${count}${refusal}`);
             // Show up to 5 key matches per file
             const keyMatches = tf.matches
-                .filter(m => m.matchType === 'call' || m.matchType === 'test-case')
+                .filter(m => m.matchType === 'call' || m.matchType === 'test-case' || m.matchType === 'inherited-test')
                 .slice(0, 5);
             for (const m of keyMatches) {
-                lines.push(`    L${m.line}: ${m.content}  [${m.matchType}]`);
+                const origin = m.matchType === 'inherited-test' ? `  ${m.name} (from ${m.from})` : '';
+                lines.push(`    L${m.line}: ${m.content}${origin}  [${m.matchType}]`);
             }
         }
         if (truncatedFiles > 0) {
             lines.push(`\n  ... ${truncatedFiles} more test files (use file= and exclude= to narrow scope)`);
         }
+        if (support.length > 0) {
+            lines.push('');
+            lines.push(`Test support code reached (${support.length}) — declares no test, runs with the tests that load it:`);
+            for (const tf of support.slice(0, options.all ? Infinity : 10)) {
+                lines.push(`  ${tf.file} (links: ${linkList(tf.linkedFunctions, options)})`);
+            }
+        }
+        const commands = result.commands || [];
+        if (commands.length > 0) {
+            lines.push('');
+            lines.push('Run:');
+            const MAX_COMMANDS = options.all ? Infinity : 5;
+            for (const line of commands.slice(0, MAX_COMMANDS)) lines.push(`  ${line}`);
+            if (commands.length > MAX_COMMANDS) {
+                lines.push(`  ... ${commands.length - MAX_COMMANDS} more (${options.allHint || 'use --all'})`);
+            }
+        }
     }
 
     // Possible band: functions reachable only through unverified chains.
@@ -614,7 +641,8 @@ function formatAffectedTests(result, options = {}) {
     const pct = summary.totalAffected > 0
         ? Math.round(summary.staticallyLinkedFunctions / summary.totalAffected * 100)
         : 0;
-    let summaryLine = `Summary: ${summary.totalAffected} affected → ${summary.totalTestFiles} statically linked test files, ${summary.staticallyLinkedFunctions}/${summary.totalAffected} functions linked (${pct}%)`;
+    const totalTests = testCountText(summary.totalTests, summary.moreTests, summary.conditionalTests);
+    let summaryLine = `Summary: ${summary.totalAffected} affected → ${summary.totalTestFiles} statically linked test files${totalTests ? ` (${totalTests})` : ''}, ${summary.staticallyLinkedFunctions}/${summary.totalAffected} functions linked (${pct}%)`;
     if (summary.possiblyAffected > 0) {
         summaryLine += ` · ${summary.possiblyAffected} possibly affected (unverified chains)`;
     }