ucn 4.0.2 → 4.1.0

package/cli/index.js

@@ -221,7 +221,7 @@ function parseFlags(tokens) {
         addParam: getValueFlag('--add-param'),
         removeParam: getValueFlag('--remove-param'),
         renameTo: getValueFlag('--rename-to'),
-        defaultValue: getValueFlag('--default'),
+        defaultValue: getValueFlag('--default-value') ?? getValueFlag('--default'),
         base: getValueFlag('--base'),
         staged: tokens.includes('--staged') || undefined,
         deep: tokens.includes('--deep') || undefined,
@@ -234,6 +234,9 @@ function parseFlags(tokens) {
         diverse: tokens.includes('--diverse') || undefined,
         git: tokens.includes('--git') || undefined,
         className: getValueFlag('--class-name'),
+        // Explicit line pin (fix #249: our own disambiguation notes advertise
+        // line= but no surface accepted it).
+        line: parseInt(getValueFlag('--line') || '0', 10) || undefined,
         limit: parseInt(getValueFlag('--limit') || '0') || undefined,
         limitRaw: getValueFlag('--limit'),
         maxFiles: parseInt(getValueFlag('--max-files') || '0') || undefined,
@@ -286,11 +289,11 @@ const knownFlags = new Set([
     '--no-cache', '--clear-cache', '--include-tests', '--exclude-tests',
     '--include-exported', '--include-decorated', '--expand', '--interactive', '-i', '--all', '--include-methods', '--no-include-methods', '--include-uncertain', '--expand-unverified', '--detailed', '--calls-only',
     '--file', '--context', '--exclude', '--not', '--in',
-    '--depth', '--direction', '--add-param', '--remove-param', '--rename-to',
+    '--depth', '--direction', '--add-param', '--remove-param', '--rename-to', '--default-value',
     '--default', '--top', '--no-follow-symlinks',
     '--base', '--staged', '--stack',
     '--regex', '--no-regex', '--functions', '--hot', '--diverse', '--git',
-    '--max-lines', '--class-name', '--limit', '--max-files',
+    '--max-lines', '--class-name', '--line', '--limit', '--max-files',
     '--type', '--param', '--receiver', '--returns', '--decorator', '--exported', '--unused',
     '--hide-confidence', '--no-confidence', '--min-confidence', '--unreachable-only',
     '--framework', '--workers', '--deep', '--compact',
@@ -344,8 +347,8 @@ try {
 // Value flags that consume the next token (space form: --flag value)
 const VALUE_FLAGS = new Set([
     '--file', '--depth', '--top', '--context', '--direction',
-    '--add-param', '--remove-param', '--rename-to', '--default',
-    '--base', '--exclude', '--not', '--in', '--max-lines', '--class-name',
+    '--add-param', '--remove-param', '--rename-to', '--default', '--default-value',
+    '--base', '--exclude', '--not', '--in', '--max-lines', '--class-name', '--line',
     '--type', '--param', '--receiver', '--returns', '--decorator',
     '--limit', '--max-files', '--min-confidence', '--stack', '--framework',
     '--workers', '--method', '--prefix'
@@ -398,30 +401,40 @@ function printOutput(result, jsonFn, textFn) {
 }
 
 /**
- * Print inline 3-line code previews for each callee (--expand support).
- * Used by context in project, interactive, and glob modes.
+ * Print inline 3-line code previews for context items (--expand support).
+ * Used by context in project, interactive, and glob modes. Previews both
+ * directions with attribution headers (fix #252: callees only — the flag
+ * was a silent no-op for caller-only contexts, and the unlabeled preview
+ * rendered detached from the item it expanded).
  */
 function printInlineExpand(ctx, root) {
-    if (!root || !ctx || !ctx.callees) return;
-    for (const c of ctx.callees) {
-        if (c.relativePath && c.startLine) {
-            try {
-                const filePath = path.join(root, c.relativePath);
-                const content = fs.readFileSync(filePath, 'utf-8');
-                const codeLines = content.split('\n');
-                const endLine = c.endLine || c.startLine + 5;
-                const previewLines = Math.min(3, endLine - c.startLine + 1);
-                for (let i = 0; i < previewLines && c.startLine - 1 + i < codeLines.length; i++) {
-                    console.log(`      │ ${codeLines[c.startLine - 1 + i]}`);
-                }
-                if (endLine - c.startLine + 1 > 3) {
-                    console.log(`      │ ... (${endLine - c.startLine - 2} more lines)`);
-                }
-            } catch (e) {
-                // Skip on error
+    if (!root || !ctx) return;
+    const preview = (c, label) => {
+        // Caller entries locate the enclosing FUNCTION via callerStartLine;
+        // callee entries are definitions with startLine.
+        const startLine = label === 'caller' ? c.callerStartLine : c.startLine;
+        const endLine = label === 'caller'
+            ? (c.callerEndLine || (startLine ? startLine + 5 : null))
+            : (c.endLine || (startLine ? startLine + 5 : null));
+        if (!c.relativePath || !startLine) return;
+        try {
+            const filePath = path.join(root, c.relativePath);
+            const content = fs.readFileSync(filePath, 'utf-8');
+            const codeLines = content.split('\n');
+            console.log(`      ┌ ${label}: ${c.name || c.callerName || '(anonymous)'} — ${c.relativePath}:${startLine}`);
+            const previewLines = Math.min(3, endLine - startLine + 1);
+            for (let i = 0; i < previewLines && startLine - 1 + i < codeLines.length; i++) {
+                console.log(`      │ ${codeLines[startLine - 1 + i]}`);
+            }
+            if (endLine - startLine + 1 > 3) {
+                console.log(`      │ ... (${endLine - startLine - 2} more lines)`);
             }
+        } catch (e) {
+            // Skip on error
         }
-    }
+    };
+    for (const c of ctx.callers || []) preview(c, 'caller');
+    for (const c of ctx.callees || []) preview(c, 'callee');
 }
 
 // ============================================================================
@@ -460,21 +473,74 @@ function main() {
         target = positionalArgs[0];
         command = positionalArgs[1] || 'toc';
         arg = positionalArgs[2];
+        // lines takes `<file> <range>` as two positionals (fix #252 —
+        // the extra token was silently dropped and the command then
+        // demanded a --file the user had plainly given).
+        if (command === 'lines' && positionalArgs.length > 3) {
+            arg = positionalArgs.slice(2).join(' ');
+        }
     }
 
-    // Determine mode: single file, glob pattern, or project
-    if (target === '.' || (fs.existsSync(target) && fs.statSync(target).isDirectory())) {
-        // Project mode
-        runProjectCommand(target, command, arg);
-    } else if (target.includes('*') || target.includes('{')) {
-        // Glob pattern mode
-        runGlobCommand(target, command, arg);
-    } else if (fs.existsSync(target)) {
-        // Single file mode
-        runFileCommand(target, command, arg);
-    } else {
-        console.error(`Error: "${target}" not found`);
-        process.exit(1);
+    // Determine mode: single file, glob pattern, or project.
+    // CommandError is the fail() control-flow signal — project mode catches
+    // it internally, but file/glob mode errors used to escape main() and
+    // dump a raw stack trace after the message (fix #249).
+    try {
+        if (target === '.' || (fs.existsSync(target) && fs.statSync(target).isDirectory())) {
+            // Project mode
+            runProjectCommand(target, command, arg);
+        } else if (target.includes('*') || target.includes('{')) {
+            // Glob pattern mode
+            runGlobCommand(target, command, arg);
+        } else if (fs.existsSync(target)) {
+            // Single file mode
+            runFileCommand(target, command, arg);
+        } else {
+            console.error(`Error: "${target}" not found`);
+            process.exit(1);
+        }
+    } catch (e) {
+        if (!(e instanceof CommandError)) {
+            console.error(`Error: ${e.message}`);
+        }
+        process.exitCode = 1;
+    }
+}
+
+/**
+ * Parse the lines command's target forms (fix #252: `lines main.ts 1-10`
+ * silently dropped the second positional and demanded a --file that was
+ * plainly given): `<range>` (+ --file), `<file> <range>`, `<file>:<range>`.
+ */
+function parseLinesTarget(arg, fileFlag) {
+    let file = fileFlag;
+    let range = arg;
+    const parts = String(arg || '').trim().split(/\s+/);
+    if (parts.length === 2 && /^\d+(-\d+)?$/.test(parts[1])) {
+        file = parts[0];
+        range = parts[1];
+    } else if (!/^\d+(-\d+)?$/.test(range)) {
+        const m = String(range).match(/^(.+):(\d+(?:-\d+)?)$/);
+        if (m) { file = m[1]; range = m[2]; }
+    }
+    return { file, range };
+}
+
+/**
+ * Tiered-output contract notes: unverified callers are always shown for
+ * these commands, so the legacy reveal flags are implied no-ops. Shared by
+ * one-shot and interactive mode (fix #250 — interactive printed nothing).
+ */
+function printTieredNoOpNotes(canonical, flags, print) {
+    if (!['about', 'context', 'impact', 'trace', 'blast', 'reverseTrace', 'affectedTests', 'verify', 'smart'].includes(canonical)) return;
+    if (flags.includeUncertain) {
+        print(`Note: --include-uncertain has no effect on '${toCliName(canonical)}' — unverified candidates are always shown (tiered).`);
+    }
+    if (['impact', 'verify', 'blast', 'reverseTrace', 'affectedTests'].includes(canonical) && flags.includeMethods) {
+        print(`Note: --include-methods has no effect on '${toCliName(canonical)}' — method calls are always tiered by receiver evidence.`);
+    }
+    if (['about', 'context', 'smart'].includes(canonical) && flags.includeMethods) {
+        print(`Note: --include-methods on '${toCliName(canonical)}' affects only method-callee display for standalone-function targets — caller tiers are always evidence-based, and method targets analyze method calls by default.`);
     }
 }
 
@@ -546,7 +612,7 @@ function runFileCommand(filePath, command, arg) {
         case 'toc':
             printOutput(result, output.formatTocJson, r => output.formatToc(r, {
                 detailedHint: 'Add --detailed to list all functions, or "ucn . about <name>" for full details on a symbol',
-                uncertainHint: 'use --include-uncertain to include all'
+                uncertainHint: 'run "ucn . about <name>" for tiered detail on a specific symbol'
             }));
             break;
         case 'find':
@@ -660,16 +726,8 @@ function runProjectCommand(rootDir, command, arg) {
                 console.error(`Warning: ${flagToCli(key)} has no effect on '${toCliName(canonical)}'.`);
             }
         }
-        // Tiered-output contract: unverified callers are always shown for
-        // these commands, so the legacy reveal flags are implied no-ops.
-        if (['about', 'context', 'impact', 'trace', 'blast', 'reverseTrace', 'affectedTests'].includes(canonical)) {
-            if (flags.includeUncertain) {
-                console.error(`Note: --include-uncertain is implied for '${toCliName(canonical)}' — unverified candidates are always shown (tiered).`);
-            }
-            if (['about', 'context', 'impact'].includes(canonical) && flags.includeMethods) {
-                console.error(`Note: --include-methods is implied for '${toCliName(canonical)}' — method calls are tiered by receiver evidence.`);
-            }
-        }
+        // Tiered-output contract notes (shared with interactive mode).
+        printTieredNoOpNotes(canonical, flags, (m) => console.error(m));
     }
 
     switch (canonical) {
@@ -681,7 +739,7 @@ function runProjectCommand(rootDir, command, arg) {
             if (note) console.error(note);
             printOutput(result, output.formatTocJson, r => output.formatToc(r, {
                 detailedHint: 'Add --detailed to list all functions, or "ucn . about <name>" for full details on a symbol',
-                uncertainHint: 'use --include-uncertain to include all'
+                uncertainHint: 'run "ucn . about <name>" for tiered detail on a specific symbol'
             }));
             break;
         }
@@ -735,9 +793,7 @@ function runProjectCommand(rootDir, command, arg) {
                 console.log(output.formatContextJson(ctx));
             } else {
                 const { text, expandable } = output.formatContext(ctx, {
-                    methodsHint: 'Note: obj.method() calls excluded — use --include-methods to include them',
                     expandHint: 'Use "expand <N>" or --expand to see code for items',
-                    uncertainHint: 'use --include-uncertain to include all',
                     showConfidence: flags.showConfidence !== false,
                     compact: !!flags.compact,
                 });
@@ -757,10 +813,12 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'expand': {
             requireArg(arg, 'Usage: ucn . expand <N>\nFirst run "ucn . context <name>" to get numbered items');
-            const expandNum = parseInt(arg);
-            if (isNaN(expandNum)) {
+            // Whole-token integers only (fix #248: parseInt truncation made
+            // `expand 1abc` and `expand 2.5` silently expand items 1 and 2).
+            if (!/^\d+$/.test(String(arg).trim())) {
                 fail(`Invalid item number: "${arg}"`);
             }
+            const expandNum = parseInt(arg, 10);
             const cached = loadExpandableItems(index.root);
             const items = cached?.items || [];
             const match = items.find(i => i.num === expandNum);
@@ -798,7 +856,7 @@ function runProjectCommand(rootDir, command, arg) {
             const { ok, result, error, note } = execute(index, 'smart', { name: arg, ...flags });
             if (!ok) fail(error);
             printOutput(result, output.formatSmartJson, r => output.formatSmart(r, {
-                uncertainHint: 'use --include-uncertain to include all'
+                uncertainHint: 'unverified callees are listed below with reasons'
             }));
             if (note) console.error(note);
             break;
@@ -878,7 +936,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'brief': {
             requireArg(arg, 'Usage: ucn . brief <name>');
-            const { ok, result, error } = execute(index, 'brief', { name: arg, file: flags.file, className: flags.className, git: flags.git });
+            const { ok, result, error } = execute(index, 'brief', { name: arg, file: flags.file, className: flags.className, line: flags.line, git: flags.git });
             if (!ok) fail(error);
             printOutput(result, output.formatBriefJson, output.formatBrief);
             break;
@@ -894,6 +952,14 @@ function runProjectCommand(rootDir, command, arg) {
             break;
         }
 
+        case 'orient': {
+            const topVal = flags.topRaw != null ? flags.topRaw : (flags.top || undefined);
+            const { ok, result, error } = execute(index, 'orient', { top: topVal });
+            if (!ok) fail(error);
+            printOutput(result, output.formatOrientJson, output.formatOrient);
+            break;
+        }
+
         case 'check': {
             const { ok, result, error } = execute(index, 'check', {
                 base: flags.base, staged: flags.staged,
@@ -908,7 +974,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'fn': {
             requireArg(arg, 'Usage: ucn . fn <name>');
-            const { ok, result, error, note } = execute(index, 'fn', { name: arg, file: flags.file, all: flags.all, className: flags.className });
+            const { ok, result, error, note } = execute(index, 'fn', { name: arg, file: flags.file, all: flags.all, className: flags.className, line: flags.line });
             if (!ok) fail(error);
             if (note) console.error(note);
             printOutput(result, output.formatFnResultJson, output.formatFnResult);
@@ -917,7 +983,7 @@ function runProjectCommand(rootDir, command, arg) {
 
         case 'class': {
             requireArg(arg, 'Usage: ucn . class <name>');
-            const { ok, result, error, note } = execute(index, 'class', { name: arg, file: flags.file, all: flags.all, maxLines: flags.maxLines });
+            const { ok, result, error, note } = execute(index, 'class', { name: arg, file: flags.file, all: flags.all, maxLines: flags.maxLines, line: flags.line });
             if (!ok) fail(error);
             if (note) console.error(note);
             printOutput(result, output.formatClassResultJson, output.formatClassResult);
@@ -925,8 +991,9 @@ function runProjectCommand(rootDir, command, arg) {
         }
 
         case 'lines': {
-            requireArg(arg, 'Usage: ucn . lines <range> --file <path>');
-            const { ok, result, error, note } = execute(index, 'lines', { file: flags.file, range: arg });
+            requireArg(arg, 'Usage: ucn . lines <range> --file <path> (or: lines <file> <range>)');
+            const linesTarget = parseLinesTarget(arg, flags.file);
+            const { ok, result, error, note } = execute(index, 'lines', { file: linesTarget.file, range: linesTarget.range });
             if (!ok) fail(error);
             if (note) console.error(note);
             printOutput(result, output.formatLinesJson, r => output.formatLines(r));
@@ -1052,7 +1119,7 @@ function runProjectCommand(rootDir, command, arg) {
                 r => output.formatDeadcode(r, {
                     top: flags.top,
                     decoratedHint: !flags.includeDecorated && result.excludedDecorated > 0 ? `${result.excludedDecorated} decorated/annotated symbol(s) hidden (framework-registered). Use --include-decorated to include them.` : undefined,
-                    exportedHint: !flags.includeExported && result.excludedExported > 0 ? `${result.excludedExported} exported symbol(s) excluded (all have callers). Use --include-exported to audit them.` : undefined,
+                    exportedHint: !flags.includeExported && result.excludedExported > 0 ? `${result.excludedExported} exported symbol(s) excluded from the audit (public API may have external callers). Use --include-exported to audit them.` : undefined,
                     externalContractHint: !flags.includeExported && result.excludedExternalContract > 0 ? `${result.excludedExternalContract} symbol(s) hidden (override an out-of-tree base class — reachable via external contract, not dead). Use --include-exported to include them.` : undefined
                 })
             );
@@ -1329,8 +1396,6 @@ function runGlobCommand(pattern, command, arg) {
                 console.log(output.formatContextJson(result));
             } else {
                 const { text } = output.formatContext(result, {
-                    methodsHint: 'Note: obj.method() calls excluded — use --include-methods to include them',
-                    uncertainHint: 'use --include-uncertain to include all',
                     expandHint: 'Use --expand to see inline callee previews',
                     showConfidence: flags.showConfidence !== false,
                     compact: !!flags.compact,
@@ -1506,7 +1571,7 @@ FILE DEPENDENCIES
 ═══════════════════════════════════════════════════════════════════════════════
 REFACTORING HELPERS
 ═══════════════════════════════════════════════════════════════════════════════
-  plan <name>         Preview refactoring (--add-param, --remove-param, --rename-to)
+  plan <name>         Preview refactoring (--add-param, --remove-param, --rename-to, --default-value)
   verify <name>       Check all call sites match signature
   diff-impact         What changed in git diff and who calls it (--base, --staged)
   check               Pre-commit summary: diff-impact + verify + affected-tests in one shot
@@ -1523,6 +1588,7 @@ OTHER
   typedef <name>      Find type definitions
   stats               Project statistics (--functions for per-function line counts, --hot for top callers)
   doctor              Project trust report (counts, blind spots, parse failures, verdict; --deep for resolution coverage)
+  orient              One-screen repo orientation: size, top dirs, hot functions, entry points, trust verdict (--top=N)
   stacktrace <text>   Parse stack trace, show code at each frame (alias: stack)
   audit-async         Find calls in async functions that are likely missing await (JS/TS/Python)
 
@@ -1545,11 +1611,11 @@ Common Flags:
   --include-tests     Include test files in usage counts (about) and results (find, usages, deadcode)
   --exclude-tests     Exclude test files (entrypoints — tests are included by default)
   --class-name=X      Scope to specific class (e.g., --class-name=Repository)
-  --include-methods   Include method calls (obj.fn) in trace/blast/smart/verify analysis
-                        (implied for about/context/impact — method calls are tiered by evidence)
-  --include-uncertain Include ambiguous/uncertain matches in smart/verify
-                        (implied for about/context/impact/trace/blast/reverse-trace/affected-tests —
-                        unverified candidates always shown, tiered)
+  --include-methods   Include method-call (obj.fn) callee expansion in trace/smart
+                        (no effect on caller-direction commands — about/context/impact/verify/
+                        blast/reverse-trace/affected-tests always tier method calls by evidence)
+  --include-uncertain No effect on tiered commands — unverified candidates are always
+                        shown in their own section with reasons
   --expand-unverified Follow unverified caller edges in blast/reverse-trace trees
                         (downstream nodes marked as unverified chains — possible, not confirmed, impact)
   --hide-confidence   Hide confidence scores (shown by default in about, context)
@@ -1587,6 +1653,7 @@ Common Flags:
   -v, --version       Print the UCN version and exit
 
 Quick Start:
+  ucn orient                          # First look at a new repo
   ucn toc                             # See project structure
   ucn about handleRequest             # Understand a function
   ucn impact handleRequest            # Before modifying
@@ -1604,9 +1671,26 @@ function runInteractive(rootDir) {
 
     console.log('Building index...');
     const index = new ProjectIndex(rootDir);
-    index.build(null, { quiet: true, workers: flags.workers });
+    // Same cache discipline as one-shot mode (fix #250: the REPL fully
+    // re-parsed every session and never consumed cache-persisted state —
+    // the divergence mechanism behind the relocation P1).
+    let iCacheFresh = false;
+    if (flags.cache && !flags.clearCache) {
+        const loaded = index.loadCache();
+        iCacheFresh = loaded && !index.isCacheStale();
+        if (!iCacheFresh && loaded) {
+            index.build(null, { quiet: true, forceRebuild: true, workers: flags.workers });
+        } else if (!iCacheFresh) {
+            index.build(null, { quiet: true, workers: flags.workers });
+        }
+        if (!iCacheFresh) {
+            try { index.saveCache(); } catch (_) { /* best-effort */ }
+        }
+    } else {
+        index.build(null, { quiet: true, workers: flags.workers });
+    }
     const iExpandCache = new ExpandCache({ maxSize: 20 });
-    console.log(`Index ready: ${index.files.size} files, ${index.symbols.size} symbols`);
+    console.log(`Index ready: ${index.files.size} files, ${index.symbols.size} unique symbol names`);
     console.log('Type commands (e.g., "find parseFile", "about main", "toc")');
     console.log('Type "help" for commands, "quit" to exit\n');
 
@@ -1662,7 +1746,7 @@ Commands:
   typedef <name>         Find type definitions
   deadcode               Find unused functions/classes
   verify <name>          Check call sites match signature
-  plan <name>            Preview refactoring (--add-param=, --remove-param=, --rename-to=)
+  plan <name>            Preview refactoring (--add-param=, --remove-param=, --rename-to=, --default-value=)
   stacktrace <text>      Parse a stack trace
   api                    Show public symbols
   diff-impact            What changed and who's affected
@@ -1681,7 +1765,7 @@ Flags can be added per-command: context myFunc --include-methods
             index.build(null, { quiet: true, forceRebuild: true, workers: flags.workers });
             // Clear expand cache — stale line ranges after rebuild
             if (iExpandCache) iExpandCache.clearForRoot(index.root);
-            console.log(`Index ready: ${index.files.size} files, ${index.symbols.size} symbols`);
+            console.log(`Index ready: ${index.files.size} files, ${index.symbols.size} unique symbol names`);
             rl.prompt();
             return;
         }
@@ -1690,7 +1774,7 @@ Flags can be added per-command: context myFunc --include-methods
         const tokens = input.split(/\s+/);
         const command = tokens[0];
         // Flags that take a space-separated value (--flag value)
-        const valueFlagNames = new Set(['--file', '--in', '--base', '--add-param', '--remove-param', '--rename-to', '--default', '--depth', '--top', '--context', '--max-lines', '--direction', '--exclude', '--not', '--stack', '--type', '--param', '--receiver', '--returns', '--decorator', '--limit', '--max-files', '--min-confidence', '--class-name', '--framework', '--method', '--prefix']);
+        const valueFlagNames = new Set(['--file', '--in', '--base', '--add-param', '--remove-param', '--rename-to', '--default', '--depth', '--top', '--context', '--max-lines', '--direction', '--exclude', '--not', '--stack', '--type', '--param', '--receiver', '--returns', '--decorator', '--limit', '--max-files', '--min-confidence', '--class-name', '--line', '--framework', '--method', '--prefix']);
         const flagTokens = [];
         const argTokens = [];
         const skipNext = new Set();
@@ -1708,7 +1792,23 @@ Flags can be added per-command: context myFunc --include-methods
             }
         }
         const arg = argTokens.join(' ');
+
+        // Unknown flags error instead of folding their VALUE into the
+        // symbol name (fix #250: `about AddTask --bogus 5` searched for
+        // "AddTask 5"). Same vocabulary as one-shot mode.
+        const unknown = flagTokens.filter(t =>
+            t.startsWith('--') && !knownFlags.has(t.split('=')[0]));
+        if (unknown.length > 0) {
+            console.log(`Unknown flag(s): ${unknown.join(', ')}`);
+            rl.prompt();
+            return;
+        }
         const iflags = parseFlags(flagTokens);
+        // parseFlags never extracts --json (it is a global-argv flag), so
+        // check the raw tokens.
+        if (flagTokens.includes('--json')) {
+            console.log('Note: interactive mode prints text output — run `ucn . <command> --json` one-shot for JSON.');
+        }
 
         try {
             // Validate numeric flags (--top, --limit, etc) — same rules as
@@ -1747,9 +1847,9 @@ Flags can be added per-command: context myFunc --include-methods
 
 const INTERACTIVE_DISPATCH = {
     // ── Understanding Code ───────────────────────────────────────────
-    about:        { params: 'name', format: (r, _a, f, idx) => output.formatAbout(r, { expand: f.expand, root: idx.root, showAll: f.all, depth: f.depth, showConfidence: f.showConfidence !== false, git: !!f.git }) },
-    smart:        { params: 'name', format: (r) => output.formatSmart(r, { uncertainHint: 'use --include-uncertain to include all' }) },
-    impact:       { params: 'name', format: (r) => output.formatImpact(r) },
+    about:        { params: 'name', format: (r, _a, f, idx) => output.formatAbout(r, { expand: f.expand, root: idx.root, showAll: f.all, depth: f.depth, showConfidence: f.showConfidence !== false, compact: !!f.compact, git: !!f.git }) },
+    smart:        { params: 'name', format: (r) => output.formatSmart(r, { uncertainHint: 'unverified callees are listed below with reasons' }) },
+    impact:       { params: 'name', format: (r, _a, f) => output.formatImpact(r, { compact: !!f.compact }) },
     blast:        { params: 'name', format: (r) => output.formatBlast(r) },
     trace:        { params: 'name', format: (r) => output.formatTrace(r) },
     reverseTrace: { params: 'name', format: (r) => output.formatReverseTrace(r) },
@@ -1759,8 +1859,8 @@ const INTERACTIVE_DISPATCH = {
 
     // ── Finding Code ─────────────────────────────────────────────────
     find:          { params: 'name', format: (r, a, f) => output.formatFindDetailed(r, a, { depth: f.depth, top: f.top, all: f.all }) },
-    usages:        { params: 'name', format: (r, a) => output.formatUsages(r, a) },
-    toc:           { params: 'flags', format: (r) => output.formatToc(r, { detailedHint: 'Add --detailed to list all functions, or "about <name>" for full details on a symbol', uncertainHint: 'use --include-uncertain to include all' }) },
+    usages:        { params: 'name', format: (r, a, f) => output.formatUsages(r, a, { compact: !!f.compact }) },
+    toc:           { params: 'flags', format: (r) => output.formatToc(r, { detailedHint: 'Add --detailed to list all functions, or "about <name>" for full details on a symbol', uncertainHint: 'run "about <name>" for tiered detail on a specific symbol' }) },
     tests:         { params: 'name', format: (r, a) => output.formatTests(r, a) },
     affectedTests: { params: 'name', format: (r, _a, f) => output.formatAffectedTests(r, { all: f.all }) },
     typedef:       { params: 'name', format: (r, a) => output.formatTypedef(r, a) },
@@ -1781,9 +1881,10 @@ const INTERACTIVE_DISPATCH = {
     endpoints:    { params: (a, f) => ({ file: f.file, exclude: f.exclude, limit: f.limit, framework: f.framework, bridge: f.bridge, serverOnly: f.serverOnly, clientOnly: f.clientOnly, unmatched: f.unmatched, method: f.method, prefix: f.prefix, hideUncertain: f.hideUncertain }), format: (r) => output.formatEndpoints(r, { bridge: r._bridge, unmatched: r._unmatched }) },
 
     // ── Other ────────────────────────────────────────────────────────
-    api:          { params: (a, f) => ({ file: a || f.file, limit: f.limit }), format: (r, a, f) => output.formatApi(r, a || f.file || '.') },
+    api:          { params: (a, f) => ({ file: a || f.file, limit: f.limit }), format: (r, a, f) => output.formatApi(r, a || f.file) },
     stacktrace:   { params: (a, f) => ({ stack: f.stack || a }), format: (r) => output.formatStackTrace(r) },
     doctor:       { params: (a, f) => ({ file: f.file, in: f.in, limit: f.limit, deep: f.deep }), format: (r) => output.formatDoctor(r) },
+    orient:       { params: (a, f) => ({ top: f.topRaw != null ? f.topRaw : (f.top || undefined) }), format: (r) => output.formatOrient(r) },
     // MED-2: stats handler in execute.js rejects top<=0; without explicit
     // coercion, parseFlags's `top: 0` default would surface as
     // "Invalid --top value" on bare `stats`. Mirror the project-mode top
@@ -1822,6 +1923,9 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
                 console.log(`Warning: ${flagToCli(key)} has no effect on '${command}'.`);
             }
         }
+        // Tiered-output contract notes (fix #250 — one-shot mode printed
+        // these; interactive silently accepted the flags).
+        printTieredNoOpNotes(command, iflags, (m) => console.log(m));
     }
 
     // ── Commands with unique behavior (not data-driven) ──────────────
@@ -1829,25 +1933,26 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
 
         case 'fn': {
             if (!arg) { console.log('Usage: fn <name>[,name2,...] [--file=<pattern>] [--class-name=<class>]'); return; }
-            const { ok, result, error, note } = execute(index, 'fn', { name: arg, file: iflags.file, all: iflags.all, className: iflags.className });
+            const { ok, result, error, note } = execute(index, 'fn', { name: arg, file: iflags.file, all: iflags.all, className: iflags.className, line: iflags.line });
             if (!ok) { console.log(error); return; }
-            if (note) console.log(note);
             console.log(output.formatFnResult(result));
+            if (note) console.log(note);
             break;
         }
 
         case 'class': {
             if (!arg) { console.log('Usage: class <name> [--file=<pattern>]'); return; }
-            const { ok, result, error, note } = execute(index, 'class', { name: arg, file: iflags.file, all: iflags.all, maxLines: iflags.maxLines });
+            const { ok, result, error, note } = execute(index, 'class', { name: arg, file: iflags.file, all: iflags.all, maxLines: iflags.maxLines, line: iflags.line });
             if (!ok) { console.log(error); return; }
-            if (note) console.log(note);
             console.log(output.formatClassResult(result));
+            if (note) console.log(note);
             break;
         }
 
         case 'lines': {
-            if (!arg) { console.log('Usage: lines <range> --file=<file>'); return; }
-            const { ok, result, error } = execute(index, 'lines', { file: iflags.file, range: arg });
+            if (!arg) { console.log('Usage: lines <range> --file=<file> (or: lines <file> <range>)'); return; }
+            const iLinesTarget = parseLinesTarget(arg, iflags.file);
+            const { ok, result, error } = execute(index, 'lines', { file: iLinesTarget.file, range: iLinesTarget.range });
             if (!ok) { console.log(error); return; }
             console.log(output.formatLines(result));
             break;
@@ -1858,11 +1963,12 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
                 console.log('Usage: expand <number>');
                 return;
             }
-            const expandNum = parseInt(arg, 10);
-            if (isNaN(expandNum)) {
+            // Whole-token integers only (fix #248: parseInt truncation).
+            if (!/^\d+$/.test(String(arg).trim())) {
                 console.log(`Invalid item number: "${arg}"`);
                 return;
             }
+            const expandNum = parseInt(arg, 10);
             let match, itemCount, symbolName;
             if (cache) {
                 const lookup = cache.lookup(index.root, expandNum);
@@ -1887,10 +1993,9 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
             const { ok, result, error, note } = execute(index, 'context', { name: arg, ...iflags });
             if (!ok) { console.log(error); return; }
             const { text, expandable } = output.formatContext(result, {
-                methodsHint: 'Note: obj.method() calls excluded — use --include-methods to include them',
                 expandHint: 'Use "expand <N>" to see code for item N',
-                uncertainHint: 'use --include-uncertain to include all',
                 showConfidence: iflags.showConfidence !== false,
+                compact: !!iflags.compact,
             });
             console.log(text);
             if (iflags.expand) {
@@ -1908,25 +2013,25 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
         case 'deadcode': {
             const { ok, result, error, note } = execute(index, 'deadcode', iflags);
             if (!ok) { console.log(error); return; }
-            if (note) console.log(note);
             console.log(output.formatDeadcode(result, {
                 top: iflags.top,
                 decoratedHint: !iflags.includeDecorated && result.excludedDecorated > 0 ? `${result.excludedDecorated} decorated/annotated symbol(s) hidden (framework-registered). Use --include-decorated to include them.` : undefined,
-                exportedHint: !iflags.includeExported && result.excludedExported > 0 ? `${result.excludedExported} exported symbol(s) excluded (all have callers). Use --include-exported to audit them.` : undefined,
+                exportedHint: !iflags.includeExported && result.excludedExported > 0 ? `${result.excludedExported} exported symbol(s) excluded from the audit (public API may have external callers). Use --include-exported to audit them.` : undefined,
                 externalContractHint: !iflags.includeExported && result.excludedExternalContract > 0 ? `${result.excludedExternalContract} symbol(s) hidden (override an out-of-tree base class — reachable via external contract, not dead). Use --include-exported to include them.` : undefined
             }));
+            if (note) console.log(note);
             break;
         }
 
         case 'search': {
             const { ok, result, error, structural, note } = execute(index, 'search', { term: arg, ...iflags });
             if (!ok) { console.log(error); return; }
-            if (note) console.log(note);
             if (structural) {
                 console.log(output.formatStructuralSearch(result));
             } else {
                 console.log(output.formatSearch(result, arg));
             }
+            if (note) console.log(note);
             break;
         }
 
@@ -1940,8 +2045,8 @@ function executeInteractiveCommand(index, command, arg, iflags = {}, cache = nul
             const params = buildInteractiveParams(entry.params, arg, iflags);
             const { ok, result, error, note } = execute(index, command, params);
             if (!ok) { console.log(error); return; }
-            if (note) console.log(note);
             console.log(entry.format(result, arg, iflags, index));
+            if (note) console.log(note);
         }
     }
 }

package/core/account.js

@@ -72,7 +72,9 @@ function computeGroundSet(index, name) {
             continue; // deleted since indexing; not part of the universe anymore
         }
         if (!content.includes(name)) continue;
-        const lines = content.split('\n');
+        // Shared read-only lines array — split once per file per operation,
+        // reused across the symbols of a multi-symbol command (diff-impact).
+        const lines = index._getFileLines(filePath);
         const matched = [];
         for (let i = 0; i < lines.length; i++) {
             if (wordRe.test(lines[i])) matched.push(i + 1);