ucn 3.7.46 → 3.8.0

package/core/deadcode.js

@@ -7,14 +7,29 @@
 
 const { detectLanguage, getParser, getLanguageModule, safeParse } = require('../languages');
 const { isTestFile } = require('./discovery');
+const { escapeRegExp } = require('./shared');
+
+/** Check if a position in a line is inside a string literal (quotes/backticks) */
+function isInsideString(line, pos) {
+    let inSingle = false, inDouble = false, inBacktick = false;
+    for (let j = 0; j < pos; j++) {
+        const ch = line[j];
+        if (ch === '\\') { j++; continue; }
+        if (ch === '"' && !inSingle && !inBacktick) inDouble = !inDouble;
+        if (ch === "'" && !inDouble && !inBacktick) inSingle = !inSingle;
+        if (ch === '`' && !inDouble && !inSingle) inBacktick = !inBacktick;
+    }
+    return inSingle || inDouble || inBacktick;
+}
 
 /**
- * Build a usage index for all identifiers in the codebase (optimized for deadcode)
+ * Build a usage index for identifiers in the codebase (optimized for deadcode)
  * Scans all files ONCE and builds a reverse index: name -> [usages]
  * @param {object} index - ProjectIndex instance
+ * @param {Set<string>} [filterNames] - If provided, only track these names (reduces memory)
  * @returns {Map<string, Array>} Usage index
  */
