ucn 5.2.2 → 5.3.1

package/core/output/analysis-ext.js

@@ -215,6 +215,10 @@ function formatDiffImpact(result, options = {}) {
     if (result.nonSourcePaths > 0) {
         lines.push(`Note: ${result.nonSourcePaths} changed path(s) outside supported source files not analyzed.`);
     }
+    // fix #346: untracked source files join the working-tree diff.
+    if (result.untrackedPaths > 0) {
+        lines.push(`Note: ${result.untrackedPaths} untracked source file(s) included as whole-file additions.`);
+    }
     lines.push('');
 
     // Modified functions

package/core/output/analysis.js

@@ -786,8 +786,8 @@ function formatImpact(impact, options = {}) {
     // Summary (confirmed + unverified tiers reported separately)
     const impactUnverified = impact.unverifiedSites || [];
     const unverifiedSuffix = impactUnverified.length > 0 ? ` confirmed + ${impactUnverified.length} unverified` : '';
-    if (impact.propertyAccesses) {
-        const pa = impact.propertyAccesses;
+    if (impact.propertyAccesses || impact.typeReferences) {
+        const pa = impact.propertyAccesses || impact.typeReferences;
         const uv = pa.unverifiedCount ? ` + ${pa.unverifiedCount} unverified` : '';
         lines.push(`DEPENDENCY SITES: ${impact.totalDependencySites} confirmed${uv}`);
     }
@@ -885,6 +885,34 @@ function formatImpact(impact, options = {}) {
         }
     }
 
+    // fix #345: annotation sites of a type-kind definition, tiered like the
+    // accessor band. The headline no longer says 0 for a type with dependents.
+    if (impact.typeReferences) {
+        const refs = impact.typeReferences;
+        lines.push(`${compact ? '' : '\n'}TYPE REFERENCE SITES: ${refs.confirmedCount} confirmed` +
+            (refs.unverifiedCount ? ` + ${refs.unverifiedCount} unverified` : '') +
+            (refs.excluded?.total ? ` (${refs.excluded.total} other-target)` : ''));
+        for (const group of refs.byFile) {
+            for (const site of group.sites) {
+                const expr = site.expression ? `: ${site.expression.replace(/\s+/g, ' ').slice(0, 100)}` : '';
+                lines.push(`  ${group.file}:${site.line}${expr}`);
+            }
+        }
+        if (refs.unverifiedSites.length > 0) {
+            lines.push(`${compact ? '' : '\n'}UNVERIFIED TYPE REFERENCE CANDIDATES (${refs.unverifiedSites.length}) — name matches, no import link to this definition:`);
+            for (const site of refs.unverifiedSites.slice(0, 10)) {
+                const expr = site.expression ? `: ${site.expression.replace(/\s+/g, ' ').slice(0, 100)}` : '';
+                lines.push(`  ${site.file}:${site.line}${expr} (${site.reason})`);
+            }
+            if (refs.unverifiedSites.length > 10) {
+                lines.push(`  (+${refs.unverifiedSites.length - 10} more unverified)`);
+            }
+        }
+        if (refs.confirmedCount === 0 && refs.unverifiedCount === 0) {
+            lines.push('  (no annotation sites outside the definition)');
+        }
+    }
+
     // Unverified tier: visible, capped at 10 one-liners
     if (impactUnverified.length > 0) {
         lines.push(`${compact ? '' : '\n'}UNVERIFIED CALL SITES (${impactUnverified.length}) — call syntax, no binding/receiver evidence:`);

package/core/output/endpoints.js

@@ -84,7 +84,7 @@ function formatRoutesAndRequests(routes, requests, meta, options, advisory = nul
 
     if (showClient) {
         if (requests.length === 0) {
-            if (showServer) lines.push('No client requests detected.');
+            if (showServer) lines.push('Client Requests: 0 — no static route literal found in any indexed file (wrapped or dynamically built request paths are invisible to this scan).');
         } else {
             if (showServer) lines.push('');
             lines.push(`Client Requests: ${requests.length}`);

package/core/output/graph.js

@@ -21,7 +21,7 @@ function formatImports(imports, filePath) {
     if (internal.length > 0) {
         lines.push('INTERNAL:');
         for (const imp of internal) {
-            lines.push(`  ${imp.module}${imp.deferred ? ' [function-local/deferred]' : ''}`);
+            lines.push(`  ${imp.module}${deferredImportLabel(imp)}`);
             if (imp.resolved) {
                 lines.push(`    -> ${imp.resolved}${imp.indexed === false
                     ? ' (not indexed; absent from dependency graph)'
@@ -37,7 +37,7 @@ function formatImports(imports, filePath) {
         if (internal.length > 0) lines.push('');
         lines.push('EXTERNAL:');
         for (const imp of external) {
-            lines.push(`  ${imp.module}${imp.deferred ? ' [function-local/deferred]' : ''}`);
+            lines.push(`  ${imp.module}${deferredImportLabel(imp)}`);
             if (imp.names && imp.names.length > 0) {
                 lines.push(`    ${imp.names.join(', ')}`);
             }
@@ -48,7 +48,7 @@ function formatImports(imports, filePath) {
         if (internal.length > 0 || external.length > 0) lines.push('');
         lines.push('DYNAMIC (unresolved):');
         for (const imp of dynamic) {
-            lines.push(`  ${imp.module || '(variable)'}${imp.deferred ? ' [function-local/deferred]' : ''}`);
+            lines.push(`  ${imp.module || '(variable)'}${deferredImportLabel(imp)}`);
             if (imp.names && imp.names.length > 0) {
                 lines.push(`    ${imp.names.join(', ')}`);
             }
@@ -407,6 +407,22 @@ function formatGraphJson(graph) {
     return JSON.stringify(result, null, 2);
 }
 
+// fix #338: deferred-edge vocabulary shared by deps and cycle output.
+const DEFERRED_REASON_LABELS = {
+    'function-local': 'function-local import',
+    'type-checking': 'TYPE_CHECKING-only import, never executed at runtime',
+    'type-only': 'type-only import, erased at compile time',
+};
+function deferredReasonLabel(reason) {
+    return DEFERRED_REASON_LABELS[reason] || 'deferred import';
+}
+const EAGER_CYCLE_DISPLAY_LIMIT = 25;
+const DEFERRED_CYCLE_DISPLAY_LIMIT = 10;
+function deferredImportLabel(imp) {
+    if (!imp.deferred) return '';
+    return imp.deferredReason ? ` [deferred: ${imp.deferredReason}]` : ' [deferred]';
+}
+
 function formatCircularDeps(result) {
     if (!result) return 'No results.';
     const lines = [];
@@ -420,7 +436,7 @@ function formatCircularDeps(result) {
 
     const scannedCount = result.filesWithImports != null ? result.filesWithImports : result.totalFiles;
 
-    if (result.cycles.length === 0) {
+    if (result.cycles.length === 0 && !(result.components || []).length && !result.summary?.truncated) {
         lines.push('');
         lines.push('No circular dependencies found.');
         lines.push(`Scanned ${scannedCount} files with import relationships.`);
@@ -429,12 +445,32 @@ function formatCircularDeps(result) {
 
     const eager = result.cycles.filter(cycle => cycle.classification !== 'deferred');
     const deferred = result.cycles.filter(cycle => cycle.classification === 'deferred');
+
+    // Groups first: a strongly connected file set is the unit a refactor has
+    // to break, and a 14-file tangle can hold hundreds of elementary cycles.
+    const groups = result.components || [];
+    if (groups.length > 0) {
+        lines.push('');
+        lines.push(`CYCLE GROUPS (${groups.length}) — every member reaches every other member:`);
+        for (const group of groups) {
+            const counts = [];
+            if (group.eagerCycles != null) counts.push(`${group.eagerCycles} import-time`);
+            if (group.deferredCycles != null) counts.push(`${group.deferredCycles} deferred`);
+            const suffix = counts.length > 0 ? `  [${counts.join(', ')}${result.summary.truncated ? '; enumerated counts only' : ''}]` : '';
+            lines.push(`  ${group.size} files: ${group.files.join(', ')}${suffix}`);
+        }
+    }
+
     let cycleNumber = 0;
-    const renderGroup = (title, group, deferredGroup = false) => {
+    const renderGroup = (title, group, deferredGroup, displayLimit) => {
         if (group.length === 0) return;
+        const shown = group.slice(0, displayLimit);
         lines.push('');
-        lines.push(`${title} (${group.length}):`);
-        for (const cycle of group) {
+        const heading = shown.length < group.length
+            ? `${title} (${group.length}, showing ${shown.length} shortest):`
+            : `${title} (${group.length}):`;
+        lines.push(heading);
+        for (const cycle of shown) {
             cycleNumber++;
             lines.push('');
             lines.push(`Cycle ${cycleNumber} (${cycle.length} files):`);
@@ -442,19 +478,32 @@ function formatCircularDeps(result) {
             if (deferredGroup) {
                 for (const edge of cycle.deferredEdges || []) {
                     const at = edge.line != null ? `:${edge.line}` : '';
-                    lines.push(`  deferred edge: ${edge.from}${at} → ${edge.to} (function-local import)`);
+                    const why = (edge.reasons || []).map(deferredReasonLabel).join('; ') || 'function-local import';
+                    lines.push(`  deferred edge: ${edge.from}${at} → ${edge.to} (${why})`);
                 }
             }
         }
+        if (shown.length < group.length) {
+            lines.push(`  ... and ${group.length - shown.length} more (use --json for the full list)`);
+        }
     };
-    renderGroup('IMPORT-TIME CYCLES', eager);
-    renderGroup('DEFERRED CYCLES', deferred, true);
+    renderGroup('IMPORT-TIME CYCLES', eager, false, EAGER_CYCLE_DISPLAY_LIMIT);
+    renderGroup('DEFERRED CYCLES', deferred, true, DEFERRED_CYCLE_DISPLAY_LIMIT);
 
     lines.push('');
     const { totalCycles, filesInCycles } = result.summary;
     lines.push(`Summary: ${totalCycles} circular dependency chain${totalCycles !== 1 ? 's' : ''} involving ${filesInCycles} file${filesInCycles !== 1 ? 's' : ''} (${scannedCount} files with imports scanned).`);
+    if (result.summary.truncated) {
+        if (result.summary.truncationReasons?.includes('component-size')) {
+            lines.push(`Cycle enumeration skipped groups larger than ${result.summary.maxComponentSize} files.`);
+        }
+        if (!result.summary.truncationReasons || result.summary.truncationReasons.includes('cycle-limit')) {
+            lines.push(`Enumeration stopped at ${result.summary.cycleLimit} elementary cycles.`);
+        }
+        lines.push('The CYCLE GROUPS list and files-in-cycles count are complete; enumerated cycle counts are lower bounds.');
+    }
     if (deferred.length > 0) {
-        lines.push(`${deferred.length} chain${deferred.length === 1 ? '' : 's'} contain a function-local import; they are not unconditional import-time cycles, but may still matter if invoked during initialization.`);
+        lines.push(`${deferred.length} chain${deferred.length === 1 ? '' : 's'} close only through deferred edges (function-local, TYPE_CHECKING-only, or type-only imports); they are not unconditional import-time cycles, but a function-local edge may still matter if invoked during initialization.`);
     }
 
     return lines.join('\n');

package/core/output/lines.js

@@ -0,0 +1,272 @@
+/**
+ * core/output/lines.js - grep-shaped and raw output modes (fix #341).
+ *
+ * `--lines`: one `path:line:text` record per line — the `grep -n` shape — so
+ * `ucn` composes with head/cut/xargs and reads like the tool agents already
+ * reach for in a shell. Everything that is not a record (ACCOUNT/CONTRACT
+ * lines, disambiguation, notes) follows the records as `# ` comment lines:
+ * the CLI routes those to stderr, MCP keeps them in its single text block.
+ * Records outside the confirmed tier carry a trailing `\t# tag`, so the
+ * `path:line:` prefix stays parseable while the tier stays visible.
+ *
+ * `--raw` (source): the code text and nothing else — no header, no gutter —
+ * so an agent can extract pristine text for an exact-string edit.
+ */
+'use strict';
+
+const { CALLABLE_SYMBOL_KINDS } = require('../shared');
+const { formatSurfaceMessage } = require('../registry');
+const { formatAccountLines, formatCalleeAccountLine } = require('./analysis');
+
+const LINES_COMMANDS = new Set(['find', 'usages', 'search', 'show', 'impact']);
+
+function record(pathLike, line, text, tag = '') {
+    // One record per line is the contract: a multi-line signature or a
+    // wrapped call expression folds onto one line, and the source line's
+    // indentation is dropped (a locate result needs the text, `--raw` has
+    // the layout).
+    const body = String(text == null ? '' : text).replace(/\s*\n\s*/g, ' ').trim();
+    // Keep unusual filenames from becoming notes or extra physical records.
+    let file = String(pathLike).replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t');
+    if (file.startsWith('# ')) file = './' + file;
+    return `${file}:${line == null ? 0 : line}:${body}${tag ? `\t# ${tag}` : ''}`;
+}
+
+function commentLines(text) {
+    return String(text || '').split(/\r?\n/).filter(Boolean).map(line => `# ${line}`);
+}
+
+function signatureOf(symbol) {
+    const owner = symbol.className ? `${symbol.className}.` : '';
+    const callable = CALLABLE_SYMBOL_KINDS.has(symbol.type) || symbol.params != null;
+    // A multi-line parameter list folds onto one line and drops the trailing
+    // comma the source may carry before its closing paren.
+    const params = String(symbol.params || '').replace(/\s*\n\s*/g, ' ').replace(/,\s*$/, '');
+    return callable ? `${owner}${symbol.name}(${params})` : `${owner}${symbol.name}`;
+}
+
+function pathOf(entry) {
+    return entry.relativePath || entry.file || '';
+}
+
+function unverifiedTag(entry) {
+    const reason = entry.reason || 'unverified';
+    const via = entry.dispatchVia ? ` via ${entry.dispatchVia}` : '';
+    return `unverified: ${reason}${via}`;
+}
+
+function accountComments(account) {
+    if (!account) return [];
+    return [].concat(formatAccountLines(account) || [])
+        .join('\n').split('\n').filter(Boolean).map(line => `# ${line}`);
+}
+
+function findRecords(result) {
+    const out = [];
+    if (Array.isArray(result)) {
+        for (const symbol of result) out.push(record(pathOf(symbol), symbol.startLine, signatureOf(symbol), symbol.type));
+    } else if (result && Array.isArray(result.types)) {
+        for (const type of result.types) {
+            out.push(record(pathOf(type), type.startLine ?? type.line, type.name, type.type || type.kind));
+        }
+    }
+    return { records: out, notes: [] };
+}
+
+function usagesRecords(result) {
+    const out = [];
+    const notes = [];
+    for (const usage of Array.isArray(result) ? result : []) {
+        const kind = usage.isDefinition ? 'definition' : (usage.usageType || 'reference');
+        out.push(record(pathOf(usage), usage.line, usage.content, kind === 'call' ? '' : kind));
+    }
+    const counts = result && result.summaryCounts;
+    if (counts && counts.hiddenTestUsages > 0) {
+        notes.push(`# ${counts.hiddenTestUsages} test-file usage(s) hidden by default (--include-tests)`);
+    }
+    return { records: out, notes };
+}
+
+function searchRecords(result) {
+    const out = [];
+    const notes = [];
+    // Structural search (--type=...) returns { meta, results: [{file, line,
+    // name, kind, receiver, params?}] }; text search returns file groups.
+    if (result && !Array.isArray(result) && Array.isArray(result.results)) {
+        for (const item of result.results) {
+            const text = item.params != null ? `${item.name}(${item.params})` : item.name;
+            out.push(record(item.file, item.line, text, item.kind || item.type));
+        }
+        const meta = result.meta;
+        if (meta && meta.totalMatched > meta.shown) {
+            notes.push(`# ${meta.totalMatched - meta.shown} more match(es) (--limit=N / --all)`);
+        }
+        return { records: out, notes };
+    }
+    for (const item of Array.isArray(result) ? result : []) {
+        if (Array.isArray(item.matches)) {
+            for (const match of item.matches) out.push(record(item.file, match.line, match.content));
+        } else if (item.file != null && item.line != null) {
+            const text = item.content != null ? item.content : signatureOf(item);
+            out.push(record(pathOf(item), item.line, text, item.type || item.kind));
+        }
+    }
+    const meta = result && result.meta;
+    if (meta && meta.filesSkipped > 0) {
+        notes.push(`# ${meta.filesSkipped} test file(s) hidden by default (--include-tests)`);
+    }
+    if (meta && meta.truncatedMatches > 0) {
+        notes.push(`# ${meta.truncatedMatches} more match(es) omitted by --top/--limit`);
+    }
+    return { records: out, notes };
+}
+
+function callerRecords(context) {
+    const out = [];
+    for (const caller of context.callers || []) {
+        const tag = caller.tier && caller.tier !== 'confirmed' ? unverifiedTag(caller) : '';
+        out.push(record(pathOf(caller), caller.line, caller.content, tag));
+    }
+    for (const caller of context.unverifiedCallers || []) {
+        out.push(record(pathOf(caller), caller.line, caller.content, unverifiedTag(caller)));
+    }
+    return out;
+}
+
+function showRecords(result, params = {}) {
+    const out = [];
+    const notes = [];
+    const context = result && result.context;
+    // Only an EXPLICIT --sections selects the band: the resolved defaults
+    // (summary, callers, callees) would mix callee records into a caller
+    // listing and skew `cut -d: -f1 | sort | uniq -c`.
+    const explicit = (Array.isArray(params.sections) ? params.sections : String(params.sections || '').split(','))
+        .map(s => String(s).trim().toLowerCase()).filter(Boolean);
+    const selected = new Set(explicit.length > 0 ? explicit : ['callers']);
+    if (context) {
+        if (selected.has('callers')) out.push(...callerRecords(context));
+        if (selected.has('callees')) {
+            for (const callee of context.callees || []) {
+                const count = callee.callCount > 1 ? ` x${callee.callCount}` : '';
+                out.push(record(pathOf(callee), callee.startLine, signatureOf(callee), `callee${count}`));
+            }
+            for (const callee of context.unverifiedCallees || []) {
+                for (const site of callee.sites || []) {
+                    out.push(record(pathOf(context), site, callee.name, `${unverifiedTag(callee)}; callee`));
+                }
+            }
+        }
+        notes.push(...accountComments(context.meta && context.meta.account));
+        if (context.meta && context.meta.calleeAccount && selected.has('callees')) {
+            notes.push(`# ${formatCalleeAccountLine(context.meta.calleeAccount)}`);
+        }
+    }
+    if (result && result.target && result.target.alternatives && result.target.alternatives.length > 0) {
+        notes.push(`# ${result.target.alternatives.length + 1} definitions; using ${result.target.handle || result.target.file}. Pass a file:line:name handle to pin another.`);
+    }
+    return { records: out, notes };
+}
+
+function impactRecords(result) {
+    const out = [];
+    const notes = [];
+    if (!result) return { records: out, notes };
+    if (Array.isArray(result.functions)) {
+        for (const fn of result.functions) {
+            out.push(...callerRecords(fn));
+            notes.push(...accountComments(fn.account));
+        }
+        for (const fn of result.deletedFunctions || []) {
+            for (const site of fn.remainingCallSites || []) {
+                out.push(record(pathOf(site), site.line, site.content, 'unverified: deleted-target-name-match'));
+            }
+        }
+        const summary = result.summary || {};
+        notes.push(`# Diff: ${summary.modifiedFunctions || 0} modified, ${summary.newFunctions || 0} new, ${summary.deletedFunctions || 0} deleted functions; ${(result.moduleLevelChanges || []).length} file(s) with module-level changes.`);
+        if (result.nonSourcePaths) notes.push(`# ${result.nonSourcePaths} changed path(s) outside supported source files not analyzed.`);
+        if (result.untrackedPaths) notes.push(`# ${result.untrackedPaths} untracked source file(s) included as whole-file additions.`);
+        return { records: [...new Set(out)], notes };
+    }
+    for (const group of result.byFile || []) {
+        for (const site of group.sites || []) {
+            const tag = site.tier && site.tier !== 'confirmed' ? unverifiedTag(site) : '';
+            out.push(record(group.file, site.line, site.expression, tag));
+        }
+    }
+    for (const site of result.unverifiedSites || []) {
+        out.push(record(pathOf(site), site.line, site.content || site.expression, unverifiedTag(site)));
+    }
+    if (result.propertyAccesses) {
+        const accesses = result.propertyAccesses;
+        for (const group of accesses.byFile || []) {
+            for (const access of group.sites || []) {
+                out.push(record(group.file, access.line, access.expression, 'property-access'));
+            }
+        }
+        for (const access of accesses.unverifiedSites || []) {
+            out.push(record(pathOf(access), access.line, access.expression, `${unverifiedTag(access)}; property-access`));
+        }
+        notes.push(`# PROPERTY ACCESS SITES: ${accesses.confirmedCount} confirmed, ${accesses.unverifiedCount} unverified, ${accesses.excluded?.total || 0} other-target (separate from caller ACCOUNT).`);
+    }
+    if (result.typeReferences) {
+        const refs = result.typeReferences;
+        for (const group of refs.byFile || []) {
+            for (const site of group.sites || []) {
+                out.push(record(group.file, site.line, site.expression, 'type-reference'));
+            }
+        }
+        for (const site of refs.unverifiedSites || []) {
+            out.push(record(pathOf(site), site.line, site.expression, `unverified: ${site.reason}; type-reference`));
+        }
+        notes.push(`# TYPE REFERENCE SITES: ${refs.confirmedCount} confirmed, ${refs.unverifiedCount} unverified, ${refs.excluded?.total || 0} other-target (separate from caller ACCOUNT).`);
+    }
+    notes.push(...accountComments(result.account));
+    for (const warning of result.warnings || []) notes.push(...commentLines(warning.message));
+    if (result.scopeWarning?.hint) notes.push(...commentLines(result.scopeWarning.hint));
+    if (result.shownCallSites < result.totalCallSites) {
+        notes.push(`# ${result.totalCallSites - result.shownCallSites} more call site(s) omitted by --top/--limit`);
+    }
+    return { records: out, notes };
+}
+
+/**
+ * Render a public command result as grep-shaped records followed by `# `
+ * comment lines. Returns '' when the command has nothing to list.
+ */
+function formatPublicLines(command, result, params = {}, execution = {}) {
+    let shaped;
+    switch (command) {
+        case 'find': shaped = findRecords(result); break;
+        case 'usages': shaped = usagesRecords(result); break;
+        case 'search': shaped = searchRecords(result); break;
+        case 'show': shaped = showRecords(result, params); break;
+        case 'impact': shaped = impactRecords(result); break;
+        default: return null;
+    }
+    const lines = [...shaped.records, ...shaped.notes];
+    if (execution.note) lines.push(...commentLines(execution.note));
+    return lines.map(line => line.startsWith('# ')
+        ? commentLines(formatSurfaceMessage(line.slice(2), execution.surface)).join('\n') : line).join('\n');
+}
+
+/**
+ * Render a `source` result as the code text alone.
+ */
+function formatPublicRaw(result, execution = {}) {
+    let code = '';
+    if (result && Array.isArray(result.lines)) code = result.lines.join('\n');
+    else if (result && Array.isArray(result.entries)) {
+        code = result.entries.map(entry => entry.code == null ? '' : String(entry.code)).join('\n\n');
+    } else if (result && typeof result.code === 'string') code = result.code;
+    // A note (the same-name disambiguation, a hidden-section warning) must
+    // not vanish in raw mode. Code lines are never reinterpreted, so it
+    // cannot ride inside the text: the CLI prints `execution.note` to stderr
+    // itself (see emitCliText); the single-block surfaces get it appended as
+    // one trailing `# ` line after the code.
+    if (execution.note && execution.surface !== 'cli') {
+        return `${code.replace(/\n$/, '')}\n${commentLines(execution.note).join('\n')}`;
+    }
+    return code;
+}
+
+module.exports = { LINES_COMMANDS, formatPublicLines, formatPublicRaw, commentLines };

package/core/output/public.js

@@ -11,6 +11,7 @@
 const { COMMAND_CONTRACTS } = require('../command-contracts');
 const { COMMAND_TRUST_MATRIX } = require('../trust-matrix');
 const { toCliName, toMcpName, formatSurfaceMessage } = require('../registry');
+const { LINES_COMMANDS, formatPublicLines, formatPublicRaw } = require('./lines');
 
 const legacy = {
     ...require('./analysis'),
@@ -274,6 +275,20 @@ function formatRepo(result, params = {}, hints = presentationHints()) {
 }
 
 function formatPublicText(command, result, params = {}, execution = {}) {
+    // Grep-shaped and raw modes (fix #341): the agent-in-a-shell surface.
+    if (params.raw && command === 'source') {
+        return formatPublicRaw(result, {
+            ...execution,
+            note: execution.note ? formatSurfaceMessage(execution.note, execution.surface) : undefined,
+        });
+    }
+    if (params.lines && LINES_COMMANDS.has(command)) {
+        const shaped = formatPublicLines(command, result, params, {
+            ...execution,
+            note: execution.note ? formatSurfaceMessage(execution.note, execution.surface) : undefined,
+        });
+        if (shaped != null) return shaped;
+    }
     const hints = presentationHints(execution.surface);
     if (result?.scopeWarning?.hint) {
         result.scopeWarning = {

package/core/output/reporting.js

@@ -1,6 +1,7 @@
 /**
  * core/output/reporting.js - Stats/TOC/deadcode/entrypoints formatters
  */
+const path = require('path');
 
 const {
     lineRange,
@@ -457,7 +458,10 @@ function formatEntrypointsJson(results) {
  */
 function formatOrient(result, options = {}) {
     const lines = [];
-    lines.push(`PROJECT ORIENTATION — ${result.root}${result.scope ? ` (scoped to ${result.scope})` : ''}`);
+    // The title names the project (fix #343); the absolute root is the
+    // caller's own argument and `--sections=stats` prints it in full.
+    const projectName = path.basename(String(result.root || '')) || String(result.root || '');
+    lines.push(`PROJECT ORIENTATION — ${projectName}${result.scope ? ` (scoped to ${result.scope})` : ''}`);
     lines.push('═'.repeat(60));
 
     // Size + language mix (percent by symbols, largest first)
@@ -486,7 +490,10 @@ function formatOrient(result, options = {}) {
         const population = result.hot.totalKind === 'raw-call-candidates'
             ? `${result.hot.total} raw candidates`
             : result.hot.total;
-        lines.push(`HOT (most-called ${scope}, top ${result.hot.items.length} of ${population}):`);
+        const budgetNote = result.hot.budgetExhausted
+            ? `; refinement budget ${result.hot.maxRefine} reached — ranking approximate, exact list: ucn repo --sections=stats --hot`
+            : '';
+        lines.push(`HOT (most-called ${scope}, top ${result.hot.items.length} of ${population}${budgetNote}):`);
         for (const h of result.hot.items) {
             const label = h.className ? `${h.className}.${h.name}` : h.name;
             lines.push(`  ${label} — ${h.callCount} call(s) · ${h.file}:${h.line}`);

package/core/output/tracing.js

@@ -532,6 +532,14 @@ function formatReverseTraceJson(result) {
 /**
  * Format affected-tests command output - text
  */
+// fix #347: a hub symbol at depth 2 links hundreds of names per test file;
+// the list is the answer only for leaves. Cap at 8 unless --all.
+function linkList(names, options) {
+    const MAX_LINKS = options?.all ? Infinity : 8;
+    if (!Array.isArray(names) || names.length <= MAX_LINKS) return (names || []).join(', ');
+    return `${names.slice(0, MAX_LINKS).join(', ')}, +${names.length - MAX_LINKS} more`;
+}
+
 function formatAffectedTests(result, options = {}) {
     if (!result) return 'Function not found.';
 
@@ -553,7 +561,7 @@ function formatAffectedTests(result, options = {}) {
         lines.push(`Test files to run (${summary.totalTestFiles}):`);
         lines.push('');
         for (const tf of displayFiles) {
-            lines.push(`  ${tf.file} (links: ${tf.linkedFunctions.join(', ')})`);
+            lines.push(`  ${tf.file} (links: ${linkList(tf.linkedFunctions, options)})`);
             // Show up to 5 key matches per file
             const keyMatches = tf.matches
                 .filter(m => m.matchType === 'call' || m.matchType === 'test-case')
@@ -581,7 +589,7 @@ function formatAffectedTests(result, options = {}) {
             lines.push(`  Additional test files (${pat.length}):`);
             const MAX_POSSIBLE = options.all ? Infinity : 10;
             for (const tf of pat.slice(0, MAX_POSSIBLE)) {
-                lines.push(`    ${tf.file} (links: ${tf.linkedFunctions.join(', ')})`);
+                lines.push(`    ${tf.file} (links: ${linkList(tf.linkedFunctions, options)})`);
             }
             if (pat.length > MAX_POSSIBLE) {
                 lines.push(`    ... ${pat.length - MAX_POSSIBLE} more (${options.allHint || 'use --all'})`);

package/core/output-budget.js

@@ -33,18 +33,21 @@ function preservedContractMetadata(fullText, visibleText, options = {}) {
         // one physical line. Preserve the actionable test-scope contract as
         // its own sentence so a later parse-failure note cannot make the
         // whole metadata item too large for a small transport budget.
-        const firstSentenceEnd = /^\s*\d+ test-file usage\(s\) hidden\b/.test(rawLine)
+        const firstSentenceEnd = /^\s*(?:# )?\d+ test-file usage\(s\) hidden\b/.test(rawLine)
             ? rawLine.indexOf('. ')
             : -1;
         const contractLine = firstSentenceEnd >= 0
             ? rawLine.slice(0, firstSentenceEnd + 1)
             : rawLine;
-        if (!CONTRACT_LINE_RE.test(contractLine)) continue;
+        // Shell-shaped MCP/interactive results prefix disclosures with '# '.
+        // Match their contents but retain the prefix in the preserved text.
+        const evidenceLine = contractLine.replace(/^\s*# /, '').trim();
+        if (!CONTRACT_LINE_RE.test(evidenceLine)) continue;
         const line = contractLine.trim();
         if (!line || visible.has(line)) continue;
-        const priority = /^(?:ACCOUNT|CONTRACT|WARNING|FILTERED|CALLEE ACCOUNT|TREE ACCOUNT):/.test(line)
+        const priority = /^(?:ACCOUNT|CONTRACT|WARNING|FILTERED|CALLEE ACCOUNT|TREE ACCOUNT):/.test(evidenceLine)
             ? 0
-            : /^\d+ test-file usage\(s\) hidden\b/.test(line) ? 1 : 2;
+            : /^\d+ test-file usage\(s\) hidden\b/.test(evidenceLine) ? 1 : 2;
         candidates.push({ line, priority, sourceIndex });
     }
 

package/core/project.js

@@ -149,6 +149,7 @@ class ProjectIndex {
             this._opCppPathReceiverTypeCache = new Map();
             this._opDerefPairs = undefined;
             this._opAliasPairs = undefined;
+            this._opFindCallersCaches = null; // fix #340: findCallers per-file derivations
             this._opDepth = 0;
         }
         this._opDepth++;
@@ -178,6 +179,7 @@ class ProjectIndex {
             this._opCppPathReceiverTypeCache = null;
             this._opDerefPairs = null;
             this._opAliasPairs = null;
+            this._opFindCallersCaches = null;
             // Free cached file content from callsCache entries (retained during
             // operation for _readFile caching, not needed between operations)
             for (const entry of this.callsCache.values()) {
@@ -1249,7 +1251,7 @@ class ProjectIndex {
         const typeOrder = new Set([
             'class', 'struct', 'interface', 'type', 'impl', 'enum', 'record',
         ]);
-        const { isTestPath } = require('./shared');
+        const { isTestPath, CALLABLE_SYMBOL_KINDS } = require('./shared');
         const scored = definitions.map(d => {
             let score = 0;
             const rp = d.relativePath || '';
@@ -1280,10 +1282,21 @@ class ProjectIndex {
             // Deprioritize type-only overload signatures (TypeScript function_signature)
             if (d.isSignature) score -= 200;
             // Prefer larger function bodies (implementation over overload signature)
-            // Only for functions/methods — not for class-level types (struct vs impl)
+            // Only for functions — not for class-level types (struct vs impl).
+            // Same-named METHODS keep tying here on purpose: widening this to
+            // every callable kind reshuffled method-vs-method picks project-wide
+            // (httpx `send`), which is not the fix #343 defect.
             if (d.startLine && d.endLine && d.type === 'function') {
                 score += Math.min(d.endLine - d.startLine, 100);
             }
+            // Fix #343: a bare name denotes the CALLABLE when a field shares it.
+            // A Rust/Go/Java method used to tie with a same-named field (the
+            // builder idiom: `heap_limit` field + `heap_limit(&mut self)` setter)
+            // and lose on file order, so `impact heap_limit` answered 0 call
+            // sites against the field while the setter had 10 confirmed callers.
+            // Callable kinds tie among themselves as before; only the
+            // callable-vs-field tie is decided (a zero-line Java getter too).
+            if (CALLABLE_SYMBOL_KINDS.has(d.type)) score += 25;
             // Prefer shallower paths (fewer directory levels = more central to project)
             // Max bonus 50 for root-level files, decreasing with depth
             const depth = (rp.match(/\//g) || []).length;