ucn 5.3.6 → 5.3.8

package/.claude/skills/ucn/SKILL.md

@@ -41,6 +41,12 @@ three. The text block is the whole response on every surface.
 
 Persistent indexes live in a per-user, project-keyed cache rather than the analyzed repository. Set `UCN_CACHE_DIR` to override the cache root; CLI `--no-cache` bypasses persistence and `--clear-cache` removes the current project's cache. Legacy `<project>/.ucn-cache` directories are migrated on first use. Concurrent invocations on a cold cache share one build: the first process takes a build lock, the others wait for its cache (`Waiting for another ucn process building the index...` on stderr) instead of rebuilding; a lock left by a dead process is broken automatically.
 
+Files named `*.min.js`, `*.bundle.js`, and `*.map` are disclosed as skipped
+bundled sources; they make observed-text completeness partial. Pass
+`--include-bundled` (MCP `include_bundled=true`) to index the JavaScript files.
+This option bypasses the shared cache and still respects user exclusions.
+Source maps remain disclosed but unindexed; inspect them with text tools.
+
 Supported source families are JavaScript/TypeScript/TSX, Python, Go, Rust, Java, C, C++, C#, and HTML inline JavaScript/event handlers. C/C++ uses `compile_commands.json` when available to classify headers and resolve include paths. Recoverable preprocessor branches contribute AST-proven source facts, so a single selected configuration does not silently erase definitions or calls; disagreeing conditional macro identities stay visible as unverified. C++ resolution uses namespace ownership, static overload shape (including arrays), and macro-parameter requalification. C# resolution uses declared property/field receiver types plus overload and hiding discipline. This is portable AST analysis, not a compiler build; macros, templates, generated code, reflection, and external dependency semantics can remain unverified.
 
 `repo` refines its HOT list exactly for up to 400 candidate definitions per
@@ -78,6 +84,7 @@ counts them; `CALL SITES` stays call-shaped.
 Target-less `impact` and `check` diff the working tree against `HEAD` AND
 include untracked, non-ignored source files as whole-file additions, so new
 modules are checked before `git add`. `--staged` keeps its index-only meaning.
+The changed-path note also counts untracked documentation and configuration.
 
 An observed-text zero is not semantic zero or safe-delete proof. Numeric evidence values are ordinal ranking weights, not probabilities.
 
@@ -119,7 +126,7 @@ answers:
 ucn find handleRequest --lines            # path:line:signature   # kind
 ucn show handleRequest --lines            # callers as path:line:text; unverified ones end in "\t# unverified: <reason>"
 ucn show handleRequest --lines --sections=callees
-ucn usages handleRequest --lines          # every literal-name line; non-call kinds tagged "# import" / "# definition"
+ucn usages handleRequest --lines          # every literal-name occurrence; non-call kinds tagged "# import" / "# definition"
 ucn search 'retry(' --lines               # grep -n output, code-aware scope
 ucn impact handleRequest --lines
 ucn source handleRequest --raw            # the code and nothing else, ready for an exact-string edit
@@ -129,6 +136,12 @@ ucn source src/server.js:40-80 --raw
 Records go to stdout; the `ACCOUNT` / `CONTRACT` lines, notes, and the
 same-name disambiguation go to stderr prefixed `# ` (MCP keeps them in the one
 text block, and `--raw` appends its note as one trailing `# ` line there).
+`usages` emits one record per occurrence, so a source line may repeat; deduplicate
+`path:line` values for line counts. Definition handles start at decorators when
+present, while usages point at token lines (`nameLine` identifies the declaration
+token when it differs from `startLine`). Structural `search --unused` keeps its
+safety note and decorator tags in shell output; runtime registrations can appear
+and zero call edges do not prove a symbol is safe to delete.
 `--lines` lists the whole band without default row/character caps, so pipe through
 `grep -v '# unverified'` for the confirmed tier or `cut -d: -f1 | sort | uniq -c`
 for callers per file. Nothing to list prints nothing and exits 1, grep's
@@ -143,6 +156,11 @@ characters (backslash/tab/CR/LF) are escaped; use JSON for exact filenames.
 languages; use `ucn ... --lines` when the question is a symbol, a caller, or a
 definition, and `--raw` when the next step is an edit.
 
