@descent-vtt/spec-guard 0.4.0 → 0.5.1

package/dist/runner.js

@@ -7,13 +7,24 @@
  */
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { createCachedEngine, enumerateCandidates, resolveEngine, runSearches, } from "./engine.js";
+import { comparePaths, createCachedEngine, enumerateCandidates, passKey, resolveEngine, runSearches, ANY_FILE_PROBE, ROOT_TARGETS, } from "./engine.js";
 import { createExcludeMatcher, expandSpecPatterns, toPosix } from "./glob.js";
-import { ANALYSABLE_EXTENSIONS, createImportIndex, resolveSpecifier, } from "./imports.js";
+import { ANALYSABLE_EXTENSIONS, createImportIndex, resolveModule, } from "./imports.js";
 import { parseDirectives } from "./parser.js";
-import { createScope, DEFAULT_SCOPE, EMPTY_LEDGER, UNCERTAIN_REASONS, } from "./scope.js";
+import { createScope, DEFAULT_SCOPE, EMPTY_LEDGER, } from "./scope.js";
 export const DEFAULT_MAX_SNIPPETS = 5;
 export const DEFAULT_CONCURRENCY = 8;
+/**
+ * Milliseconds between two `performance.now()` marks.
+ *
+ * Seven results carry a duration and each used to subtract inline, which is
+ * seven chances to write the operands the wrong way round and report a negative
+ * time - and seven copies of one subtraction that nothing could pin down,
+ * because "a plausible number of milliseconds" is not an assertion.
+ */
+export function elapsed(from, to = performance.now()) {
+    return to - from;
+}
 const TRUE_VALUES = new Set(["true", "1", "yes", "on"]);
 const FALSE_VALUES = new Set(["false", "0", "no", "off"]);
 function parseBoolean(value, attribute) {
@@ -44,13 +55,19 @@ function parseCount(value, attribute) {
 function splitList(value) {
     if (value === undefined)
         return [];
-    return value
-        .split(/[,\s]+/)
-        .map((item) => item.trim())
-        .filter((item) => item.length > 0);
+    // Taking the items rather than splitting on the separators. Split needed a
+    // `+` on the separator class, a trim and a length filter, and any two of the
+    // three made the third unnecessary - so none of them could be tested. What is
+    // wanted is "the runs of non-separator characters", and that is one pattern.
+    return value.match(/[^,\s]+/g) ?? [];
 }
 /** Rejects absolute paths and any `..` escape out of the root. */
 function normalizeTarget(target, root, attribute) {
+    // The second test is not redundant with the first: `path.isAbsolute` follows
+    // the host platform, so a Windows drive path is absolute on Windows and an
+    // ordinary relative name on Linux. A spec naming `C:/repo/src` has to be
+    // refused on both, or the same document means two different things. It is
+    // anchored, because a colon partway along a path is just a character.
     if (path.isAbsolute(target) || /^[a-zA-Z]:[\\/]/.test(target)) {
         throw new Error(`Attribute "${attribute}" must be relative to --root, got "${target}".`);
     }
@@ -75,7 +92,6 @@ function describeBounds(bounds) {
         return `at least ${min} match${plural(min)}`;
     if (max !== undefined)
         return max === 0 ? "no matches" : `at most ${max} match${plural(max)}`;
-    /* c8 ignore next */
     return "any number of matches";
 }
 /** Prose form used in the assertion description ("must appear at most 3 times"). */
@@ -91,10 +107,10 @@ function describeExpectation(bounds) {
         return `must appear at least ${times(min)}`;
     if (max === 0)
         return "must not appear";
-    /* c8 ignore next */
-    return max === undefined
-        ? "may appear any number of times"
-        : `must appear at most ${times(max)}`;
+    // No branch for "neither bound": this is only ever called from
+    // `resolveDirective`, which refuses a directive that names none. Carrying a
+    // fourth case here meant carrying a string no run could print.
+    return `must appear at most ${times(max ?? 0)}`;
 }
 /** Prose for an import claim: "must not import", "must import at least 2 files". */
 function describeImportExpectation(bounds) {
@@ -109,17 +125,149 @@ function describeImportExpectation(bounds) {
     }
     if (min !== undefined)
         return `must import from at least ${files(min)}`;
-    /* c8 ignore next */
-    return max === undefined
-        ? "may import"
-        : `must import from at most ${files(max)}`;
+    // As above: `resolveDirective` never produces an unbounded import claim.
+    return `must import from at most ${files(max ?? 0)}`;
 }
-function satisfies(count, bounds) {
-    if (bounds.min !== undefined && count < bounds.min)
-        return false;
-    if (bounds.max !== undefined && count > bounds.max)
-        return false;
-    return true;
+/**
+ * What a report says when an assertion covered nothing.
+ *
+ * The fourth silent false green, after the three ADR-0007 closed. A rule whose
+ * scope holds no files passes every time, forever, and reads in the report
+ * exactly like a rule that inspected a thousand files and found nothing. The
+ * usual causes are a `glob` that matches no extension in the tree, an `exclude`
+ * that swallowed the target, or a directory that has since been emptied.
+ *
+ * Deliberately no file count alongside it: under ripgrep spec-guard never
+ * enumerates the tree, so "inspected 412 files" would be a number only one of
+ * the two engines could produce. "Nothing at all" is the same answer in both,
+ * and it is the only part that changes an outcome.
+ */
+const EMPTY_SCOPE_HINT = 'add allow-empty="true" if that is expected';
+/**
+ * The one-line explanation under a result.
+ *
+ * Built from parts rather than written per branch so that a run with a
+ * baseline, an unreadable file and a stale entry says all three things instead
+ * of whichever one the branch order happened to reach first.
+ */
+function describeOutcome(bounds, actual, extras) {
+    const parts = [`expected ${describeBounds(bounds)}, found ${actual}`];
+    if (extras.excluded > 0) {
+        parts.push(`${extras.excluded} more ${extras.excluded === 1 ? "is" : "are"} on the baseline`);
+    }
+    if (extras.gaps > 0) {
+        parts.push(`${extras.gaps} file${extras.gaps === 1 ? "" : "s"} could not be inspected`);
+    }
+    if (extras.stale.length > 0) {
+        // Naming the entries matters more than counting them: the fix is to delete
+        // exactly these lines from the spec, and a reader should not have to work
+        // out which.
+        const listed = extras.stale
+            .map((entry) => entry.found === 0
+            ? `${entry.path} (no longer matches)`
+            : `${entry.path} (declares ${entry.declared}, found ${entry.found})`)
+            .join(", ");
+        parts.push(`the baseline is out of date and must be pruned: ${listed}`);
+    }
+    return parts.join("; ");
+}
+/**
+ * Reads a `baseline="..."` attribute into entries.
+ *
+ * Each item is a path, optionally `path:count`; a bare path means one match.
+ * The separator is a colon because a path here is always relative and
+ * POSIX-shaped, so it cannot contain one - the same reasoning that lets
+ * `target` split on whitespace.
+ */
+function parseBaseline(value, root) {
+    const entries = [];
+    const seen = new Set();
+    for (const item of splitList(value)) {
+        const separator = item.lastIndexOf(":");
+        const rawPath = separator === -1 ? item : item.slice(0, separator);
+        const rawCount = separator === -1 ? "1" : item.slice(separator + 1);
+        const declared = parseCount(rawCount, "baseline");
+        if (declared === 0) {
+            throw new Error(`Baseline entry "${item}" declares 0 matches. Remove the entry instead; a baseline lists violations that exist.`);
+        }
+        const normalized = normalizeTarget(rawPath, root, "baseline");
+        if (seen.has(normalized)) {
+            throw new Error(`Baseline lists "${normalized}" twice.`);
+        }
+        seen.add(normalized);
+        entries.push({ path: normalized, declared });
+    }
+    return entries;
+}
+/**
+ * Subtracts the declared debt from what was found.
+ *
+ * Two questions, and the ratchet needs both. Matches inside a baselined file
+ * stop counting *up to the declared number* - so a file allowed two violations
+ * that grows a third reports one, not three, and the failure points at the
+ * change rather than at the history. And a file that no longer has as many as
+ * it declares is a stale entry: the debt was paid and the ledger still claims
+ * it, which is a spec asserting something untrue about the code.
+ */
+export function applyBaseline(entries, fileCounts) {
+    let excluded = 0;
+    const stale = [];
+    const declaredBy = new Map(entries.map((entry) => [entry.path, entry.declared]));
+    for (const entry of entries) {
+        const found = fileCounts.get(entry.path) ?? 0;
+        excluded += Math.min(found, entry.declared);
+        if (found < entry.declared)
+            stale.push({ path: entry.path, declared: entry.declared, found });
+    }
+    return {
+        excluded,
+        stale,
+        // Which files a failure should show. A file inside its allowance is not
+        // what went wrong, and printing it points the reader at the history
+        // instead of at the change - the first version of this did exactly that,
+        // and reported a new violation by quoting a twelve-year-old one. A file
+        // *over* its allowance still shows, because the excess is a real
+        // violation living in it.
+        shows: (file) => (fileCounts.get(file) ?? 0) > (declaredBy.get(file) ?? 0),
+    };
+}
+/**
+ * Per-run cache for "does this scope contain anything at all".
+ *
+ * The same shape as the import index, and for the same reason: a document with
+ * twenty assertions over `src/` asks this question twenty times and it has one
+ * answer. Without the cache the probe measured about 0.9 ms per assertion,
+ * which is small until a spec has two hundred of them.
+ */
+export function createScopeProbe() {
+    const cache = new Map();
+    return (request) => {
+        const key = JSON.stringify([
+            request.root,
+            request.targets,
+            request.options.globs,
+            request.options.excludeGlobs,
+        ]);
+        let pending = cache.get(key);
+        if (!pending) {
+            // The walk abandons at the first file it finds, so proving a scope is
+            // populated costs a couple of directory reads rather than a traversal.
+            pending = enumerateCandidates(request, ANY_FILE_PROBE).then((enumeration) => enumeration.files.length > 0);
+            cache.set(key, pending);
+        }
+        return pending;
+    };
+}
+/**
+ * Whether a count is inside the bounds. An absent bound is no bound.
+ *
+ * Written as defaults rather than as two `!== undefined` guards. Those guards
+ * could not change an answer - `count < undefined` is false for every count, so
+ * the comparison already admitted everything - which meant two conditions in
+ * the middle of the pass/fail decision that no test could hold in place.
+ */
+function satisfies(count, { min = 0, max = Number.POSITIVE_INFINITY }) {
+    return count >= min && count <= max;
 }
 /** Turns one directive into an executable assertion, or an error. */
 export function resolveDirective(directive, context) {
@@ -144,6 +292,10 @@ export function resolveDirective(directive, context) {
                     files,
                     bounds: { min: files.length, max: files.length },
                     missingTargets: [],
+                    // A file list is never empty here: resolution rejects that above.
+                    allowEmpty: true,
+                    baseline: [],
+                    ratchet: "two-sided",
                 },
             };
         }
@@ -153,12 +305,25 @@ export function resolveDirective(directive, context) {
         if (symbol === undefined || symbol.length === 0) {
             return fail(`@${kind} requires a non-empty ${subject}="..." attribute.`);
         }
+        const allowEmpty = parseBoolean(attributes["allow-empty"], "allow-empty");
+        // `baseline` and `ratchet` reach here only on the absence kinds: the parser
+        // rejects them elsewhere, because "these known files may violate" means
+        // nothing for an assertion that is not forbidding anything.
+        const baseline = parseBaseline(attributes["baseline"], context.root);
+        const rawRatchet = (attributes["ratchet"] ?? "two-sided").trim().toLowerCase();
+        if (rawRatchet !== "two-sided" && rawRatchet !== "one-way") {
+            return fail(`Attribute "ratchet" must be two-sided or one-way, got "${attributes["ratchet"]}".`);
+        }
+        if (baseline.length === 0 && attributes["ratchet"] !== undefined) {
+            return fail(`Attribute "ratchet" needs a baseline="..." to ratchet.`);
+        }
+        const ratchet = rawRatchet;
         const comments = (attributes["comments"] ?? "ignore").trim().toLowerCase();
         if (comments !== "ignore" && comments !== "include") {
             return fail(`Attribute "comments" must be ignore or include, got "${attributes["comments"]}".`);
         }
         const rawTargets = splitList(attributes["target"]);
-        const targets = (rawTargets.length > 0 ? rawTargets : ["."]).map((target) => normalizeTarget(target, context.root, "target"));
+        const targets = (rawTargets.length > 0 ? rawTargets : ROOT_TARGETS).map((target) => normalizeTarget(target, context.root, "target"));
         const bounds = {};
         if (kind === "assert-absence" || kind === "assert-import-absence") {
             if (attributes["expected"] !== undefined &&
@@ -191,9 +356,10 @@ export function resolveDirective(directive, context) {
                     bounds.min = parseCount(attributes["min"], "min");
                 if (attributes["max"] !== undefined)
                     bounds.max = parseCount(attributes["max"], "max");
-                if (bounds.min !== undefined &&
-                    bounds.max !== undefined &&
-                    bounds.min > bounds.max) {
+                // Defaults rather than presence checks, for the same reason as
+                // `satisfies`: `min > undefined` is false whatever min is, so the two
+                // `!== undefined` guards this used to carry could not decide anything.
+                if ((bounds.min ?? 0) > (bounds.max ?? Number.POSITIVE_INFINITY)) {
                     return fail(`min="${bounds.min}" is greater than max="${bounds.max}".`);
                 }
             }
@@ -233,6 +399,9 @@ export function resolveDirective(directive, context) {
                     },
                     imports: { modules: splitList(symbol), includeTypes },
                     missingTargets: [],
+                    allowEmpty,
+                    baseline,
+                    ratchet,
                 },
             };
         }
@@ -251,7 +420,10 @@ export function resolveDirective(directive, context) {
                 new RegExp(symbol);
             }
             catch (error) {
-                return fail(`Invalid regular expression: ${error instanceof Error ? error.message : String(error)}`);
+                // No prefix of our own. V8's message already begins "Invalid regular
+                // expression: /(/: ...", so adding one produced the phrase twice in a
+                // row and pushed the pattern itself off the useful part of the line.
+                return fail(error instanceof Error ? error.message : String(error));
             }
         }
         const scope = targets.join(", ");
@@ -270,6 +442,9 @@ export function resolveDirective(directive, context) {
                 bounds,
                 search,
                 missingTargets: [],
+                allowEmpty,
+                baseline,
+                ratchet,
             },
         };
     }
@@ -300,6 +475,9 @@ async function prepareAssertion(assertion, options) {
         commentMatches: 0,
         unclassifiedFiles: 0,
         scope: EMPTY_LEDGER,
+        baselinedMatches: 0,
+        staleBaseline: [],
+        fileMatches: [],
     };
     if (assertion.kind === "assert-present") {
         const missing = [];
@@ -316,7 +494,7 @@ async function prepareAssertion(assertion, options) {
                 ? `all ${assertion.files.length} referenced ${assertion.files.length === 1 ? "path exists" : "paths exist"}`
                 : `missing: ${missing.join(", ")}`,
             matches: [],
-            durationMs: performance.now() - startedAt,
+            durationMs: elapsed(startedAt),
         };
     }
     if (assertion.imports) {
@@ -339,43 +517,79 @@ async function prepareAssertion(assertion, options) {
             actual: 0,
             message: `target path${assertion.missingTargets.length === 1 ? " does" : "s do"} not exist: ${assertion.missingTargets.join(", ")}`,
             matches: [],
-            durationMs: performance.now() - startedAt,
+            durationMs: elapsed(startedAt),
         };
     }
+    const request = {
+        root: options.root,
+        symbol: assertion.symbol,
+        targets: existingTargets,
+        options: assertion.search,
+    };
+    if (!options.allowEmptyScope && !assertion.allowEmpty && !(await options.hasFiles(request))) {
+        {
+            return {
+                ...base,
+                ok: false,
+                actual: 0,
+                message: `no files were inspected, so this assertion verified nothing (${EMPTY_SCOPE_HINT})`,
+                matches: [],
+                durationMs: elapsed(startedAt),
+            };
+        }
+    }
     return {
-        request: {
-            root: options.root,
-            symbol: assertion.symbol,
-            targets: existingTargets,
-            options: assertion.search,
-        },
+        request,
         finish: (search) => {
             // A file that could not be read, or whose bytes are not text but did
             // contain the symbol, is a hole in the answer rather than a detail of it.
             // The count is still reported, because it is still true of everything
             // that was read; --strict is for runs where "true of what we read" is not
             // good enough.
-            const gaps = search.scope.skipped.filter((entry) => UNCERTAIN_REASONS.has(entry.reason));
+            //
+            // No filter for uncertainty here any more. The ledger only ever holds
+            // gaps: the walk drops a policy skip before recording it, and the only
+            // other reasons the scanner adds are "unreadable" and "binary". Filtering
+            // again was a second statement of an invariant that is enforced where it
+            // is created, and being a no-op, nothing could tell it from its absence.
+            const gaps = search.scope.skipped;
             const strictFailure = options.strictTargets && gaps.length > 0;
+            const { excluded, stale, shows } = applyBaseline(assertion.baseline, search.fileCounts);
+            const staleFailure = assertion.ratchet === "two-sided" && stale.length > 0;
+            const actual = search.count - excluded;
             return {
                 ...base,
-                ok: satisfies(search.count, assertion.bounds) && !strictFailure,
-                actual: search.count,
-                message: strictFailure
-                    ? `expected ${describeBounds(assertion.bounds)}, found ${search.count}, and ${gaps.length} file${gaps.length === 1 ? "" : "s"} could not be inspected`
-                    : `expected ${describeBounds(assertion.bounds)}, found ${search.count}`,
-                matches: search.matches.slice(0, options.maxSnippets),
+                ok: satisfies(actual, assertion.bounds) && !strictFailure && !staleFailure,
+                actual,
+                message: describeOutcome(assertion.bounds, actual, {
+                    excluded,
+                    stale: staleFailure ? stale : [],
+                    gaps: strictFailure ? gaps.length : 0,
+                }),
+                baselinedMatches: excluded,
+                staleBaseline: stale,
+                fileMatches: [...search.fileCounts].map(([file, count]) => ({ file, count })),
+                matches: search.matches.filter((match) => shows(match.file)).slice(0, options.maxSnippets),
                 // Carried as numbers, not prose, so the reporter can total them across a
                 // run and JSON consumers can act on them.
                 commentMatches: search.commentMatches,
                 unclassifiedFiles: search.unclassifiedFiles,
                 scope: search.scope,
                 engine: search.engine,
-                durationMs: performance.now() - startedAt,
+                durationMs: elapsed(startedAt),
             };
         },
     };
 }
