ucn 5.2.2 → 5.3.0

package/cli/index.js

@@ -30,6 +30,16 @@ const { buildPublicParams, isPublicCommand } = require('../core/public-command')
 const { execute } = require('../core/execute');
 const { applyOutputBudget, MAX_OUTPUT_CHARS } = require('../core/output-budget');
 const { clearAllCaches } = require('../core/cache');
+const { commentLines } = require('../core/output/lines');
+
+// A downstream consumer such as head may finish before our write drains.
+// Handle the pipe closure without an unhandled Node error or bypassing cache
+// cleanup. Other write failures are real command errors.
+process.stdout.on('error', error => {
+    if (error.code === 'EPIPE') return;
+    process.stderr.write(`Error writing stdout: ${error.message}\n`);
+    process.exitCode = 2;
+});
 
 let activeCanonicalCommand = null;
 
@@ -315,6 +325,8 @@ function parseFlags(tokens) {
         functions: tokens.includes('--functions') || undefined,
         hot: tokens.includes('--hot') || undefined,
         diverse: tokens.includes('--diverse') || undefined,
+        raw: tokens.includes('--raw') || undefined,
+        lines: tokens.includes('--lines') || undefined,
         git: tokens.includes('--git') || undefined,
         className: getValueFlag('--class-name'),
         // Explicit line pin (fix #249: our own disambiguation notes advertise
@@ -396,7 +408,7 @@ if (unknownFlags.length > 0) {
     emitCliError(
         `Unknown flag(s): ${unknownFlags.join(', ')}. Use --help to see available flags.`,
     );
-    process.exit(1);
+    process.exit(flags.lines || flags.raw ? 2 : 1);
 }
 
 // Validate numeric flag values up front so bad input fails before we build
@@ -407,7 +419,7 @@ try {
 } catch (e) {
     if (e instanceof FlagValidationError) {
         emitCliError(e.message);
-        process.exit(1);
+        process.exit(flags.lines || flags.raw ? 2 : 1);
     }
     throw e;
 }
@@ -456,6 +468,16 @@ function formatCliText(command, result, params, execution, displayFlags) {
         ...execution,
         surface: 'cli',
     });
+    // --lines / --raw are pipe surfaces: records are compact, a truncated
+    // function body is worse than a long one, and an empty answer must stay
+    // empty (grep prints nothing and exits 1). An explicit --max-chars acts
+    // as a fail-before-output guard, never a lossy source/record truncation.
+    if (params?.lines || params?.raw) {
+        if (displayFlags?.maxChars && text.length > displayFlags.maxChars) {
+            fail(`Output exceeds --max-chars=${displayFlags.maxChars}; shell output cannot be truncated. Narrow the query, use --limit/--max-lines, or omit --max-chars.`);
+        }
+        return text;
+    }
     return applyOutputBudget(text, {
         command,
         maxChars: displayFlags?.maxChars,
@@ -465,6 +487,36 @@ function formatCliText(command, result, params, execution, displayFlags) {
     }).text;
 }
 
+/**
+ * Print a formatted answer the way the mode asks for it (fix #341).
+ * --lines: `path:line:text` records on stdout, `# ` comment lines (ACCOUNT,
+ * notes) on stderr, exit 1 when nothing matched — grep's own contract.
+ * --raw: the text verbatim with exactly one trailing newline.
+ */
+function emitCliText(text, params, json, note) {
+    if (!json && params?.lines) {
+        const records = [];
+        const comments = [];
+        for (const line of String(text).split('\n')) {
+            if (line === '') continue;
+            (line.startsWith('# ') ? comments : records).push(line);
+        }
+        if (records.length > 0) process.stdout.write(records.join('\n') + '\n');
+        if (comments.length > 0) process.stderr.write(comments.join('\n') + '\n');
+        if (records.length === 0) process.exitCode = Math.max(process.exitCode || 0, 1);
+        return;
+    }
+    if (!json && params?.raw) {
+        const body = String(text);
+        process.stdout.write(body.endsWith('\n') ? body : body + '\n');
+        // Code lines are never reinterpreted (a Python comment starts with
+        // "# " too), so the note travels on its own channel.
+        if (note) process.stderr.write(commentLines(formatSurfaceMessage(note, 'cli')).join('\n') + '\n');
+        return;
+    }
+    console.log(text);
+}
+
 // ============================================================================
 // MAIN
 // ============================================================================
