@descent-vtt/spec-guard 0.1.0 → 0.3.0

package/dist/engine.js

@@ -17,7 +17,8 @@
 import { spawn } from 'node:child_process';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import { createGlobMatcher, toPosix, walkFiles } from './glob.js';
+import { createCommentMask } from './comments.js';
+import { createExcludeMatcher, createGlobMatcher, toPosix, walkFiles } from './glob.js';
 /** Files larger than this are skipped by both engines, keeping them in sync. */
 export const MAX_FILE_SIZE = 20 * 1024 * 1024;
 /** Hard cap on collected locations; the reporter only ever shows a handful. */
@@ -31,11 +32,31 @@ function truncate(value) {
     const trimmed = value.replace(/\r?\n$/, '');
     return trimmed.length > MAX_SNIPPET_LENGTH ? `${trimmed.slice(0, MAX_SNIPPET_LENGTH)}…` : trimmed;
 }
-function sortLocations(locations) {
+/**
+ * Converts ripgrep's byte column into a character column.
+ *
+ * ripgrep counts bytes; the scanner counts characters, and so does every editor
+ * that a reader will paste the location into. On an ASCII line the two agree,
+ * which is why the difference went unnoticed - it only appears once a line
+ * holds a non-ASCII character before the match, and then the two engines report
+ * different columns for the same match.
+ */
+export function byteColumnToCharacter(line, byteOffset) {
+    // One byte per character, so the offset is already a character count. This
+    // also covers the case where ripgrep gave us no line text to measure.
+    if (line.length === Buffer.byteLength(line))
+        return byteOffset + 1;
+    return Buffer.from(line, 'utf8').subarray(0, byteOffset).toString('utf8').length + 1;
+}
+/**
+ * Orders matches by path, then by line. ripgrep searches in parallel and emits
+ * files in no fixed order, so this is what makes snippet output stable.
+ */
+export function sortLocations(locations) {
     return locations.sort((a, b) => (a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1));
 }
 function emptyTally() {
-    return { count: 0, locations: [] };
+    return { count: 0, locations: [], commentCount: 0 };
 }
 /**
  * True when no two of these literals can ever match overlapping text, which is
@@ -75,6 +96,8 @@ function sharesOnePass(requests) {
         request.options.ignoreCase === first.options.ignoreCase &&
         request.options.globs.length === first.options.globs.length &&
         request.options.globs.every((glob, index) => glob === first.options.globs[index]) &&
+        request.options.excludeGlobs.length === first.options.excludeGlobs.length &&
+        request.options.excludeGlobs.every((glob, index) => glob === first.options.excludeGlobs[index]) &&
         request.options.excludeFiles === first.options.excludeFiles);
 }
 /** Runs requests through the batch API when the engine has one. */
@@ -131,6 +154,10 @@ export function buildRipgrepArgs(request, patterns = [request.symbol]) {
         args.push('--ignore-case');
     for (const glob of options.globs)
         args.push('--glob', glob);
+    // ripgrep reads a leading "!" as an exclusion, with gitignore semantics that
+    // createExcludeMatcher mirrors for the JavaScript engine.
+    for (const glob of options.excludeGlobs)
+        args.push('--glob', `!${glob}`);
     for (const pattern of patterns)
         args.push('--regexp', pattern);
     args.push('--');
@@ -147,6 +174,10 @@ class RipgrepEngine {
         this.binary = binary;
     }
     async search(request) {
+        if (request.options.ignoreComments) {
+            const [result] = await this.commentAware(request, [request.symbol], [request]);
+            return result;
+        }
         const tallies = await this.run(request, [request.symbol]);
         return this.toResult(tallies.get(request.symbol));
     }
@@ -155,14 +186,21 @@ class RipgrepEngine {
         if (!first)
             return [];
         const patterns = [...new Set(requests.map((request) => request.symbol))];
-        const batchable = patterns.length > 1 && !first.options.regex && !first.options.ignoreCase && canBatchLiterals(patterns);
-        if (!batchable) {
+        // Comment-aware counting needs the file's text, which ripgrep's match
+        // stream does not carry. Rather than re-implement classification twice,
+        // ripgrep is used for what it is unmatched at - telling us which handful of
+        // files out of thousands contain the symbol at all - and those files are
+        // then counted by the scanner, which already knows about comments. Both
+        // engines therefore produce comment-aware counts through one code path.
+        if (first.options.ignoreComments) {
+            return this.commentAware(first, patterns, requests);
+        }
+        if (!shouldBatchPatterns(patterns, first.options)) {
             return Promise.all(requests.map((request) => this.search(request)));
         }
         try {
             const tallies = await this.run(first, patterns);
             return requests.map((request) => this.toResult(tallies.get(request.symbol)));
-            /* c8 ignore next 4 */
         }
         catch (error) {
             if (!(error instanceof UnattributableBatch))
@@ -170,9 +208,63 @@ class RipgrepEngine {
             return Promise.all(requests.map((request) => this.search(request)));
         }
     }
+    /**
+     * Two-phase search, used whenever comments must be classified.
+     *
+     * The result still names ripgrep: it did the searching, and classification is
+     * a post-step both engines share rather than a different engine.
+     */
+    async commentAware(request, patterns, requests) {
+        const files = await this.filesWithMatches(request, patterns);
+        const results = await javascriptEngine.searchFiles(files, requests);
+        return results.map((result) => ({ ...result, engine: this.name }));
+    }
+    /** Phase one: which files contain any of these patterns at all. */
+    filesWithMatches(request, patterns) {
+        return new Promise((resolve, reject) => {
+            const args = buildRipgrepArgs(request, patterns).map((argument) => argument === '--json' ? '--files-with-matches' : argument);
+            const child = spawn(this.binary, args, {
+                cwd: request.root,
+                windowsHide: true,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let stderr = '';
+            child.stdout.setEncoding('utf8');
+            child.stdout.on('data', (chunk) => (stdout += chunk));
+            child.stderr.setEncoding('utf8');
+            child.stderr.on('data', (chunk) => (stderr += chunk));
+            child.once('error', reject);
+            child.once('close', (code) => {
+                // 0 = matches, 1 = none, anything else is a real failure.
+                if (code !== 0 && code !== 1) {
+                    reject(new Error(`ripgrep exited with code ${code}${stderr ? `: ${stderr.trim()}` : ''}`));
+                    return;
+                }
+                const files = [];
+                for (const line of stdout.split('\n')) {
+                    const trimmed = line.trim();
+                    if (trimmed.length === 0)
+                        continue;
+                    const absolutePath = path.resolve(request.root, trimmed);
+                    if (request.options.excludeFiles.has(absolutePath))
+                        continue;
+                    files.push({ absolutePath, relativePath: toPosix(path.relative(request.root, absolutePath)) });
+                }
+                files.sort((a, b) => (a.relativePath < b.relativePath ? -1 : 1));
+                resolve(files);
+            });
+        });
+    }
     toResult(tally) {
         const resolved = tally ?? emptyTally();
-        return { count: resolved.count, matches: sortLocations(resolved.locations), engine: this.name };
+        return {
+            count: resolved.count,
+            commentMatches: resolved.commentCount,
+            unclassifiedFiles: 0,
+            matches: sortLocations(resolved.locations),
+            engine: this.name,
+        };
     }
     /** One ripgrep pass; returns a tally per pattern. */
     run(request, patterns) {
@@ -182,62 +274,15 @@ class RipgrepEngine {
                 windowsHide: true,
                 stdio: ['ignore', 'pipe', 'pipe'],
             });
-            const single = patterns.length === 1 ? patterns[0] : null;
-            const tallies = new Map(patterns.map((pattern) => [pattern, emptyTally()]));
+            const sink = createRipgrepSink(request, patterns);
             let pending = '';
             let stderr = '';
-            let failure = null;
-            const handleEvent = (line) => {
-                if (line.length === 0 || failure)
-                    return;
-                let event;
-                try {
-                    event = JSON.parse(line);
-                }
-                catch {
-                    /* c8 ignore next -- ripgrep only ever emits valid JSON lines */
-                    return;
-                }
-                if (event.type !== 'match' || !event.data)
-                    return;
-                const data = event.data;
-                const submatches = data.submatches ?? [];
-                if (submatches.length === 0)
-                    return;
-                // ripgrep echoes the path as given ("./src/a.ts" when the target is
-                // "."); normalise so both engines report the same relative path.
-                const absolute = path.resolve(request.root, decodeText(data.path));
-                if (request.options.excludeFiles.has(absolute))
-                    return;
-                const file = toPosix(path.relative(request.root, absolute));
-                const lineNumber = data.line_number ?? 0;
-                const text = truncate(decodeText(data.lines));
-                for (const submatch of submatches) {
-                    // With --fixed-strings and no --ignore-case the matched text is the
-                    // pattern verbatim, which is what makes attribution exact.
-                    const pattern = single ?? decodeText(submatch.match);
-                    const tally = tallies.get(pattern);
-                    /* c8 ignore next 4 -- belt and braces: --fixed-strings guarantees a hit */
-                    if (!tally) {
-                        failure = new UnattributableBatch(`ripgrep reported an unexpected match: ${pattern}`);
-                        return;
-                    }
-                    tally.count += 1;
-                    const last = tally.locations.at(-1);
-                    if (last && last.file === file && last.line === lineNumber) {
-                        last.count += 1;
-                    }
-                    else if (tally.locations.length < MAX_COLLECTED_MATCHES) {
-                        tally.locations.push({ file, line: lineNumber, column: (submatch.start ?? 0) + 1, text, count: 1 });
-                    }
-                }
-            };
             child.stdout.setEncoding('utf8');
             child.stdout.on('data', (chunk) => {
                 pending += chunk;
                 let newline = pending.indexOf('\n');
                 while (newline !== -1) {
-                    handleEvent(pending.slice(0, newline));
+                    sink.line(pending.slice(0, newline));
                     pending = pending.slice(newline + 1);
                     newline = pending.indexOf('\n');
                 }
@@ -248,9 +293,9 @@ class RipgrepEngine {
             });
             child.once('error', reject);
             child.once('close', (code) => {
-                handleEvent(pending);
-                if (failure) {
-                    reject(failure);
+                sink.line(pending);
+                if (sink.failure) {
+                    reject(sink.failure);
                     return;
                 }
                 // 0 = matches, 1 = no matches, 2 = an actual failure.
@@ -258,11 +303,93 @@ class RipgrepEngine {
                     reject(new Error(`ripgrep exited with code ${code}${stderr ? `: ${stderr.trim()}` : ''}`));
                     return;
                 }
-                resolve(tallies);
+                resolve(sink.tallies);
             });
         });
     }
 }
+/**
+ * Whether a set of patterns may share one ripgrep pass.
+ *
+ * Kept separate from the engine so the decision can be asserted directly: from
+ * the outside a correct batch and a correct set of separate passes are
+ * indistinguishable by design, which makes this the only place the rule is
+ * observable.
+ */
+export function shouldBatchPatterns(patterns, options) {
+    if (patterns.length <= 1)
+        return false;
+    if (options.regex || options.ignoreCase)
+        return false;
+    return canBatchLiterals(patterns);
+}
+/**
+ * Parses ripgrep's newline-delimited JSON into per-pattern tallies.
+ *
+ * This is deliberately pure and separate from the subprocess: every interesting
+ * case here - a base64 path, a match with no submatches, an excluded file, an
+ * unattributable match - is trivial to exercise as data and nearly impossible
+ * to provoke from a real ripgrep on demand.
+ */
+export function createRipgrepSink(request, patterns) {
+    const single = patterns.length === 1 ? patterns[0] : null;
+    const tallies = new Map(patterns.map((pattern) => [pattern, emptyTally()]));
+    const sink = {
+        tallies,
+        failure: null,
+        line(text) {
+            if (text.length === 0 || sink.failure)
+                return;
+            let event;
+            try {
+                event = JSON.parse(text);
+            }
+            catch {
+                return;
+            }
+            if (event.type !== 'match' || !event.data)
+                return;
+            const data = event.data;
+            const submatches = data.submatches ?? [];
+            if (submatches.length === 0)
+                return;
+            // ripgrep echoes the path as given ("./src/a.ts" when the target is
+            // "."); normalise so both engines report the same relative path.
+            const absolute = path.resolve(request.root, decodeText(data.path));
+            if (request.options.excludeFiles.has(absolute))
+                return;
+            const file = toPosix(path.relative(request.root, absolute));
+            const lineNumber = data.line_number ?? 0;
+            const lineText = decodeText(data.lines);
+            const text_ = truncate(lineText);
+            for (const submatch of submatches) {
+                // With --fixed-strings and no --ignore-case the matched text is the
+                // pattern verbatim, which is what makes attribution exact.
+                const pattern = single ?? decodeText(submatch.match);
+                const tally = tallies.get(pattern);
+                if (!tally) {
+                    sink.failure = new UnattributableBatch(`ripgrep reported an unexpected match: ${pattern}`);
+                    return;
+                }
+                tally.count += 1;
+                const last = tally.locations.at(-1);
+                if (last && last.file === file && last.line === lineNumber) {
+                    last.count += 1;
+                }
+                else if (tally.locations.length < MAX_COLLECTED_MATCHES) {
+                    tally.locations.push({
+                        file,
+                        line: lineNumber,
+                        column: byteColumnToCharacter(lineText, submatch.start ?? 0),
+                        text: text_,
+                        count: 1,
+                    });
+                }
+            }
+        },
+    };
+    return sink;
+}
 /* --------------------------------------------------------------- javascript */
 /** Builds the matching RegExp shared by the JS engine. */
 export function buildJsRegExp(symbol, options) {
@@ -299,12 +426,20 @@ class JavaScriptEngine {
         if (!first)
             return [];
         const files = await this.collectFiles(first);
+        return this.searchFiles(files, requests);
+    }
+    /** Scans an already-enumerated file list. */
+    async searchFiles(files, requests) {
+        const [first] = requests;
+        if (!first)
+            return [];
         const patterns = [...new Set(requests.map((request) => request.symbol))];
         const regexps = new Map(patterns.map((pattern) => [pattern, buildJsRegExp(pattern, first.options)]));
         const tallies = new Map(patterns.map((pattern) => [pattern, emptyTally()]));
         const concurrency = Math.min(16, Math.max(1, files.length));
         let cursor = 0;
         const perFile = new Map();
+        let unclassifiedFiles = 0;
         const worker = async () => {
             while (cursor < files.length) {
                 const file = files[cursor++];
@@ -315,10 +450,19 @@ class JavaScriptEngine {
                 if (!buffer || isProbablyBinary(buffer))
                     continue;
                 const content = buffer.toString('utf8');
+                let mask;
+                const getMask = first.options.ignoreComments
+                    ? () => (mask ??= createCommentMask(content, file.relativePath))
+                    : undefined;
                 const scanned = new Map();
                 for (const [pattern, regexp] of regexps) {
-                    scanned.set(pattern, scanContent(content, file.relativePath, regexp));
+                    scanned.set(pattern, scanContent(content, file.relativePath, regexp, getMask));
                 }
+                // A mask exists only if some pattern matched, since that is the only
+                // thing that calls getMask - so reaching here already means this file
+                // matched and its language was not understood.
+                if (mask && !mask.classified)
+                    unclassifiedFiles += 1;
                 perFile.set(file.relativePath, scanned);
             }
         };
@@ -331,6 +475,7 @@ class JavaScriptEngine {
             for (const [pattern, tally] of scanned) {
                 const total = tallies.get(pattern);
                 total.count += tally.count;
+                total.commentCount += tally.commentCount;
                 for (const location of tally.locations) {
                     if (total.locations.length < MAX_COLLECTED_MATCHES)
                         total.locations.push(location);
@@ -339,43 +484,84 @@ class JavaScriptEngine {
         }
         return requests.map((request) => {
             const tally = tallies.get(request.symbol) ?? emptyTally();
-            return { count: tally.count, matches: tally.locations, engine: this.name };
+            return {
+                count: tally.count,
+                commentMatches: tally.commentCount,
+                unclassifiedFiles,
+                matches: tally.locations,
+                engine: this.name,
+            };
         });
     }
     /** Every file a request should look at, sorted by relative path. */
     async collectFiles(request) {
-        const matcher = createGlobMatcher(request.options.globs);
-        const found = new Map();
-        for (const target of request.targets.length > 0 ? request.targets : ['.']) {
-            const absoluteTarget = path.resolve(request.root, target);
-            const stats = await fs.stat(absoluteTarget).catch(() => null);
-            if (!stats)
+        return (await enumerateCandidates(request)).files;
+    }
+}
+/**
+ * Lists the files a request would search, sorted by relative path.
+ *
+ * With a budget, the walk abandons as soon as the tree proves bigger than the
+ * budget allows. That makes it usable as a cheap probe: enumeration is stat-only
+ * work, so finding out a tree is "too big" costs a bounded number of stats
+ * rather than a full traversal.
+ */
+export async function enumerateCandidates(request, budget) {
+    const matcher = createGlobMatcher(request.options.globs);
+    const excluded = createExcludeMatcher(request.options.excludeGlobs);
+    const admits = (relativePath) => matcher(relativePath) && !excluded(relativePath);
+    const found = new Map();
+    let bytes = 0;
+    let exceeded = false;
+    const admit = (absolutePath, relativePath, size) => {
+        found.set(absolutePath, { absolutePath, relativePath });
+        bytes += size;
+        if (budget && (found.size > budget.maxFiles || bytes > budget.maxBytes)) {
+            exceeded = true;
+            return false;
+        }
+        return true;
+    };
+    outer: for (const target of request.targets.length > 0 ? request.targets : ['.']) {
+        const absoluteTarget = path.resolve(request.root, target);
+        const stats = await fs.stat(absoluteTarget).catch(() => null);
+        if (!stats)
+            continue;
+        if (stats.isFile()) {
+            const relativePath = toPosix(path.relative(request.root, absoluteTarget));
+            if (stats.size <= MAX_FILE_SIZE && admits(relativePath)) {
+                if (!admit(absoluteTarget, relativePath, stats.size))
+                    break outer;
+            }
+            continue;
+        }
+        for await (const file of walkFiles(absoluteTarget)) {
+            if (file.size > MAX_FILE_SIZE)
                 continue;
-            if (stats.isFile()) {
-                const relativePath = toPosix(path.relative(request.root, absoluteTarget));
-                if (stats.size <= MAX_FILE_SIZE && matcher(relativePath)) {
-                    found.set(absoluteTarget, { absolutePath: absoluteTarget, relativePath });
-                }
+            const relativePath = toPosix(path.relative(request.root, file.absolutePath));
+            if (!admits(relativePath))
                 continue;
-            }
-            for await (const file of walkFiles(absoluteTarget)) {
-                if (file.size > MAX_FILE_SIZE)
-                    continue;
-                const relativePath = toPosix(path.relative(request.root, file.absolutePath));
-                if (!matcher(relativePath))
-                    continue;
-                found.set(file.absolutePath, { absolutePath: file.absolutePath, relativePath });
-            }
+            if (!admit(file.absolutePath, relativePath, file.size))
+                break outer;
         }
-        for (const excluded of request.options.excludeFiles)
-            found.delete(excluded);
-        return [...found.values()].sort((a, b) => (a.relativePath < b.relativePath ? -1 : 1));
     }
+    for (const excluded of request.options.excludeFiles)
+        found.delete(excluded);
+    const files = [...found.values()].sort((a, b) => (a.relativePath < b.relativePath ? -1 : 1));
+    return { files, exceeded, bytes };
 }
 /** Counts matches in one file and records per-line snippets. */
-export function scanContent(content, relativePath, regexp) {
+export function scanContent(content, relativePath, regexp, 
+/**
+ * Resolved lazily, and only once the file has produced a match. Classifying
+ * every file in scope would mean a comment scan of the whole tree; this way
+ * the cost is proportional to matches, which for an architecture assertion is
+ * usually zero.
+ */
+getMask) {
     regexp.lastIndex = 0;
     let count = 0;
+    let commentCount = 0;
     const byLine = new Map();
     // Lazily built line index: only paid for when the file actually matches.
     let lineStarts = null;
@@ -400,6 +586,12 @@ export function scanContent(content, relativePath, regexp) {
     };
     let match;
     while ((match = regexp.exec(content)) !== null) {
+        if (getMask?.().isComment(match.index)) {
+            commentCount += 1;
+            if (match[0].length === 0)
+                regexp.lastIndex += 1;
+            continue;
+        }
         count += 1;
         const { line, column } = lineOf(match.index);
         const existing = byLine.get(line);
@@ -420,44 +612,116 @@ export function scanContent(content, relativePath, regexp) {
         if (match[0].length === 0)
             regexp.lastIndex += 1;
     }
-    return { count, locations: [...byLine.values()].sort((a, b) => a.line - b.line) };
+    // No sort: exec scans forward, so lines are discovered in increasing order and
+    // a Map preserves insertion order. Sorting here was dead code - mutation
+    // testing found it by reporting that neither reversing nor removing the
+    // comparator changed any result.
+    return { count, locations: [...byLine.values()], commentCount };
 }
 export const javascriptEngine = new JavaScriptEngine();
+/**
+ * How much scanning the JavaScript engine may do before ripgrep is worth a
+ * process spawn.
+ *
+ * Measured with scripts/bench-engines.mjs. ripgrep's cost is dominated by
+ * process startup and is nearly flat in tree size; the JavaScript scanner grows
+ * linearly. The crossover is therefore wherever a spawn costs, and that differs
+ * by an order of magnitude between platforms:
+ *
+ *   Windows 11, Node 24, rg 15   spawn floor ~130ms   crossover ~575 files
+ *   Linux (container), Node 22, rg 13   spawn floor ~15ms   crossover ~25 files
+ *
+ * The budget is set just below each crossover, so choosing JavaScript is never
+ * the slower option by more than a few milliseconds, while a small tree on
+ * Windows avoids a spawn that would cost ten times the whole search.
+ */
+export const SMALL_TREE_BUDGET = process.platform === 'win32' ? { maxFiles: 512, maxBytes: 1024 * 1024 } : { maxFiles: 32, maxBytes: 64 * 1024 };
 /** Spawn failures that mean "this binary is not installed", not "search failed". */
 const MISSING_BINARY_CODES = new Set(['ENOENT', 'EACCES', 'EPERM', 'EINVAL', 'UNKNOWN']);
-function isMissingBinary(error) {
+/** Exported so the code list can be asserted; EACCES and friends are not
+ * reproducible on demand from a real spawn. */
+export function isMissingBinary(error) {
     const code = error?.code;
     return typeof code === 'string' && MISSING_BINARY_CODES.has(code);
 }
 /**
- * Tries ripgrep on the first search and remembers the answer.
+ * Identity tokens for exclude sets.
  *
- * Probing with `rg --version` up front would be simpler, but a process spawn
- * costs ~27ms on Windows - as much as a whole search - and that probe sits on
- * the critical path of every run. Discovering ripgrep's absence from the first
- * real search is free.
+ * The enumeration cache key has to account for `excludeFiles`, because
+ * enumeration applies it - two groups over the same targets but with different
+ * exclusions are different questions. Hashing the paths would be wasteful (a
+ * run excludes every spec file), and the runner passes one set for the whole
+ * run, so identity is both cheap and sufficient.
  */
-class AutoEngine {
-    mode = 'unknown';
+const excludeSetIds = new WeakMap();
+let nextExcludeSetId = 0;
+function excludeSetId(excludeFiles) {
+    let id = excludeSetIds.get(excludeFiles);
+    if (id === undefined) {
+        id = nextExcludeSetId++;
+        excludeSetIds.set(excludeFiles, id);
+    }
+    return id;
+}
+function enumerationKey(request) {
+    return JSON.stringify([
+        request.root,
+        request.targets,
+        request.options.globs,
+        request.options.excludeGlobs,
+        excludeSetId(request.options.excludeFiles),
+    ]);
+}
+/**
+ * Picks an engine per search group instead of once per run.
+ *
+ * The probe is the work: it enumerates the target set under a budget, which is
+ * stat-only. If the tree fits, the file list is already in hand and the
+ * JavaScript scan runs against it with no spawn and no second walk. If the walk
+ * abandons, the tree is big enough that ripgrep will win comfortably, and the
+ * abandoned enumeration cost a bounded number of stats.
+ *
+ * Deciding per group rather than per run matters because one spec can assert
+ * against `src/` and a single file in the same run.
+ */
+class AdaptiveEngine {
+    usedRipgrep = false;
+    ripgrepMissing = false;
     ripgrep = new RipgrepEngine(process.env.SPEC_GUARD_RG || 'rg');
+    enumerations = new Map();
     get name() {
-        return this.mode === 'javascript' ? 'javascript' : 'ripgrep';
+        return this.usedRipgrep ? 'ripgrep' : 'javascript';
     }
     async search(request) {
         const [result] = await this.searchBatch([request]);
         return result;
     }
     async searchBatch(requests) {
-        if (this.mode !== 'javascript') {
+        const [first] = requests;
+        if (!first)
+            return [];
+        if (!this.ripgrepMissing) {
+            const key = enumerationKey(first);
+            let probe = this.enumerations.get(key);
+            if (!probe) {
+                probe = enumerateCandidates(first, SMALL_TREE_BUDGET);
+                this.enumerations.set(key, probe);
+            }
+            const enumeration = await probe;
+            if (!enumeration.exceeded) {
+                // Small tree: the walk already produced the file list, so scanning it
+                // here costs less than starting a process.
+                return javascriptEngine.searchFiles(enumeration.files, requests);
+            }
             try {
                 const results = await this.ripgrep.searchBatch(requests);
-                this.mode = 'ripgrep';
+                this.usedRipgrep = true;
                 return results;
             }
             catch (error) {
                 if (!isMissingBinary(error))
                     throw error;
-                this.mode = 'javascript';
+                this.ripgrepMissing = true;
             }
         }
         return javascriptEngine.searchBatch(requests);
@@ -474,7 +738,7 @@ export async function resolveEngine(preference = 'auto') {
         }
         return new RipgrepEngine(binary);
     }
-    return new AutoEngine();
+    return new AdaptiveEngine();
 }
 /**
  * Wraps an engine with a de-duplicating cache plus an automatic fallback to the
@@ -491,6 +755,7 @@ export function createCachedEngine(engine) {
         request.options.word,
         request.options.ignoreCase,
         request.options.globs,
+        request.options.excludeGlobs,
         [...request.options.excludeFiles].sort(),
     ]);
     const recordFallback = (error) => {