ucn 4.0.2 → 4.1.0

package/core/execute.js

@@ -100,8 +100,10 @@ function applyHandleSyntax(p) {
 /** Normalize exclude to an array (accepts string CSV, array, or falsy). */
 function toExcludeArray(exclude) {
     if (!exclude) return [];
-    if (Array.isArray(exclude)) return exclude;
-    return exclude.split(',').map(s => s.trim()).filter(Boolean);
+    if (Array.isArray(exclude)) return exclude.map(String);
+    // Programmatic callers can pass anything — a number here used to
+    // surface the raw "exclude.split is not a function" TypeError (fix #245).
+    return String(exclude).split(',').map(s => s.trim()).filter(Boolean);
 }
 
 /** Apply test exclusions unless includeTests is set. */
@@ -127,6 +129,27 @@ function buildCallerOptions(p) {
     };
 }
 
+/** Kinds the `class` command extracts (fix #248: Java records and their
+ *  fn-side suggestion were unreachable — indexed as type 'record'). */
+const CLASS_KIND_TYPES = ['class', 'interface', 'type', 'enum', 'struct', 'trait', 'record', 'namespace'];
+
+/**
+ * Disambiguation advice that can actually work (fix #248): --file cannot
+ * split same-file matches, and repeating it when already given is circular.
+ * Class.method (or --class-name) splits same-name methods across classes.
+ */
+function disambiguationHint(matches, chosen, fileGiven) {
+    const sameFile = matches.every(m => m.relativePath === chosen.relativePath);
+    if (sameFile || fileGiven) {
+        const classes = new Set(matches.map(m => m.className).filter(Boolean));
+        if (classes.size > 1) {
+            return 'Use Class.method syntax (or --class-name) to disambiguate, or --all to show all.';
+        }
+        return 'Use --all to show all.';
+    }
+    return 'Use --file to disambiguate or --all to show all.';
+}
+
 /** Check if a file-based result has a file error. */
 function checkFileError(result, file) {
     if (!result) return null;
@@ -150,6 +173,12 @@ function validateClassName(index, name, className) {
     if (!allDefs || allDefs.length === 0) return null; // no defs at all — let the command handle "not found"
     const matching = allDefs.filter(d => d.className === className);
     if (matching.length > 0) return null; // className matched
+    // Namespace-qualified names (fix #252): namespace members are indexed
+    // at top level, so "Geometry.area" must not misdirect to an unrelated
+    // class that happens to define an `area` method.
+    if ((index.symbols.get(className) || []).some(d => d.type === 'namespace')) {
+        return `"${className}" is a namespace — its members are indexed at top level. Use \`${name}\` directly (with --file to scope).`;
+    }
     // className specified but no definitions match
     const available = [...new Set(allDefs.filter(d => d.className).map(d => d.className))];
     if (available.length > 0) {
@@ -190,9 +219,9 @@ function truncationNote(index) {
 /** Build notes for tree-based results (blast, trace, reverseTrace, affectedTests). */
 function treeNote(result) {
     const parts = [];
-    if (result?.warnings?.length > 0) {
-        for (const w of result.warnings) parts.push(w.message || w);
-    }
+    // result.warnings are NOT copied here — the tree formatters render them
+    // in the body (Note: lines under the header); copying them into the
+    // handler note printed each warning twice (fix #237).
     if (result?.tree?.truncatedChildren > 0) {
         parts.push(`${result.tree.truncatedChildren} children truncated. Use --depth=N or --all to expand.`);
     }
@@ -231,6 +260,47 @@ function checkFilePatternMatch(index, filePattern) {
     return `No files matched pattern '${filePattern}'.`;
 }
 
+/**
+ * Definition-pin validation for commands that analyze ONE symbol: when
+ * `file`/`line` are given, some definition of the symbol must actually match
+ * them. Without this, resolution silently falls back to the full definition
+ * set and the command answers about a DIFFERENT definition than the one the
+ * user pinned. Returns an error string, or null when the pin is satisfiable
+ * (or when the symbol has no definitions at all — the not-found path
+ * downstream owns that case).
+ */
+function checkDefinitionPin(index, p) {
+    if (!p.name || (!p.file && !p.line)) return null;
+    const defs = index.symbols.get(p.name) || [];
+    if (defs.length === 0) return null;
+    let candidates = defs;
+    if (p.className) {
+        const byClass = candidates.filter(d => d.className === p.className);
+        if (byClass.length > 0) candidates = byClass;
+    }
+    const describe = (list) => {
+        const shown = list.slice(0, 10)
+            .map(d => `  ${d.relativePath}:${d.startLine}${d.className ? ` (${d.className})` : ''}`)
+            .join('\n');
+        return list.length > 10 ? `${shown}\n  ... and ${list.length - 10} more` : shown;
+    };
+    if (p.file) {
+        const byFile = candidates.filter(d => d.relativePath && d.relativePath.includes(p.file));
+        if (byFile.length === 0) {
+            return `Symbol "${p.name}" not found in files matching "${p.file}". Found ${candidates.length} definition(s) elsewhere:\n${describe(candidates)}\nUse file= with a path fragment from the list above to disambiguate.`;
+        }
+        candidates = byFile;
+    }
+    const line = Number(p.line);
+    if (p.line && Number.isFinite(line)) {
+        const atLine = candidates.filter(d => d.startLine === line);
+        if (atLine.length === 0) {
+            return `No definition of "${p.name}" at line ${line}${p.file ? ` in files matching "${p.file}"` : ''}. Definitions:\n${describe(candidates)}`;
+        }
+    }
+    return null;
+}
+
 /** Read a file and extract lines for a symbol match, applying HTML cleanup. */
 function readAndExtract(match) {
     const content = fs.readFileSync(match.file, 'utf-8');
@@ -289,6 +359,8 @@ const HANDLERS = {
         if (fileErr) return { ok: false, error: fileErr };
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
+        const pinErr = checkDefinitionPin(index, p);
+        if (pinErr) return { ok: false, error: pinErr };
         const result = index.context(p.name, {
             ...buildCallerOptions(p),
             unreachableOnly: !!p.unreachableOnly,
@@ -307,6 +379,8 @@ const HANDLERS = {
         if (fileErr) return { ok: false, error: fileErr };
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
+        const pinErr = checkDefinitionPin(index, p);
+        if (pinErr) return { ok: false, error: pinErr };
         const result = index.impact(p.name, {
             file: p.file,
             className: p.className,
@@ -333,6 +407,8 @@ const HANDLERS = {
         if (fileErr) return { ok: false, error: fileErr };
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
+        const pinErr = checkDefinitionPin(index, p);
+        if (pinErr) return { ok: false, error: pinErr };
         const depthVal = num(p.depth, undefined);
         const result = index.blast(p.name, {
             ...buildCallerOptions(p),
@@ -355,6 +431,8 @@ const HANDLERS = {
         if (fileErr) return { ok: false, error: fileErr };
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
+        const pinErr = checkDefinitionPin(index, p);
+        if (pinErr) return { ok: false, error: pinErr };
         const depthVal = num(p.depth, undefined);
         const result = index.reverseTrace(p.name, {
             ...buildCallerOptions(p),
@@ -377,6 +455,8 @@ const HANDLERS = {
         if (fileErr) return { ok: false, error: fileErr };
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
+        const pinErr = checkDefinitionPin(index, p);
+        if (pinErr) return { ok: false, error: pinErr };
         const result = index.smart(p.name, {
             ...buildCallerOptions(p),
             withTypes: p.withTypes || false,
@@ -394,6 +474,8 @@ const HANDLERS = {
         if (fileErr) return { ok: false, error: fileErr };
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
+        const pinErr = checkDefinitionPin(index, p);
+        if (pinErr) return { ok: false, error: pinErr };
         const depthVal = num(p.depth, undefined);
         const result = index.trace(p.name, {
             ...buildCallerOptions(p),
@@ -427,14 +509,9 @@ const HANDLERS = {
         });
         if (!result) return { ok: false, error: `No examples found for "${p.name}".` };
         // MEDIUM-8: when no non-test examples found but test-file usages
-        // exist, return success with a note so the user knows to retry.
-        if (!result.best && result.excludedTestCalls > 0) {
-            return {
-                ok: true,
-                result,
-                note: `0 examples found (excluded ${result.excludedTestCalls} test-file usage${result.excludedTestCalls === 1 ? '' : 's'} — pass --include-tests to include them)`,
-            };
-        }
+        // exist, the formatter surfaces that fact in the body ("No call
+        // examples found ... excluded N test-file usages") — no handler
+        // note, which printed the same message twice (fix #237).
         return { ok: true, result };
     },
 
@@ -444,6 +521,10 @@ const HANDLERS = {
         applyClassMethodSyntax(p);
         const fileErr = checkFilePatternMatch(index, p.file);
         if (fileErr) return { ok: false, error: fileErr };
+        const pinErr = checkDefinitionPin(index, p);
+        if (pinErr) return { ok: false, error: pinErr };
+        const classErr = validateClassName(index, p.name, p.className);
+        if (classErr) return { ok: false, error: classErr };
         const result = index.related(p.name, {
             file: p.file,
             className: p.className,
@@ -472,12 +553,30 @@ const HANDLERS = {
         if (fileErr) return { ok: false, error: fileErr };
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
+        const pinErr = checkDefinitionPin(index, p);
+        if (pinErr) return { ok: false, error: pinErr };
         const { brief } = require('./brief');
-        const result = brief(index, p.name, { file: p.file, className: p.className, git: !!p.git });
+        // Thread the line pin (fix #249: a `lib.js:5:run` handle silently
+        // resolved the OTHER same-name def — the pin's whole point).
+        const result = brief(index, p.name, { file: p.file, className: p.className, line: p.line, git: !!p.git });
         if (!result) return { ok: false, error: `Symbol "${p.name}" not found.` };
         return { ok: true, result };
     },
 
+    orient: (index, p) => {
+        let top;
+        if (p.top != null) {
+            const n = Number(String(p.top).trim());
+            if (!Number.isInteger(n) || n <= 0) {
+                return { ok: false, error: `Invalid --top value: must be a positive integer (got "${p.top}")` };
+            }
+            top = Math.min(n, 100);
+        }
+        const { orient } = require('./reporting');
+        const result = orient(index, { top });
+        return { ok: true, result };
+    },
+
     doctor: (index, p) => {
         const { doctor } = require('./reporting');
         const result = doctor(index, {
@@ -559,23 +658,54 @@ const HANDLERS = {
             const classErr = validateClassName(index, p.name, p.className);
             if (classErr) return { ok: false, error: classErr };
         }
-        const result = index.usages(p.name, {
+        // Scan once WITHOUT the default test exclusion, then filter in the
+        // handler — the hidden count must be VISIBLE (fix #234, campaign
+        // G2-java: usages silently hid test-file usages while search noted
+        // them — a silently incomplete answer from the raw escape hatch).
+        // Normalize the user's exclude first (fix #239): MCP delivers a CSV
+        // STRING, and matchesFilters iterates its CHARACTERS — exclude=test
+        // emptied every TypeScript project ('t' matched the .ts extension).
+        const userExclude = toExcludeArray(p.exclude);
+        const unfiltered = index.usages(p.name, {
             codeOnly: p.codeOnly || false,
             context: num(p.context, 0),
             className: p.className,
             file: p.file,
-            exclude,
+            exclude: userExclude,
             in: p.in,
         });
+        const notes = [];
+        let result = unfiltered;
+        if (exclude.length !== userExclude.length && Array.isArray(unfiltered)) {
+            result = unfiltered.filter(u => index.matchesFilters(u.relativePath, { exclude }));
+            const hidden = unfiltered.length - result.length;
+            if (hidden > 0) notes.push(`${hidden} test-file usage(s) hidden by default — pass --include-tests to include them.`);
+        }
         // Apply limit to total usages (result is a flat array)
         const limit = num(p.limit, undefined);
-        let note;
         let limited = result;
         if (limit && limit > 0 && Array.isArray(result) && result.length > limit) {
-            note = limitNote(limit, result.length);
+            notes.push(limitNote(limit, result.length));
             limited = result.slice(0, limit);
+            // Summary counts describe the FULL result set — the limit applies
+            // to listed entries only (fix #237: the header claimed '0 calls'
+            // for a called function whenever the definition filled the limit).
+            // Non-enumerable so the JSON array shape is unchanged.
+            Object.defineProperty(limited, 'summaryCounts', {
+                value: {
+                    definitions: result.filter(u => u.isDefinition).length,
+                    calls: result.filter(u => u.usageType === 'call').length,
+                    imports: result.filter(u => u.usageType === 'import').length,
+                    // Exhaustive complement (fix #241): every non-definition
+                    // record that isn't a call or import is a reference —
+                    // same-name definer sites (usageType 'definition' with
+                    // isDefinition false) used to render in NO band.
+                    references: result.filter(u => !u.isDefinition && u.usageType !== 'call' && u.usageType !== 'import').length,
+                },
+                enumerable: false, writable: true, configurable: true,
+            });
         }
-        return { ok: true, result: limited, note };
+        return { ok: true, result: limited, note: notes.length ? notes.join(' ') : undefined };
     },
 
     toc: (index, p) => {
@@ -587,12 +717,21 @@ const HANDLERS = {
             all: p.all,
             top: num(p.top, undefined),
             file: p.file,
-            exclude: p.exclude,
+            // Normalized (fix #239) — a raw MCP CSV string iterated
+            // per-character emptied whole projects (exclude=test vs .ts).
+            exclude: toExcludeArray(p.exclude),
             in: p.in,
         });
         // Apply limit to detailed toc entries (symbols are in f.symbols.functions/classes arrays)
         const limit = num(p.limit, undefined);
         let note;
+        if (limit && limit > 0 && !p.detailed) {
+            // --limit only bounds the per-symbol listing, which compact mode
+            // doesn't render (fix #234 — three campaign cells hit the silent
+            // no-op; FLAG_APPLICABILITY lists limit for toc, so no
+            // inapplicable-flag warning fires either).
+            note = '--limit applies to the symbol listing — combine it with --detailed.';
+        }
         if (limit && limit > 0 && p.detailed && result.files) {
             let totalEntries = result.files.reduce((s, f) => {
                 const syms = f.symbols || {};
@@ -688,7 +827,15 @@ const HANDLERS = {
     tests: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
-        applyClassMethodSyntax(p);
+        // tests() accepts a FILE PATH as the target ("tests helper.go" — the
+        // engine's isFilePath branch searches the basename). Class.method
+        // splitting would shear the filename at the dot into
+        // className='helper', name='go' and silently return nothing
+        // (fix #239, G3-go-measured). Mirror the engine's file-path test.
+        const testsTargetIsFile = typeof p.name === 'string' && (
+            p.name.includes('/') || p.name.includes('\\') ||
+            /\.(js|ts|py|go|java|rs)$/.test(p.name));
+        if (!testsTargetIsFile) applyClassMethodSyntax(p);
         if (p.file) {
             const fileErr = checkFilePatternMatch(index, p.file);
             if (fileErr) return { ok: false, error: fileErr };
@@ -722,6 +869,8 @@ const HANDLERS = {
         if (fileErr) return { ok: false, error: fileErr };
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
+        const pinErr = checkDefinitionPin(index, p);
+        if (pinErr) return { ok: false, error: pinErr };
         const depthVal = num(p.depth, undefined);
         const result = index.affectedTests(p.name, {
             ...buildCallerOptions(p),
@@ -737,6 +886,15 @@ const HANDLERS = {
     deadcode: (index, p) => {
         const fileErr = checkFilePatternMatch(index, p.file);
         if (fileErr) return { ok: false, error: fileErr };
+        // A typo'd 'in' directory used to yield a clean-sounding 'No dead
+        // code found.' (fix #243) — validate it like the file pattern.
+        if (p.in) {
+            let anyIn = false;
+            for (const [, fe] of index.files) {
+                if (index.matchesFilters(fe.relativePath, { in: p.in })) { anyIn = true; break; }
+            }
+            if (!anyIn) return { ok: false, error: `No files matched the 'in' directory filter '${p.in}'.` };
+        }
         let result = index.deadcode({
             includeExported: p.includeExported || false,
             includeDecorated: p.includeDecorated || false,
@@ -755,6 +913,13 @@ const HANDLERS = {
             if (result.excludedExported != null) sliced.excludedExported = result.excludedExported;
             if (result.excludedDecorated != null) sliced.excludedDecorated = result.excludedDecorated;
             if (result.excludedExternalContract != null) sliced.excludedExternalContract = result.excludedExternalContract;
+            // Truncation must be visible IN the JSON payload, not only in the
+            // stderr note (fix #242) — the formatter reads this to emit
+            // meta.total + truncated.
+            Object.defineProperty(sliced, 'limitInfo', {
+                value: { total: result.length, shown: limit },
+                enumerable: false, writable: true, configurable: true,
+            });
             result = sliced;
         }
         const tNote = truncationNote(index);
@@ -783,11 +948,22 @@ const HANDLERS = {
             file: p.file,
             exclude,
         });
+        if (result && result.error) {
+            return { ok: false, error: result.message || result.error };
+        }
         const limit = num(p.limit, undefined);
         let note;
         if (limit && limit > 0 && Array.isArray(result) && result.length > limit) {
             note = limitNote(limit, result.length);
-            result = result.slice(0, limit);
+            const sliced = result.slice(0, limit);
+            // Full-set size travels with the payload so --json can carry
+            // meta.total + truncated (fix #247 — mirrors deadcode's #242
+            // shape; the stderr note alone loses the signal).
+            Object.defineProperty(sliced, 'limitInfo', {
+                value: { total: result.length, shown: limit },
+                enumerable: false, writable: true, configurable: true,
+            });
+            result = sliced;
         }
         return { ok: true, result, note };
     },
@@ -890,7 +1066,11 @@ const HANDLERS = {
     fn: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
-        applyClassMethodSyntax(p);
+        // Comma lists split Class.method PER ITEM below — the whole-string
+        // splitter mangled "helper,Service.buildUrl" into className
+        // "helper,Service" (fix #252). Handles contain no commas.
+        if (p.name.includes(',')) applyHandleSyntax(p);
+        else applyClassMethodSyntax(p);
         const fileErr = checkFilePatternMatch(index, p.file);
         if (fileErr) return { ok: false, error: fileErr };
         if (p.className) {
@@ -910,23 +1090,54 @@ const HANDLERS = {
             const fnSplit = splitClassMethod(fnName);
             const actualName = fnSplit ? fnSplit.methodName : fnName;
             const fnClassName = fnSplit ? fnSplit.className : p.className;
-            const matches = index.find(actualName, { file: p.file, className: fnClassName, skipCounts: true })
+            let matches = index.find(actualName, { file: p.file, className: fnClassName, skipCounts: true })
                 .filter(m => m.type === 'function' || m.params !== undefined);
 
+            // Line pin from a stable handle or explicit line= (fix #249:
+            // `fn both.js:5:run` returned the OTHER same-name def — the
+            // pin's whole point is exactness, so a non-matching line errors
+            // instead of falling back).
+            const pinLine = num(p.line, null);
+            if (pinLine != null && matches.length > 0) {
+                const atLine = matches.filter(m => m.startLine === pinLine || m.nameLine === pinLine);
+                if (atLine.length === 0) {
+                    notes.push(`No definition of "${fnName}" at line ${pinLine}. Found: ${matches.map(m => `${m.relativePath}:${m.startLine}`).join(', ')}.`);
+                    continue;
+                }
+                matches = atLine;
+            }
+
             if (matches.length === 0) {
                 // Check if it's a class — suggest `class` command instead
-                const CLASS_TYPES = ['class', 'interface', 'type', 'enum', 'struct', 'trait'];
                 const classMatches = index.find(actualName, { file: p.file, className: fnClassName, skipCounts: true })
-                    .filter(m => CLASS_TYPES.includes(m.type));
+                    .filter(m => CLASS_KIND_TYPES.includes(m.type));
                 if (classMatches.length > 0) {
-                    notes.push(`"${fnName}" is a ${classMatches[0].type}, not a function. Use \`class ${fnName}\` instead.`);
+                    {
+                    const kind = classMatches[0].type;
+                    const article = /^[aeiou]/.test(kind) ? 'an' : 'a';
+                    notes.push(`"${fnName}" is ${article} ${kind}, not a function. Use \`class ${fnName}\` instead.`);
+                }
+                } else if ((index.symbols.get(actualName) || []).some(s => s.type === 'macro')) {
+                    notes.push(`"${fnName}" is a macro. fn/class extract functions and classes — use \`lines <file>:<start>-<end>\` for macro bodies.`);
                 } else {
                     notes.push(`Function "${fnName}" not found.`);
                 }
                 continue;
             }
 
-            if (matches.length > 1 && !p.file && p.all) {
+            // Fuzzy substitution is never silent (fix #248: `fn run`
+            // returned runAll with no indication).
+            const isFuzzy = !matches.some(m => m.name === actualName);
+            if (isFuzzy) {
+                const shown = [...new Set(matches.map(m => m.name))].join('", "');
+                notes.push(`No exact match for "${fnName}" — showing closest match: "${shown}".`);
+            }
+
+            // --all and the disambiguation note apply whenever the pattern
+            // matched several definitions — a --file filter narrows the set
+            // but does not make it single (fix #248: with --file, extra
+            // in-file matches were silently dropped in three languages).
+            if (matches.length > 1 && p.all) {
                 for (const m of matches) {
                     const code = readAndExtract(m);
                     entries.push({ match: m, code });
@@ -934,14 +1145,15 @@ const HANDLERS = {
                 continue;
             }
 
-            const match = matches.length > 1 && !p.file
+            const match = matches.length > 1
                 ? pickBestDefinition(matches)
                 : matches[0];
 
-            if (matches.length > 1 && !p.file) {
+            if (matches.length > 1) {
                 const others = matches.filter(m => m !== match)
                     .map(m => `${m.relativePath}:${m.startLine}`).join(', ');
-                notes.push(`Found ${matches.length} definitions for "${fnName}". Showing ${match.relativePath}:${match.startLine}. Also in: ${others}. Use --file to disambiguate or --all to show all.`);
+                const what = isFuzzy ? 'fuzzy matches' : 'definitions';
+                notes.push(`Found ${matches.length} ${what} for "${fnName}". Showing ${match.relativePath}:${match.startLine}. Also in: ${others}. ${disambiguationHint(matches, match, p.file)}`);
             }
 
             const code = readAndExtract(match);
@@ -957,14 +1169,32 @@ const HANDLERS = {
     class: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
+        // Stable handles roundtrip here too (fix #249: `class svc.js:7:Service`
+        // errored "not found" — find→class was the one broken hop).
+        applyHandleSyntax(p);
         const fileErr = checkFilePatternMatch(index, p.file);
         if (fileErr) return { ok: false, error: fileErr };
 
-        const CLASS_TYPES = ['class', 'interface', 'type', 'enum', 'struct', 'trait'];
-        const matches = index.find(p.name, { file: p.file, skipCounts: true })
-            .filter(m => CLASS_TYPES.includes(m.type));
+        let matches = index.find(p.name, { file: p.file, skipCounts: true })
+            .filter(m => CLASS_KIND_TYPES.includes(m.type));
+
+        const classPinLine = num(p.line, null);
+        if (classPinLine != null && matches.length > 0) {
+            const atLine = matches.filter(m => m.startLine === classPinLine || m.nameLine === classPinLine);
+            if (atLine.length === 0) {
+                return { ok: false, error: `No definition of "${p.name}" at line ${classPinLine}. Found: ${matches.map(m => `${m.relativePath}:${m.startLine}`).join(', ')}.` };
+            }
+            matches = atLine;
+        }
 
         if (matches.length === 0) {
+            // Cross-kind hint parity with fn (fix #252): a function by this
+            // name deserves a redirect, not a bare "not found".
+            const fnMatches = index.find(p.name, { file: p.file, skipCounts: true })
+                .filter(m => m.type === 'function' || (m.params !== undefined && !CLASS_KIND_TYPES.includes(m.type)));
+            if (fnMatches.length > 0) {
+                return { ok: false, error: `Class "${p.name}" not found — "${p.name}" is a ${fnMatches[0].type}. Use \`fn ${p.name}\` instead.` };
+            }
             return { ok: false, error: `Class "${p.name}" not found.` };
         }
 
@@ -976,7 +1206,14 @@ const HANDLERS = {
             return { ok: false, error: '--max-lines must be a positive integer.' };
         }
 
-        if (matches.length > 1 && !p.file && p.all) {
+        // Fuzzy substitution is never silent (fix #248).
+        const classFuzzy = !matches.some(m => m.name === p.name);
+        if (classFuzzy) {
+            const shown = [...new Set(matches.map(m => m.name))].join('", "');
+            notes.push(`No exact match for "${p.name}" — showing closest match: "${shown}".`);
+        }
+
+        if (matches.length > 1 && p.all) {
             for (const m of matches) {
                 const code = readAndExtract(m);
                 const totalLines = m.endLine - m.startLine + 1;
@@ -985,14 +1222,15 @@ const HANDLERS = {
             return { ok: true, result: { entries }, note: notes.length ? notes.map(n => 'Note: ' + n).join('\n') : undefined };
         }
 
-        const match = matches.length > 1 && !p.file
+        const match = matches.length > 1
             ? pickBestDefinition(matches)
             : matches[0];
 
-        if (matches.length > 1 && !p.file) {
+        if (matches.length > 1) {
             const others = matches.filter(m => m !== match)
                 .map(m => `${m.relativePath}:${m.startLine}`).join(', ');
-            notes.push(`Found ${matches.length} definitions for "${p.name}". Showing ${match.relativePath}:${match.startLine}. Also in: ${others}. Use --file to disambiguate or --all to show all.`);
+            const what = classFuzzy ? 'fuzzy matches' : 'definitions';
+            notes.push(`Found ${matches.length} ${what} for "${p.name}". Showing ${match.relativePath}:${match.startLine}. Also in: ${others}. ${disambiguationHint(matches, match, p.file)}`);
         }
 
         const totalLines = match.endLine - match.startLine + 1;
@@ -1043,13 +1281,22 @@ const HANDLERS = {
         const startLine = Math.min(rawStart, rawEnd);
         const endLine = Math.max(rawStart, rawEnd);
 
-        const filePath = index.findFile(p.file);
-        if (!filePath) {
-            return { ok: false, error: `File not found in project: ${p.file}` };
-        }
+        // Ambiguity-aware resolution (fix #248: an ambiguous basename
+        // reported "File not found" — factually wrong; imports/exporters
+        // list the candidates for the same input).
+        const resolved = index.resolveFilePathForQuery(p.file);
+        const resolveErr = checkFileError(typeof resolved === 'string' ? null : resolved, p.file);
+        if (resolveErr) return { ok: false, error: resolveErr };
+        const filePath = resolved;
 
         const content = fs.readFileSync(filePath, 'utf-8');
         const fileLines = content.split('\n');
+        // A trailing newline is a line TERMINATOR, not a phantom last line
+        // (fix #248: a 279-line file counted as 280 — the empty split tail
+        // was retrievable and skewed the bounds error).
+        if (fileLines.length > 1 && fileLines[fileLines.length - 1] === '') {
+            fileLines.pop();
+        }
 
         if (startLine > fileLines.length) {
             return { ok: false, error: `Line ${startLine} is out of bounds. File has ${fileLines.length} lines.` };
@@ -1118,6 +1365,8 @@ const HANDLERS = {
     },
 
     circularDeps: (index, p) => {
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
         const result = index.circularDeps({
             file: p.file,
             exclude: toExcludeArray(p.exclude),
@@ -1135,9 +1384,16 @@ const HANDLERS = {
         if (fileErr) return { ok: false, error: fileErr };
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
+        const pinErr = checkDefinitionPin(index, p);
+        if (pinErr) return { ok: false, error: pinErr };
         const result = index.verify(p.name, {
             file: p.file,
             className: p.className,
+            // Pin to an exact definition (stable-handle roundtrip: `verify
+            // lib.js:4:save`). resolveSymbol filters by startLine — without
+            // this passthrough the pin was silently dropped and scoring picked
+            // among same-name defs (fix #227).
+            ...(p.line && { line: p.line }),
             // BUG-H3: pass through user-supplied flags. Verify defaults to including
             // method calls (current behavior) so call-arity checks reach all forms,
             // including obj.method() invocations. User can disable with
@@ -1145,6 +1401,9 @@ const HANDLERS = {
             ...(p.includeMethods !== undefined && { includeMethods: p.includeMethods }),
             ...(p.includeUncertain !== undefined && { includeUncertain: p.includeUncertain }),
         });
+        if (result && result.found === false) {
+            return { ok: false, error: `Function "${p.name}" not found.` };
+        }
         return { ok: true, result };
     },
 
@@ -1156,6 +1415,8 @@ const HANDLERS = {
         if (fileErr) return { ok: false, error: fileErr };
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
+        const pinErr = checkDefinitionPin(index, p);
+        if (pinErr) return { ok: false, error: pinErr };
         if (!p.addParam && !p.removeParam && !p.renameTo) {
             return { ok: false, error: 'Plan requires an operation: add_param, remove_param, or rename_to.' };
         }
@@ -1166,7 +1427,12 @@ const HANDLERS = {
             defaultValue: p.defaultValue,
             file: p.file,
             className: p.className,
+            // Exact-definition pin (stable-handle roundtrip) — see verify.
+            ...(p.line && { line: p.line }),
         });
+        if (result && result.found === false) {
+            return { ok: false, error: `Function "${p.name}" not found.` };
+        }
         return { ok: true, result };
     },
 
@@ -1222,7 +1488,15 @@ const HANDLERS = {
         let note;
         if (limit && limit > 0 && Array.isArray(result)) {
             const { items, total, limited } = applyLimit(result, limit);
-            if (limited) note = limitNote(limit, total);
+            if (limited) {
+                note = limitNote(limit, total);
+                // Full-set size travels with the payload for --json
+                // (fix #251 — the deadcode/entrypoints #242/#247 shape).
+                Object.defineProperty(items, 'limitInfo', {
+                    value: { total, shown: limit },
+                    enumerable: false, writable: true, configurable: true,
+                });
+            }
             result = items;
         }
         return { ok: true, result, note };
@@ -1265,6 +1539,12 @@ const HANDLERS = {
                 top = n;
             }
         }
+        // --top only shapes the --hot leaderboard (fix #251: validated then
+        // silently ignored without it).
+        if (p.top != null && !p.hot) {
+            const depNote = 'Note: --top applies to the --hot leaderboard — add --hot to rank functions by call count.';
+            note = note ? `${note}\n${depNote}` : depNote;
+        }
         const result = index.getStats({
             functions: p.functions || false,
             hot: p.hot || false,
@@ -1330,6 +1610,13 @@ function execute(index, command, params = {}) {
     if (!handler) {
         return { ok: false, error: `Unknown command: ${command}` };
     }
+    // Handlers normalize params in place (handle syntax, Class.method
+    // splitting) — dispatch on a shallow copy so the caller's object
+    // survives reuse (fix #255: `execute(index, 'fn', p)` rewrote p.name
+    // 'Service.buildUrl' → 'buildUrl' + className, corrupting a reused or
+    // logged params object; a frozen object silently no-oped the
+    // normalizers and returned wrong not-found answers).
+    params = { ...params };
     try {
         // Resolve name-less handles (e.g. `lib.js:42`) via index lookup before dispatch.
         // Handles WITH a name suffix are handled later by applyClassMethodSyntax.