ucn 5.4.1 → 5.4.2

package/cli/index.js

@@ -933,9 +933,9 @@ Common flags:
   --all --compact --no-compact --json --include-tests --class-name=X --line=N
   --range=N-M (source with --file=PATH)
   --base=REF --staged --no-cache --clear-cache [--all] --max-files=N --workers=N
-  --max-chars=N (text output; default 10K targeted / 3K broad, ceiling 100K)
+  --max-chars=N (text characters, not UTF-8 bytes; default 10K targeted / 3K broad, ceiling 100K)
   --lines  find/usages/search/show/impact: grep -n shape, one path:line:text
-           record per output line; usages may repeat a source line per occurrence
+           record per output line; usages combines occurrences on each source line
            (tags after a tab: # unverified: <reason>, # import,
            # callee); accounting and notes go to stderr as "# " lines; exit 1
            when nothing matched; exit 2 on errors. No default result cap.

package/core/output/analysis-ext.js

@@ -204,18 +204,18 @@ function formatDiffImpact(result, options = {}) {
 
     const s = result.summary || {};
     const parts = [];
-    if (s.modifiedFunctions > 0) parts.push(`${s.modifiedFunctions} modified`);
-    if (s.deletedFunctions > 0) parts.push(`${s.deletedFunctions} deleted`);
-    if (s.newFunctions > 0) parts.push(`${s.newFunctions} new`);
-    if (s.modifiedSymbols || s.newSymbols || s.deletedSymbols) {
-        parts.push(`${s.modifiedSymbols || 0} modified, ${s.newSymbols || 0} new, ${s.deletedSymbols || 0} deleted non-callable declarations`);
+    for (const [label, suffix] of [['Functions', 'Functions'], ['Declarations', 'Symbols']]) {
+        const counts = ['modified', 'new', 'deleted']
+            .filter(kind => s[kind + suffix] > 0)
+            .map(kind => `${s[kind + suffix]} ${kind}`);
+        if (counts.length) parts.push(`${label}: ${counts.join(', ')}`);
     }
     parts.push(`${s.totalCallSites || 0} call sites across ${s.affectedFiles || 0} files`);
     if (s.unverifiedCallSites > 0) parts.push(`${s.unverifiedCallSites} unverified`);
     if (s.totalDependencySites || s.unverifiedDependencySites) {
         parts.push(`${s.totalDependencySites || 0} confirmed + ${s.unverifiedDependencySites || 0} unverified non-call dependency sites across ${s.dependencyFiles || 0} files`);
     }
-    lines.push(parts.join(', '));
+    lines.push(parts.join('; '));
     // fix #283: changed paths outside supported source are invisible to the
     // symbol analysis — disclose instead of silently narrowing the diff.
     if (result.nonSourcePaths > 0) {

package/core/output/find.js

@@ -158,10 +158,13 @@ function formatFindDetailed(symbols, query, options = {}) {
         const confStr = confidence.level !== 'high' ? ` [${confidence.level}]` : '';
         const handle = formatSymbolHandle(s);
         const loc = handle || (s.relativePath + ':' + s.startLine);
+        const nameLocation = s.nameLine && s.nameLine !== s.startLine
+            ? `name token at ${s.relativePath || s.file}:${s.nameLine}` : '';
 
         if (compact) {
             // One line per result: "<handle>  <sig>  <usages?>  <doc snippet?>"
             const parts = [`${loc}  ${sig}${confStr}`];
+            if (nameLocation) parts.push(`[${nameLocation}]`);
             if (s.usageCounts !== undefined && s.usageCounts.total > 0) {
                 const scope = sameNameDefinitionCounts.get(s.name) > 1 ? ' name-wide' : '';
                 const label = s.usageCounts.complete === false
@@ -186,6 +189,7 @@ function formatFindDetailed(symbols, query, options = {}) {
         }
 
         lines.push(`${loc}  ${sig}${confStr}`);
+        if (nameLocation) lines.push(`  ${nameLocation} (handle starts at declaration line ${s.startLine})`);
         if (s.docstring) {
             const snip = firstSentenceShort(s.docstring);
             if (snip) lines.push(`  "${snip}"`);

package/core/output/lines.js

@@ -64,14 +64,20 @@ function accountComments(account) {
 
 function findRecords(result) {
     const out = [];
+    const notes = [];
     if (Array.isArray(result)) {
-        for (const symbol of result) out.push(record(pathOf(symbol), symbol.startLine, signatureOf(symbol), symbol.type));
+        for (const symbol of result) {
+            out.push(record(pathOf(symbol), symbol.startLine, signatureOf(symbol), symbol.type));
+            if (symbol.nameLine && symbol.nameLine !== symbol.startLine) {
+                notes.push(`# ${record(pathOf(symbol), symbol.startLine, symbol.name)} starts at the declaration; name token at line ${symbol.nameLine} (usages reports the token line).`);
+            }
+        }
     } 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: [] };
+    return { records: out, notes };
 }
 
 function usagesRecords(result) {

package/core/output-budget.js

@@ -15,7 +15,7 @@ const BROAD_COMMANDS = new Set([
     ...[...BROAD_CANONICAL].map(toMcpName),
 ]);
 
-const CONTRACT_LINE_RE = /^\s*(?:(?:Summary|ACCOUNT|CONTRACT|WARNING|FILTERED|CALLEE ACCOUNT|TREE ACCOUNT):|\d+ test-file usage\(s\) hidden\b|(?:Note:\s*)?Found \d+ (?:definitions|fuzzy matches)\b)/;
+const CONTRACT_LINE_RE = /^\s*(?:(?:Summary|ACCOUNT|CONTRACT|WARNING|FILTERED|CALLEE ACCOUNT|TREE ACCOUNT|Note):|\d+ test-file usage\(s\) hidden\b|Found \d+ (?:definitions|fuzzy matches)\b)/;
 const MAX_PRESERVED_CONTRACT_LINES = 24;
 const MAX_PRESERVED_CONTRACT_CHARS = 8000;
 
@@ -134,23 +134,23 @@ function applyOutputBudget(text, {
     params = {},
     trailingChars = 0,
 } = {}) {
+    const defaultLimit = BROAD_COMMANDS.has(command)
+        ? BROAD_OUTPUT_CHARS
+        : DEFAULT_OUTPUT_CHARS;
+    const requested = maxChars || (all ? MAX_OUTPUT_CHARS : defaultLimit);
+    const hardLimit = Math.min(requested, MAX_OUTPUT_CHARS);
+    const limit = Math.max(0, hardLimit - trailingChars);
     if (!text) {
         return {
-            text: '(no output)',
-            truncated: false,
+            text: '(no output)'.slice(0, limit),
+            truncated: '(no output)'.length > limit,
             fullChars: 0,
-            requestedLimit: maxChars || null,
+            requestedLimit: hardLimit,
             contractMetadata: [],
             contractMetadataComplete: true,
         };
     }
 
-    const defaultLimit = BROAD_COMMANDS.has(command)
-        ? BROAD_OUTPUT_CHARS
-        : DEFAULT_OUTPUT_CHARS;
-    const requested = maxChars || (all ? MAX_OUTPUT_CHARS : defaultLimit);
-    const hardLimit = Math.min(requested, MAX_OUTPUT_CHARS);
-    const limit = Math.max(0, hardLimit - trailingChars);
     if (text.length <= limit) {
         return {
             text,
@@ -196,10 +196,21 @@ function applyOutputBudget(text, {
     // can consume most of the transport. Trust/account lines take precedence
     // over body detail and are appended directly after a compact notice.
     if (compactBudget) {
-        const metadataCapacity = Math.max(0, limit - notice.length - 1);
-        const candidate = preservedContractMetadata(text, '', {
-            maxChars: metadataCapacity,
+        let candidate = preservedContractMetadata(text, '', {
+            maxChars: Math.max(0, limit - notice.length - 1),
         });
+        if (candidate.omitted > 0) {
+            // Spend less on generic guidance when that lets a complete scope
+            // or parameter warning survive even a tiny transport ceiling.
+            const shorterNotice = `... OUTPUT TRUNCATED. Raise ${raiseHint}.`;
+            const shorterCandidate = preservedContractMetadata(text, '', {
+                maxChars: Math.max(0, limit - shorterNotice.length - 1),
+            });
+            if (shorterNotice.length < notice.length && shorterCandidate.lines.length > candidate.lines.length) {
+                notice = shorterNotice;
+                candidate = shorterCandidate;
+            }
+        }
         const candidateText = candidate.lines.join('\n');
         const separatorChars = candidateText ? 2 : 1;
         const bodyBudget = Math.max(0,

package/mcp/server.js

@@ -119,7 +119,7 @@ const server = new StdioMcpServer({
 
 function toolResult(text, command, maxChars, suffixNote, params = {}) {
     const suffix = suffixNote || '';
-    const budget = applyOutputBudget(text, {
+    const budget = applyOutputBudget(text + suffix, {
         command,
         maxChars,
         surface: 'mcp',
@@ -130,7 +130,7 @@ function toolResult(text, command, maxChars, suffixNote, params = {}) {
     // narrowing hints; preserved contract lines follow). A structuredContent
     // side-channel is rendered INSTEAD of content by MCP clients that prefer
     // structured results, which discards the entire answer (fix #284).
-    return { content: [{ type: 'text', text: budget.text + suffix }] };
+    return { content: [{ type: 'text', text: budget.text }] };
 }
 
 function toolError(message) {
@@ -307,7 +307,7 @@ const INPUT_SHAPE = {
     line: integerParam('Definition line pin. Resolves the symbol defined at this exact line (the middle component of a file:line:name handle). Disambiguates same-file same-name definitions.', { exclusiveMinimum: 0, maximum: Number.MAX_SAFE_INTEGER }),
     limit: integerParam('Max results to return (default: 500; structural search: 50; usages and lines: uncapped). Caps find, usages, search, deadcode, api, and repo files. Must be a positive integer.', { exclusiveMinimum: 0, maximum: 1000000 }),
     max_files: integerParam('Max files to index (default: 10000). Use for very large codebases. Must be a positive integer.', { exclusiveMinimum: 0, maximum: 10000000 }),
-    max_chars: integerParam('Max output chars before truncation. Broad sweep commands (repo, entrypoints, endpoints, deadcode, deps, check, audit_async) default to 3K; all other commands default to 10K. Maximum: 100K. all=true lifts formatter caps but keeps the 100K transport ceiling.', { exclusiveMinimum: 0, maximum: 100000 }),
+    max_chars: integerParam('Max output characters, not UTF-8 bytes, including notes and preserved metadata. Broad sweep commands (repo, entrypoints, endpoints, deadcode, deps, check, audit_async) default to 3K; all other commands default to 10K. Maximum: 100K. all=true lifts formatter caps but keeps the 100K transport ceiling.', { exclusiveMinimum: 0, maximum: 100000 }),
     type: stringParam('Symbol type filter for structural search: function, class, call, method, type, state, field, constant, macro. Triggers index-based search.'),
     param: stringParam('Filter by parameter name or type (structural search). E.g. "Request", "ctx".'),
     receiver: stringParam('Filter calls by receiver (structural search, type=call). E.g. "db", "http".'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucn",
-  "version": "5.4.1",
+  "version": "5.4.2",
   "mcpName": "io.github.mleoca/ucn",
   "description": "Auditable AST code intelligence for AI agents: 18 task-oriented commands through one MCP tool, CLI, or agent skill. Supports JS/TS, Python, Go, Rust, Java, C, C++, C#, and HTML.",
   "main": "index.js",