ucn 5.2.2 → 5.3.0

package/core/output/lines.js

@@ -0,0 +1,259 @@
+/**
+ * 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.`);
+        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).`);
+    }
+    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-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;

package/core/registry.js

@@ -133,13 +133,13 @@ const FLAG_APPLICABILITY = {
     // Understand one symbol. `sections` is a comma-separated projection:
     // summary, callers, callees, source, dependencies, tests, types, example,
     // related. Caller-bearing projections always preserve ACCOUNT/CONTRACT.
-    show:         ['name', 'file', 'exclude', 'className', 'line', 'sections', 'includeMethods', 'includeTests', 'top', 'all', 'withTypes', 'minConfidence', 'showConfidence', 'unreachableOnly', 'compact', 'git', 'diverse'],
-    find:         ['name', 'file', 'exclude', 'className', 'includeTests', 'limit', 'exact', 'in', 'compact', 'type', 'withSource'],
-    usages:       ['name', 'file', 'exclude', 'className', 'includeTests', 'limit', 'codeOnly', 'context', 'in', 'compact', 'all'],
-    search:       ['term', 'file', 'exclude', 'includeTests', 'top', 'limit', 'codeOnly', 'caseSensitive', 'context', 'regex', 'in', 'type', 'param', 'receiver', 'returns', 'decorator', 'exported', 'unused'],
-    source:       ['name', 'file', 'className', 'line', 'range', 'all', 'maxLines'],
+    show:         ['name', 'file', 'exclude', 'className', 'line', 'sections', 'includeMethods', 'includeTests', 'top', 'all', 'withTypes', 'minConfidence', 'showConfidence', 'unreachableOnly', 'compact', 'git', 'diverse', 'lines'],
+    find:         ['name', 'file', 'exclude', 'className', 'includeTests', 'limit', 'exact', 'in', 'compact', 'type', 'withSource', 'lines'],
+    usages:       ['name', 'file', 'exclude', 'className', 'includeTests', 'limit', 'codeOnly', 'context', 'in', 'compact', 'all', 'lines'],
+    search:       ['term', 'file', 'exclude', 'includeTests', 'top', 'limit', 'codeOnly', 'caseSensitive', 'context', 'regex', 'in', 'type', 'param', 'receiver', 'returns', 'decorator', 'exported', 'unused', 'lines'],
+    source:       ['name', 'file', 'className', 'line', 'range', 'all', 'maxLines', 'raw'],
     trace:        ['name', 'file', 'exclude', 'className', 'line', 'direction', 'to', 'includeMethods', 'depth', 'all', 'expandUnverified'],
-    impact:       ['name', 'file', 'exclude', 'className', 'line', 'includeMethods', 'top', 'unreachableOnly', 'compact', 'base', 'staged', 'limit', 'all'],
+    impact:       ['name', 'file', 'exclude', 'className', 'line', 'includeMethods', 'top', 'unreachableOnly', 'compact', 'base', 'staged', 'limit', 'all', 'lines'],
     tests:        ['name', 'file', 'exclude', 'className', 'line', 'callsOnly', 'depth', 'includeMethods', 'all'],
     deps:         ['file', 'exclude', 'depth', 'direction', 'all', 'detailed', 'cycles'],
     api:          ['file', 'in', 'limit'],
@@ -308,6 +308,7 @@ function formatSurfaceMessage(message, surface = 'cli') {
         'expandUnverified', 'withSource', 'all', 'compact', 'exact',
         'regex', 'exported', 'unused', 'staged', 'detailed', 'functions',
         'hot', 'deep', 'cycles', 'bridge', 'unmatched', 'diverse', 'git',
+        'raw', 'lines',
     ]);
     if (surface === 'mcp') {
         rendered = rendered.replace(/--([a-z][a-z0-9-]*)(?:=([^\s,.)]+))?/g,