+Command errors exit 2 in ordinary text mode as well. CLI JSON preserves its
+own contract: successful empty results exit 0; command errors exit 1 with
+`meta.ok: false` and an `error` field. A target-less `check` exits 1 when
+`TRUST` is `BLOCKED`, 0 otherwise; a check that could not run exits 2.
+
 ## Breaking-change protocol
 
 1. Pin the exact definition with `find`.
@@ -183,6 +201,12 @@ rejected, and unsupported advanced syntax should be handed to ripgrep.
 `find` activity counts are definition-pinned: confirmed plus visible unverified
 call candidates. Calls proved to belong to another same-name target are
 disclosed separately and excluded from the activity total.
+Broad queries rank candidates by inexpensive approximate usage totals before
+applying the row limit; only returned definitions receive caller adjudication.
+The selection note discloses that approximation. `find`, text `search`,
+`deadcode`, `api`, and `repo --sections=files` default to at most 500 results
+(structural `search`: 50). Use an explicit `--limit=N` to request more;
+`usages` and `--lines` have no default row cap.
 
 For `plan --rename-to`, the selected declaration is only the starting point.
 When the index proves the relationship, the rename unit closes over

package/.claude/skills/ucn/references/commands.md

@@ -33,7 +33,7 @@ structural or code-only search.
 |---|---|
 | `repo` | Repository orientation. Select `summary,files,stats,health` with `--sections`; `--deep` includes readiness evidence. Skipped unsupported source is listed with a grep/language-tool handoff. |
 | `deps <file>` | File dependency graph. Use `--direction=imports\|importers\|both`, `--detailed`, or `--cycles`. Cycles distinguish eager edges from function-local, Python typing-guarded, and TypeScript type-only edges. Complete cycle groups remain visible when enumeration is capped. |
-| `api [file]` | Static exported/public surface for a project or file. |
+| `api [file]` | Static exported/public surface for a project or file. An exact file includes tests; broader scans exclude tests with a count. Use `--include-tests` to include them. |
 | `entrypoints` | Framework, route, task, test, and runtime entry points. |
 | `endpoints` | Server/client HTTP surface; `--bridge` adds advisory matching. |
 
@@ -49,6 +49,14 @@ structural or code-only search.
 
 Symbol-listing commands emit handles such as `src/api.ts:42:handler`. Pass the full handle to symbol commands. `path:line` also works. Handles prevent same-named definitions from being silently combined.
 
+Definition handles and source spans start at the first decorator or annotation when present; literal usages point at the actual token line. Use a symbol's `nameLine` (when present, otherwise `startLine`) to compare declaration tokens with usages.
+
+Structural `search --param` matches parameter names, types, and defaults; `--returns` matches return annotations. Both exclude AST comments and preserve string contents. `--unused` lists callable symbols without call edges, not safe-delete candidates; decorated runtime registrations may still appear. Its safety note and decorator tags are retained in `--lines` output. Use `deadcode` and `usages` before deletion.
+
+`repo` summary/stats `buildTime` is the duration of the last index build (discovery, parsing, and graphs), retained in the cache. It excludes cache loading/saving and query execution, so it is not command wall time; `buildTimeNote` states this boundary.
+
+`--lines` writes one record per output line. `usages` records occurrences, so multiple tokens on the same source line can produce repeated `path:line` values. Deduplicate those values when counting source lines.
+
 ## Common flags
 
 | Flag | Meaning |
@@ -58,6 +66,8 @@ Symbol-listing commands emit handles such as `src/api.ts:42:handler`. Pass the f
 | `--class-name=<name>` | Scope a member when no handle is available. |
 | `--in=<directory>` | Limit query scope to a directory. |
 | `--exclude=<patterns>` | Exclude matching paths. |
+| `--limit=N` | Default maximum of 500 results for `find`, text `search`, `deadcode`, `api`, and `repo` files; structural `search` defaults to 50. Explicit limits override these caps; `usages` and `--lines` are uncapped by default. |
+| `--include-bundled` | Include `*.min.js` and `*.bundle.js` in discovery, respecting user exclusions and bypassing the shared cache. By default these and `*.map` are disclosed as skipped sources and completeness is partial. Source maps remain unindexed. MCP: `include_bundled=true`. |
 | `--depth=N` | Set trace/dependency/test traversal depth. |
 | `--direction=<value>` | Select trace or dependency direction. |
 | `--all` | Lift result and formatter caps where supported. It is recommended only for commands that accept it. |