@@ -555,7 +607,7 @@ function main() {
         if (!(e instanceof CommandError)) {
             emitCliError(`Error: ${e.message}`);
         }
-        process.exitCode = 1;
+        process.exitCode = flags.lines || flags.raw ? 2 : 1;
     }
 }
 
@@ -665,11 +717,11 @@ function runFileCommand(filePath, command, arg) {
     const execution = execute(index, canonical, params);
     const { ok, result, error } = execution;
     if (!ok) fail(formatSurfaceMessage(error, 'cli'));
-    console.log(flags.json
+    emitCliText(flags.json
         ? output.formatPublicJson(canonical, result, params, {
             ...execution, surface: 'cli',
         })
-        : formatCliText(canonical, result, params, execution, scopedFlags));
+        : formatCliText(canonical, result, params, execution, scopedFlags), params, flags.json, execution.note);
 }
 
 // ============================================================================
@@ -737,11 +789,12 @@ function runProjectCommand(rootDir, command, arg) {
     if (!publicExecution.ok) {
         fail(formatSurfaceMessage(publicExecution.error, 'cli'));
     }
-    console.log(flags.json
+    emitCliText(flags.json
         ? output.formatPublicJson(canonical, publicExecution.result, publicParams, {
             ...publicExecution, surface: 'cli',
         })
-        : formatCliText(canonical, publicExecution.result, publicParams, publicExecution, flags));
+        : formatCliText(canonical, publicExecution.result, publicParams, publicExecution, flags),
+    publicParams, flags.json, publicExecution.note);
     // A gate that could not run (check outside git / bad base ref) must not
     // exit 0 — CI gating on the exit code would read "could not run" as "passed".
     process.exitCode = Math.max(process.exitCode || 0,
@@ -750,7 +803,7 @@ function runProjectCommand(rootDir, command, arg) {
         if (!(e instanceof CommandError)) {
             emitCliError(`Error: ${e.message}`);
         }
-        process.exitCode = 1;
+        process.exitCode = flags.lines || flags.raw ? 2 : 1;
     } finally {
         // Save cache after command execution so callsCache populated
         // by findCallers/findCallees gets persisted to disk.
@@ -796,11 +849,12 @@ function runGlobCommand(pattern, command, arg) {
     if (!publicExecution.ok) {
         fail(formatSurfaceMessage(publicExecution.error, 'cli'));
     }
-    console.log(flags.json
+    emitCliText(flags.json
         ? output.formatPublicJson(canonical, publicExecution.result, publicParams, {
             ...publicExecution, surface: 'cli',
         })
-        : formatCliText(canonical, publicExecution.result, publicParams, publicExecution, flags));
+        : formatCliText(canonical, publicExecution.result, publicParams, publicExecution, flags),
+    publicParams, flags.json, publicExecution.note);
     process.exitCode = Math.max(process.exitCode || 0,
         resultExitCode(canonical, publicExecution.result));
 }
@@ -860,6 +914,13 @@ Common flags:
   --range=N-M (source with --file=PATH)
   --base=REF --staged --no-cache --clear-cache [--all] --max-files=N --workers=N
   --max-chars=N (text output; default 10K targeted / 3K broad, ceiling 100K)
+  --lines  find/usages/search/show/impact: grep -n shape, one path:line:text
+           record per line (tags after a tab: # unverified: <reason>, # import,
+           # callee); accounting and notes go to stderr as "# " lines; exit 1
+           when nothing matched; exit 2 on errors. No default result cap.
+           show defaults to callers; --sections=callers,callees selects bands.
+  --raw    source: full code, no header or gutter (including large classes).
+           Shell modes fail before output if an explicit --max-chars is exceeded.
   Cache: per-user by default; set UCN_CACHE_DIR to override the cache root.
 
 Accepted flags by command:

package/core/cache.js

@@ -690,7 +690,14 @@ function clearAllCaches() {
 // types for values bound from declared map, slice, and array indexes.
 // v208 (fix #335): Go indexed-value calls preserve receiver-root/field
 // provenance so sibling-file container declarations resolve query-time.
-const CACHE_FORMAT_VERSION = 208;
+// v210 (fixes #337-#339): importDetails persisted for every language (was Python-only),
+// require(path.join(__dirname, ...)) composes to a static relative specifier,
+// and import records carry deferredReason (function-local / type-checking / type-only).
+// v211: path-utility composition requires unshadowed binding evidence; mixed
+// default/type imports and inline type re-exports preserve execution timing.
+// Python TYPE_CHECKING guards require typing ownership and no rebinding.
+// v212 (fix #342): extendsGraph/extendedByGraph no longer persisted (rebuilt on load).
+const CACHE_FORMAT_VERSION = 212;
 const USAGE_CACHE_FILE = 'usage-results.json';
 
 /**
@@ -901,9 +908,13 @@ function saveCache(index, cachePath) {
         symbols: strippedSymbols,
         importGraph: relGraph(index.importGraph),
         exportGraph: relGraph(index.exportGraph),
-        // extendsGraph/extendedByGraph use class names as keys (not file paths)
-        extendsGraph: Array.from(index.extendsGraph.entries()),
-        extendedByGraph: Array.from(index.extendedByGraph.entries()),
+        // extendsGraph/extendedByGraph are NOT persisted (fix #342): their
+        // entries carry absolute file paths in the build-time spelling, and
+        // the cache key is realpath-normalized — a root reached through a
+        // symlink (/var → /private/var on macOS) loaded a graph whose files
+        // matched nothing, so an overriding Go embed read as a non-overriding
+        // subclass and confirmed two false callers. loadCache rebuilds both
+        // from the rehydrated symbols (8ms on 1037 files).
         failedFiles: index.failedFiles
             ? Array.from(index.failedFiles).map(f => path.relative(root, f))
             : [],
@@ -1116,13 +1127,8 @@ function loadCache(index, cachePath) {
         index.buildTime = cacheData.buildTime;
 
         // Restore optional graphs if present
-        // extendsGraph/extendedByGraph use class names as keys (not file paths)
-        if (Array.isArray(cacheData.extendsGraph)) {
-            index.extendsGraph = new Map(cacheData.extendsGraph);
-        }
-        if (Array.isArray(cacheData.extendedByGraph)) {
-            index.extendedByGraph = new Map(cacheData.extendedByGraph);
-        }
+        // extendsGraph/extendedByGraph are derived below from the rehydrated
+        // symbols (fix #342) — never read from the payload.
 
         // Prepare lazy calls cache loading — load manifest but defer shard parsing.
         // Shards are loaded on first getCachedCalls access via ensureCallsCacheLoaded().
@@ -1194,13 +1200,16 @@ function loadCache(index, cachePath) {
             }
         }
 
-        // Only rebuild graphs if config changed (e.g., aliases modified)
+        // Only rebuild the import graph if config changed (e.g., aliases
+        // modified); it is persisted with relative paths. The inheritance
+        // graph is always derived from the rehydrated symbols (fix #342) so
+        // its file paths agree with index.root whatever spelling built it.
         const currentConfigHash = crypto.createHash('md5')
             .update(JSON.stringify(index.config || {})).digest('hex');
         if (currentConfigHash !== cacheData.configHash) {
             index.buildImportGraph();
-            index.buildInheritanceGraph();
         }
+        index.buildInheritanceGraph();
 
         loadUsageCache(index, cacheFile);
 

package/core/callers.js

@@ -592,10 +592,22 @@ function findCallers(index, name, options = {}) {
     // completion. Phase 2 still only enriches the first `maxResults` items —
     // file reads stay bounded, but the candidate count reflects the true total.
     const needsTotal = !!options.needsTotal;
-    const localTypeCache = new Map(); // `${filePath}:${startLine}` -> localTypes Map or null
-    const returnFlowCache = new Map(); // filePath -> return-type-flow map (see _buildReturnTypeFlowMap)
-    const foldCtxCache = new Map(); // filePath -> chained-receiver fold context (fix #258)
-    const pythonIndexedReceiverCache = new Map();
+    // Per-file query-time derivations that depend only on a file's immutable
+    // call records — never on the pinned target — so they live for the whole
+    // OPERATION, not one findCallers call (fix #340): stats --hot / repo run
+    // findCallers for hundreds of candidates over the same files, and
+    // rebuilding fold contexts (producer index, flow maps) and typed-local
+    // maps per candidate made grpc-go's `repo` cost 40s (1375 calls).
+    if (!index._opFindCallersCaches) {
+        index._opFindCallersCaches = {
+            localTypeCache: new Map(), // `${filePath}:${startLine}` -> localTypes Map or null
+            returnFlowCache: new Map(), // filePath -> return-type-flow map (see _buildReturnTypeFlowMap)
+            foldCtxCache: new Map(), // filePath -> chained-receiver fold context (fix #258)
+            pythonIndexedReceiverCache: new Map(),
+        };
+    }
+    const { localTypeCache, returnFlowCache, foldCtxCache, pythonIndexedReceiverCache } =
+        index._opFindCallersCaches;
 
     // Use inverted callee index to skip files that don't contain calls to this name
     let calleeFiles = index.getCalleeFiles(name);
@@ -1157,12 +1169,8 @@ function findCallers(index, name, options = {}) {
                                 receiverTypeFlowFile: path.join(index.root, project.rel),
                             };
                         } else {
-                            const projectish = bindings.some(b => {
-                                const mod = String(b.module || '');
-                                const first = mod.split(/[./]/).filter(Boolean)[0];
-                                return mod.startsWith('.') ||
-                                    (first && _projectTopLevelNames(index).has(first));
-                            });
+                            const projectish = bindings.some(b =>
+                                _unresolvedModuleIsGap(index, b.module, b));
                             const via = `${bindings[0].module}.${bindings[0].name}`;
                             if (BUILTIN_RECEIVER_TYPES.has(call.receiverType)) {
                                 // Stable stdlib runtime classes (StringIO,
@@ -1657,10 +1665,7 @@ function findCallers(index, name, options = {}) {
                         for (const binding of cbNameBindings) {
                             const rel = fileEntry.moduleResolved?.[binding.module];
                             if (!rel) {
-                                const mod = String(binding.module || '');
-                                const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-                                if (mod.startsWith('.') ||
-                                    (firstSeg && _projectTopLevelNames(index).has(firstSeg))) {
+                                if (_unresolvedModuleIsGap(index, binding.module, binding)) {
                                     cbBindingUnknown = true;
                                 }
                                 continue;
@@ -2851,10 +2856,7 @@ function findCallers(index, name, options = {}) {
                                 // relative (project-internal by construction)
                                 // or its first segment names a project path
                                 // (resolution gap, not externality evidence)
-                                const mod = String(b.module);
-                                const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-                                if (mod.startsWith('.') ||
-                                    (firstSeg && _projectTopLevelNames(index).has(firstSeg))) {
+                                if (_unresolvedModuleIsGap(index, b.module, b)) {
                                     undetermined = true;
                                 }
                                 continue;
@@ -3129,10 +3131,7 @@ function findCallers(index, name, options = {}) {
                             const rel = recvSubmoduleRel ||
                                 (fileEntry.moduleResolved && fileEntry.moduleResolved[b.module]);
                             if (!rel) {
-                                const mod = String(b.module);
-                                const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-                                if (mod.startsWith('.') ||
-                                    (firstSeg && _projectTopLevelNames(index).has(firstSeg))) {
+                                if (_unresolvedModuleIsGap(index, b.module, b)) {
                                     projectish = true;
                                     undetermined = true;
                                 }
@@ -7956,10 +7955,7 @@ function _buildReturnTypeFlowMap(index, filePath, calls) {
                 // project `info`) is not identity evidence. Same externality
                 // test as #209 module ownership: relative or project-ish
                 // modules are resolver gaps, never externality evidence.
-                const mod = String(binding.module);
-                const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-                if (!mod.startsWith('.') &&
-                    !(firstSeg && _projectTopLevelNames(index).has(firstSeg))) {
+                if (!_unresolvedModuleIsGap(index, binding.module, binding)) {
                     const scope = call.enclosingFunction ? `${call.enclosingFunction.startLine}` : '';
                     if (!map) map = new Map();
                     const key = `${scope}:${call.assignedTo}`;
@@ -9103,9 +9099,7 @@ function _structuralQualifiedReceiverOrigin(index, fileEntry, qualifier, typeNam
                 fromFile: path.join(index.root, rel),
             };
         }
-        const first = moduleName.split(/[./]/).filter(Boolean)[0];
-        if (moduleName.startsWith('.') ||
-            (first && _projectTopLevelNames(index).has(first))) {
+        if (_unresolvedModuleIsGap(index, moduleName)) {
             projectish = true;
         }
     }
@@ -9296,10 +9290,7 @@ function _nameBindingReaches(index, startAbs, name, targetFiles, maxDepth = 4) {
                     // Unresolved: relative or project-ish → resolver gap, not
                     // a terminal; clearly external → that path pins outside
                     // the project (dead end, consistent with #209c).
-                    const mod = String(module);
-                    const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-                    if (mod.startsWith('.') ||
-                        (firstSeg && _projectTopLevelNames(index).has(firstSeg))) unknown = true;
+                    if (_unresolvedModuleIsGap(index, module)) unknown = true;
                     return;
                 }
                 next.push([path.join(index.root, rel), nextAttr]);
@@ -9860,6 +9851,25 @@ function _projectTopLevelNames(index) {
     return names;
 }
 
+/**
+ * Is an UNRESOLVED module specifier a resolver gap rather than externality
+ * evidence? (fix #337b) Relative specifiers and first segments naming a
+ * project top-level path were already gaps (#209); a NON-LITERAL specifier —
+ * `require(path.join(__dirname, ...))`, `require(name)`, template paths — is
+ * one too: the parser records the expression text as the module, which can
+ * never match a package name, so judging it external excluded true callers as
+ * `other-definition-import`. Statically composable `__dirname` paths are
+ * resolved parser-side; whatever stays dynamic must route 'unknown'.
+ */
+function _unresolvedModuleIsGap(index, module, binding) {
+    const mod = String(module || '');
+    if (binding && binding.dynamic) return true;
+    if (mod.startsWith('.')) return true;
+    if (/[()$`{}+\s]/.test(mod)) return true;
+    const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
+    return !!(firstSeg && _projectTopLevelNames(index).has(firstSeg));
+}
+
 const IDENTITY_TYPE_KINDS = new Set(['class', 'struct', 'interface', 'trait', 'enum']);
 
 /**
@@ -10740,10 +10750,9 @@ function _goQualifierNamesImport(index, fieldFile, qualifier) {
 function _iterExternalProducerVia(index, fileEntry, call) {
     if (!fileEntry || langTraits(fileEntry.language)?.typeSystem === 'nominal') return null;
     const externalModule = (mod) => {
-        if (!mod || mod.startsWith('.')) return false;
+        if (!mod) return false;
         if (fileEntry.moduleResolved?.[mod]) return false;
-        const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-        return !(firstSeg && _projectTopLevelNames(index).has(firstSeg));
+        return !_unresolvedModuleIsGap(index, mod);
     };
     if (call.isMethod && call.receiverIsModule && call.receiver) {
         const binding = _structuralModuleBindings(fileEntry, call)[0];
@@ -10831,10 +10840,9 @@ function _structuralCompositeModuleOwnership(
 
 function _pythonBuiltinContractAllowed(index, fileEntry, moduleName) {
     const module = String(moduleName || '');
-    if (!module || module.startsWith('.')) return false;
+    if (!module) return false;
     if (fileEntry.moduleResolved?.[module]) return false;
-    const first = module.split('.')[0];
-    return !first || !_projectTopLevelNames(index).has(first);
+    return !_unresolvedModuleIsGap(index, module);
 }
 
 function _structuralImportedReceiverType(index, fileEntry, receiver) {
@@ -10957,10 +10965,7 @@ function _calleeStructuralBindingRoute(index, fileEntry, call, language, binding
     for (const binding of bindings) {
         const rel = fileEntry.moduleResolved && fileEntry.moduleResolved[binding.module];
         if (!rel) {
-            const mod = String(binding.module || '');
-            const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-            if (mod.startsWith('.') ||
-                (firstSeg && _projectTopLevelNames(index).has(firstSeg))) {
+            if (_unresolvedModuleIsGap(index, binding.module, binding)) {
                 sawProjectish = true;
                 sawUnknown = true;
             }
@@ -11008,10 +11013,7 @@ function _calleeExportDefinitions(index, startAbs, exposedName, language, call,
             const enqueue = (module, nextAttr) => {
                 const rel = fe.moduleResolved && fe.moduleResolved[module];
                 if (!rel) {
-                    const mod = String(module || '');
-                    const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-                    if (mod.startsWith('.') ||
-                        (firstSeg && _projectTopLevelNames(index).has(firstSeg))) unknown = true;
+                    if (_unresolvedModuleIsGap(index, module)) unknown = true;
                     return;
                 }
                 next.push([path.join(index.root, rel), nextAttr]);
@@ -15600,10 +15602,7 @@ function _typeOfCallResultFoldInner(index, fileEntry, filePath, record, ctx, con
             (binding && fileEntry.moduleResolved &&
                 fileEntry.moduleResolved[binding.module]);
         if (binding && !rel) {
-            const mod = String(binding.module);
-            const firstSeg = mod.split(/[./]/).filter(Boolean)[0];
-            if (!mod.startsWith('.') &&
-                !(firstSeg && _projectTopLevelNames(index).has(firstSeg))) {
+            if (!_unresolvedModuleIsGap(index, binding.module, binding)) {
                 return {
                     externalVia: `${record.receiver}.${name}`,
                     ...(/^[A-Z]/.test(name) && { externalConcrete: true }),
@@ -16129,4 +16128,4 @@ function findCallbackUsages(index, name) {
     return usages;
 }
 
-module.exports = { getCachedCalls, findCallers, findCallees, getInstanceAttributeTypes, findCallbackUsages, _nameBindingReaches, _moduleAttributeBindingReaches, _declaredFieldType, _projectTopLevelNames, _callArityCompatible, _closeCallableIdentityGroup, _overloadDiscipline, _overloadApplicable };
+module.exports = { _unresolvedModuleIsGap, getCachedCalls, findCallers, findCallees, getInstanceAttributeTypes, findCallbackUsages, _nameBindingReaches, _moduleAttributeBindingReaches, _declaredFieldType, _projectTopLevelNames, _callArityCompatible, _closeCallableIdentityGroup, _overloadDiscipline, _overloadApplicable };

package/core/execute.js

@@ -464,6 +464,14 @@ const PUBLIC_COMMAND_SET = new Set(CANONICAL_COMMANDS);
  * glob, file, and programmatic callers receive the same answer.
  */
 function validatePublicParams(command, p) {
+    if (p.raw && command !== 'source') return '--raw is supported only by source.';
+    if (p.lines && !['find', 'usages', 'search', 'show', 'impact'].includes(command)) {
+        return '--lines is supported by find, usages, search, show, and impact.';
+    }
+    if (p.lines && command === 'show' && p.sections) {
+        const parsed = parseSections(p.sections, ['callers'], new Set(['callers', 'callees']), 'show --lines');
+        if (parsed.error) return parsed.error;
+    }
     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) {
@@ -569,7 +577,7 @@ const HANDLERS = {
         } : query;
         const parsed = parseSections(
             p.sections,
-            ['summary', 'callers', 'callees'],
+            p.lines ? ['callers'] : ['summary', 'callers', 'callees'],
             SHOW_SECTIONS,
             'show',
         );
@@ -693,6 +701,8 @@ const HANDLERS = {
         const notes = [
             ...(resolved.warnings || []).map(warning => warning.message),
             response.note,
+            ...(p.raw ? (response.result.entries || []).filter(entry => entry.truncated)
+                .map(entry => `Source truncated: ${entry.match.relativePath}:${entry.match.startLine}; showing ${entry.shownLines || entry.maxLines} of ${entry.totalLines} lines (--max-lines).`) : []),
         ].filter(Boolean);
         return notes.length > 0
             ? { ...response, note: combineNotes(notes) }
@@ -1174,6 +1184,9 @@ const HANDLERS = {
             file: p.file,
             className: p.className,
             exact: p.exact || false,
+            // A shell definition listing renders no activity counts. Avoid a
+            // full pinned caller query for every definition in a wildcard.
+            skipCounts: !!p.lines,
             exclude,
             in: p.in,
         });
@@ -1430,7 +1443,7 @@ const HANDLERS = {
                 exclude,
                 in: p.in,
                 file: p.file,
-                top: topVal || 50,
+                top: topVal || (p.lines ? undefined : 50),
             });
             if (result.meta.error) return { ok: false, error: result.meta.error };
             const unsupported = (!p.regex && (p.term || p.name))
@@ -1456,7 +1469,7 @@ const HANDLERS = {
         // 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 effectiveLimit = topVal || (p.lines ? undefined : 500);
         const result = index.search(p.term, {
             codeOnly: p.codeOnly || false,
             context: num(p.context, 0),
@@ -2014,9 +2027,12 @@ const HANDLERS = {
 
         if (matches.length > 1 && p.all) {
             for (const m of matches) {
-                const code = readAndExtract(m);
+                const fullCode = readAndExtract(m);
                 const totalLines = m.endLine - m.startLine + 1;
-                entries.push({ match: m, code, totalLines, summaryMode: false, truncated: false });
+                const truncated = !!maxLines && totalLines > maxLines;
+                const code = truncated ? fullCode.split('\n').slice(0, maxLines).join('\n') : fullCode;
+                entries.push({ match: m, code, totalLines, summaryMode: false, truncated,
+                    ...(truncated && { maxLines }) });
             }
             return { ok: true, result: { entries }, note: notes.length ? notes.map(n => 'Note: ' + n).join('\n') : undefined };
         }
@@ -2035,7 +2051,7 @@ const HANDLERS = {
         const totalLines = match.endLine - match.startLine + 1;
 
         // Large class summary mode (>200 lines, no maxLines)
-        if (totalLines > 200 && !maxLines) {
+        if (totalLines > 200 && !maxLines && !p.raw) {
             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 };
@@ -2457,6 +2473,8 @@ function execute(index, command, params = {}) {
     // logged params object; a frozen object silently no-oped the
     // normalizers and returned wrong not-found answers).
     params = { ...params };
+    // Listing completeness belongs to execution, including direct API calls.
+    if (params.lines) params.all = true;
     try {
         if (PUBLIC_COMMAND_SET.has(command)) {
             const validationError = validatePublicParams(command, params);