-function buildUsageIndex(index) {
+function buildUsageIndex(index, filterNames) {
     const usageIndex = new Map(); // name -> [{file, line}]
 
     for (const [filePath, fileEntry] of index.files) {
@@ -24,6 +39,19 @@ function buildUsageIndex(index) {
 
             const content = index._readFile(filePath);
 
+            // Text pre-filter: skip files that don't contain any target names
+            // (avoids expensive tree-sitter parse + AST traversal for irrelevant files)
+            if (filterNames && filterNames.size > 0) {
+                let hasAny = false;
+                for (const name of filterNames) {
+                    if (content.includes(name)) {
+                        hasAny = true;
+                        break;
+                    }
+                }
+                if (!hasAny) continue;
+            }
+
             // For HTML files, parse the virtual JS content instead of raw HTML
             // (HTML tree-sitter sees script content as raw_text, not JS identifiers)
             let tree;
@@ -72,6 +100,8 @@ function buildUsageIndex(index) {
                             }
                         }
                         // Member expression property: obj.Separator — not a standalone reference
+                        // EXCEPTION: If the selector/member expression is part of a call_expression,
+                        // this IS a method call (e.g., dc.syncDeployment()) and should count as usage.
                         if (parentType === 'member_expression' ||
                             parentType === 'field_expression' ||
                             parentType === 'member_access_expression' ||
@@ -82,15 +112,31 @@ function buildUsageIndex(index) {
                             // by checking if it's NOT the object (left side)
                             const firstChild = node.parent.child(0);
                             if (firstChild !== node) {
-                                // This is the property part — skip it for deadcode counting
-                                for (let i = 0; i < node.childCount; i++) {
-                                    traverse(node.child(i));
+                                // Check if this member expression is part of a call or
+                                // used as a function reference (callback argument)
+                                const grandparent = node.parent.parent;
+                                const isCall = grandparent &&
+                                    (grandparent.type === 'call_expression' ||
+                                     grandparent.type === 'argument_list' ||
+                                     grandparent.type === 'arguments');
+                                if (!isCall) {
+                                    // Pure field access — skip for deadcode counting
+                                    for (let i = 0; i < node.childCount; i++) {
+                                        traverse(node.child(i));
+                                    }
+                                    return;
                                 }
-                                return;
+                                // Method call or callback — fall through to count as usage
                             }
                         }
                     }
                     const name = node.text;
+                    if (filterNames && !filterNames.has(name)) {
+                        for (let i = 0; i < node.childCount; i++) {
+                            traverse(node.child(i));
+                        }
+                        return;
+                    }
                     if (!usageIndex.has(name)) {
                         usageIndex.set(name, []);
                     }
@@ -144,19 +190,89 @@ function deadcode(index, options = {}) {
     let excludedDecorated = 0;
     let excludedExported = 0;
 
-    // Build usage index once (instead of per-symbol)
-    const usageIndex = buildUsageIndex(index);
+    // Ensure callee index is built (lazy, reused across operations)
+    if (!index.calleeIndex) {
+        index.buildCalleeIndex();
+    }
+
+    // Collect callable symbol names to reduce usage index scope
+    const callableTypes = ['function', 'method', 'static', 'public', 'abstract', 'constructor'];
+    const callableNames = new Set();
+    for (const [symbolName, symbols] of index.symbols) {
+        if (symbols.some(s => callableTypes.includes(s.type))) {
+            callableNames.add(symbolName);
+        }
+    }
+
+    // Pre-filter: names in the callee index have call sites → definitely used → not dead.
+    const potentiallyDeadNames = new Set();
+    for (const name of callableNames) {
+        if (!index.calleeIndex.has(name)) {
+            potentiallyDeadNames.add(name);
+        }
+    }
+
+    // Build usage index for potentially dead names using text scan (no tree-sitter reparsing).
+    // The callee index already covers all call-based usages. For remaining names, a word-boundary
+    // text scan catches imports, exports, shorthand properties, type refs, and variable refs.
+    // Trade-off: may match names in comments/strings (false "used" → fewer dead code reports),
+    // but avoids ~1.9s of tree-sitter re-parsing. buildUsageIndex() is kept for direct callers.
+    const usageIndex = new Map();
+    if (potentiallyDeadNames.size > 0) {
+        for (const [filePath, fileEntry] of index.files) {
+            try {
+                const content = index._readFile(filePath);
+                const lines = content.split('\n');
+                for (const name of potentiallyDeadNames) {
+                    if (!content.includes(name)) continue;
+                    const nameLen = name.length;
+                    for (let i = 0; i < lines.length; i++) {
+                        const line = lines[i];
+                        if (!line.includes(name)) continue;
+                        // Skip line if entirely inside a line comment (// or #)
+                        const commentIdx = line.indexOf('//');
+                        const hashIdx = line.indexOf('#');
+                        let searchFrom = 0;
+                        while (searchFrom < line.length) {
+                            const pos = line.indexOf(name, searchFrom);
+                            if (pos === -1) break;
+                            searchFrom = pos + 1;
+                            // Word boundary check
+                            if (pos > 0 && /\w/.test(line[pos - 1])) continue;
+                            if (pos + nameLen < line.length && /\w/.test(line[pos + nameLen])) continue;
+                            // Skip if inside a // comment (not :// URL)
+                            if (commentIdx !== -1 && commentIdx < pos &&
+                                (commentIdx === 0 || line[commentIdx - 1] !== ':')) continue;
+                            // Skip if inside a # comment (Python — # preceded by whitespace or at start)
+                            if (hashIdx !== -1 && hashIdx < pos &&
+                                (hashIdx === 0 || /\s/.test(line[hashIdx - 1]))) continue;
+                            // Skip if inside a string literal
+                            if (isInsideString(line, pos)) continue;
+                            // Skip property/field access: preceded by '.' unless followed by '(' (method call)
+                            if (pos > 0 && line[pos - 1] === '.' &&
+                                (pos + nameLen >= line.length || line[pos + nameLen] !== '(')) continue;
+                            // Skip object literal key: name followed by ':' (not '::' for Rust paths)
+                            const afterChar = pos + nameLen < line.length ? line[pos + nameLen] : '';
+                            const afterChar2 = pos + nameLen + 1 < line.length ? line[pos + nameLen + 1] : '';
+                            if (afterChar === ':' && afterChar2 !== ':') continue;
+                            // Valid reference found
+                            if (!usageIndex.has(name)) usageIndex.set(name, []);
+                            usageIndex.get(name).push({
+                                file: filePath,
+                                line: i + 1,
+                                relativePath: fileEntry.relativePath
+                            });
+                            break; // one match per line is enough for deadcode
+                        }
+                    }
+                }
+            } catch {}
+        }
+    }
 
     for (const [name, symbols] of index.symbols) {
         for (const symbol of symbols) {
-            // Skip non-function/class types
-            // Include various method types from different languages:
-            // - function: standalone functions
-            // - class, struct, interface: type definitions (skip them in deadcode)
-            // - method: class methods
-            // - static, public, abstract: Java method modifiers used as types
-            // - constructor: constructors
-            const callableTypes = ['function', 'method', 'static', 'public', 'abstract', 'constructor'];
+            // Skip non-function/class types (callableTypes defined above)
             if (!callableTypes.includes(symbol.type)) {
                 continue;
             }
@@ -174,6 +290,11 @@ function deadcode(index, options = {}) {
                 continue;
             }
 
+            // Apply file filter (scopes deadcode to matching files)
+            if (options.file && !symbol.relativePath.includes(options.file)) {
+                continue;
+            }
+
             // Apply exclude and in filters
             if ((options.exclude && options.exclude.length > 0) || options.in) {
                 if (!index.matchesFilters(symbol.relativePath, { exclude: options.exclude, in: options.in })) {
@@ -282,7 +403,12 @@ function deadcode(index, options = {}) {
                 continue;
             }
 
-            // Use pre-built index for O(1) lookup instead of O(files) scan
+            // Fast path: name has call sites in callee index → definitely used → not dead
+            if (index.calleeIndex.has(name)) {
+                continue;
+            }
+
+            // Slow path: check AST-based usage index for remaining names
             const allUsages = usageIndex.get(name) || [];
 
             // Filter out usages that are at the definition location

package/core/discovery.js

@@ -191,7 +191,7 @@ function expandGlob(pattern, options = {}) {
     const root = path.resolve(options.root || process.cwd());
     const ignores = options.ignores || DEFAULT_IGNORES;
     const maxDepth = options.maxDepth || 20;
-    const maxFiles = options.maxFiles || 10000;
+    const maxFiles = options.maxFiles || 50000;
     const followSymlinks = options.followSymlinks !== false; // default true
 
     // Handle home directory expansion

package/core/execute.js

@@ -124,6 +124,34 @@ function num(val, fallback) {
     return isNaN(n) ? fallback : n;
 }
 
+/**
+ * Apply limit to an array result.
+ * Returns { items, total, limited } where limited is true if truncated.
+ */
+function applyLimit(arr, limit) {
+    if (!arr || !limit || limit <= 0 || arr.length <= limit) {
+        return { items: arr, total: arr ? arr.length : 0, limited: false };
+    }
+    return { items: arr.slice(0, limit), total: arr.length, limited: true };
+}
+
+/** Build a limit note string */
+function limitNote(limit, total) {
+    return `Showing ${limit} of ${total} results. Use --limit N to see more.`;
+}
+
+/**
+ * Check if a --file pattern matches any files in the index.
+ * Returns error string if no files match, null otherwise.
+ */
+function checkFilePatternMatch(index, filePattern) {
+    if (!filePattern) return null;
+    for (const [, fileEntry] of index.files) {
+        if (fileEntry.relativePath.includes(filePattern)) return null;
+    }
+    return `No files matched pattern '${filePattern}'.`;
+}
+
 /** Read a file and extract lines for a symbol match, applying HTML cleanup. */
 function readAndExtract(match) {
     const content = fs.readFileSync(match.file, 'utf-8');
@@ -180,6 +208,8 @@ const HANDLERS = {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
         const result = index.context(p.name, {
@@ -197,6 +227,8 @@ const HANDLERS = {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
         const result = index.impact(p.name, {
@@ -209,10 +241,56 @@ const HANDLERS = {
         return { ok: true, result };
     },
 
+    blast: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        applyClassMethodSyntax(p);
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
+        const classErr = validateClassName(index, p.name, p.className);
+        if (classErr) return { ok: false, error: classErr };
+        const depthVal = num(p.depth, undefined);
+        const result = index.blast(p.name, {
+            depth: depthVal ?? 3,
+            file: p.file,
+            className: p.className,
+            all: p.all || depthVal !== undefined,
+            exclude: toExcludeArray(p.exclude),
+            includeMethods: p.includeMethods,
+            includeUncertain: p.includeUncertain || false,
+        });
+        if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
+        return { ok: true, result };
+    },
+
+    reverseTrace: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        applyClassMethodSyntax(p);
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
+        const classErr = validateClassName(index, p.name, p.className);
+        if (classErr) return { ok: false, error: classErr };
+        const depthVal = num(p.depth, undefined);
+        const result = index.reverseTrace(p.name, {
+            depth: depthVal ?? 5,
+            file: p.file,
+            className: p.className,
+            all: p.all || depthVal !== undefined,
+            exclude: toExcludeArray(p.exclude),
+            includeMethods: p.includeMethods,
+            includeUncertain: p.includeUncertain || false,
+        });
+        if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
+        return { ok: true, result };
+    },
+
     smart: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
         const result = index.smart(p.name, {
             file: p.file,
             className: p.className,
@@ -228,6 +306,8 @@ const HANDLERS = {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
         const depthVal = num(p.depth, undefined);
         const result = index.trace(p.name, {
             depth: depthVal ?? 3,
@@ -245,6 +325,8 @@ const HANDLERS = {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
         const result = index.example(p.name, { file: p.file, className: p.className });
         if (!result) return { ok: false, error: `No examples found for "${p.name}".` };
         return { ok: true, result };
@@ -254,6 +336,8 @@ const HANDLERS = {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
         const result = index.related(p.name, {
             file: p.file,
             className: p.className,
@@ -270,14 +354,17 @@ const HANDLERS = {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
+        // Check if --file pattern matches any files
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
         // Auto-include tests when pattern clearly targets test functions
         // But only if the user didn't explicitly set include_tests=false
         let includeTests = p.includeTests;
-        if (includeTests === undefined && p.name && /^test[_*?]/i.test(p.name)) {
+        if (includeTests === undefined && p.name && /^test[_*?A-Z]/i.test(p.name)) {
             includeTests = true;
         }
         const exclude = applyTestExclusions(p.exclude, includeTests);
-        const result = index.find(p.name, {
+        let result = index.find(p.name, {
             file: p.file,
             className: p.className,
             exact: p.exact || false,
@@ -285,11 +372,18 @@ const HANDLERS = {
             in: p.in,
         });
         // Warn if exact mode silently disables glob expansion
-        let note;
+        const notes = [];
         if (p.exact && p.name && (p.name.includes('*') || p.name.includes('?'))) {
-            note = `Note: exact=true treats "${p.name}" as a literal name (glob expansion disabled).`;
+            notes.push(`Note: exact=true treats "${p.name}" as a literal name (glob expansion disabled).`);
         }
-        return { ok: true, result, note };
+        // 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;
+        }
+        return { ok: true, result, note: notes.length ? notes.join('\n') : undefined };
     },
 
     usages: (index, p) => {
@@ -304,7 +398,29 @@ const HANDLERS = {
             exclude,
             in: p.in,
         });
-        return { ok: true, result };
+        // Apply limit to total usages across files
+        const limit = num(p.limit, undefined);
+        let note;
+        if (limit && limit > 0 && result.files) {
+            let total = result.files.reduce((s, f) => s + f.usages.length, 0);
+            if (total > limit) {
+                let remaining = limit;
+                const truncated = [];
+                for (const f of result.files) {
+                    if (remaining <= 0) break;
+                    if (f.usages.length <= remaining) {
+                        truncated.push(f);
+                        remaining -= f.usages.length;
+                    } else {
+                        truncated.push({ ...f, usages: f.usages.slice(0, remaining) });
+                        remaining = 0;
+                    }
+                }
+                result.files = truncated;
+                note = limitNote(limit, total);
+            }
+        }
+        return { ok: true, result, note };
     },
 
     toc: (index, p) => {
@@ -315,14 +431,73 @@ const HANDLERS = {
             top: num(p.top, undefined),
             file: p.file,
         });
-        return { ok: true, result };
+        // Apply limit to detailed toc entries
+        const limit = num(p.limit, undefined);
+        let note;
+        if (limit && limit > 0 && p.detailed && result.files) {
+            let totalEntries = result.files.reduce((s, f) => s + (f.functions?.length || 0) + (f.classes?.length || 0), 0);
+            if (totalEntries > limit) {
+                let remaining = limit;
+                for (const f of result.files) {
+                    if (remaining <= 0) {
+                        f.functions = [];
+                        f.classes = [];
+                        continue;
+                    }
+                    const fns = f.functions?.length || 0;
+                    const cls = f.classes?.length || 0;
+                    if (fns + cls <= remaining) {
+                        remaining -= fns + cls;
+                    } else {
+                        if (f.functions && remaining > 0) {
+                            f.functions = f.functions.slice(0, remaining);
+                            remaining -= f.functions.length;
+                        }
+                        if (f.classes && remaining > 0) {
+                            f.classes = f.classes.slice(0, remaining);
+                            remaining -= f.classes.length;
+                        } else if (f.classes) {
+                            f.classes = [];
+                        }
+                    }
+                }
+                note = limitNote(limit, totalEntries);
+            }
+        }
+        return { ok: true, result, note };
     },
 
     search: (index, p) => {
+        // Detect structural search mode: any of these flags triggers index-based search
+        const isStructural = p.type || p.param || p.receiver || p.returns || p.decorator || p.exported || p.unused;
+        if (isStructural) {
+            const exclude = applyTestExclusions(p.exclude, p.includeTests);
+            const topVal = num(p.top, undefined) || num(p.limit, undefined);
+            const result = index.structuralSearch({
+                term: p.term || p.name,
+                type: p.type,
+                param: p.param,
+                receiver: p.receiver,
+                returns: p.returns,
+                decorator: p.decorator,
+                exported: p.exported || false,
+                unused: p.unused || false,
+                caseSensitive: p.caseSensitive || false,
+                exclude,
+                in: p.in,
+                file: p.file,
+                top: topVal || 50,
+            });
+            if (result.meta.error) return { ok: false, error: result.meta.error };
+            return { ok: true, result, structural: true };
+        }
+
         const err = requireTerm(p.term);
         if (err) return { ok: false, error: err };
         const testsExcluded = !p.includeTests;
         const exclude = applyTestExclusions(p.exclude, p.includeTests);
+        // Use limit as top if top not set
+        const topVal = num(p.top, undefined) || num(p.limit, undefined);
         const result = index.search(p.term, {
             codeOnly: p.codeOnly || false,
             context: num(p.context, 0),
@@ -330,7 +505,8 @@ const HANDLERS = {
             exclude,
             in: p.in,
             regex: p.regex,
-            top: num(p.top, undefined),
+            top: topVal,
+            file: p.file,
         });
         if (result.meta) result.meta.testsExcluded = testsExcluded;
         return { ok: true, result };
@@ -347,15 +523,49 @@ const HANDLERS = {
         return { ok: true, result };
     },
 
+    affectedTests: (index, p) => {
+        const err = requireName(p.name);
+        if (err) return { ok: false, error: err };
+        applyClassMethodSyntax(p);
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
+        const classErr = validateClassName(index, p.name, p.className);
+        if (classErr) return { ok: false, error: classErr };
+        const depthVal = num(p.depth, undefined);
+        const result = index.affectedTests(p.name, {
+            depth: depthVal ?? 3,
+            file: p.file,
+            className: p.className,
+            exclude: toExcludeArray(p.exclude),
+            includeMethods: p.includeMethods,
+            includeUncertain: p.includeUncertain || false,
+        });
+        if (!result) return { ok: false, error: `Function "${p.name}" not found.` };
+        return { ok: true, result };
+    },
+
     deadcode: (index, p) => {
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
         const result = index.deadcode({
             includeExported: p.includeExported || false,
             includeDecorated: p.includeDecorated || false,
             includeTests: p.includeTests || false,
             exclude: toExcludeArray(p.exclude),
             in: p.in,
+            file: p.file,
         });
-        return { ok: true, result };
+        // Apply limit to dead code results
+        const limit = num(p.limit, undefined);
+        let note;
+        if (limit && limit > 0 && result.dead) {
+            const { items, total, limited } = applyLimit(result.dead, limit);
+            if (limited) {
+                note = limitNote(limit, total);
+                result.dead = items;
+            }
+        }
+        return { ok: true, result, note };
     },
 
     // ── Extracting Code ─────────────────────────────────────────────────
@@ -364,6 +574,8 @@ const HANDLERS = {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
 
         const fnNames = p.name.includes(',')
             ? p.name.split(',').map(n => n.trim()).filter(Boolean)
@@ -424,6 +636,8 @@ const HANDLERS = {
     class: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
 
         const CLASS_TYPES = ['class', 'interface', 'type', 'enum', 'struct', 'trait'];
         const matches = index.find(p.name, { file: p.file, skipCounts: true })
@@ -579,12 +793,22 @@ const HANDLERS = {
         return { ok: true, result };
     },
 
+    circularDeps: (index, p) => {
+        const result = index.circularDeps({
+            file: p.file,
+            exclude: toExcludeArray(p.exclude),
+        });
+        return { ok: true, result };
+    },
+
     // ── Refactoring ─────────────────────────────────────────────────────
 
     verify: (index, p) => {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
         const result = index.verify(p.name, { file: p.file, className: p.className });
@@ -595,6 +819,8 @@ const HANDLERS = {
         const err = requireName(p.name);
         if (err) return { ok: false, error: err };
         applyClassMethodSyntax(p);
+        const fileErr = checkFilePatternMatch(index, p.file);
+        if (fileErr) return { ok: false, error: fileErr };
         const classErr = validateClassName(index, p.name, p.className);
         if (classErr) return { ok: false, error: classErr };
         if (!p.addParam && !p.removeParam && !p.renameTo) {
@@ -639,12 +865,20 @@ const HANDLERS = {
     },
 
     api: (index, p) => {
-        const result = index.api(p.file);
+        let result = index.api(p.file);
         if (p.file) {
             const fileErr = checkFileError(result, p.file);
             if (fileErr) return { ok: false, error: fileErr };
         }
-        return { ok: true, result };
+        // Apply limit to api results (api returns an array)
+        const limit = num(p.limit, undefined);
+        let note;
+        if (limit && limit > 0 && Array.isArray(result)) {
+            const { items, total, limited } = applyLimit(result, limit);
+            if (limited) note = limitNote(limit, total);
+            result = items;
+        }
+        return { ok: true, result, note };
     },
 
     stats: (index, p) => {