@@ -84,6 +94,13 @@ ucn [target] <command> [argument] [flags]
 
 Omit the target for the current project. A target may be a file, directory, or quoted glob such as `"src/**/*.py"`.
 
+Ordinary text and shell command errors exit 2. JSON command errors retain
+exit 1 with `meta.ok: false` and an `error` field; successful empty JSON
+results exit 0. Target-less `check` exits 1 for `TRUST: BLOCKED`, 0 for other
+completed checks, and 2 when the check could not run. Working-tree `impact`
+and `check` count untracked documentation/configuration in their non-source
+path note; `--staged` excludes all untracked paths.
+
 ## Language notes
 
 Supported source families are JavaScript/TypeScript/TSX, Python, Go, Rust, Java, C, C++, C#, and HTML inline JavaScript/event handlers. C/C++ consumes `compile_commands.json` when present for header-language and include-path context, and retains AST-proven facts across recoverable preprocessor branches. C++ call identity uses namespace ownership, static overload shape (including arrays), and macro requalification; disagreeing conditional macro definitions remain visible as unverified. C# uses declared property/field receiver types and overload/hiding discipline. UCN remains portable AST analysis: it does not run a compiler, preprocessor, Roslyn, or an LSP during normal queries, and it does not assert which conditional branch a build activates.

package/README.md

@@ -213,6 +213,23 @@ and a shell-mode character budget fails before writing partial output.
 `source --raw` extracts complete functions and classes unless an explicit
 line limit is requested; any resulting truncation is reported on stderr.
 
+Ordinary text-mode command errors also exit 2. JSON keeps exit 0 for successful
+empty results and exit 1 for command errors (`meta.ok: false` plus `error`).
+Target-less `check` exits 1 when `TRUST` is `BLOCKED`, 0 for other completed
+checks, and 2 if it could not run.
+
+Outside `--lines`, `find`, text `search`, `deadcode`, `api`, and
+`repo --sections=files` default to a maximum of 500 results. Use `--limit=N`
+to request more; `usages` lists every site unless a limit is given. Broad `find` queries select candidates by approximate usage
+totals before calculating definition-pinned caller activity, and disclose
+that selection when limited.
+
+Files named `*.min.js`, `*.bundle.js`, and `*.map` are reported as skipped
+sources and make completeness partial. `--include-bundled` (MCP
+`include_bundled=true`) indexes the JavaScript bundles while respecting user
+exclusions; it bypasses the shared cache. Source maps remain disclosed but
+unindexed.
+
 ## AI setup
 
 One tool, 18 commands, compact source-linked answers that keep their trust

package/cli/index.js

@@ -48,7 +48,7 @@ let activeCanonicalCommand = null;
 class CommandError extends Error { constructor() { super(); } }
 
 // Thrown by validateNumericFlags when a numeric flag has a bad value.
