ucn 4.0.2 → 4.1.1

package/core/imports.js

@@ -303,8 +303,21 @@ function findCargoRoot(startDir) {
     while (dir !== path.dirname(dir)) {
         const cargoPath = path.join(dir, 'Cargo.toml');
         if (fs.existsSync(cargoPath)) {
+            // Flat-layout crates (lib.rs/main.rs next to Cargo.toml, no src/)
+            // root their module tree at the Cargo.toml directory — requiring
+            // src/ left every crate:: path in such crates unresolved.
             const srcDir = path.join(dir, 'src');
-            const result = fs.existsSync(srcDir) ? { root: dir, srcDir } : null;
+            // The [package] name is the crate's import identity for its OWN
+            // integration tests/benches/examples (`use mypkg::...` in
+            // tests/*.rs — fix #246); `-` normalizes to `_` in code.
+            let packageName = null;
+            try {
+                const toml = fs.readFileSync(cargoPath, 'utf-8');
+                const pkgSection = toml.split(/^\s*\[/m).find(s => s.startsWith('package]'));
+                const m = pkgSection && pkgSection.match(/^\s*name\s*=\s*"([^"]+)"/m);
+                if (m) packageName = m[1].replace(/-/g, '_');
+            } catch { /* unreadable Cargo.toml — no package identity */ }
+            const result = { root: dir, srcDir: fs.existsSync(srcDir) ? srcDir : dir, packageName };
             cargoCache.set(startDir, result);
             return result;
         }
@@ -315,6 +328,31 @@ function findCargoRoot(startDir) {
     return null;
 }
 
+/**
+ * Resolve the FILE that owns the module rooted at `dir`: dir/mod.rs (2015
+ * layout), <dir>.rs (2018 layout — the module file sits beside its directory),
+ * or the crate root lib.rs/main.rs. Used when a use-path names an ITEM
+ * declared directly in that module file (e.g. `use super::CONFIG`) — there is
+ * no <item>.rs to find, the import points at the module file itself.
+ * @param {string} dir - Module directory
+ * @param {string} [fromFile] - Importing file, never returned as its own target
+ * @returns {string|null}
+ */
+function rustModuleOwnFile(dir, fromFile) {
+    const candidates = [
+        path.join(dir, 'mod.rs'),
+        dir + '.rs',
+        path.join(dir, 'lib.rs'),
+        path.join(dir, 'main.rs'),
+    ];
+    for (const c of candidates) {
+        if (c !== fromFile && fs.existsSync(c) && fs.statSync(c).isFile()) {
+            return c;
+        }
+    }
+    return null;
+}
+
 /**
  * Try to resolve a Rust module path to a file
  * Checks both <path>.rs and <path>/mod.rs
@@ -358,7 +396,34 @@ function resolveRustImport(importPath, fromFile, projectRoot) {
 
         const rest = importPath.slice('crate::'.length);
         const segments = rest.split('::');
-        return resolveRustModulePath(cargo.srcDir, segments);
+        // `use crate::ITEM` where ITEM is declared in the crate root file has
+        // no ITEM.rs — the import points at lib.rs/main.rs itself.
+        return resolveRustModulePath(cargo.srcDir, segments) ||
+            rustModuleOwnFile(cargo.srcDir, fromFile);
+    }
+
+    // Own-package-name paths (fix #246): integration tests, benches, and
+    // examples are separate crates that import the lib target by its Cargo
+    // [package] name — `use mypkg::helper;` in tests/*.rs is the crate under
+    // test, resolved exactly like crate:: into the package's source tree.
+    // Only fires for files OUTSIDE the package's own module tree (inside
+    // src/, a path starting with the package name is a 2015-edition CHILD
+    // module, never the crate itself). Cross-crate workspace imports keep
+    // their own package names and never match this file's Cargo.toml.
+    {
+        const firstSeg = importPath.split('::')[0].replace(/-/g, '_');
+        const cargo = findCargoRoot(fromDir);
+        if (cargo && cargo.packageName && firstSeg === cargo.packageName) {
+            const topDir = path.relative(cargo.root, fromFile).split(path.sep)[0];
+            const externalTarget = topDir === 'tests' || topDir === 'benches' || topDir === 'examples' ||
+                !fromFile.startsWith(cargo.srcDir + path.sep);
+            if (externalTarget) {
+                const restSegs = importPath.split('::').slice(1);
+                const resolved = restSegs.length > 0 ? resolveRustModulePath(cargo.srcDir, restSegs) : null;
+                const fallback = resolved || rustModuleOwnFile(cargo.srcDir, fromFile);
+                if (fallback) return fallback;
+            }
+        }
     }
 
     // super:: paths - resolve relative to parent module
@@ -380,7 +445,11 @@ function resolveRustImport(importPath, fromFile, projectRoot) {
             dir = path.dirname(dir);
         }
         const segments = rest.split('::');
-        return resolveRustModulePath(dir, segments);
+        // `use super::ITEM` where ITEM is declared in the parent module FILE
+        // (mod.rs / <dir>.rs / crate root) — or in an inline `mod {}` there —
+        // has no ITEM.rs to find; the import points at the parent file itself.
+        return resolveRustModulePath(dir, segments) ||
+            rustModuleOwnFile(dir, fromFile);
     }
 
     // self:: paths - resolve within current module directory

package/core/output/analysis-ext.js

@@ -2,7 +2,8 @@
  * core/output/analysis-ext.js - Extended analysis formatters (related, smart, diffImpact)
  */
 
-const { dynamicImportsNote, formatLineRanges } = require('./shared');
+const { dynamicImportsNote, formatLineRanges, unverifiedReasonLabel, advisoryLine } = require('./shared');
+const { formatAccountLines, formatCalleeAccountLine, unverifiedCalleeLines } = require('./analysis');
 
 /**
  * Format related command output - text
@@ -18,20 +19,25 @@ function formatRelated(related, options = {}) {
     lines.push(`Related to ${related.target.name}`);
     lines.push('═'.repeat(60));
     lines.push(`${related.target.file}:${related.target.line}`);
+    const relAdvisory = advisoryLine(related.advisory);
+    if (relAdvisory) lines.push(relAdvisory);
     lines.push('');
 
-    // Same file
+    // Same file (result is already capped by --top at the source; total in
+    // sameFileTotal — fix #230)
     let relatedTruncated = false;
     if (related.sameFile.length > 0) {
         const maxSameFile = options.top || (options.all ? Infinity : 8);
-        lines.push(`SAME FILE (${related.sameFile.length}):`);
+        const sameFileTotal = related.sameFileTotal || related.sameFile.length;
+        lines.push(`SAME FILE (${sameFileTotal}):`);
         for (const f of related.sameFile.slice(0, maxSameFile)) {
             const params = f.params ? `(${f.params})` : '';
             lines.push(`  :${f.line} ${f.name}${params}`);
         }
-        if (related.sameFile.length > maxSameFile) {
+        const shown = Math.min(related.sameFile.length, maxSameFile);
+        if (sameFileTotal > shown) {
             relatedTruncated = true;
-            lines.push(`  ... and ${related.sameFile.length - maxSameFile} more`);
+            lines.push(`  ... and ${sameFileTotal - shown} more`);
         }
         lines.push('');
     }
@@ -103,7 +109,9 @@ function formatSmart(smart, options = {}) {
     if (!smart) return 'Function not found.';
 
     const lines = [];
-    lines.push(`${smart.target.name} (${smart.target.file}:${smart.target.startLine})`);
+    // Project-relative path in the header, like every other command (fix #230
+    // — the absolute def.file leaked here).
+    lines.push(`${smart.target.name} (${smart.target.relativePath || smart.target.file}:${smart.target.startLine})`);
     lines.push('═'.repeat(60));
 
     if (smart.meta) {
@@ -135,6 +143,12 @@ function formatSmart(smart, options = {}) {
         }
     }
 
+    // v4 callee contract: unresolved calls inside the target — visible with
+    // reasons (they may be dependencies smart could not inline).
+    lines.push(...unverifiedCalleeLines(smart.unverifiedCallees, false));
+    const smartCalleeAcct = formatCalleeAccountLine(smart.meta && smart.meta.calleeAccount);
+    if (smartCalleeAcct) lines.push(`\n${smartCalleeAcct}`);
+
     return lines.join('\n');
 }
 
@@ -168,7 +182,10 @@ function formatSmartJson(result) {
                 callCount: d.callCount,
                 code: d.code
             })),
-            types: result.types || []
+            types: result.types || [],
+            // v4 callee contract: visible unresolved-call entries, reconciled
+            // by meta.calleeAccount.
+            unverifiedCallees: result.unverifiedCallees || []
         }
     });
 }
@@ -191,6 +208,7 @@ function formatDiffImpact(result, options = {}) {
     if (s.deletedFunctions > 0) parts.push(`${s.deletedFunctions} deleted`);
     if (s.newFunctions > 0) parts.push(`${s.newFunctions} new`);
     parts.push(`${s.totalCallSites || 0} call sites across ${s.affectedFiles || 0} files`);
+    if (s.unverifiedCallSites > 0) parts.push(`${s.unverifiedCallSites} unverified`);
     lines.push(parts.join(', '));
     lines.push('');
 
@@ -221,7 +239,28 @@ function formatDiffImpact(result, options = {}) {
                     lines.push(`    ... ${truncated} more callers (use file= to scope diff to specific files, or use impact with class_name= for type-filtered results)`);
                 }
             } else {
-                lines.push('  Callers: none found');
+                lines.push('  Callers: none confirmed');
+            }
+
+            // Unverified tier: visible one-liners with reasons (never silently dropped)
+            const unverified = fn.unverifiedCallers || [];
+            if (unverified.length > 0) {
+                const cap = options.all ? Infinity : 10;
+                lines.push(`  Unverified call sites (${unverified.length}) — call syntax, no binding/receiver evidence:`);
+                for (const u of unverified.slice(0, cap)) {
+                    const caller = u.callerName ? ` [${u.callerName}]` : '';
+                    const reason = u.reason ? ` (${unverifiedReasonLabel(u)})` : '';
+                    const expr = u.content ? `: ${u.content.replace(/\s+/g, ' ').slice(0, 100)}` : '';
+                    lines.push(`    ${u.relativePath}:${u.line}${caller}${expr}${reason}`);
+                }
+                if (unverified.length > cap) {
+                    lines.push(`    (+${unverified.length - cap} more unverified)`);
+                }
+            }
+
+            // Conservation contract lines, indented inside the function block
+            for (const al of formatAccountLines(fn.account)) {
+                lines.push(`  ${al}`);
             }
         }
     }
@@ -235,11 +274,22 @@ function formatDiffImpact(result, options = {}) {
         }
     }
 
-    // Deleted functions
+    // Deleted functions — with any call sites that still reference the name
+    // (likely breaks; name-level candidates, the definition is gone)
     if (result.deletedFunctions.length > 0) {
         lines.push('\nDELETED FUNCTIONS:');
         for (const fn of result.deletedFunctions) {
             lines.push(`  ${fn.name} — ${fn.relativePath}:${fn.startLine}`);
+            const remaining = fn.remainingCallSites || [];
+            if (remaining.length > 0) {
+                lines.push(`  ⚠ still called from ${remaining.length} site(s) — name-level matches:`);
+                for (const site of remaining.slice(0, 10)) {
+                    lines.push(`    ${site.relativePath}:${site.line}  ${site.content}`);
+                }
+                if (remaining.length > 10) {
+                    lines.push(`    ... and ${remaining.length - 10} more`);
+                }
+            }
         }
     }
 
@@ -258,7 +308,17 @@ function formatDiffImpact(result, options = {}) {
 }
 
 function formatDiffImpactJson(result) {
-    return JSON.stringify(result, null, 2);
+    // Standard {meta, data} envelope (fix #230 — diff-impact was one of
+    // three commands still emitting a bare result object). Per-symbol
+    // accounts stay on each entry inside data; meta carries the aggregate
+    // completeness signal.
+    return JSON.stringify({
+        meta: {
+            complete: (result?.summary?.unverifiedCallSites || 0) === 0,
+            unverified: result?.summary?.unverifiedCallSites || 0,
+        },
+        data: result,
+    }, null, 2);
 }
 
 module.exports = {

package/core/output/analysis.js

@@ -19,30 +19,6 @@ function calleeDocstringSnippet(text) {
     return s;
 }
 
-/**
- * Render a single-line confidence histogram for caller/callee sections.
- * Returns null when there are <= 1 edges (not informative).
- *
- * @param {{high:number, medium:number, low:number, total:number}|null} h
- * @returns {string|null}
- */
-function formatHistogramLine(h) {
-    if (!h || h.total <= 1) return null;
-    return `  confidence: ${h.high} high (>0.8), ${h.medium} medium (0.5-0.8), ${h.low} low (<0.5)`;
-}
-
-/**
- * Decide whether the formatter should print reachability markers per item.
- * To reduce noise, markers only appear when at least one item is unreachable.
- *
- * @param {Array} items - Caller or callee objects with `reachable` field
- * @returns {boolean}
- */
-function shouldShowReachability(items) {
-    if (!items || items.length === 0) return false;
-    return items.some(c => c.reachable === false);
-}
-
 /**
  * Reachability display policy for a section: per-line [unreachable] markers
  * ONLY when reachability is mixed (they distinguish which); when ALL items are
@@ -137,6 +113,36 @@ function formatAccountLines(account) {
     return lines;
 }
 
+/**
+ * Single-node CALLEE ACCOUNT line (context/smart — the per-def callee
+ * contract from #223). Matches the tree rollup's arithmetic phrasing.
+ */
+function formatCalleeAccountLine(acct) {
+    if (!acct) return null;
+    let line = `CALLEE ACCOUNT: ${acct.totalSites} call site${acct.totalSites === 1 ? '' : 's'} = ` +
+        `${acct.confirmed} confirmed + ${acct.unverified} unverified + ` +
+        `${acct.external.count} external/builtin + ${acct.excluded.total} excluded`;
+    if (acct.filtered.count > 0) line += ` + ${acct.filtered.count} filtered`;
+    if (!acct.conserved) line += ` — ${acct.unaccounted} UNACCOUNTED`;
+    return line;
+}
+
+/**
+ * Render unverified callee entries (aggregated name+reason from findCallees
+ * collectAccount) as one-liners. Returns [] when the band is empty.
+ */
+function unverifiedCalleeLines(entries, compact) {
+    if (!entries || entries.length === 0) return [];
+    const lines = [];
+    lines.push(`${compact ? '' : '\n'}CALLEES — UNVERIFIED (${entries.length}) — call syntax, receiver/binding unresolved:`);
+    for (const u of entries) {
+        const owners = u.ownerCount > 1 ? ` (${u.ownerCount} owners)` : '';
+        const sites = u.sites && u.sites.length > 0 ? ` L${u.sites.join(',L')}` : '';
+        lines.push(`  ${u.name} ×${u.callCount} — ${u.reason}${owners}${sites}`);
+    }
+    return lines;
+}
+
 /** "NON-CALL OCCURRENCES" summary line from the account. */
 function formatNonCallLine(account, hintName) {
     if (!account || !account.nonCall || account.nonCall.total === 0) return null;
@@ -244,8 +250,14 @@ function formatContextJson(context) {
                 params: c.params,  // FULL params
                 weight: c.weight || 'normal',  // Dependency weight: core, setup, utility
                 ...(c.confidence != null && { confidence: c.confidence, resolution: c.resolution }),
+                ...(c.tier && { tier: c.tier }),
+                ...(c.sites && { sites: c.sites }),
+                ...(c.functionReference && { functionReference: true }),
                 ...(c.reachable !== undefined && { reachable: c.reachable }),
             })),
+            // v4 callee contract: visible unresolved-call entries (aggregated
+            // name+reason), reconciled by meta.calleeAccount.
+            unverifiedCallees: context.unverifiedCallees || [],
             ...(context.warnings && { warnings: context.warnings })
         }
     });
