@descent-vtt/spec-guard 0.3.0 → 0.5.0

package/dist/runner.js

@@ -5,16 +5,17 @@
  * number, an unknown boolean or a path escaping the root is an error, never a
  * silently-passing assertion. A spec that lies is worse than no spec at all.
  */
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
-import { createCachedEngine, enumerateCandidates, resolveEngine, runSearches, } from './engine.js';
-import { createExcludeMatcher, expandSpecPatterns, toPosix } from './glob.js';
-import { ANALYSABLE_EXTENSIONS, createImportIndex, resolveSpecifier, } from './imports.js';
-import { parseDirectives } from './parser.js';
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { createCachedEngine, enumerateCandidates, resolveEngine, runSearches, ANY_FILE_PROBE, } from "./engine.js";
+import { createExcludeMatcher, expandSpecPatterns, toPosix } from "./glob.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";
 export const DEFAULT_MAX_SNIPPETS = 5;
 export const DEFAULT_CONCURRENCY = 8;
-const TRUE_VALUES = new Set(['true', '1', 'yes', 'on']);
-const FALSE_VALUES = new Set(['false', '0', 'no', 'off']);
+const TRUE_VALUES = new Set(["true", "1", "yes", "on"]);
+const FALSE_VALUES = new Set(["false", "0", "no", "off"]);
 function parseBoolean(value, attribute) {
     if (value === undefined)
         return false;
@@ -55,53 +56,193 @@ function normalizeTarget(target, root, attribute) {
     }
     const absolute = path.resolve(root, target);
     const relative = path.relative(root, absolute);
-    if (relative.startsWith('..')) {
+    if (relative.startsWith("..")) {
         throw new Error(`Attribute "${attribute}" escapes the root directory: "${target}".`);
     }
-    return toPosix(relative) || '.';
+    return toPosix(relative) || ".";
 }
 function plural(count) {
-    return count === 1 ? '' : 'es';
+    return count === 1 ? "" : "es";
 }
 function describeBounds(bounds) {
     const { min, max } = bounds;
     if (min !== undefined && max !== undefined) {
-        return min === max ? `exactly ${min} match${plural(min)}` : `between ${min} and ${max} matches`;
+        return min === max
+            ? `exactly ${min} match${plural(min)}`
+            : `between ${min} and ${max} matches`;
     }
     if (min !== undefined)
         return `at least ${min} match${plural(min)}`;
     if (max !== undefined)
-        return max === 0 ? 'no matches' : `at most ${max} match${plural(max)}`;
+        return max === 0 ? "no matches" : `at most ${max} match${plural(max)}`;
     /* c8 ignore next */
-    return 'any number of matches';
+    return "any number of matches";
 }
 /** Prose form used in the assertion description ("must appear at most 3 times"). */
 function describeExpectation(bounds) {
     const { min, max } = bounds;
-    const times = (value) => `${value} time${value === 1 ? '' : 's'}`;
+    const times = (value) => `${value} time${value === 1 ? "" : "s"}`;
     if (min !== undefined && max !== undefined) {
-        return min === max ? `must appear exactly ${times(min)}` : `must appear between ${min} and ${max} times`;
+        return min === max
+            ? `must appear exactly ${times(min)}`
+            : `must appear between ${min} and ${max} times`;
     }
     if (min !== undefined)
         return `must appear at least ${times(min)}`;
     if (max === 0)
-        return 'must not appear';
+        return "must not appear";
     /* c8 ignore next */
-    return max === undefined ? 'may appear any number of times' : `must appear at most ${times(max)}`;
+    return max === undefined
+        ? "may appear any number of times"
+        : `must appear at most ${times(max)}`;
 }
 /** Prose for an import claim: "must not import", "must import at least 2 files". */
 function describeImportExpectation(bounds) {
     const { min, max } = bounds;
-    const files = (value) => `${value} file${value === 1 ? '' : 's'}`;
+    const files = (value) => `${value} file${value === 1 ? "" : "s"}`;
     if (max === 0 && min === undefined)
-        return 'must not import';
+        return "must not import";
     if (min !== undefined && max !== undefined) {
-        return min === max ? `must import from exactly ${files(min)}` : `must import from between ${min} and ${max} files`;
+        return min === max
+            ? `must import from exactly ${files(min)}`
+            : `must import from between ${min} and ${max} files`;
     }
     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)}`;
+    return max === undefined
+        ? "may import"
+        : `must import from at most ${files(max)}`;
+}
+/**
+ * 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;
+    };
 }
 function satisfies(count, bounds) {
     if (bounds.min !== undefined && count < bounds.min)
@@ -117,9 +258,9 @@ export function resolveDirective(directive, context) {
         error: { location, raw: directive.raw, message },
     });
     try {
-        const reason = attributes['reason'];
-        if (kind === 'assert-present') {
-            const files = splitList(attributes['file']).map((file) => normalizeTarget(file, context.root, 'file'));
+        const reason = attributes["reason"];
+        if (kind === "assert-present") {
+            const files = splitList(attributes["file"]).map((file) => normalizeTarget(file, context.root, "file"));
             if (files.length === 0) {
                 return fail('@assert-present requires a file="..." attribute.');
             }
@@ -127,65 +268,92 @@ export function resolveDirective(directive, context) {
                 assertion: {
                     kind,
                     location,
-                    description: `${files.join(', ')} must exist`,
+                    description: `${files.join(", ")} must exist`,
                     reason,
                     targets: [],
                     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",
                 },
             };
         }
-        const isImportKind = kind === 'assert-import-absence' || kind === 'assert-import-count';
-        const subject = isImportKind ? 'module' : 'symbol';
+        const isImportKind = kind === "assert-import-absence" || kind === "assert-import-count";
+        const subject = isImportKind ? "module" : "symbol";
         const symbol = attributes[subject];
         if (symbol === undefined || symbol.length === 0) {
             return fail(`@${kind} requires a non-empty ${subject}="..." attribute.`);
         }
-        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 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"]}".`);
         }
