ucn 4.2.3 → 5.0.2

package/core/execute.js

@@ -15,11 +15,18 @@ const path = require('path');
 const { addTestExclusions, pickBestDefinition, parseSymbolHandle, looksLikeHandle } = require('./shared');
 const { cleanHtmlScriptTags, detectLanguage } = require('./parser');
 const { renderExpandItem } = require('./expand-cache');
+const { CANONICAL_COMMANDS } = require('./registry');
 
 // ============================================================================
 // HELPERS
 // ============================================================================
 
+const NO_STATIC_TEST_LINK_NOTE =
+    'No confirmed static test link was found. This is not runtime coverage evidence: ' +
+    'subprocess/black-box tests, reflection, generated code, and external harnesses can still ' +
+    'exercise the target. Inspect the project test runner and search for the defining module/file ' +
+    'before concluding it is untested.';
+
 function requireName(name) {
     if (!name || (typeof name === 'string' && !name.trim())) {
         return 'Symbol name is required.';
@@ -41,6 +48,59 @@ function requireTerm(term) {
     return null;
 }
 
+function editDistance(a, b) {
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diagonal = prev[0];
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const above = prev[j];
+            prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1,
+                diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return prev[b.length];
+}
+
+function symbolNotFound(index, name, label = 'Symbol') {
+    const query = String(name || '');
+    const lower = query.toLowerCase();
+    let best = null;
+    for (const candidate of index.symbols.keys()) {
+        const value = String(candidate);
+        const candidateLower = value.toLowerCase();
+        const distance = editDistance(lower, candidateLower);
+        const prefixBonus = candidateLower.startsWith(lower) || lower.startsWith(candidateLower)
+            ? -2 : 0;
+        const score = distance + prefixBonus;
+        if (!best || score < best.score ||
+            (score === best.score && value < best.value)) {
+            best = { value, score, distance };
+        }
+    }
+    const threshold = Math.max(2, Math.floor(query.length * 0.3));
+    let message;
+    if (best && best.distance <= threshold) {
+        message = `${label} "${query}" not found. Did you mean "${best.value}"? ` +
+            'Use find to confirm the symbol and obtain a stable handle.';
+    } else {
+        message = `${label} "${query}" not found. Use find with a shorter name, or search for a literal occurrence.`;
+    }
+    const unsupported = require('./account').scanUnsupportedFiles(index, query);
+    if (unsupported.lines > 0) {
+        const languages = Object.keys(unsupported.languages).join(', ');
+        message += ` ${unsupported.lines} literal match(es) exist in ` +
+            `${unsupported.fileCount} unsupported-language file(s)` +
+            `${languages ? ` (${languages})` : ''}; this is not a semantic zero. ` +
+            'Use grep/ripgrep plus a language-native analyzer.';
+    } else if (index.unsupportedFiles?.length > 0) {
+        message += ` UCN skipped ${index.unsupportedFiles.length} unsupported source ` +
+            `file(s), so this is not a repository-wide semantic zero; verify with grep/ripgrep.`;
+    }
+    return message;
+}
+
 /**
  * Split Class.method syntax into className and methodName.
  * Returns { className, methodName } or null if not applicable.
@@ -53,10 +113,21 @@ function splitClassMethod(name) {
     if (dotIndex <= 0 || dotIndex === name.length - 1) return null;
     // Only split on first dot, and only if there's exactly one dot
     if (name.indexOf('.', dotIndex + 1) !== -1) return null;
-    return {
-        className: name.substring(0, dotIndex),
-        methodName: name.substring(dotIndex + 1)
-    };
+    const className = name.substring(0, dotIndex);
+    const methodName = name.substring(dotIndex + 1);
+    // This is authored identifier syntax, not a generic string splitter.
+    // Preserve computed names, malformed handles, paths, and source text.
+    const identifier = /^[\p{L}_$][\p{L}\p{N}_$]*$/u;
+    if (!identifier.test(className) || !identifier.test(methodName)) return null;
+    return { className, methodName };
+}
+
+function validateInFilter(index, value) {
+    if (!value) return null;
+    for (const [, fileEntry] of index.files) {
+        if (index.matchesFilters(fileEntry.relativePath, { in: value })) return null;
+    }
+    return `No files matched the 'in' directory filter '${value}'.`;
 }
 
 /**
@@ -88,12 +159,17 @@ function applyHandleSyntax(p) {
     if (!looksLikeHandle(p.name)) return;
     const h = parseSymbolHandle(p.name);
     if (!h) return;
+    p._handleFile = h.file;
+    p._handleLine = h.line;
     // Pull name out of handle. If the handle has no name suffix, we need to
     // recover it from the index — but at this layer we only have params.
     // The downstream resolveSymbol path will look up by file+line if name is empty.
     if (h.name) p.name = h.name;
     // Only override p.file/p.line if they weren't explicitly set by the user
-    if (h.file && !p.file) p.file = h.file;
+    if (h.file && !p.file) {
+        p.file = h.file;
+        p._fileFromHandle = true;
+    }
     if (h.line && !p.line) p.line = h.line;
 }
 
@@ -151,9 +227,21 @@ function disambiguationHint(matches, chosen, fileGiven) {
 }
 
 /** Check if a file-based result has a file error. */
-function checkFileError(result, file) {
+function checkFileError(result, file, index = null) {
     if (!result) return null;
     if (result.error === 'file-not-found') {
+        if (index) {
+            const exactUnsupported = (index.unsupportedFiles || []).find(entry =>
+                entry.relativePath === file || entry.relativePath.endsWith('/' + file));
+            const candidate = path.isAbsolute(file)
+                ? path.resolve(file) : path.resolve(index.root, file);
+            if (exactUnsupported || fs.existsSync(candidate)) {
+                const language = exactUnsupported?.language ||
+                    exactUnsupported?.extension || 'unsupported/excluded';
+                return `File exists but is not indexed by UCN: ${file} (${language}). ` +
+                    'Use grep/ripgrep plus a language-native analyzer.';
+            }
+        }
         return `File not found in project: ${file}`;
     }
     if (result.error === 'file-ambiguous') {
@@ -222,8 +310,12 @@ function treeNote(result) {
     // 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.`);
+    const countTruncated = node => !node ? 0 :
+        (node.truncatedChildren || 0) +
+        (node.children || []).reduce((sum, child) => sum + countTruncated(child), 0);
+    const truncatedChildren = countTruncated(result?.tree);
+    if (truncatedChildren > 0) {
+        parts.push(`${truncatedChildren} children truncated by the per-node cap. Use --all to expand them; --depth controls hops only.`);
     }
     if (result?.truncatedCallers > 0) {
         parts.push(`${result.truncatedCallers} callers truncated. Use --all to expand.`);
@@ -284,7 +376,10 @@ function checkDefinitionPin(index, p) {
         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));
+        const resolvedFile = index.resolveFilePathForQuery(p.file);
+        const byFile = typeof resolvedFile === 'string'
+            ? candidates.filter(d => d.file === resolvedFile)
+            : 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.`;
         }
@@ -292,7 +387,8 @@ function checkDefinitionPin(index, p) {
     }
     const line = Number(p.line);
     if (p.line && Number.isFinite(line)) {
-        const atLine = candidates.filter(d => d.startLine === line);
+        const atLine = candidates.filter(d =>
+            d.startLine === line || d.nameLine === 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)}`;
         }
@@ -308,12 +404,363 @@ function readAndExtract(match) {
     return cleanHtmlScriptTags(extracted, detectLanguage(match.file)).join('\n');
 }
 
+const SHOW_SECTIONS = new Set([
+    'summary', 'callers', 'callees', 'source', 'dependencies',
+    'tests', 'types', 'example', 'related',
+]);
+const REPO_SECTIONS = new Set(['summary', 'files', 'stats', 'health']);
+
+/** Parse a comma-separated/array section selector with validation. */
+function parseSections(value, defaults, allowed, command) {
+    const supplied = value != null && value !== '';
+    const raw = !supplied
+        ? defaults
+        : (Array.isArray(value) ? value : String(value).split(','));
+    const sections = [...new Set(raw.map(s => String(s).trim().toLowerCase()).filter(Boolean))];
+    if (supplied && sections.length === 0) {
+        return {
+            error: `No valid ${command} sections were provided. Available: ${[...allowed].join(', ')}.`,
+        };
+    }
+    const invalid = sections.filter(s => !allowed.has(s));
+    if (invalid.length > 0) {
+        return {
+            error: `Unknown ${command} section(s): ${invalid.join(', ')}. Available: ${[...allowed].join(', ')}.`,
+        };
+    }
+    return { sections };
+}
+
+function addMode(result, mode) {
+    if (result && typeof result === 'object') {
+        Object.defineProperty(result, '_publicMode', {
+            value: mode,
+            enumerable: false,
+            configurable: true,
+        });
+    }
+    return result;
+}
+
+function combineNotes(notes) {
+    return notes.filter(Boolean).join('\n') || undefined;
+}
+
+const PUBLIC_COMMAND_SET = new Set(CANONICAL_COMMANDS);
+
+/**
+ * Validate mode-dependent parameter combinations before a handler chooses a
+ * branch. This is deliberately inside the engine so CLI, MCP, interactive,
+ * glob, file, and programmatic callers receive the same answer.
+ */
+function validatePublicParams(command, p) {
+    const hasName = typeof p.name === 'string' && p.name.trim() !== '';
+    const gitScope = p.staged || (typeof p.base === 'string' && p.base.trim() !== '');
+    if ((command === 'impact' || command === 'check') && hasName && gitScope) {
+        return `${command} accepts either a symbol target or Git diff scope (base/staged), not both.`;
+    }
+    if ((command === 'impact' || command === 'check') && p.staged && p.base) {
+        return `${command} accepts either staged=true or base, not both.`;
+    }
+    if (command === 'source' && p.range != null &&
+        (!p.file || !String(p.file).trim())) {
+        return 'source range mode requires file.';
+    }
+    if (command === 'source' && p.range != null &&
+        typeof p.name === 'string' && p.name.trim()) {
+        return 'source accepts either a symbol target or a file range, not both.';
+    }
+    if (command === 'search' && p.receiver && p.type && p.type !== 'call') {
+        return 'search receiver filtering requires type=call (or omit type to select call mode).';
+    }
+    if (command === 'trace' && p.to === 'entrypoints' &&
+        (p.direction || 'callees') !== 'callers') {
+        return 'trace --to=entrypoints requires --direction=callers.';
+    }
+    if (command === 'deps' && p.cycles &&
+        (p.file || p.direction || p.depth != null || p.detailed || p.all)) {
+        return 'deps cycles mode cannot be combined with file, direction, depth, detailed, or all.';
+    }
+    if (command === 'tests' && Number(p.depth || 0) > 0 && p.callsOnly) {
+        return 'tests callsOnly applies to direct mode and cannot be combined with depth>0.';
+    }
+    if (command === 'entrypoints' && p.includeTests === true && p.excludeTests === true) {
+        return 'entrypoints includeTests and excludeTests cannot both be true.';
+    }
+    if (command === 'endpoints' && p.serverOnly && p.clientOnly) {
+        return 'endpoints serverOnly and clientOnly cannot both be true.';
+    }
+    if (command === 'plan') {
+        const operations = [p.addParam, p.removeParam, p.renameTo]
+            .filter(value => value != null && String(value).trim() !== '');
+        if (operations.length !== 1) {
+            return 'plan requires exactly one operation: addParam, removeParam, or renameTo.';
+        }
+        if (p.defaultValue != null && !p.addParam) {
+            return 'plan defaultValue is valid only with addParam.';
+        }
+        // Names that land in declarations and call sites must at least be
+        // identifier-shaped — "foo bar" or "x-y" in a rename would write
+        // syntax errors into every planned edit. Language-specific reserved
+        // words are checked after symbol resolution (plan() knows the file).
+        const IDENTIFIER_SHAPE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+        if (p.renameTo != null && String(p.renameTo).trim() !== '' &&
+            !IDENTIFIER_SHAPE.test(String(p.renameTo).trim())) {
+            return `plan renameTo "${String(p.renameTo).trim()}" is not a valid identifier.`;
+        }
+        // addParam also accepts a typed spec (`suffix: string`, `opt?: number`)
+        // — only the NAME portion must be identifier-shaped.
+        const ADD_PARAM_SHAPE = /^[A-Za-z_$][A-Za-z0-9_$]*\??(\s*:\s*\S.*)?$/;
+        if (p.addParam != null && String(p.addParam).trim() !== '' &&
+            !ADD_PARAM_SHAPE.test(String(p.addParam).trim())) {
+            return `plan addParam "${String(p.addParam).trim()}" is not a valid parameter name (use \`name\` or \`name: type\`).`;
+        }
+    }
+    return null;
+}
+
 // ============================================================================
 // COMMAND HANDLERS
 // ============================================================================
 
 const HANDLERS = {
 
+    // ── Public v5 compositions ─────────────────────────────────────────
+
+    show: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        const originalTarget = p.name;
+        const query = { ...p };
+        applyClassMethodSyntax(query);
+        const fileErr = checkFilePatternMatch(index, query.file);
+        if (fileErr) return { ok: false, error: fileErr };
+        const classErr = validateClassName(index, query.name, query.className);
+        if (classErr) return { ok: false, error: classErr };
+        const pinErr = checkDefinitionPin(index, query);
+        if (pinErr) return { ok: false, error: pinErr };
+        const resolved = index.resolveSymbol(query.name, {
+            file: query.file,
+            className: query.className,
+            line: query.line,
+        });
+        if (!resolved.def) return { ok: false, error: symbolNotFound(index, query.name) };
+        // A composed answer must use one exact definition in every section.
+        // Let the child handler provide the normal not-found/filter error, but
+        // once resolution succeeds pin every composition to the selected file
+        // and line. Otherwise brief/context and source can apply different
+        // legitimate ranking policies and contradict each other.
+        const targetParams = resolved.def ? {
+            ...query,
+            name: resolved.def.name,
+            file: resolved.def.relativePath,
+            line: resolved.def.nameLine || resolved.def.startLine,
+            ...(resolved.def.className && { className: resolved.def.className }),
+        } : query;
+        const parsed = parseSections(
+            p.sections,
+            ['summary', 'callers', 'callees'],
+            SHOW_SECTIONS,
+            'show',
+        );
+        if (parsed.error) return { ok: false, error: parsed.error };
+        if (p.withTypes && !parsed.sections.includes('types')) parsed.sections.push('types');
+
+        const selected = new Set(parsed.sections);
+        const result = { target: originalTarget, sections: parsed.sections };
+        const notes = (resolved.warnings || []).map(warning => warning.message);
+        if (resolved.warnings?.length) result.warnings = resolved.warnings;
+        const run = (section, handler, params) => {
+            const response = HANDLERS[handler](index, { ...params });
+            if (!response.ok) {
+                if (!result.unavailableSections) result.unavailableSections = [];
+                result.unavailableSections.push({ section, reason: response.error });
+                notes.push(`Section "${section}" unavailable: ${response.error}`);
+                return null;
+            }
+            if (response.note) notes.push(response.note);
+            return response;
+        };
+
+        if (selected.has('summary')) {
+            const response = run('summary', 'brief', targetParams);
+            if (response) result.summary = response.result;
+        }
+        if (selected.has('callers') || selected.has('callees')) {
+            const response = run('relationships', 'context', targetParams);
+            if (response) {
+            // Apply the projection in the engine result so text and JSON
+            // expose the same sections. ACCOUNT/CONTRACT metadata stays
+            // attached even when one relationship direction is omitted.
+            result.context = { ...response.result };
+            if (!selected.has('callers')) {
+                delete result.context.callers;
+                delete result.context.unverifiedCallers;
+            }
+            if (!selected.has('callees')) {
+                delete result.context.callees;
+                delete result.context.unverifiedCallees;
+            }
+            result.context.omittedSections = [
+                ...(!selected.has('callers') ? ['callers'] : []),
+                ...(!selected.has('callees') ? ['callees'] : []),
+            ];
+            }
+        }
+        if (selected.has('source')) {
+            const response = run('source', 'source', targetParams);
+            if (response) result.source = response.result;
+        }
+        if (selected.has('dependencies')) {
+            const response = run('dependencies', 'smart', targetParams);
+            if (response) result.dependencies = response.result;
+        }
+        if (selected.has('tests')) {
+            const response = run('tests', 'tests', { ...targetParams, depth: 0 });
+            if (response) result.tests = response.result;
+        }
+        if (selected.has('types')) {
+            const response = run('types', 'about', {
+                ...targetParams, withTypes: true, compact: true,
+            });
+            if (response) {
+                result.types = {
+                    types: response.result.types || [],
+                    otherDefinitions: response.result.otherDefinitions || [],
+                };
+            }
+        }
+        if (selected.has('example')) {
+            const response = run('example', 'example', targetParams);
+            if (response) result.example = response.result;
+        }
+        if (selected.has('related')) {
+            const response = run('related', 'related', targetParams);
+            if (response) result.related = response.result;
+        }
+
+        const note = combineNotes(notes);
+        return note ? { ok: true, result, note } : { ok: true, result };
+    },
+
+    source: (index, p) => {
+        if (p.range != null) {
+            const response = HANDLERS.lines(index, { file: p.file, range: p.range });
+            if (response.ok) addMode(response.result, 'lines');
+            return response;
+        }
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: 'Symbol name or file range is required.' };
+        const query = { ...p };
+        applyClassMethodSyntax(query);
+        const fileErr = checkFilePatternMatch(index, query.file);
+        if (fileErr) return { ok: false, error: fileErr };
+        const classErr = validateClassName(index, query.name, query.className);
+        if (classErr) return { ok: false, error: classErr };
+        const pinErr = checkDefinitionPin(index, query);
+        if (pinErr) return { ok: false, error: pinErr };
+
+        // Use the same ranker as `show`; once selected, pin extraction to the
+        // exact definition so a second handler cannot choose differently.
+        const resolved = index.resolveSymbol(query.name, {
+            file: query.file,
+            className: query.className,
+            line: query.line,
+        });
+        if (!resolved.def) return { ok: false, error: symbolNotFound(index, query.name) };
+
+        const isClass = CLASS_KIND_TYPES.includes(resolved.def.type);
+        const targetParams = query.all ? query : {
+            ...query,
+            name: resolved.def.name,
+            file: resolved.def.relativePath,
+            line: resolved.def.nameLine || resolved.def.startLine,
+            ...(resolved.def.className && { className: resolved.def.className }),
+        };
+        const response = HANDLERS[isClass ? 'class' : 'fn'](index, targetParams);
+        if (!response.ok) return response;
+        addMode(response.result, isClass ? 'class' : 'function');
+        const notes = [
+            ...(resolved.warnings || []).map(warning => warning.message),
+            response.note,
+        ].filter(Boolean);
+        return notes.length > 0
+            ? { ...response, note: combineNotes(notes) }
+            : response;
+    },
+
+    deps: (index, p) => {
+        if (p.cycles) {
+            const response = HANDLERS.circularDeps(index, { file: p.file, exclude: p.exclude });
+            if (response.ok) addMode(response.result, 'cycles');
+            return response;
+        }
+        const err = requireFile(p.file);
+        if (err) return { ok: false, error: err };
+        const direction = p.direction || 'both';
+        if (!['imports', 'importers', 'both'].includes(direction)) {
+            return { ok: false, error: 'deps direction must be imports, importers, or both.' };
+        }
+        const graphResponse = HANDLERS.graph(index, {
+            file: p.file,
+            direction,
+            depth: p.depth,
+            all: p.all,
+        });
+        if (!graphResponse.ok) return graphResponse;
+        const result = {
+            file: p.file,
+            direction,
+            graph: graphResponse.result,
+        };
+        if (p.detailed && (direction === 'imports' || direction === 'both')) {
+            const response = HANDLERS.imports(index, { file: p.file });
+            if (!response.ok) return response;
+            result.imports = response.result;
+        }
+        if (p.detailed && (direction === 'importers' || direction === 'both')) {
+            const response = HANDLERS.exporters(index, { file: p.file });
+            if (!response.ok) return response;
+            result.importers = response.result;
+        }
+        addMode(result, 'graph');
+        return { ok: true, result };
+    },
+
+    repo: (index, p) => {
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
+        const inErr = validateInFilter(index, p.in);
+        if (inErr) return { ok: false, error: inErr };
+        const defaults = p.deep ? ['summary', 'health'] : ['summary'];
+        const parsed = parseSections(p.sections, defaults, REPO_SECTIONS, 'repo');
+        if (parsed.error) return { ok: false, error: parsed.error };
+        const selected = new Set(parsed.sections);
+        const result = { sections: parsed.sections };
+        const notes = [];
+        const collect = (key, handler, params) => {
+            const response = HANDLERS[handler](index, { ...params });
+            if (!response.ok) return response;
+            result[key] = response.result;
+            if (response.note) notes.push(response.note);
+            return null;
+        };
+        let failure;
+        if (selected.has('summary')) failure = collect('summary', 'orient', p);
+        if (!failure && selected.has('files')) failure = collect('files', 'toc', {
+            ...p,
+            // repo's public limit caps the file result set. Direct toc's
+            // legacy symbol-list cap is intentionally not composed here.
+            top: p.top || p.limit,
+            limit: undefined,
+        });
+        if (!failure && selected.has('stats')) failure = collect('stats', 'stats', p);
+        if (!failure && selected.has('health')) failure = collect('health', 'doctor', p);
+        if (failure) return failure;
+        const note = combineNotes(notes);
+        return note ? { ok: true, result, note } : { ok: true, result };
+    },
+
     // ── Understanding Code ──────────────────────────────────────────────
 
     about: (index, p) => {
@@ -344,7 +791,7 @@ const HANDLERS = {
                     return { ok: false, error: `Symbol "${p.name}" not found in ${filterDesc}. Found ${allDefs.length} definition(s) elsewhere:\n${locations}${more}\nUse file= with a path fragment from the list above to disambiguate.` };
                 }
             }
-            return { ok: false, error: `Symbol "${p.name}" not found.` };
+            return { ok: false, error: symbolNotFound(index, p.name) };
         }
         const tNote = truncationNote(index);
         return { ok: true, result, showConfidence: !!p.showConfidence, ...(tNote && { note: tNote }) };
@@ -362,15 +809,24 @@ const HANDLERS = {
         if (pinErr) return { ok: false, error: pinErr };
         const result = index.context(p.name, {
             ...buildCallerOptions(p),
+            maxCallers: num(p.top, undefined),
+            maxCallees: num(p.top, undefined),
             unreachableOnly: !!p.unreachableOnly,
             all: !!p.all,
         });
-        if (!result) return { ok: false, error: `Symbol "${p.name}" not found.` };
+        if (!result) return { ok: false, error: symbolNotFound(index, p.name) };
         const tNote = truncationNote(index);
         return { ok: true, result, showConfidence: !!p.showConfidence, ...(tNote && { note: tNote }) };
     },
 
     impact: (index, p) => {
+        // Public v5 overload: no symbol means Git-diff impact. This replaces
+        // the separate diff-impact command without changing the symbol path.
+        if (!p.name || (typeof p.name === 'string' && !p.name.trim())) {
+            const response = HANDLERS.diffImpact(index, { ...p });
+            if (response.ok) addMode(response.result, 'diff');
+            return response;
+        }
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
@@ -383,8 +839,9 @@ const HANDLERS = {
         const result = index.impact(p.name, {
             file: p.file,
             className: p.className,
+            line: p.line,
             exclude: toExcludeArray(p.exclude),
-            top: num(p.top, undefined),
+            top: num(p.limit, undefined) || num(p.top, undefined),
             unreachableOnly: !!p.unreachableOnly,
             // BUG-H3: pass through user-supplied flags. impact defaults to including
             // method calls because "what breaks if I change this" should include
@@ -393,8 +850,9 @@ const HANDLERS = {
             ...(p.includeMethods !== undefined && { includeMethods: p.includeMethods }),
             ...(p.includeUncertain !== undefined && { includeUncertain: p.includeUncertain }),
         });
-        if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
+        if (!result) return { ok: false, error: symbolNotFound(index, p.name, 'Function') };
         const tNote = truncationNote(index);
+        addMode(result, 'symbol');
         return { ok: true, result, ...(tNote && { note: tNote }) };
     },
 
@@ -412,10 +870,10 @@ const HANDLERS = {
         const result = index.blast(p.name, {
             ...buildCallerOptions(p),
             depth: depthVal ?? 3,
-            all: p.all || depthVal !== undefined,
+            all: !!p.all,
             expandUnverified: !!p.expandUnverified,
         });
-        if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
+        if (!result) return { ok: false, error: symbolNotFound(index, p.name, 'Function') };
         const note = treeNote(result);
         const tNote = truncationNote(index);
         const combined = [note, tNote].filter(Boolean).join('\n') || undefined;
@@ -436,10 +894,10 @@ const HANDLERS = {
         const result = index.reverseTrace(p.name, {
             ...buildCallerOptions(p),
             depth: depthVal ?? 5,
-            all: p.all || depthVal !== undefined,
+            all: !!p.all,
             expandUnverified: !!p.expandUnverified,
         });
-        if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
+        if (!result) return { ok: false, error: symbolNotFound(index, p.name, 'Function') };
         const note = treeNote(result);
         const tNote = truncationNote(index);
         const combined = [note, tNote].filter(Boolean).join('\n') || undefined;
@@ -460,12 +918,29 @@ const HANDLERS = {
             ...buildCallerOptions(p),
             withTypes: p.withTypes || false,
         });
-        if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
+        if (!result) return { ok: false, error: symbolNotFound(index, p.name, 'Function') };
         const tNote = truncationNote(index);
         return { ok: true, result, ...(tNote && { note: tNote }) };
     },
 
     trace: (index, p) => {
+        const direction = p.direction || 'callees';
+        if (!['callees', 'callers'].includes(direction)) {
+            return { ok: false, error: 'trace direction must be callees or callers.' };
+        }
+        if (p.to && p.to !== 'entrypoints') {
+            return { ok: false, error: 'trace --to currently accepts only entrypoints.' };
+        }
+        if (direction === 'callers') {
+            const response = p.to === 'entrypoints'
+                ? HANDLERS.reverseTrace(index, { ...p, direction: undefined, to: undefined })
+                : HANDLERS.blast(index, { ...p, direction: undefined, to: undefined });
+            if (response.ok) addMode(response.result, p.to === 'entrypoints' ? 'entrypoints' : 'callers');
+            return response;
+        }
+        if (p.to) {
+            return { ok: false, error: 'trace --to=entrypoints requires --direction=callers.' };
+        }
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
@@ -479,13 +954,14 @@ const HANDLERS = {
         const result = index.trace(p.name, {
             ...buildCallerOptions(p),
             depth: depthVal ?? 3,
-            all: p.all || depthVal !== undefined,
+            all: !!p.all,
             expandUnverified: !!p.expandUnverified,
         });
-        if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
+        if (!result) return { ok: false, error: symbolNotFound(index, p.name, 'Function') };
         const note = treeNote(result);
         const tNote = truncationNote(index);
         const combined = [note, tNote].filter(Boolean).join('\n') || undefined;
+        addMode(result, 'callees');
         return { ok: true, result, ...(combined && { note: combined }) };
     },
 
@@ -537,7 +1013,7 @@ const HANDLERS = {
             top: num(p.top, undefined),
             all: p.all,
         });
-        if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
+        if (!result) return { ok: false, error: symbolNotFound(index, p.name, 'Function') };
         const parts = [];
         if (result.similarNamesTotal > result.similarNames.length)
             parts.push(`similar names: showing ${result.similarNames.length} of ${result.similarNamesTotal}`);
@@ -565,7 +1041,7 @@ const HANDLERS = {
         // 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.` };
+        if (!result) return { ok: false, error: symbolNotFound(index, p.name) };
         return { ok: true, result };
     },
 
@@ -579,7 +1055,12 @@ const HANDLERS = {
             top = Math.min(n, 100);
         }
         const { orient } = require('./reporting');
-        const result = orient(index, { top });
+        const result = orient(index, {
+            top,
+            file: p.file,
+            in: p.in,
+            exclude: toExcludeArray(p.exclude),
+        });
         return { ok: true, result };
     },
 
@@ -588,12 +1069,20 @@ const HANDLERS = {
         const result = doctor(index, {
             in: p.in,
             file: p.file,
+            exclude: toExcludeArray(p.exclude),
             deep: !!p.deep,
         });
         return { ok: true, result };
     },
 
     check: (index, p) => {
+        // Public v5 overload: a symbol target performs the former verify
+        // operation; a target-less invocation remains the diff/precommit check.
+        if (p.name && String(p.name).trim()) {
+            const response = HANDLERS.verify(index, { ...p });
+            if (response.ok) addMode(response.result, 'symbol');
+            return response;
+        }
         const { check } = require('./check');
         try {
             const result = check(index, {
@@ -602,6 +1091,7 @@ const HANDLERS = {
                 file: p.file,
                 limit: num(p.limit, undefined),
             });
+            addMode(result, 'diff');
             return { ok: true, result };
         } catch (e) {
             return { ok: false, error: e && e.message ? e.message : String(e) };
@@ -611,6 +1101,35 @@ const HANDLERS = {
     // ── Finding Code ────────────────────────────────────────────────────
 
     find: (index, p) => {
+        const inErr = validateInFilter(index, p.in);
+        if (inErr) return { ok: false, error: inErr };
+        const validFindTypes = new Set([
+            'type', 'function', 'class', 'variable', 'state', 'constant',
+            'field', 'macro', 'method', 'constructor', 'interface', 'enum',
+            'struct', 'trait', 'record', 'namespace',
+        ]);
+        if (p.type && !validFindTypes.has(p.type)) {
+            return { ok: false, error: `Invalid find type "${p.type}". Valid types: ${[...validFindTypes].join(', ')}.` };
+        }
+        if (p.type === 'type') {
+            const response = HANDLERS.typedef(index, { ...p });
+            if (response.ok) {
+                if (!p.withSource && Array.isArray(response.result)) {
+                    response.result = response.result.map(({ code, ...item }) => item);
+                }
+                const limit = num(p.limit, undefined);
+                if (limit && limit > 0 && Array.isArray(response.result)) {
+                    const { items, total, limited } = applyLimit(response.result, limit);
+                    response.result = items;
+                    if (limited) {
+                        const note = limitNote(limit, total);
+                        response.note = response.note ? `${response.note}\n${note}` : note;
+                    }
+                }
+                addMode(response.result, 'type');
+            }
+            return response;
+        }
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
@@ -621,12 +1140,15 @@ const HANDLERS = {
             const classErr = validateClassName(index, p.name, p.className);
             if (classErr) return { ok: false, error: classErr };
         }
-        // Auto-include tests when pattern clearly targets test functions
-        // But only if the user didn't explicitly set include_tests=false
-        let includeTests = p.includeTests;
-        if (includeTests === undefined && p.name && /^test[_*?A-Z]/i.test(p.name)) {
-            includeTests = true;
+        if (p.line) {
+            const pinErr = checkDefinitionPin(index, p);
+            if (pinErr) return { ok: false, error: pinErr };
         }
+        // Symbol lookup is an inventory operation: a definition must not
+        // disappear merely because it lives in a test file. Call-bearing
+        // analysis commands retain their conservative test defaults; find
+        // includes every indexed definition unless explicitly asked not to.
+        const includeTests = p.includeTests !== false;
         const exclude = applyTestExclusions(p.exclude, includeTests);
         let result = index.find(p.name, {
             file: p.file,
@@ -635,11 +1157,49 @@ const HANDLERS = {
             exclude,
             in: p.in,
         });
+        const line = Number(p.line);
+        if (p.line && Number.isFinite(line)) {
+            result = result.filter(item =>
+                item.startLine === line || item.nameLine === line);
+        }
+        if (p.type) {
+            const kindGroups = {
+                function: new Set(['function', 'method', 'constructor', 'get', 'set']),
+                class: new Set(CLASS_KIND_TYPES),
+                variable: new Set(['state', 'constant', 'field']),
+            };
+            const kinds = kindGroups[p.type] || new Set([p.type]);
+            result = result.filter(item => kinds.has(item.type));
+        }
+        if (p.withSource) {
+            result = result.map(item => ({ ...item, code: readAndExtract(item) }));
+        }
+        const fullFindCount = result.length;
+        const nameWideDefinitionCounts = Object.fromEntries(
+            [...new Set(result.map(item => item.name))].map(name => [
+                name,
+                (index.symbols.get(name) || []).length,
+            ]),
+        );
         // Warn if exact mode silently disables glob expansion
         const notes = [];
         if (p.exact && p.name && (p.name.includes('*') || p.name.includes('?'))) {
             notes.push(`Note: exact=true treats "${p.name}" as a literal name (glob expansion disabled).`);
         }
+        let unsupportedMatches = null;
+        if (fullFindCount === 0 && index.unsupportedFiles?.length > 0) {
+            unsupportedMatches = require('./account').scanUnsupportedFiles(index, p.name);
+            const languages = Object.keys(unsupportedMatches.languages).join(', ');
+            if (unsupportedMatches.lines > 0) {
+                notes.push(`${unsupportedMatches.lines} literal match(es) exist in ` +
+                    `${unsupportedMatches.fileCount} unsupported-language file(s)` +
+                    `${languages ? ` (${languages})` : ''}; this is not a semantic zero. ` +
+                    'Use grep/ripgrep plus a language-native analyzer.');
+            } else {
+                notes.push(`UCN skipped ${index.unsupportedFiles.length} unsupported source ` +
+                    'file(s), so this is not a repository-wide semantic zero; verify with grep/ripgrep.');
+            }
+        }
         // Apply limit
         const limit = num(p.limit, undefined);
         if (limit && limit > 0) {
@@ -647,6 +1207,20 @@ const HANDLERS = {
             if (limited) notes.push(limitNote(limit, total));
             result = items;
         }
+        Object.defineProperty(result, 'findInfo', {
+            value: {
+                total: fullFindCount,
+                shown: result.length,
+                nameWideDefinitionCounts,
+            },
+            enumerable: false, writable: true, configurable: true,
+        });
+        if (unsupportedMatches) {
+            Object.defineProperty(result, 'unsupportedMatches', {
+                value: unsupportedMatches,
+                enumerable: false, writable: true, configurable: true,
+            });
+        }
         const tNote = truncationNote(index);
         if (tNote) notes.push(tNote);
         return { ok: true, result, note: notes.length ? notes.join('\n') : undefined };
@@ -656,6 +1230,8 @@ const HANDLERS = {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
+        const inErr = validateInFilter(index, p.in);
+        if (inErr) return { ok: false, error: inErr };
         const exclude = applyTestExclusions(p.exclude, p.includeTests);
         const fileErr = checkFilePatternMatch(index, p.file);
         if (fileErr) return { ok: false, error: fileErr };
@@ -675,7 +1251,11 @@ const HANDLERS = {
             codeOnly: p.codeOnly || false,
             context: num(p.context, 0),
             className: p.className,
-            file: p.file,
+            // A stable handle pins which definition is meant; it must not
+            // silently turn into a same-file-only usage scan. An explicit
+            // --file remains a deliberate scan scope.
+            file: p._fileFromHandle ? undefined : p.file,
+            definitionFile: p._fileFromHandle ? p.file : undefined,
             exclude: userExclude,
             in: p.in,
         });
@@ -705,11 +1285,44 @@ const HANDLERS = {
                     // 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,
+                    references: result.filter(u => !u.isDefinition &&
+                        !['call', 'import', 'text', 'definition'].includes(u.usageType)).length,
+                    otherDefinitions: result.filter(u => !u.isDefinition &&
+                        u.usageType === 'definition').length,
+                    text: result.filter(u => u.usageType === 'text').length,
                 },
                 enumerable: false, writable: true, configurable: true,
             });
         }
+        // Escape-hatch integrity: usages is the raw name-match view, so it
+        // must not silently omit matches in files UCN cannot parse (.rb in a
+        // mixed repo). Counts ride a note + non-enumerable field; the
+        // account-bearing commands list the actual sites.
+        const accountTools = require('./account');
+        const unsupportedMatches = accountTools.scanUnsupportedFiles(index, p.name);
+        if (unsupportedMatches.lines > 0) {
+            const langs = Object.keys(unsupportedMatches.languages).join(', ');
+            notes.push(`${unsupportedMatches.lines} line(s) in ${unsupportedMatches.fileCount} ` +
+                `unsupported-language file(s)${langs ? ` (${langs})` : ''} also match — ` +
+                'NOT analyzed by UCN; verify with grep/ripgrep.');
+            Object.defineProperty(limited, 'unsupportedMatches', {
+                value: unsupportedMatches,
+                enumerable: false, writable: true, configurable: true,
+            });
+        }
+        const failed = accountTools.scanFailedFiles(index, p.name);
+        if (failed.unparsed.lines > 0) {
+            notes.push(`${failed.unparsed.lines} matching line(s) in ${failed.unparsed.fileCount} unparsed file(s) were not classified: ${failed.unparsed.files.join(', ')}.`);
+        }
+        if (failed.unreadableFiles.length > 0) {
+            notes.push(`${failed.unreadableFiles.length} unreadable file(s) could not be searched: ${failed.unreadableFiles.join(', ')}.`);
+        }
+        if (failed.unparsed.lines > 0 || failed.unreadableFiles.length > 0) {
+            Object.defineProperty(limited, 'analysisGaps', {
+                value: failed,
+                enumerable: false, writable: true, configurable: true,
+            });
+        }
         return { ok: true, result: limited, note: notes.length ? notes.join(' ') : undefined };
     },
 
@@ -749,8 +1362,6 @@ const HANDLERS = {
                     if (remaining <= 0) {
                         if (syms.functions) syms.functions = [];
                         if (syms.classes) syms.classes = [];
-                        f.functions = 0;
-                        f.classes = 0;
                         continue;
                     }
                     const fns = syms.functions?.length || 0;
@@ -761,15 +1372,12 @@ const HANDLERS = {
                         if (syms.functions && remaining > 0) {
                             syms.functions = syms.functions.slice(0, remaining);
                             remaining -= syms.functions.length;
-                            f.functions = syms.functions.length;
                         }
                         if (syms.classes && remaining > 0) {
                             syms.classes = syms.classes.slice(0, remaining);
                             remaining -= syms.classes.length;
-                            f.classes = syms.classes.length;
                         } else if (syms.classes) {
                             syms.classes = [];
-                            f.classes = 0;
                         }
                     }
                 }
@@ -805,15 +1413,30 @@ const HANDLERS = {
                 top: topVal || 50,
             });
             if (result.meta.error) return { ok: false, error: result.meta.error };
-            return { ok: true, result, structural: true };
+            const unsupported = (!p.regex && (p.term || p.name))
+                ? require('./account').scanUnsupportedFiles(index, p.term || p.name)
+                : null;
+            let note;
+            if (unsupported?.lines > 0) {
+                Object.defineProperty(result, 'unsupportedMatches', {
+                    value: unsupported,
+                    enumerable: false, writable: true, configurable: true,
+                });
+                note = `${unsupported.lines} matching line(s) in ${unsupported.fileCount} unsupported-language file(s) were not structurally analyzed; verify with grep/ripgrep.`;
+            }
+            return { ok: true, result, structural: true, note };
         }
 
         const err = requireTerm(p.term);
         if (err) return { ok: false, error: err };
         const testsExcluded = !p.includeTests;
         const exclude = applyTestExclusions(p.exclude, p.includeTests);
-        // Use limit as top if top not set
+        // JSON is intentionally structured rather than byte-truncated, so
+        // text search needs a row bound of its own. Keep the documented
+        // default at 500 and retain total/truncated metadata for controlled
+        // expansion with an explicit top/limit.
         const topVal = num(p.top, undefined) || num(p.limit, undefined);
+        const effectiveLimit = topVal || 500;
         const result = index.search(p.term, {
             codeOnly: p.codeOnly || false,
             context: num(p.context, 0),
@@ -821,15 +1444,33 @@ const HANDLERS = {
             exclude,
             in: p.in,
             regex: p.regex,
-            top: topVal,
+            top: effectiveLimit,
             file: p.file,
         });
         if (result.meta) result.meta.testsExcluded = testsExcluded;
+        const notes = [];
+        if (!p.regex) {
+            const unsupported = require('./account').scanUnsupportedFiles(index, p.term);
+            if (unsupported.lines > 0) {
+                Object.defineProperty(result, 'unsupportedMatches', {
+                    value: unsupported,
+                    enumerable: false, writable: true, configurable: true,
+                });
+                notes.push(`${unsupported.lines} matching line(s) in ${unsupported.fileCount} unsupported-language file(s) were not searched; verify with grep/ripgrep.`);
+            }
+        }
         const tNote = truncationNote(index);
-        return { ok: true, result, ...(tNote && { note: tNote }) };
+        if (tNote) notes.push(tNote);
+        return { ok: true, result, ...(notes.length && { note: notes.join('\n') }) };
     },
 
     tests: (index, p) => {
+        const depth = num(p.depth, 0);
+        if (depth > 0) {
+            const response = HANDLERS.affectedTests(index, { ...p, depth });
+            if (response.ok) addMode(response.result, 'affected');
+            return response;
+        }
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         // tests() accepts a FILE PATH as the target ("tests helper.go" — the
@@ -844,8 +1485,12 @@ const HANDLERS = {
         if (!testsTargetIsFile) applyClassMethodSyntax(p);
         if (testsTargetIsHandle && p.line) {
             const line = Number(p.line);
+            const resolvedFile = p.file ? index.resolveFilePathForQuery(p.file) : null;
             const pinned = (index.symbols.get(p.name) || []).filter(d =>
-                d.startLine === line && (!p.file || d.relativePath?.includes(p.file)));
+                (d.startLine === line || d.nameLine === line) &&
+                (!p.file || (typeof resolvedFile === 'string'
+                    ? d.file === resolvedFile
+                    : d.relativePath?.includes(p.file))));
             if (pinned.length === 1 && !p.className && pinned[0].className) {
                 p.className = pinned[0].className;
             }
@@ -863,18 +1508,59 @@ const HANDLERS = {
                     const files = allDefs.map(d => d.relativePath).join(', ');
                     return { ok: false, error: `Symbol "${p.name}" not found in files matching "${p.file}". Defined in: ${files}` };
                 }
-                return { ok: false, error: `Symbol "${p.name}" not found.` };
+                return { ok: false, error: symbolNotFound(index, p.name) };
             }
         }
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
+        let testsResolution = null;
+        if (!testsTargetIsFile) {
+            testsResolution = index.resolveSymbol(p.name, {
+                file: p.file,
+                className: p.className,
+                line: p.line,
+            });
+            if (!testsResolution.def) return { ok: false, error: symbolNotFound(index, p.name) };
+        }
         const result = index.tests(p.name, {
             callsOnly: p.callsOnly || false,
             className: p.className,
-            file: p.file,
+            // Bare ambiguous names use the same deterministic definition as
+            // the rest of the semantic surface. The warning below discloses
+            // that choice and gives the caller a stable file= escape hatch.
+            file: p.file || testsResolution?.def?.relativePath,
             exclude: toExcludeArray(p.exclude),
         });
-        return { ok: true, result };
+        addMode(result, 'direct');
+        if (testsResolution?.warnings?.length > 0) {
+            Object.defineProperty(result, 'warnings', {
+                value: testsResolution.warnings,
+                enumerable: false, writable: true, configurable: true,
+            });
+        }
+        const testNotes = [];
+        if (result.length === 0) testNotes.push(NO_STATIC_TEST_LINK_NOTE);
+        // Mixed-language honesty: test files in unsupported languages (RSpec
+        // for a .rb service, etc.) are invisible to the static scan — say so
+        // whenever the target name occurs in unsupported files at all.
+        if (!testsTargetIsFile) {
+            const unsupportedMatches = require('./account').scanUnsupportedFiles(index, p.name);
+            if (unsupportedMatches.lines > 0) {
+                const langs = Object.keys(unsupportedMatches.languages).join(', ');
+                testNotes.push(`"${p.name}" also occurs on ${unsupportedMatches.lines} line(s) in ` +
+                    `${unsupportedMatches.fileCount} unsupported-language file(s)${langs ? ` (${langs})` : ''} — ` +
+                    'their test files are invisible to UCN; verify with grep/ripgrep.');
+                Object.defineProperty(result, 'unsupportedMatches', {
+                    value: unsupportedMatches,
+                    enumerable: false, writable: true, configurable: true,
+                });
+            }
+        }
+        return {
+            ok: true,
+            result,
+            ...(testNotes.length > 0 && { note: testNotes.join(' ') }),
+        };
     },
 
     affectedTests: (index, p) => {
@@ -892,10 +1578,11 @@ const HANDLERS = {
             ...buildCallerOptions(p),
             depth: depthVal ?? 3,
         });
-        if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
+        if (!result) return { ok: false, error: symbolNotFound(index, p.name, 'Function') };
         const note = treeNote(result);
         const tNote = truncationNote(index);
-        const combined = [note, tNote].filter(Boolean).join('\n') || undefined;
+        const selectionNote = result.testFiles.length === 0 ? NO_STATIC_TEST_LINK_NOTE : null;
+        const combined = [note, tNote, selectionNote].filter(Boolean).join('\n') || undefined;
         return { ok: true, result, ...(combined && { note: combined }) };
     },
 
@@ -929,6 +1616,11 @@ 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;
+            if (result.excludedRuntimeContract != null) sliced.excludedRuntimeContract = result.excludedRuntimeContract;
+            if (result.excludedDynamicDispatch != null) sliced.excludedDynamicDispatch = result.excludedDynamicDispatch;
+            if (result.pythonImplicitExportFiles != null) sliced.pythonImplicitExportFiles = result.pythonImplicitExportFiles;
+            if (result.computedDispatch != null) sliced.computedDispatch = result.computedDispatch;
+            if (result.coverage != null) sliced.coverage = result.coverage;
             // 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.
@@ -951,26 +1643,53 @@ const HANDLERS = {
         // Rust #[test], etc.) — show them by default. Previously this command
         // applied addTestExclusions() unconditionally, which stripped Java
         // *Tests.java entries while letting Rust #[test] through (asymmetric).
-        // Now consistent: default = include test entries; user opts out via
-        // --exclude-tests (or --include-tests=false for back-compat).
+        // Tests are excluded by default, matching search/usages/deadcode —
+        // an agent orienting via entrypoints needs the routes that describe
+        // the project, not every fixture route under test/. --include-tests
+        // restores the full universe; --exclude-tests stays accepted as the
+        // explicit spelling of the default. Internal consumers (reachability
+        // seeding, check's orphan detection) call detectEntrypoints directly
+        // and always see the full universe.
         const userExclude = Array.isArray(p.exclude)
             ? p.exclude
             : (p.exclude ? p.exclude.split(',').map(s => s.trim()).filter(Boolean) : []);
-        const wantsExcludeTests = p.excludeTests === true || p.includeTests === false;
-        const exclude = wantsExcludeTests ? addTestExclusions(userExclude) : userExclude;
-        let result = detectEntrypoints(index, {
+        const exclude = p.includeTests === true
+            ? userExclude
+            : addTestExclusions(userExclude);
+        const fullResult = detectEntrypoints(index, {
             type: p.type,
             framework: p.framework,
             file: p.file,
-            exclude,
+            exclude: userExclude,
         });
+        if (fullResult && fullResult.error) {
+            return { ok: false, error: fullResult.message || fullResult.error };
+        }
+        let result = p.includeTests === true
+            ? fullResult
+            : detectEntrypoints(index, {
+                type: p.type,
+                framework: p.framework,
+                file: p.file,
+                exclude,
+            });
         if (result && result.error) {
             return { ok: false, error: result.message || result.error };
         }
+        const hiddenTests = p.includeTests === true || !Array.isArray(fullResult)
+            ? 0
+            : Math.max(0, fullResult.length - result.length);
+        Object.defineProperty(result, 'filterInfo', {
+            value: { hiddenTests, testsIncluded: p.includeTests === true },
+            enumerable: false, writable: true, configurable: true,
+        });
         const limit = num(p.limit, undefined);
-        let note;
+        let note = hiddenTests > 0
+            ? `${hiddenTests} test-path entry point(s) hidden by default. Use --include-tests to include them.`
+            : undefined;
         if (limit && limit > 0 && Array.isArray(result) && result.length > limit) {
-            note = limitNote(limit, result.length);
+            const limitMessage = limitNote(limit, result.length);
+            note = note ? `${note}\n${limitMessage}` : limitMessage;
             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
@@ -979,6 +1698,10 @@ const HANDLERS = {
                 value: { total: result.length, shown: limit },
                 enumerable: false, writable: true, configurable: true,
             });
+            Object.defineProperty(sliced, 'filterInfo', {
+                value: result.filterInfo,
+                enumerable: false, writable: true, configurable: true,
+            });
             result = sliced;
         }
         return { ok: true, result, note };
@@ -1016,6 +1739,27 @@ const HANDLERS = {
             prefix: p.prefix || null,
             showUncertain: !p.hideUncertain,
         });
+        if (p.framework != null && String(p.framework).trim() !== '') {
+            const framework = String(p.framework).trim().toLowerCase();
+            const known = new Set([
+                'actix', 'aspnet', 'aspnet-minimal', 'axios', 'axum',
+                'dotnet-httpclient', 'express', 'fastapi', 'fetch', 'flask',
+                'go-http', 'jax-rs', 'nestjs', 'nextjs', 'requests',
+                'reqwest', 'spring', 'spring-client', 'unknown-python',
+            ]);
+            if (!known.has(framework)) {
+                return {
+                    ok: false,
+                    error: `Invalid --framework value: "${p.framework}". Valid: ${[...known].join(', ')}.`,
+                };
+            }
+            result.routes = result.routes.filter(route => route.framework === framework);
+            result.requests = result.requests.filter(request => request.framework === framework);
+            result.bridges = result.bridges.filter(bridge =>
+                bridge.route.framework === framework || bridge.request.framework === framework);
+            result.unmatchedRoutes = result.unmatchedRoutes.filter(route => route.framework === framework);
+            result.unmatchedRequests = result.unmatchedRequests.filter(request => request.framework === framework);
+        }
         // Apply --file pattern as an additional filter on routes/requests
         if (p.file) {
             const sub = String(p.file);
@@ -1030,9 +1774,7 @@ const HANDLERS = {
         // Apply --exclude patterns to route/request files (deadcode-style boundary matching)
         const exclude = toExcludeArray(p.exclude);
         if (exclude.length > 0) {
-            const regexes = exclude.map(pat =>
-                new RegExp('(^|[/._-])' + pat + 's?([/._-]|$)', 'i'));
-            const matches = (file) => regexes.some(rx => rx.test(file));
+            const matches = (file) => !index.matchesFilters(file, { exclude });
             result.routes = result.routes.filter(r => !matches(r.file));
             result.requests = result.requests.filter(r => !matches(r.file));
             result.bridges = result.bridges.filter(b => !matches(b.route.file) && !matches(b.request.file));
@@ -1074,6 +1816,8 @@ const HANDLERS = {
         // suppress the "Matched" section in unmatched-only mode.)
         result._bridge = wantBridge;
         result._unmatched = wantUnmatched;
+        result._serverOnly = !!p.serverOnly;
+        result._clientOnly = !!p.clientOnly;
         return { ok: true, result, note };
     },
 
@@ -1100,6 +1844,11 @@ const HANDLERS = {
 
         const entries = [];
         const notes = [];
+        const maxLines = num(p.maxLines, null);
+        if (p.maxLines != null &&
+            (maxLines === null || !Number.isInteger(maxLines) || maxLines < 1)) {
+            return { ok: false, error: '--max-lines must be a positive integer.' };
+        }
 
         for (const fnName of fnNames) {
             // For comma-separated names, each may have Class.method syntax
@@ -1131,10 +1880,10 @@ const HANDLERS = {
                     {
                     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.`);
+                    notes.push(`"${fnName}" is ${article} ${kind}, not a function. Use \`source ${fnName}\` to extract it.`);
                 }
                 } 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.`);
+                    notes.push(`"${fnName}" is a macro. Use \`source <file>:<start>-<end>\` for its body.`);
                 } else {
                     notes.push(`Function "${fnName}" not found.`);
                 }
@@ -1155,8 +1904,14 @@ const HANDLERS = {
             // 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 });
+                    const fullCode = readAndExtract(m);
+                    const totalLines = m.endLine - m.startLine + 1;
+                    const truncated = !!maxLines && totalLines > maxLines;
+                    const code = truncated
+                        ? fullCode.split('\n').slice(0, maxLines).join('\n')
+                        : fullCode;
+                    entries.push({ match: m, code, totalLines, truncated,
+                        shownLines: truncated ? maxLines : totalLines });
                 }
                 continue;
             }
@@ -1172,8 +1927,14 @@ const HANDLERS = {
                 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);
-            entries.push({ match, code });
+            const fullCode = readAndExtract(match);
+            const totalLines = match.endLine - match.startLine + 1;
+            const truncated = !!maxLines && totalLines > maxLines;
+            const code = truncated
+                ? fullCode.split('\n').slice(0, maxLines).join('\n')
+                : fullCode;
+            entries.push({ match, code, totalLines, truncated,
+                shownLines: truncated ? maxLines : totalLines });
         }
 
         if (entries.length === 0 && notes.length > 0) {
@@ -1209,9 +1970,9 @@ const HANDLERS = {
             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 — "${p.name}" is a ${fnMatches[0].type}. Use \`source ${p.name}\` instead.` };
             }
-            return { ok: false, error: `Class "${p.name}" not found.` };
+            return { ok: false, error: symbolNotFound(index, p.name, 'Class') };
         }
 
         const entries = [];
@@ -1253,7 +2014,7 @@ const HANDLERS = {
 
         // Large class summary mode (>200 lines, no maxLines)
         if (totalLines > 200 && !maxLines) {
-            const methods = index.findMethodsForType(match.name);
+            const methods = index.findMethodsForType(match.name, match);
             entries.push({ match, code: null, methods, totalLines, summaryMode: true, truncated: false });
             return { ok: true, result: { entries }, note: notes.length ? notes.map(n => 'Note: ' + n).join('\n') : undefined };
         }
@@ -1301,7 +2062,7 @@ const HANDLERS = {
         // 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);
+        const resolveErr = checkFileError(typeof resolved === 'string' ? null : resolved, p.file, index);
         if (resolveErr) return { ok: false, error: resolveErr };
         const filePath = resolved;
 
@@ -1342,7 +2103,7 @@ const HANDLERS = {
         const err = requireFile(p.file);
         if (err) return { ok: false, error: err };
         const result = index.imports(p.file);
-        const fileErr = checkFileError(result, p.file);
+        const fileErr = checkFileError(result, p.file, index);
         if (fileErr) return { ok: false, error: fileErr };
         return { ok: true, result };
     },
@@ -1351,7 +2112,7 @@ const HANDLERS = {
         const err = requireFile(p.file);
         if (err) return { ok: false, error: err };
         const result = index.exporters(p.file);
-        const fileErr = checkFileError(result, p.file);
+        const fileErr = checkFileError(result, p.file, index);
         if (fileErr) return { ok: false, error: fileErr };
         return { ok: true, result };
     },
@@ -1360,7 +2121,7 @@ const HANDLERS = {
         const err = requireFile(p.file);
         if (err) return { ok: false, error: err };
         const result = index.fileExports(p.file);
-        const fileErr = checkFileError(result, p.file);
+        const fileErr = checkFileError(result, p.file, index);
         if (fileErr) return { ok: false, error: fileErr };
         return { ok: true, result };
     },
@@ -1375,7 +2136,7 @@ const HANDLERS = {
         if (result && result.error === 'invalid-direction') {
             return { ok: false, error: result.message };
         }
-        const fileErr = checkFileError(result, p.file);
+        const fileErr = checkFileError(result, p.file, index);
         if (fileErr) return { ok: false, error: fileErr };
         return { ok: true, result };
     },
@@ -1418,7 +2179,7 @@ const HANDLERS = {
             ...(p.includeUncertain !== undefined && { includeUncertain: p.includeUncertain }),
         });
         if (result && result.found === false) {
-            return { ok: false, error: `Function "${p.name}" not found.` };
+            return { ok: false, error: symbolNotFound(index, p.name, 'Function') };
         }
         return { ok: true, result };
     },
@@ -1447,8 +2208,9 @@ const HANDLERS = {
             ...(p.line && { line: p.line }),
         });
         if (result && result.found === false) {
-            return { ok: false, error: `Function "${p.name}" not found.` };
+            return { ok: false, error: symbolNotFound(index, p.name, 'Function') };
         }
+        if (result && result.error) return { ok: false, error: result.error };
         return { ok: true, result };
     },
 
@@ -1460,9 +2222,21 @@ const HANDLERS = {
         });
         const limit = num(p.limit, undefined);
         let note;
-        if (limit && limit > 0 && result && result.changed && result.changed.length > limit) {
-            note = limitNote(limit, result.changed.length);
-            result = { ...result, changed: result.changed.slice(0, limit) };
+        if (limit && limit > 0 && result) {
+            const groups = ['functions', 'moduleLevelChanges', 'newFunctions', 'deletedFunctions'];
+            const total = groups.reduce((sum, key) => sum + (result[key]?.length || 0), 0);
+            if (total > limit) {
+                let remaining = limit;
+                const limited = { ...result };
+                for (const key of groups) {
+                    const values = result[key] || [];
+                    limited[key] = values.slice(0, Math.max(0, remaining));
+                    remaining -= limited[key].length;
+                }
+                limited.limitInfo = { total, shown: limit };
+                result = limited;
+                note = limitNote(limit, total);
+            }
         }
         return { ok: true, result, note };
     },
@@ -1477,7 +2251,13 @@ 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 result = index.typedef(p.name, { exact: p.exact || false, className: p.className, file: p.file });
+        const result = index.typedef(p.name, {
+            exact: p.exact || false,
+            className: p.className,
+            file: p.file,
+            exclude: applyTestExclusions(p.exclude, p.includeTests),
+            in: p.in,
+        });
         return { ok: true, result };
     },
 