@@ -388,7 +400,7 @@ function formatContext(ctx, options = {}) {
         ? `CALLERS — CONFIRMED (${callers.length}, ${prodCallers.length} prod + ${testCallers.length} test):`
         : `CALLERS — CONFIRMED (${callers.length}):`;
     lines.push(`${compact ? '' : '\n'}${tierHeader}`);
-    const callerEvidence = formatEvidenceLine(callers);
+    const callerEvidence = options.showConfidence !== false ? formatEvidenceLine(callers) : null;
     if (callerEvidence && !compact) lines.push(callerEvidence);
     const callerReach = reachabilityDisplay(callers, hasEntrypoints, 'caller');
     const renderCaller = (c) => {
@@ -420,11 +432,9 @@ function formatContext(ctx, options = {}) {
     }
     if (callerReach.note && !compact) lines.push(callerReach.note);
 
-    // Structural hint: class methods may have callers through constructed/injected instances
-    // that static analysis can't track. Only show when caller count is low (≤3) to avoid noise.
-    if (ctx.meta && (ctx.meta.isMethod || ctx.meta.className || ctx.meta.receiver) && callers.length <= 3) {
-        lines.push(`  Note: ${ctx.function} is a class/struct method — additional callers through constructed or injected instances are not tracked by static analysis.`);
-    }
+    // No hedge note here: under the tiered contract, instance-dispatch caller
+    // candidates ARE analyzed — they render in the unverified band with
+    // reasons, and the ACCOUNT line reconciles every text occurrence.
 
     // UNVERIFIED tier: call-syntax matches without binding/receiver evidence.
     // Always visible (the contract: never silently hide an occurrence), capped
@@ -459,7 +469,7 @@ function formatContext(ctx, options = {}) {
 
     const callees = ctx.callees || [];
     lines.push(`${compact ? '' : '\n'}CALLEES (${callees.length}):`);
-    const calleeEvidence = formatEvidenceLine(callees);
+    const calleeEvidence = options.showConfidence !== false ? formatEvidenceLine(callees) : null;
     if (calleeEvidence && !compact) lines.push(calleeEvidence);
     const calleeReach = reachabilityDisplay(callees, hasEntrypoints, 'callee');
     for (const c of callees) {
@@ -490,6 +500,10 @@ function formatContext(ctx, options = {}) {
     }
     if (calleeReach.note && !compact) lines.push(calleeReach.note);
 
+    // Unverified callee band (v4): aggregated name+reason entries — visible,
+    // never silently dropped. Not expandable (no definition resolved).
+    lines.push(...unverifiedCalleeLines(ctx.unverifiedCallees, compact));
+
     // Conservation contract lines: non-call summary + ACCOUNT/WARNING/FILTERED
     const account = ctx.meta && ctx.meta.account;
     if (account) {
@@ -501,6 +515,8 @@ function formatContext(ctx, options = {}) {
             lines.push(...accountLines);
         }
     }
+    const ctxCalleeAcct = formatCalleeAccountLine(ctx.meta && ctx.meta.calleeAccount);
+    if (ctxCalleeAcct) lines.push(ctxCalleeAcct);
 
     if (expandable.length > 0) {
         lines.push(`\n${expandHint}`);
@@ -717,7 +733,7 @@ function formatAbout(about, options = {}) {
         } else {
             lines.push(`CALLERS — CONFIRMED (${about.callers.total}${testTop.length > 0 ? `, ${prodTop.length} prod + ${testTop.length} test` : ''}):`);
         }
-        const callerEvidence = formatEvidenceLine(top);
+        const callerEvidence = options.showConfidence !== false ? formatEvidenceLine(top) : null;
         if (callerEvidence) lines.push(callerEvidence);
         const aboutCallerReach = reachabilityDisplay(top, hasEntrypoints, 'caller');
         const renderAboutCaller = (c) => {
@@ -774,7 +790,7 @@ function formatAbout(about, options = {}) {
         } else {
             lines.push(`CALLEES (${about.callees.total}):`);
         }
-        const calleeEvidence = formatEvidenceLine(about.callees.top);
+        const calleeEvidence = options.showConfidence !== false ? formatEvidenceLine(about.callees.top) : null;
         if (calleeEvidence) lines.push(calleeEvidence);
         const aboutCalleeReach = reachabilityDisplay(about.callees.top, hasEntrypoints, 'callee');
         for (const c of about.callees.top) {
@@ -897,4 +913,7 @@ module.exports = {
     // Shared with output/tracing.js: the tree commands render the same
     // root-hop ACCOUNT/WARNING/FILTERED lines as context/impact.
     formatAccountLines,
+    // Shared with output/analysis-ext.js (smart): single-node callee contract.
+    formatCalleeAccountLine,
+    unverifiedCalleeLines,
 };

package/core/output/check.js

@@ -30,7 +30,10 @@ function formatCheck(result) {
             if (it.signatureMismatches > 0) tags.push(`SIG-DRIFT(${it.signatureMismatches})`);
             if (it.orphan) tags.push('ORPHAN');
             const tagStr = tags.length ? ' [' + tags.join(', ') + ']' : '';
-            const callers = it.callerCount != null ? `${it.callerCount} caller${it.callerCount === 1 ? '' : 's'}` : '';
+            let callers = it.callerCount != null ? `${it.callerCount} caller${it.callerCount === 1 ? '' : 's'}` : '';
+            if (it.unverifiedCallerCount > 0) {
+                callers += ` (+${it.unverifiedCallerCount} unverified)`;
+            }
             lines.push(`  ${it.name} (${it.file}:${it.line})${tagStr}  ${callers}`);
             if (it.mismatches && it.mismatches.length > 0) {
                 for (const m of it.mismatches.slice(0, 3)) {

package/core/output/endpoints.js

@@ -12,6 +12,9 @@
 
 'use strict';
 
+const { advisoryLine } = require('./shared');
+const { codeUnitCompare } = require('../shared');
+
 const SEP_TIER = { exact: 'EXACT', partial: 'PARTIAL', uncertain: 'UNCERTAIN' };
 
 function pad(s, n) {
@@ -27,7 +30,7 @@ function formatEndpoints(result, options = {}) {
     if (!showBridge) {
         return formatRoutesAndRequests(routes, requests, meta, options);
     }
-    return formatBridges(bridges, unmatchedRoutes, unmatchedRequests, meta, options);
+    return formatBridges(bridges, unmatchedRoutes, unmatchedRequests, meta, options, result.advisory);
 }
 
 /**
@@ -111,13 +114,15 @@ function formatRoutesAndRequests(routes, requests, meta, options) {
     return lines.join('\n').trimEnd();
 }
 
-function formatBridges(bridges, unmatchedRoutes, unmatchedRequests, meta, options = {}) {
+function formatBridges(bridges, unmatchedRoutes, unmatchedRequests, meta, options = {}, advisory = null) {
     const lines = [];
     const matched = bridges.length;
     const unmatchedOnly = !!options.unmatched;
 
     lines.push(`Endpoint Bridges`);
     lines.push(`================`);
+    const brAdvisory = advisoryLine(advisory);
+    if (brAdvisory) lines.push(brAdvisory);
     lines.push(`Server routes: ${meta.totalRoutes}    Client requests: ${meta.totalRequests}`);
     // HIGH-3: percentage = unique matched client requests / total client
     // requests. Counting bridges directly inflates >100% on many-to-many
@@ -138,7 +143,7 @@ function formatBridges(bridges, unmatchedRoutes, unmatchedRequests, meta, option
         }
         // Sort routes alphabetically
         const sorted = [...byRoute.values()].sort((a, b) => {
-            if (a.route.file !== b.route.file) return a.route.file.localeCompare(b.route.file);
+            if (a.route.file !== b.route.file) return codeUnitCompare(a.route.file, b.route.file);
             return a.route.line - b.route.line;
         });
 

package/core/output/extraction.js

@@ -15,7 +15,13 @@ const {
 function formatFn(match, fnCode) {
     const lines = [];
     lines.push(`${match.relativePath}:${match.startLine}`);
-    lines.push(`${lineRange(match.startLine, match.endLine)} ${formatFunctionSignature(match)}`);
+    // Class attribution: three same-name `clear` methods under --all were
+    // indistinguishable without their owning class (fix #248).
+    const sig = formatFunctionSignature(match);
+    const attributed = match.className && !sig.includes(`${match.className}.`)
+        ? `${match.className}.${sig}`
+        : sig;
+    lines.push(`${lineRange(match.startLine, match.endLine)} ${attributed}`);
     lines.push('─'.repeat(60));
     lines.push(fnCode);
     return lines.join('\n');
@@ -43,6 +49,10 @@ function formatFunctionJson(fn, code) {
         paramsStructured: fn.paramsStructured || [],
         startLine: fn.startLine,
         endLine: fn.endLine,
+        // Location + class attribution (fix #248: single-entry fn --json
+        // said neither WHERE the function lives nor WHOSE method it is).
+        file: fn.relativePath || fn.file,
+        ...(fn.className && { className: fn.className }),
         modifiers: fn.modifiers || [],
         ...(fn.returnType && { returnType: fn.returnType }),
         ...(fn.paramTypes && { paramTypes: fn.paramTypes }),
@@ -81,6 +91,7 @@ function formatFnResultJson(result) {
         paramsStructured: match.paramsStructured || [],
         startLine: match.startLine,
         endLine: match.endLine,
+        ...(match.className && { className: match.className }),
         modifiers: match.modifiers || [],
         ...(match.returnType && { returnType: match.returnType }),
         ...(match.paramTypes && { paramTypes: match.paramTypes }),

package/core/output/find.js

@@ -100,7 +100,10 @@ function formatFindJson(items) {
  * @param {object} options - { depth, top, all }
  */
 function formatFindDetailed(symbols, query, options = {}) {
-    const { depth, top, all, compact } = options;
+    const { top, all, compact } = options;
+    // Surfaces pass validated NUMBERS; the string comparisons below made
+    // --depth 0/2 dead code everywhere (fix #250). Normalize once.
+    const depth = options.depth != null ? String(options.depth) : undefined;
     const DEFAULT_LIMIT = 5;
 
     if (symbols.length === 0) {
@@ -242,7 +245,11 @@ function formatUsagesJson(usages, name) {
 
     const calls = refs.filter(u => u.usageType === 'call');
     const imports = refs.filter(u => u.usageType === 'import');
-    const references = refs.filter(u => u.usageType === 'reference');
+    // Exhaustive complement (fix #241): a non-definition record that is
+    // neither call nor import lands in references — same-name definer sites
+    // (usageType 'definition', isDefinition false: shadowing locals, other
+    // defs of the name) used to inflate totals while rendering in NO band.
+    const references = refs.filter(u => u.usageType !== 'call' && u.usageType !== 'import');
 
     // Each usage record points at a call site. We emit a per-occurrence handle
     // pointing at the SITE itself in the form "relativePath:line:callerName"
@@ -268,15 +275,17 @@ function formatUsagesJson(usages, name) {
         };
     };
 
+    // Full-set counts under --limit (fix #237) — listed entries stay truncated.
+    const sc = usages.summaryCounts;
     return JSON.stringify({
         meta: { complete: true, skipped: 0, dynamicImports: 0, uncertain: 0 },
         data: {
             symbol: name,
-            definitionCount: definitions.length,
-            callCount: calls.length,
-            importCount: imports.length,
-            referenceCount: references.length,
-            totalUsages: refs.length,
+            definitionCount: sc ? sc.definitions : definitions.length,
+            callCount: sc ? sc.calls : calls.length,
+            importCount: sc ? sc.imports : imports.length,
+            referenceCount: sc ? sc.references : references.length,
+            totalUsages: sc ? (sc.calls + sc.imports + sc.references) : refs.length,
             definitions: definitions.map(d => {
                 const handle = formatSymbolHandle({ ...d, name: d.name || name });
                 return {
@@ -306,10 +315,15 @@ function formatUsages(usages, name, options = {}) {
     const defs = usages.filter(u => u.isDefinition);
     const calls = usages.filter(u => u.usageType === 'call');
     const imports = usages.filter(u => u.usageType === 'import');
-    const refs = usages.filter(u => !u.isDefinition && u.usageType === 'reference');
+    // Exhaustive complement (fix #241) — see formatUsagesJson.
+    const refs = usages.filter(u => !u.isDefinition && u.usageType !== 'call' && u.usageType !== 'import');
 
+    // Under --limit the listed entries are truncated but the summary must
+    // describe the FULL result set (fix #237) — the handler attaches the
+    // full counts as a non-enumerable property.
+    const sc = usages.summaryCounts;
     const lines = [];
-    lines.push(`Usages of "${name}": ${defs.length} definitions, ${calls.length} calls, ${imports.length} imports, ${refs.length} references`);
+    lines.push(`Usages of "${name}": ${sc ? sc.definitions : defs.length} definitions, ${sc ? sc.calls : calls.length} calls, ${sc ? sc.imports : imports.length} imports, ${sc ? sc.references : refs.length} references`);
     if (!compact) lines.push('═'.repeat(60));
 
     function renderContextLines(usage) {