+/** How each kind of reference is spelled in a report snippet. */
+const IMPORT_VERBS = {
+    import: "import",
+    export: "export",
+    require: "require",
+    "dynamic-import": "import",
+    use: "use",
+    using: "using",
+};
 /**
  * Counts the files in scope that depend on the requested module.
  *
@@ -395,16 +609,33 @@ async function executeImportAssertion(assertion, options, base, warnings, starte
     if (assertion.missingTargets.length > 0) {
         warnings.push(`target path${assertion.missingTargets.length === 1 ? "" : "s"} not found: ${assertion.missingTargets.join(", ")}`);
     }
+    // No symbol: an import assertion never runs a text search, and the walk does
+    // not depend on one. This used to pass `symbol: ""`, an invented value that
+    // reached nothing and that no test could therefore be wrong about.
     const enumeration = await enumerateCandidates({
         root: options.root,
-        symbol: "",
         targets: existingTargets,
         options: assertion.search,
     });
     const analysable = enumeration.files.filter((file) => ANALYSABLE_EXTENSIONS.has(path.posix.extname(file.relativePath)));
+    if (analysable.length === 0 && !options.allowEmptyScope && !assertion.allowEmpty) {
+        // For an import rule the bar is higher than "some file exists": a directory
+        // of YAML has nothing this can read, so a dependency claim about it is a
+        // claim about nothing.
+        return {
+            ...base,
+            ok: false,
+            actual: 0,
+            message: enumeration.files.length === 0
+                ? `no files were inspected, so this assertion verified nothing (${EMPTY_SCOPE_HINT})`
+                : `none of the ${enumeration.files.length} files here are in a language whose imports spec-guard can read, so this assertion verified nothing (${EMPTY_SCOPE_HINT})`,
+            matches: [],
+            durationMs: elapsed(startedAt),
+        };
+    }
     const skipped = enumeration.files.length - analysable.length;
     if (skipped > 0) {
-        warnings.push(`analysed ${analysable.length} of ${enumeration.files.length} files; ${skipped} are not JavaScript or TypeScript`);
+        warnings.push(`analysed ${analysable.length} of ${enumeration.files.length} files; ${skipped} ${skipped === 1 ? "is" : "are"} in a language whose imports spec-guard cannot read`);
     }
     const matchesModule = createExcludeMatcher(query.modules);
     const matches = [];
@@ -417,14 +648,18 @@ async function executeImportAssertion(assertion, options, base, warnings, starte
         const hit = analysis.references.find((reference) => {
             if (reference.typeOnly && !query.includeTypes)
                 return false;
-            return matchesModule(resolveSpecifier(reference.specifier, file.relativePath));
+            // Both forms are tried: the resolved one so `module="app/db/**"` works
+            // everywhere, and the raw one so a Python or C# author can write the
+            // dotted path they see in their own source and still be understood.
+            return (matchesModule(resolveModule(reference.specifier, file.relativePath)) ||
+                matchesModule(reference.specifier));
         });
         if (hit) {
             matches.push({
                 file: file.relativePath,
                 line: hit.line,
                 column: hit.column,
-                text: `${hit.kind === "export" ? "export" : "import"} ${hit.specifier}`,
+                text: `${IMPORT_VERBS[hit.kind]} ${hit.specifier}`,
                 count: 1,
             });
         }
@@ -433,19 +668,32 @@ async function executeImportAssertion(assertion, options, base, warnings, starte
         warnings.push(`${unresolved.length} module reference${unresolved.length === 1 ? "" : "s"} could not be resolved statically`, ...unresolved.slice(0, options.maxSnippets).map((entry) => `  ${entry}`));
     }
     const missingFailure = !options.allowMissingTargets && assertion.missingTargets.length > 0;
+    // One reference per file, so the file counts are the matches themselves.
+    const fileCounts = new Map(matches.map((match) => [match.file, 1]));
+    const { excluded, stale, shows } = applyBaseline(assertion.baseline, fileCounts);
+    const staleFailure = assertion.ratchet === "two-sided" && stale.length > 0;
+    const actual = matches.length - excluded;
     const strictFailure = missingFailure || (options.strictTargets && unresolved.length > 0);
-    const ok = satisfies(matches.length, assertion.bounds) && !strictFailure;
+    const ok = satisfies(actual, assertion.bounds) && !strictFailure && !staleFailure;
     return {
         ...base,
         ok,
-        actual: matches.length,
+        actual,
         message: missingFailure
             ? `target path${assertion.missingTargets.length === 1 ? " does" : "s do"} not exist: ${assertion.missingTargets.join(", ")}`
-            : strictFailure
-                ? `expected ${describeBounds(assertion.bounds)}, found ${matches.length}, and ${unresolved.length} reference(s) could not be resolved`
-                : `expected ${describeBounds(assertion.bounds)}, found ${matches.length}`,
-        matches: matches.slice(0, options.maxSnippets),
-        durationMs: performance.now() - startedAt,
+            : describeOutcome(assertion.bounds, actual, {
+                excluded,
+                stale: staleFailure ? stale : [],
+                gaps: 0,
+            }) +
+                (options.strictTargets && unresolved.length > 0
+                    ? `; ${unresolved.length} reference${unresolved.length === 1 ? "" : "s"} could not be resolved`
+                    : ""),
+        baselinedMatches: excluded,
+        staleBaseline: stale,
+        fileMatches: [...fileCounts].map(([file, count]) => ({ file, count })),
+        matches: matches.filter((match) => shows(match.file)).slice(0, options.maxSnippets),
+        durationMs: elapsed(startedAt),
     };
 }
 /** Executes a single resolved assertion. */