-        const rawTargets = splitList(attributes['target']);
-        const targets = (rawTargets.length > 0 ? rawTargets : ['.']).map((target) => normalizeTarget(target, context.root, 'target'));
+        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 bounds = {};
-        if (kind === 'assert-absence' || kind === 'assert-import-absence') {
-            if (attributes['expected'] !== undefined && attributes['max'] !== undefined) {
+        if (kind === "assert-absence" || kind === "assert-import-absence") {
+            if (attributes["expected"] !== undefined &&
+                attributes["max"] !== undefined) {
                 return fail(`@${kind} accepts either expected="..." or max="...", not both.`);
             }
-            const limit = attributes['expected'] ?? attributes['max'];
-            bounds.max = limit === undefined ? 0 : parseCount(limit, attributes['expected'] !== undefined ? 'expected' : 'max');
+            const limit = attributes["expected"] ?? attributes["max"];
+            bounds.max =
+                limit === undefined
+                    ? 0
+                    : parseCount(limit, attributes["expected"] !== undefined ? "expected" : "max");
         }
         else {
-            const expected = attributes['expected'];
+            const expected = attributes["expected"];
             if (expected !== undefined) {
-                if (attributes['min'] !== undefined || attributes['max'] !== undefined) {
+                if (attributes["min"] !== undefined ||
+                    attributes["max"] !== undefined) {
                     return fail(`@${kind} accepts either expected="..." or min/max, not both.`);
                 }
-                const value = parseCount(expected, 'expected');
+                const value = parseCount(expected, "expected");
                 bounds.min = value;
                 bounds.max = value;
             }
             else {
-                if (attributes['min'] === undefined && attributes['max'] === undefined) {
+                if (attributes["min"] === undefined &&
+                    attributes["max"] === undefined) {
                     return fail(`@${kind} requires expected="...", min="..." or max="...".`);
                 }
-                if (attributes['min'] !== undefined)
-                    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) {
+                if (attributes["min"] !== undefined)
+                    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) {
                     return fail(`min="${bounds.min}" is greater than max="${bounds.max}".`);
                 }
             }
         }
         if (isImportKind) {
-            const scope = targets.join(', ');
-            const excludeGlobs = splitList(attributes['exclude']);
-            const except = excludeGlobs.length > 0 ? ` (excluding ${excludeGlobs.join(', ')})` : '';
-            const includeTypes = (attributes['types'] ?? 'include').trim().toLowerCase() !== 'ignore';
-            if (!['include', 'ignore'].includes((attributes['types'] ?? 'include').trim().toLowerCase())) {
-                return fail(`Attribute "types" must be include or ignore, got "${attributes['types']}".`);
+            const scope = targets.join(", ");
+            const excludeGlobs = splitList(attributes["exclude"]);
+            const except = excludeGlobs.length > 0
+                ? ` (excluding ${excludeGlobs.join(", ")})`
+                : "";
+            const includeTypes = (attributes["types"] ?? "include").trim().toLowerCase() !== "ignore";
+            if (!["include", "ignore"].includes((attributes["types"] ?? "include").trim().toLowerCase())) {
+                return fail(`Attribute "types" must be include or ignore, got "${attributes["types"]}".`);
             }
             return {
                 assertion: {
@@ -207,20 +375,25 @@ export function resolveDirective(directive, context) {
                         // text search. It is set true because it is true: the tokenizer
                         // reads imports, so a module named in a comment was never a match.
                         ignoreComments: true,
+                        scope: context.scope ?? DEFAULT_SCOPE,
                         excludeFiles: context.excludeFiles,
                     },
                     imports: { modules: splitList(symbol), includeTypes },
                     missingTargets: [],
+                    allowEmpty,
+                    baseline,
+                    ratchet,
                 },
             };
         }
         const search = {
-            regex: parseBoolean(attributes['regex'], 'regex'),
-            word: parseBoolean(attributes['word'], 'word'),
-            ignoreCase: parseBoolean(attributes['ignore-case'], 'ignore-case'),
-            globs: splitList(attributes['glob']),
-            excludeGlobs: splitList(attributes['exclude']),
-            ignoreComments: comments !== 'include',
+            regex: parseBoolean(attributes["regex"], "regex"),
+            word: parseBoolean(attributes["word"], "word"),
+            ignoreCase: parseBoolean(attributes["ignore-case"], "ignore-case"),
+            globs: splitList(attributes["glob"]),
+            excludeGlobs: splitList(attributes["exclude"]),
+            ignoreComments: comments !== "include",
+            scope: context.scope ?? DEFAULT_SCOPE,
             excludeFiles: context.excludeFiles,
         };
         if (search.regex) {
@@ -231,8 +404,10 @@ export function resolveDirective(directive, context) {
                 return fail(`Invalid regular expression: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
-        const scope = targets.join(', ');
-        const except = search.excludeGlobs.length > 0 ? ` (excluding ${search.excludeGlobs.join(', ')})` : '';
+        const scope = targets.join(", ");
+        const except = search.excludeGlobs.length > 0
+            ? ` (excluding ${search.excludeGlobs.join(", ")})`
+            : "";
         return {
             assertion: {
                 kind,
@@ -245,6 +420,9 @@ export function resolveDirective(directive, context) {
                 bounds,
                 search,
                 missingTargets: [],
+                allowEmpty,
+                baseline,
+                ratchet,
             },
         };
     }
@@ -274,8 +452,12 @@ async function prepareAssertion(assertion, options) {
         warnings,
         commentMatches: 0,
         unclassifiedFiles: 0,
+        scope: EMPTY_LEDGER,
+        baselinedMatches: 0,
+        staleBaseline: [],
+        fileMatches: [],
     };
-    if (assertion.kind === 'assert-present') {
+    if (assertion.kind === "assert-present") {
         const missing = [];
         for (const file of assertion.files) {
             if (!(await pathExists(path.resolve(options.root, file))))
@@ -287,8 +469,8 @@ async function prepareAssertion(assertion, options) {
             ok: missing.length === 0,
             actual,
             message: missing.length === 0
-                ? `all ${assertion.files.length} referenced ${assertion.files.length === 1 ? 'path exists' : 'paths exist'}`
-                : `missing: ${missing.join(', ')}`,
+                ? `all ${assertion.files.length} referenced ${assertion.files.length === 1 ? "path exists" : "paths exist"}`
+                : `missing: ${missing.join(", ")}`,
             matches: [],
             durationMs: performance.now() - startedAt,
         };
@@ -304,40 +486,82 @@ async function prepareAssertion(assertion, options) {
             assertion.missingTargets.push(target);
     }
     if (assertion.missingTargets.length > 0) {
-        warnings.push(`target path${assertion.missingTargets.length === 1 ? '' : 's'} not found: ${assertion.missingTargets.join(', ')}`);
+        warnings.push(`target path${assertion.missingTargets.length === 1 ? "" : "s"} not found: ${assertion.missingTargets.join(", ")}`);
     }
     if (!options.allowMissingTargets && assertion.missingTargets.length > 0) {
         return {
             ...base,
             ok: false,
             actual: 0,
-            message: `target path${assertion.missingTargets.length === 1 ? ' does' : 's do'} not exist: ${assertion.missingTargets.join(', ')}`,
+            message: `target path${assertion.missingTargets.length === 1 ? " does" : "s do"} not exist: ${assertion.missingTargets.join(", ")}`,
             matches: [],
             durationMs: performance.now() - 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: performance.now() - 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));
+            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(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,
+            };
         },
-        finish: (search) => ({
-            ...base,
-            ok: satisfies(search.count, assertion.bounds),
-            actual: search.count,
-            message: `expected ${describeBounds(assertion.bounds)}, found ${search.count}`,
-            matches: search.matches.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,
-            engine: search.engine,
-            durationMs: performance.now() - 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.
  *
@@ -355,18 +579,33 @@ async function executeImportAssertion(assertion, options, base, warnings, starte
             assertion.missingTargets.push(target);
     }
     if (assertion.missingTargets.length > 0) {
-        warnings.push(`target path${assertion.missingTargets.length === 1 ? '' : 's'} not found: ${assertion.missingTargets.join(', ')}`);
+        warnings.push(`target path${assertion.missingTargets.length === 1 ? "" : "s"} not found: ${assertion.missingTargets.join(", ")}`);
     }
     const enumeration = await enumerateCandidates({
         root: options.root,
-        symbol: '',
+        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: performance.now() - 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 = [];
@@ -379,41 +618,58 @@ 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,
             });
         }
     }
     if (unresolved.length > 0) {
-        warnings.push(`${unresolved.length} module reference${unresolved.length === 1 ? '' : 's'} could not be resolved statically`, ...unresolved.slice(0, options.maxSnippets).map((entry) => `  ${entry}`));
+        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),
+            ? `target path${assertion.missingTargets.length === 1 ? " does" : "s do"} not exist: ${assertion.missingTargets.join(", ")}`
+            : 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: performance.now() - startedAt,
     };
 }
 /** Executes a single resolved assertion. */
 export async function executeAssertion(assertion, options) {
     const prepared = await prepareAssertion(assertion, options);
-    if (!('request' in prepared))
+    if (!("request" in prepared))
         return prepared;
     return prepared.finish(await options.engine.search(prepared.request));
 }
@@ -424,7 +680,13 @@ export async function executeAssertion(assertion, options) {
  */
 function groupKey(request) {
     const { options } = request;
-    return JSON.stringify([request.targets, options.regex, options.word, options.ignoreCase, options.globs]);
+    return JSON.stringify([
+        request.targets,
+        options.regex,
+        options.word,
+        options.ignoreCase,
+        options.globs,
+    ]);
 }
 /** Reads, parses and executes every directive found in the given spec files. */
 export async function runSpecGuard(options) {
@@ -433,16 +695,18 @@ 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)));
     const directives = [];
     const errors = [];
     for (const file of specFiles) {
         const relativeFile = toPosix(path.relative(root, file)) || toPosix(file);
-        const source = await fs.readFile(file, 'utf8').catch((error) => {
+        const source = await fs.readFile(file, "utf8").catch((error) => {
             errors.push({
                 location: { file, relativeFile, line: 1, column: 1 },
-                raw: '',
+                raw: "",
                 message: `Unable to read spec file: ${error instanceof Error ? error.message : String(error)}`,
             });
             return null;
@@ -455,20 +719,22 @@ export async function runSpecGuard(options) {
     }
     const assertions = [];
     for (const directive of directives) {
-        const resolved = resolveDirective(directive, { root, excludeFiles });
-        if ('error' in resolved)
+        const resolved = resolveDirective(directive, { root, excludeFiles, scope });
+        if ("error" in resolved)
             errors.push(resolved.error);
         else
             assertions.push(resolved.assertion);
     }
-    const engine = createCachedEngine(await resolveEngine(options.engine ?? 'auto'));
+    const engine = createCachedEngine(await resolveEngine(options.engine ?? "auto"));
     const executeOptions = {
         root,
         engine,
         allowMissingTargets,
         strictTargets,
+        allowEmptyScope,
         maxSnippets,
         imports: createImportIndex(),
+        hasFiles: createScopeProbe(),
     };
     const results = new Array(assertions.length);
     if (options.failFast) {
@@ -486,7 +752,7 @@ export async function runSpecGuard(options) {
         const prepared = await Promise.all(assertions.map((assertion) => prepareAssertion(assertion, executeOptions)));
         const groups = new Map();
         prepared.forEach((entry, index) => {
-            if (!('request' in entry)) {
+            if (!("request" in entry)) {
                 results[index] = entry;
                 return;
             }
@@ -525,7 +791,7 @@ export async function runSpecGuard(options) {
     return {
         ok: failed === 0 && errors.length === 0,
         root,
-        engine: warnings.length > 0 ? 'javascript' : engine.name,
+        engine: warnings.length > 0 ? "javascript" : engine.name,
         durationMs: performance.now() - startedAt,
         summary: {
             specs: specFiles.length,