@@ -1494,9 +2274,21 @@ const HANDLERS = {
             const fileErr = checkFilePatternMatch(index, p.file);
             if (fileErr) return { ok: false, error: fileErr };
         }
-        let result = index.api(p.file);
+        if (p.in) {
+            let anyIn = false;
+            for (const [, fileEntry] of index.files) {
+                if (index.matchesFilters(fileEntry.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.api(p.file, { in: p.in });
         if (p.file) {
-            const fileErr = checkFileError(result, p.file);
+            const fileErr = checkFileError(result, p.file, index);
             if (fileErr) return { ok: false, error: fileErr };
         }
         // Apply limit to api results (api returns an array)
@@ -1504,6 +2296,7 @@ const HANDLERS = {
         let note;
         if (limit && limit > 0 && Array.isArray(result)) {
             const { items, total, limited } = applyLimit(result, limit);
+            const apiInfo = result.apiInfo;
             if (limited) {
                 note = limitNote(limit, total);
                 // Full-set size travels with the payload for --json
@@ -1513,6 +2306,12 @@ const HANDLERS = {
                     enumerable: false, writable: true, configurable: true,
                 });
             }
+            if (apiInfo) {
+                Object.defineProperty(items, 'apiInfo', {
+                    value: apiInfo,
+                    enumerable: false, writable: true, configurable: true,
+                });
+            }
             result = items;
         }
         return { ok: true, result, note };
@@ -1565,6 +2364,9 @@ const HANDLERS = {
             functions: p.functions || false,
             hot: p.hot || false,
             top,
+            file: p.file,
+            in: p.in,
+            exclude: toExcludeArray(p.exclude),
         });
         return note ? { ok: true, result, note } : { ok: true, result };
     },
@@ -1601,7 +2403,7 @@ const HANDLERS = {
                 const scopeHint = p.symbolName ? ` (from context for "${p.symbolName}")` : '';
                 return { ok: false, error: `Item ${p.itemNum} not found${scopeHint}. Available: 1-${p.itemCount}` };
             }
-            return { ok: false, error: 'No expandable items. Run context first.' };
+            return { ok: false, error: 'No expandable items. Run show first.' };
         }
         const rendered = renderExpandItem(p.match, index.root, { validateRoot: p.validateRoot || false });
         if (!rendered.ok) return { ok: false, error: rendered.error };
@@ -1634,6 +2436,10 @@ function execute(index, command, params = {}) {
     // normalizers and returned wrong not-found answers).
     params = { ...params };
     try {
+        if (PUBLIC_COMMAND_SET.has(command)) {
+            const validationError = validatePublicParams(command, params);
+            if (validationError) return { ok: false, error: validationError };
+        }
         // Resolve name-less handles (e.g. `lib.js:42`) via index lookup before dispatch.
         // Handles WITH a name suffix are handled later by applyClassMethodSyntax.
         if (params && params.name && looksLikeHandle(params.name)) {
@@ -1673,4 +2479,4 @@ function lookupByLocation(index, file, line) {
     return null;
 }
 
-module.exports = { execute };
+module.exports = { execute, validatePublicParams };