@@ -456,19 +704,14 @@ export async function executeAssertion(assertion, options) {
     return prepared.finish(await options.engine.search(prepared.request));
 }
 /**
- * Groups searches that can share a single pass over the tree: same targets,
- * same flags. This is where most of spec-guard's speed comes from - a spec with
- * twenty assertions over `src/` costs one ripgrep pass, not twenty.
+ * How many workers to run over the batches.
+ *
+ * At least one, so an empty run still terminates; never more than there are
+ * batches, so a spec with three groups does not start eight workers to find
+ * five of them nothing to do.
  */
-function groupKey(request) {
-    const { options } = request;
-    return JSON.stringify([
-        request.targets,
-        options.regex,
-        options.word,
-        options.ignoreCase,
-        options.globs,
-    ]);
+export function batchConcurrency(requested, batches) {
+    return Math.max(1, Math.min(requested, batches));
 }
 /** Reads, parses and executes every directive found in the given spec files. */
 export async function runSpecGuard(options) {
@@ -477,6 +720,7 @@ export async function runSpecGuard(options) {
     const maxSnippets = options.maxSnippets ?? DEFAULT_MAX_SNIPPETS;
     const strictTargets = options.strictTargets ?? false;
     const allowMissingTargets = options.allowMissingTargets ?? false;
+    const allowEmptyScope = options.allowEmptyScope ?? false;
     const scope = createScope(options.defaultSkips ?? true);
     const specFiles = await expandSpecPatterns(options.patterns, root);
     const excludeFiles = new Set(options.includeSpecs ? [] : specFiles.map((file) => path.resolve(file)));
@@ -512,10 +756,12 @@ export async function runSpecGuard(options) {
         engine,
         allowMissingTargets,
         strictTargets,
+        allowEmptyScope,
         maxSnippets,
         imports: createImportIndex(),
+        hasFiles: createScopeProbe(),
     };
-    const results = new Array(assertions.length);
+    const results = [];
     if (options.failFast) {
         // Fail-fast trades throughput for an early exit, so it runs unbatched.
         for (let index = 0; index < assertions.length; index++) {
@@ -535,7 +781,11 @@ export async function runSpecGuard(options) {
                 results[index] = entry;
                 return;
             }
-            const key = groupKey(entry.request);
+            // The engine's own definition of "these can share one pass", rather than
+            // a second list here that had drifted four fields behind it. This is
+            // where most of spec-guard's speed comes from: a spec with twenty
+            // assertions over `src/` costs one ripgrep pass, not twenty.
+            const key = passKey(entry.request);
             const group = groups.get(key);
             if (group)
                 group.push({ index, pending: entry });
@@ -543,7 +793,7 @@ export async function runSpecGuard(options) {
                 groups.set(key, [{ index, pending: entry }]);
         });
         const batches = [...groups.values()];
-        const concurrency = Math.max(1, Math.min(options.concurrency ?? DEFAULT_CONCURRENCY, batches.length || 1));
+        const concurrency = batchConcurrency(options.concurrency ?? DEFAULT_CONCURRENCY, batches.length);
         let cursor = 0;
         const worker = async () => {
             while (cursor < batches.length) {
@@ -563,15 +813,13 @@ export async function runSpecGuard(options) {
     // Errors arrive in two waves (parse, then resolve); readers expect file order.
     errors.sort((a, b) => a.location.relativeFile === b.location.relativeFile
         ? a.location.line - b.location.line
-        : a.location.relativeFile < b.location.relativeFile
-            ? -1
-            : 1);
+        : comparePaths(a.location.relativeFile, b.location.relativeFile));
     const failed = results.filter((result) => !result.ok).length;
     return {
         ok: failed === 0 && errors.length === 0,
         root,
         engine: warnings.length > 0 ? "javascript" : engine.name,
-        durationMs: performance.now() - startedAt,
+        durationMs: elapsed(startedAt),
         summary: {
             specs: specFiles.length,
             total: results.length,