-// The CLI top-level catches this, prints the message, and exits 1. Interactive
+// The CLI top-level catches this, prints the message, and exits 2 (JSON: 1). Interactive
 // mode catches it inside its REPL try/catch and continues the session.
 class FlagValidationError extends Error {
     constructor(msg) { super(msg); this.name = 'FlagValidationError'; }
@@ -363,6 +363,7 @@ function parseFlags(tokens) {
         hideUncertain: tokens.includes('--hide-uncertain') || tokens.includes('--no-uncertain') || undefined,
         stack: getValueFlag('--stack'),
         workersRaw: getValueFlag('--workers'),
+        includeBundled: tokens.includes('--include-bundled') || undefined,
         workers: (() => {
             const v = getValueFlag('--workers');
             if (v === null) return undefined;
@@ -376,7 +377,7 @@ function parseFlags(tokens) {
 const flags = parseFlags(args);
 flags.json = args.includes('--json');
 flags.quiet = !args.includes('--verbose') && !args.includes('--no-quiet');
-flags.cache = !args.includes('--no-cache');
+flags.cache = !args.includes('--no-cache') && !flags.includeBundled;
 flags.clearCache = args.includes('--clear-cache');
 flags.interactive = args.includes('--interactive') || args.includes('-i');
 flags.followSymlinks = !args.includes('--no-follow-symlinks');
@@ -408,7 +409,7 @@ if (unknownFlags.length > 0) {
     emitCliError(
         `Unknown flag(s): ${unknownFlags.join(', ')}. Use --help to see available flags.`,
     );
-    process.exit(flags.lines || flags.raw ? 2 : 1);
+    process.exit(flags.json ? 1 : 2);
 }
 
 // Validate numeric flag values up front so bad input fails before we build
@@ -419,7 +420,7 @@ try {
 } catch (e) {
     if (e instanceof FlagValidationError) {
         emitCliError(e.message);
-        process.exit(flags.lines || flags.raw ? 2 : 1);
+        process.exit(flags.json ? 1 : 2);
     }
     throw e;
 }
@@ -607,7 +608,7 @@ function main() {
         if (!(e instanceof CommandError)) {
             emitCliError(`Error: ${e.message}`);
         }
-        process.exitCode = flags.lines || flags.raw ? 2 : 1;
+        process.exitCode = flags.json ? 1 : 2;
     }
 }
 
@@ -625,7 +626,7 @@ function printTieredNoOpNotes(canonical, flags, print) {
 }
 
 const GLOBAL_FLAG_KEYS = new Set([
-    'json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'maxFiles',
+    'json', 'quiet', 'cache', 'clearCache', 'followSymlinks', 'includeBundled', 'maxFiles',
     'verbose', 'interactive', '_fileFromFileMode', 'topRaw',
     'limitRaw', 'maxFilesRaw', 'maxLinesRaw', 'depthRaw', 'contextRaw',
     'workers', 'workersRaw', 'lineRaw', 'maxChars', 'maxCharsRaw', 'minConfidenceRaw',
@@ -752,7 +753,7 @@ function runProjectCommand(rootDir, command, arg) {
     if (flags.cache && !flags.clearCache) {
         const loaded = index.loadCache();
         cacheWasLoaded = !!loaded;
-        if (loaded && !flags.maxFiles) {
+        if (loaded && !index.includeBundled && !flags.maxFiles) {
             if (!index.isCacheStale()) {
                 usedCache = true;
                 if (!flags.quiet) {
@@ -766,7 +767,7 @@ function runProjectCommand(rootDir, command, arg) {
     // If cache was loaded but stale, force rebuild to avoid duplicates
     let needsCacheSave = false;
     if (!usedCache) {
-        const buildOpts = { quiet: flags.quiet, forceRebuild: cacheWasLoaded, followSymlinks: flags.followSymlinks, maxFiles: flags.maxFiles, workers: flags.workers };
+        const buildOpts = { quiet: flags.quiet, forceRebuild: cacheWasLoaded, followSymlinks: flags.followSymlinks, includeBundled: flags.includeBundled, maxFiles: flags.maxFiles, workers: flags.workers };
         if (flags.cache && !flags.maxFiles) {
             // Cross-process build lock (fix #354): concurrent cold-cache
             // invocations share one build instead of each rebuilding.
@@ -813,7 +814,7 @@ function runProjectCommand(rootDir, command, arg) {
         if (!(e instanceof CommandError)) {
             emitCliError(`Error: ${e.message}`);
         }
-        process.exitCode = flags.lines || flags.raw ? 2 : 1;
+        process.exitCode = flags.json ? 1 : 2;
     } finally {
         // Save cache after command execution so callsCache populated
         // by findCallers/findCallees gets persisted to disk.
@@ -834,7 +835,11 @@ function runProjectCommand(rootDir, command, arg) {
 // ============================================================================
 
 function runGlobCommand(pattern, command, arg) {
-    const files = expandGlob(pattern);
+    const discoveryIssues = [];
+    const files = expandGlob(pattern, {
+        includeBundled: flags.includeBundled,
+        onDiscoveryIssue: issue => discoveryIssues.push(issue),
+    });
 
     if (files.length === 0) {
         fail(`No files match pattern: ${pattern}`, command);
@@ -849,6 +854,9 @@ function runGlobCommand(pattern, command, arg) {
     const rootDir = findProjectRoot(path.dirname(files[0]));
     const index = new ProjectIndex(rootDir);
     index.build(files, { quiet: true });
+    index.discoveryIssues.push(...discoveryIssues.map(issue => ({
+        ...issue, relativePath: path.relative(index.root, issue.path), path: undefined,
+    })));
 
     if (!isPublicCommand(canonical)) {
         fail(unknownCommandMessage(command));
@@ -909,7 +917,8 @@ Commands:
   deps <file>                     File graph; --direction=imports|importers|both
     --detailed                     Include import declarations
   deps --cycles                   Report circular dependencies (no file target)
-  api [file]                      Project or file public API
+  api [file]                      Project or file public API (exact files include tests;
+                                  broader scans exclude tests unless --include-tests)
   check [symbol]                  Signature check; without symbol, precommit check
   plan <symbol>                   Preview rename or parameter edits
   entrypoints                     Runtime and framework entry points
@@ -925,7 +934,8 @@ Common flags:
   --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,
+           record per output line; usages may repeat a source line per occurrence
+           (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.
@@ -938,14 +948,14 @@ ${perCommandFlags}
 
 Global/build/output flags:
   --help -h --version -v --mcp --json --verbose --no-quiet --quiet
-  --interactive -i --no-cache --clear-cache --no-follow-symlinks
+  --interactive -i --no-cache --clear-cache --no-follow-symlinks --include-bundled
   --max-files=N --max-chars=N --workers=N
   --clear-cache --all clears every bounded per-user UCN project cache.
 
 Exit codes:
   0  Command completed successfully; check found no blocking issues.
-  1  Findings, unsafe changes, validation failures, or invalid user input.
-  2  Command could not run (operational/environment failure).
+  1  Empty --lines listing, blocking check findings, or JSON command error.
+  2  Text/shell command error, or a check that could not run.
 
 Boolean aliases:
   --no-include-methods --no-regex --show-confidence --hide-confidence
@@ -995,14 +1005,14 @@ function runInteractive(rootDir) {
     let iCacheFresh;
     if (flags.cache) {
         const loaded = !flags.clearCache && index.loadCache();
-        iCacheFresh = loaded && !index.isCacheStale();
+        iCacheFresh = loaded && !index.includeBundled && !index.isCacheStale();
         if (!iCacheFresh) {
             index.buildCached({ quiet: true, forceRebuild: !!loaded, workers: flags.workers }, {
                 onWait: () => console.log('Waiting for another ucn process building the index...'),
             });
         }
     } else {
-        index.build(null, { quiet: true, workers: flags.workers });
+        index.build(null, { quiet: true, workers: flags.workers, includeBundled: flags.includeBundled });
     }
     console.log(`Index ready: ${index.files.size} files, ${index.symbols.size} unique symbol names`);
     console.log('Type commands (e.g., "find parseFile", "show main", "repo")');
@@ -1118,16 +1128,18 @@ Flags can be added per-command: show myFunc --sections=source,callers
             // refreshes individual call records lazily; without this matching
             // rebuild a newly added definition was invisible while its calls
             // appeared in neighbouring answers (UCN5-044).
-            if (index.isCacheStale()) {
+            const includeBundled = !!(iflags.includeBundled || flags.includeBundled);
+            if (!!index.includeBundled !== includeBundled || index.isCacheStale()) {
                 console.log('Source changed; rebuilding index...');
                 const rebuildOpts = {
                     quiet: true,
                     forceRebuild: true,
                     followSymlinks: flags.followSymlinks,
+                    includeBundled,
                     maxFiles: flags.maxFiles,
                     workers: flags.workers,
                 };
-                if (flags.cache && !flags.maxFiles) {
+                if (flags.cache && !flags.maxFiles && !includeBundled) {
                     index.buildCached(rebuildOpts, {
                         onWait: () => console.log('Waiting for another ucn process building the index...'),
                     });

package/core/analysis.js

@@ -2052,7 +2052,14 @@ function diffImpact(index, options = {}) {
             if (known.has(localRel)) continue;
             const filePath = path.join(index.root, localRel);
             const fileEntry = index.files.get(filePath);
-            if (!fileEntry || !detectLanguage(filePath)) continue;
+            if (!fileEntry || !detectLanguage(filePath)) {
+                changes.push({
+                    filePath, relativePath: localRel,
+                    gitRelativePath: projectPrefix ? `${projectPrefix}/${localRel}` : localRel,
+                    addedLines: [], deletedLines: [], untracked: true,
+                });
+                continue;
+            }
             let lineCount = fileEntry.lines;
             if (!Number.isFinite(lineCount)) {
                 try { lineCount = fs.readFileSync(filePath, 'utf-8').split('\n').length; } catch (_) { continue; }
@@ -2096,7 +2103,10 @@ function diffImpact(index, options = {}) {
 
     for (const change of changes) {
         const lang = detectLanguage(change.filePath);
-        if (!lang) { nonSourcePaths++; continue; }
+        if (!lang || (change.untracked && !index.files.has(change.filePath))) {
+            nonSourcePaths++;
+            continue;
+        }
 
         const fileEntry = index.files.get(change.filePath);
 

package/core/cache.js

@@ -711,7 +711,9 @@ function clearAllCaches() {
 // v224 (#355 recovery): Go declaration origins; Rust aliases, wrapper patterns,
 // copied bindings and qualified macro receivers; TS indexed array evidence.
 // v225 (fix #357): Rust `use path::name as local` bindings record the original name with a paired `renames` alias.
-const CACHE_FORMAT_VERSION = 225;
+// v226: bundled/minified filename exclusions are disclosed in discoveryIssues.
+// v227: signature parameter/return text excludes AST comments in every language.
+const CACHE_FORMAT_VERSION = 227;
 const USAGE_CACHE_FILE = 'usage-results.json';
 
 /**
@@ -935,6 +937,7 @@ function saveCache(index, cachePath) {
         unsupportedFiles: Array.isArray(index.unsupportedFiles)
             ? index.unsupportedFiles
             : [],
+        includeBundled: index.includeBundled === true,
         discoveryIssues: Array.isArray(index.discoveryIssues)
             ? index.discoveryIssues
             : [],
@@ -1164,6 +1167,7 @@ function loadCache(index, cachePath) {
         index.unsupportedFiles = Array.isArray(cacheData.unsupportedFiles)
             ? cacheData.unsupportedFiles
             : [];
+        index.includeBundled = cacheData.includeBundled === true;
         index.discoveryIssues = Array.isArray(cacheData.discoveryIssues)
             ? cacheData.discoveryIssues
             : [];
@@ -1302,8 +1306,13 @@ function isCacheStale(index) {
     // Only reached when all cached files are unchanged.
     const pattern = detectProjectPattern(index.root);
     const currentUnsupported = [];
+    const currentBundled = [];
     const globOpts = {
         root: index.root,
+        includeBundled: index.includeBundled === true,
+        onDiscoveryIssue: issue => {
+            if (issue.reason === 'bundled') currentBundled.push(path.relative(index.root, issue.path));
+        },
         onSkippedFile: (filePath) => {
             const kind = classifyUnsupportedSourceFile(filePath);
             if (!kind) return;
@@ -1321,6 +1330,11 @@ function isCacheStale(index) {
         globOpts.ignores = [...DEFAULT_IGNORES, ...configExclude];
     }
     const currentFiles = expandGlob(pattern, globOpts);
+    const cachedBundled = (index.discoveryIssues || [])
+        .filter(issue => issue.reason === 'bundled').map(issue => issue.relativePath).sort();
+    currentBundled.sort();
+    if (cachedBundled.length !== currentBundled.length ||
+        cachedBundled.some((value, i) => value !== currentBundled[i])) return true;
     const cachedPaths = new Set(index.files.keys());
     const currentPaths = new Set(currentFiles);
 

package/core/check.js

@@ -73,6 +73,11 @@ function check(index, options = {}) {
     const modified = (dr && Array.isArray(dr.functions)) ? dr.functions : [];
     const added    = (dr && Array.isArray(dr.newFunctions)) ? dr.newFunctions : [];
     const deleted  = (dr && Array.isArray(dr.deletedFunctions)) ? dr.deletedFunctions : [];
+    const pathCounts = {
+        changedPaths: dr?.changedPaths || 0,
+        nonSourcePaths: dr?.nonSourcePaths || 0,
+        untrackedPaths: dr?.untrackedPaths || 0,
+    };
 
     const allChanged = [
         ...modified.map(f => ({ ...f, _kind: 'modified' })),
@@ -99,6 +104,7 @@ function check(index, options = {}) {
             status: 'clean',
             empty: true,
             reason,
+            ...pathCounts,
         };
     }
 
@@ -293,6 +299,7 @@ function check(index, options = {}) {
         staged: !!options.staged,
         ok: true,
         status: 'checked',
+        ...pathCounts,
         changed: items,
         totalChanged: allChanged.length + deleted.length,
         truncated: !!(limit && allChanged.length > limit),

package/core/discovery.js

@@ -52,16 +52,15 @@ const DEFAULT_IGNORES = [
     '.pytest_cache',
     '.mypy_cache',
 
-    // Bundled/minified
-    '*.min.js',
-    '*.bundle.js',
-    '*.map',
-
     // System
     '.DS_Store',
     '.ucn-cache'
 ];
 
+// These can contain user code: disclose their exclusion, unlike dependency
+// and VCS directories. Source maps are data and cannot be parsed as code.
+const BUNDLED_PATTERNS = ['*.min.js', '*.bundle.js', '*.map'];
+
 // Conditional ignores - only ignore when marker file exists in same directory
 // Maps directory name -> array of marker files that indicate it's a vendor dir
 const CONDITIONAL_IGNORES = {
@@ -340,6 +339,7 @@ function expandGlob(pattern, options = {}) {
         maxDepth,
         maxFileSize,
         followSymlinks,
+        includeBundled: options.includeBundled === true,
         // Anchored gitignore patterns ('/name') apply only to entries directly
         // under the project root — the .gitignore's own directory (fix #226).
         anchorRoot: root,
@@ -530,6 +530,16 @@ function walkDir(dir, options, depth = 0, visited = new Set()) {
                 walkDir(fullPath, options, depth + 1, visited);
             }
         } else if (isFile) {
+            if (shouldIgnore(entry.name, BUNDLED_PATTERNS) &&
+                (!options.includeBundled || entry.name.endsWith('.map'))) {
+                options.onDiscoveryIssue?.({
+                    path: fullPath, kind: 'file', reason: 'bundled',
+                    detail: entry.name.endsWith('.map')
+                        ? 'source maps are not supported source files'
+                        : 'bundled/minified filename; use --include-bundled to index',
+                });
+                continue;
+            }
             if (options.filePattern.test(entry.name)) {
                 let size;
                 try { size = fs.statSync(fullPath).size; } catch (e) {

package/core/execute.js

@@ -292,6 +292,11 @@ function num(val, fallback) {
     return isNaN(n) ? fallback : n;
 }
 
+/** Shared listing bound; shell listings remain uncapped unless requested. */
+function listingLimit(p) {
+    return num(p.limit, undefined) || (p.lines || p.all ? undefined : 500);
+}
+
 /**
  * Apply limit to an array result.
  * Returns { items, total, limited } where limited is true if truncated.
@@ -771,7 +776,7 @@ const HANDLERS = {
             ...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,
+            top: p.top || listingLimit(p),
             limit: undefined,
         });
         if (!failure && selected.has('stats')) failure = collect('stats', 'stats', p);
@@ -1147,10 +1152,13 @@ const HANDLERS = {
                 if (!p.withSource && Array.isArray(response.result)) {
                     response.result = response.result.map(({ code, ...item }) => item);
                 }
-                const limit = num(p.limit, undefined);
+                const limit = listingLimit(p);
                 if (limit && limit > 0 && Array.isArray(response.result)) {
                     const { items, total, limited } = applyLimit(response.result, limit);
                     response.result = items;
+                    Object.defineProperty(items, 'findInfo', {
+                        value: { total, shown: items.length }, enumerable: false,
+                    });
                     if (limited) {
                         const note = limitNote(limit, total);
                         response.note = response.note ? `${response.note}\n${note}` : note;
@@ -1184,9 +1192,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,
+            // Filter and bound the inventory before resolving any callers.
+            // Shell listings do not need the activity pass at all.
+            skipCounts: true,
             exclude,
             in: p.in,
         });
@@ -1204,9 +1212,6 @@ const HANDLERS = {
             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 => [
@@ -1234,11 +1239,21 @@ const HANDLERS = {
             }
         }
         // Apply limit
-        const limit = num(p.limit, undefined);
-        if (limit && limit > 0) {
-            const { items, total, limited } = applyLimit(result, limit);
-            if (limited) notes.push(limitNote(limit, total));
-            result = items;
+        const limit = listingLimit(p);
+        if (!p.lines) {
+            index._beginOp();
+            try {
+                result = index._applyFindFilters(result, { limit });
+            } finally { index._endOp(); }
+        } else {
+            result = applyLimit(result, limit).items;
+        }
+        if (result.length < fullFindCount) {
+            notes.push(limitNote(result.length, fullFindCount));
+            if (!p.lines) notes.push('Selection ranked by approximate usage totals; returned activity counts use definition-pinned caller evidence.');
+        }
+        if (p.withSource) {
+            result = result.map(item => ({ ...item, code: readAndExtract(item) }));
         }
         Object.defineProperty(result, 'findInfo', {
             value: {
@@ -1299,12 +1314,18 @@ const HANDLERS = {
             const hidden = unfiltered.length - result.length;
             if (hidden > 0) notes.push(`${hidden} test-file usage(s) hidden by default — pass --include-tests to include them.`);
         }
-        // Apply limit to total usages (result is a flat array)
+        // Apply limit to total usages (result is a flat array). usages is the
+        // escape-hatch listing (fix #284): only an EXPLICIT limit caps it; the
+        // release command-surface gate reads every oracle reference from it.
         const limit = num(p.limit, undefined);
         let limited = result;
         if (limit && limit > 0 && Array.isArray(result) && result.length > limit) {
             notes.push(limitNote(limit, result.length));
             limited = result.slice(0, limit);
+            Object.defineProperty(limited, 'limitInfo', {
+                value: { total: result.length, shown: limited.length },
+                enumerable: false,
+            });
             // Summary counts describe the FULL result set — the limit applies
             // to listed entries only (fix #237: the header claimed '0 calls'
             // for a called function whenever the definition filled the limit).
@@ -1640,7 +1661,7 @@ const HANDLERS = {
             file: p.file,
         });
         // Apply limit to dead code results (result is an array with custom properties)
-        const limit = num(p.limit, undefined);
+        const limit = listingLimit(p);
         let note;
         if (limit && limit > 0 && Array.isArray(result) && result.length > limit) {
             note = limitNote(limit, result.length);
@@ -2309,7 +2330,7 @@ const HANDLERS = {
     },
 
     api: (index, p) => {
-        if (p.file) {
+        if (p.file && typeof index.resolveFilePathForQuery(p.file) !== 'string') {
             const fileErr = checkFilePatternMatch(index, p.file);
             if (fileErr) return { ok: false, error: fileErr };
         }
@@ -2325,13 +2346,13 @@ const HANDLERS = {
                 return { ok: false, error: `No files matched the 'in' directory filter '${p.in}'.` };
             }
         }
-        let result = index.api(p.file, { in: p.in });
+        let result = index.api(p.file, { in: p.in, includeTests: p.includeTests });
         if (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)
-        const limit = num(p.limit, undefined);
+        const limit = listingLimit(p);
         let note;
         if (limit && limit > 0 && Array.isArray(result)) {
             const { items, total, limited } = applyLimit(result, limit);
@@ -2353,6 +2374,10 @@ const HANDLERS = {
             }
             result = items;
         }
+        if (result.apiInfo?.excludedTestFiles > 0) {
+            const excluded = `${result.apiInfo.excludedTestFiles} test file(s) excluded from API; use --include-tests to include them, or name an exact file.`;
+            note = note ? `${note}\n${excluded}` : excluded;
+        }
         return { ok: true, result, note };
     },
 
@@ -2494,7 +2519,18 @@ function execute(index, command, params = {}) {
                 }
             }
         }
-        return handler(index, params);
+        const response = handler(index, params);
+        const bundled = (index.discoveryIssues || []).filter(issue => issue.reason === 'bundled');
+        if (bundled.length > 0) {
+            const files = bundled.slice(0, 5).map(issue => issue.relativePath).join(', ');
+            const note = `UCN skipped ${bundled.length} bundled/minified or source-map file(s): ${files}` +
+                (bundled.length > 5 ? ', ...' : '') +
+                '. This is not a repository-wide semantic zero; use --include-bundled for JavaScript bundles ' +
+                '(source maps remain unindexed), or grep/ripgrep to inspect skipped files.';
+            if (response.ok) response.note = combineNotes([response.note, note]);
+            else response.error = `${response.error}\n${note}`;
+        }
+        return response;
     } catch (e) {
         return { ok: false, error: e.message };
     }