@descent-vtt/spec-guard 0.5.0 → 0.6.0

package/dist/runner.js

@@ -7,13 +7,26 @@
  */
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { createCachedEngine, enumerateCandidates, resolveEngine, runSearches, ANY_FILE_PROBE, } 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 { buildGraph, cyclicComponents, edgeKey, isGraphFile, witness, } from "./graph.js";
 import { ANALYSABLE_EXTENSIONS, createImportIndex, resolveModule, } from "./imports.js";
+import { checkLayers } from "./layers.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 +57,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}".`);
     }
@@ -61,22 +80,22 @@ function normalizeTarget(target, root, attribute) {
     }
     return toPosix(relative) || ".";
 }
-function plural(count) {
-    return count === 1 ? "" : "es";
-}
-function describeBounds(bounds) {
+const MATCHES = { one: "match", many: "matches" };
+const CYCLES = { one: "import cycle", many: "import cycles" };
+const VIOLATING_FILES = { one: "violating file", many: "violating files" };
+function describeBounds(bounds, unit = MATCHES) {
     const { min, max } = bounds;
+    const counted = (count) => `${count} ${count === 1 ? unit.one : unit.many}`;
     if (min !== undefined && max !== undefined) {
         return min === max
-            ? `exactly ${min} match${plural(min)}`
-            : `between ${min} and ${max} matches`;
+            ? `exactly ${counted(min)}`
+            : `between ${min} and ${max} ${unit.many}`;
     }
     if (min !== undefined)
-        return `at least ${min} match${plural(min)}`;
+        return `at least ${counted(min)}`;
     if (max !== undefined)
-        return max === 0 ? "no matches" : `at most ${max} match${plural(max)}`;
-    /* c8 ignore next */
-    return "any number of matches";
+        return max === 0 ? `no ${unit.many}` : `at most ${counted(max)}`;
+    return `any number of ${unit.many}`;
 }
 /** Prose form used in the assertion description ("must appear at most 3 times"). */
 function describeExpectation(bounds) {
@@ -91,10 +110,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,10 +128,8 @@ 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)}`;
 }
 /**
  * What a report says when an assertion covered nothing.
@@ -136,8 +153,8 @@ const EMPTY_SCOPE_HINT = 'add allow-empty="true" if that is expected';
  * 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}`];
+function describeOutcome(bounds, actual, extras, unit = MATCHES) {
+    const parts = [`expected ${describeBounds(bounds, unit)}, found ${actual}`];
     if (extras.excluded > 0) {
         parts.push(`${extras.excluded} more ${extras.excluded === 1 ? "is" : "are"} on the baseline`);
     }
@@ -244,12 +261,16 @@ export function createScopeProbe() {
         return pending;
     };
 }
-function satisfies(count, bounds) {
-    if (bounds.min !== undefined && count < bounds.min)
-        return false;
-    if (bounds.max !== undefined && count > bounds.max)
-        return false;
-    return true;
+/**
+ * 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) {
@@ -281,10 +302,14 @@ export function resolveDirective(directive, context) {
                 },
             };
         }
-        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) {
+        const perModule = kind === "assert-import-absence" || kind === "assert-import-count";
+        // The two directives of ADR-0011. A cycle is a claim about the graph
+        // itself and names no subject; layers name theirs in `order`.
+        const graphKind = kind === "assert-import-cycle" || kind === "assert-layers";
+        const isImportKind = perModule || graphKind;
+        const subject = kind === "assert-layers" ? "order" : perModule ? "module" : "symbol";
+        const symbol = attributes[subject] ?? "";
+        if (kind !== "assert-import-cycle" && symbol.length === 0) {
             return fail(`@${kind} requires a non-empty ${subject}="..." attribute.`);
         }
         const allowEmpty = parseBoolean(attributes["allow-empty"], "allow-empty");
@@ -305,9 +330,9 @@ export function resolveDirective(directive, context) {
             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 (kind === "assert-absence" || kind === "assert-import-absence" || graphKind) {
             if (attributes["expected"] !== undefined &&
                 attributes["max"] !== undefined) {
                 return fail(`@${kind} accepts either expected="..." or max="...", not both.`);
@@ -338,9 +363,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}".`);
                 }
             }
@@ -355,13 +381,30 @@ export function resolveDirective(directive, context) {
             if (!["include", "ignore"].includes((attributes["types"] ?? "include").trim().toLowerCase())) {
                 return fail(`Attribute "types" must be include or ignore, got "${attributes["types"]}".`);
             }
+            const layers = splitList(symbol);
+            if (kind === "assert-layers") {
+                if (layers.length < 2) {
+                    return fail(`@assert-layers needs at least two layers in order="...", got ${layers.length}.`);
+                }
+                const repeated = layers.find((layer, at) => layers.indexOf(layer) !== at);
+                if (repeated !== undefined) {
+                    return fail(`Layer "${repeated}" is listed twice in order="...".`);
+                }
+            }
+            const typesNote = includeTypes ? "" : " (type-only imports ignored)";
+            const description = kind === "assert-import-cycle"
+                ? `${scope} must have ${describeBounds(bounds, CYCLES)}${typesNote}${except}`
+                : kind === "assert-layers"
+                    ? `${scope} must keep its layers in order, ${layers.join(" < ")}${bounds.max === 0 ? "" : `, with ${describeBounds(bounds, VIOLATING_FILES)}`}${typesNote}${except}`
+                    : `${scope} ${describeImportExpectation(bounds)} "${symbol}"${except}`;
             return {
                 assertion: {
                     kind,
                     location,
-                    description: `${scope} ${describeImportExpectation(bounds)} "${symbol}"${except}`,
+                    description,
                     reason,
-                    symbol,
+                    // Only the per-module kinds have a subject a report can quote.
+                    symbol: perModule ? symbol : undefined,
                     targets,
                     files: [],
                     bounds,
@@ -378,7 +421,8 @@ export function resolveDirective(directive, context) {
                         scope: context.scope ?? DEFAULT_SCOPE,
                         excludeFiles: context.excludeFiles,
                     },
-                    imports: { modules: splitList(symbol), includeTypes },
+                    imports: { modules: perModule ? splitList(symbol) : [], includeTypes },
+                    ...(kind === "assert-layers" ? { layers } : {}),
                     missingTargets: [],
                     allowEmpty,
                     baseline,
@@ -401,7 +445,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(", ");
@@ -472,7 +519,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) {
@@ -495,7 +542,7 @@ 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 = {
@@ -512,7 +559,7 @@ async function prepareAssertion(assertion, options) {
                 actual: 0,
                 message: `no files were inspected, so this assertion verified nothing (${EMPTY_SCOPE_HINT})`,
                 matches: [],
-                durationMs: performance.now() - startedAt,
+                durationMs: elapsed(startedAt),
             };
         }
     }
@@ -524,7 +571,13 @@ async function prepareAssertion(assertion, options) {
             // 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;
@@ -548,7 +601,7 @@ async function prepareAssertion(assertion, options) {
                 unclassifiedFiles: search.unclassifiedFiles,
                 scope: search.scope,
                 engine: search.engine,
-                durationMs: performance.now() - startedAt,
+                durationMs: elapsed(startedAt),
             };
         },
     };
@@ -581,13 +634,21 @@ 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)));
+    // A cycle needs files the resolver can name, which today means JavaScript
+    // and TypeScript; every other import rule reads any language spec-guard
+    // tokenizes. ADR-0011 has the reasons, language by language.
+    const cycles = assertion.kind === "assert-import-cycle";
+    const analysable = enumeration.files.filter((file) => cycles
+        ? isGraphFile(file.relativePath)
+        : 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
@@ -598,35 +659,60 @@ async function executeImportAssertion(assertion, options, base, warnings, starte
             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})`,
+                : cycles
+                    ? `none of the ${enumeration.files.length} files here are JavaScript or TypeScript, so there is no import graph to check and 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,
+            durationMs: elapsed(startedAt),
         };
     }
     const skipped = enumeration.files.length - analysable.length;
     if (skipped > 0) {
-        warnings.push(`analysed ${analysable.length} of ${enumeration.files.length} files; ${skipped} ${skipped === 1 ? "is" : "are"} in a language whose imports spec-guard cannot read`);
+        warnings.push(cycles
+            ? `placed ${analysable.length} of ${enumeration.files.length} files in the import graph; ${skipped} ${skipped === 1 ? "is" : "are"} not JavaScript or TypeScript`
+            : `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 = [];
+    const analysed = [];
     const unresolved = [];
     for (const file of analysable) {
         const analysis = await options.imports.analyze(file.absolutePath, file.relativePath);
         for (const note of analysis.notes) {
             unresolved.push(`${note.file}:${note.line} ${note.detail}`);
         }
-        const hit = analysis.references.find((reference) => {
+        analysed.push({ file: file.relativePath, references: analysis.references });
+    }
+    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}`));
+    }
+    const read = {
+        analysed,
+        walked: enumeration.files.map((file) => file.relativePath),
+        targets: existingTargets,
+        unresolved: unresolved.length,
+        missing: !options.allowMissingTargets && assertion.missingTargets.length > 0
+            ? `target path${assertion.missingTargets.length === 1 ? " does" : "s do"} not exist: ${assertion.missingTargets.join(", ")}`
+            : null,
+    };
+    if (cycles)
+        return finishCycles(assertion, options, base, warnings, startedAt, read);
+    if (assertion.layers) {
+        return finishLayers(assertion, assertion.layers, options, base, warnings, startedAt, read);
+    }
+    const matchesModule = createExcludeMatcher(query.modules);
+    const matches = [];
+    for (const { file, references } of analysed) {
+        const hit = references.find((reference) => {
             if (reference.typeOnly && !query.includeTypes)
                 return false;
             // 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)) ||
+            return (matchesModule(resolveModule(reference.specifier, file)) ||
                 matchesModule(reference.specifier));
         });
         if (hit) {
             matches.push({
-                file: file.relativePath,
+                file,
                 line: hit.line,
                 column: hit.column,
                 text: `${IMPORT_VERBS[hit.kind]} ${hit.specifier}`,
@@ -634,36 +720,149 @@ async function executeImportAssertion(assertion, options, base, warnings, starte
             });
         }
     }
-    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}`));
-    }
-    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 strictFailure = read.missing !== null || (options.strictTargets && unresolved.length > 0);
     const ok = satisfies(actual, assertion.bounds) && !strictFailure && !staleFailure;
     return {
         ...base,
         ok,
         actual,
-        message: missingFailure
-            ? `target path${assertion.missingTargets.length === 1 ? " does" : "s do"} not exist: ${assertion.missingTargets.join(", ")}`
-            : describeOutcome(assertion.bounds, actual, {
+        message: read.missing ??
+            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`
-                    : ""),
+            }) + strictSuffix(options, unresolved.length),
         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,
+        durationMs: elapsed(startedAt),
+    };
+}
+/** What `--strict` adds to a message when references went unresolved. */
+function strictSuffix(options, unresolved) {
+    return options.strictTargets && unresolved > 0
+        ? `; ${unresolved} reference${unresolved === 1 ? "" : "s"} could not be resolved`
+        : "";
+}
+/**
+ * Counts the import cycles in scope - components, not simple cycles.
+ *
+ * Each is shown as one concrete loop with the line of every import on it, at
+ * the location of the first. The count does not move when someone adds a
+ * second route around a loop that already exists, which is what makes it a
+ * number a spec can hold. See ADR-0011.
+ */
+function finishCycles(assertion, options, base, warnings, startedAt, read) {
+    const query = assertion.imports;
+    const scope = {
+        nodes: new Set(read.analysed.map((entry) => entry.file)),
+        walked: new Set(read.walked),
+        excluded: createExcludeMatcher(assertion.search.excludeGlobs),
+        covers: (relativePath) => relativePath !== ".." &&
+            !relativePath.startsWith("../") &&
+            read.targets.some((target) => target === "." || relativePath === target || relativePath.startsWith(`${target}/`)),
+    };
+    const graph = buildGraph(read.analysed, scope, query.includeTypes);
+    const loops = cyclicComponents(graph).map((component) => witness(component, graph.successors));
+    if (graph.unresolved.length > 0) {
+        const count = graph.unresolved.length;
+        warnings.push(`${count} import${count === 1 ? "" : "s"} could not be resolved to a file, so ${count === 1 ? "its edge is" : "their edges are"} missing from the graph`, ...graph.unresolved
+            .slice(0, options.maxSnippets)
+            .map(({ file, reference }) => `  ${file}:${reference.line} ${reference.specifier}`));
+    }
+    const gaps = read.unresolved + graph.unresolved.length;
+    const actual = loops.length;
+    const ok = satisfies(actual, assertion.bounds) &&
+        read.missing === null &&
+        !(options.strictTargets && gaps > 0);
+    const matches = loops.map((loop) => {
+        const hop = (at) => graph.via.get(edgeKey(loop[at], loop[at + 1]));
+        return {
+            file: loop[0],
+            line: hop(0).line,
+            column: hop(0).column,
+            // Every file on the loop with the line that leaves it, so the imports to
+            // change can be read off without opening each file to find them.
+            text: loop.map((file, at) => (at < loop.length - 1 ? `${file}:${hop(at).line}` : file)).join(" -> "),
+            count: 1,
+        };
+    });
+    return {
+        ...base,
+        ok,
+        actual,
+        message: read.missing ??
+            describeOutcome(assertion.bounds, actual, { excluded: 0, stale: [], gaps: 0 }, CYCLES) +
+                strictSuffix(options, gaps),
+        matches: matches.slice(0, options.maxSnippets),
+        durationMs: elapsed(startedAt),
+    };
+}
+/**
+ * Checks each file's imports against the layer order.
+ *
+ * Three things fail besides a violation, because each is a rule that would
+ * otherwise pass while checking less than it says: a layer that matches no
+ * file, a file two layers claim, and a missing target. See ADR-0011.
+ */
+function finishLayers(assertion, order, options, base, warnings, startedAt, read) {
+    const query = assertion.imports;
+    const report = checkLayers(read.analysed, order, query.includeTypes);
+    const quoted = (layers) => layers.map((layer) => `"${order[layer]}"`).join(" and ");
+    const empty = order.flatMap((_, layer) => (report.members[layer] === 0 ? [layer] : []));
+    const emptyAllowed = options.allowEmptyScope || assertion.allowEmpty;
+    const one = empty.length === 1;
+    const unmatched = `${one ? "layer" : "layers"} ${quoted(empty)} ${one ? "matches" : "match"} no file in scope`;
+    if (report.unassigned.length > 0) {
+        warnings.push(`${report.unassigned.length} of ${read.analysed.length} files ${report.unassigned.length === 1 ? "belongs" : "belong"} to no layer, so nothing here constrains ${report.unassigned.length === 1 ? "it" : "them"}`);
+    }
+    if (empty.length > 0 && emptyAllowed)
+        warnings.push(unmatched);
+    const fileCounts = new Map(report.violations.map((violation) => [violation.file, 1]));
+    const { excluded, stale, shows } = applyBaseline(assertion.baseline, fileCounts);
+    const staleFailure = assertion.ratchet === "two-sided" && stale.length > 0;
+    const actual = report.violations.length - excluded;
+    const emptyFailure = empty.length > 0 && !emptyAllowed;
+    const ok = satisfies(actual, assertion.bounds) &&
+        read.missing === null &&
+        !staleFailure &&
+        !emptyFailure &&
+        report.ambiguous.length === 0 &&
+        !(options.strictTargets && read.unresolved > 0);
+    const message = read.missing ??
+        (emptyFailure
+            ? `${unmatched}, so nothing is held to ${one ? "it" : "them"} (${EMPTY_SCOPE_HINT})`
+            : report.ambiguous.length > 0
+                ? `${report.ambiguous
+                    .slice(0, options.maxSnippets)
+                    .map(({ file, layers }) => `${file} is in both ${quoted(layers)}`)
+                    .join("; ")}; a file in two layers has no single rule to follow`
+                : describeOutcome(assertion.bounds, actual, { excluded, stale: staleFailure ? stale : [], gaps: 0 }, VIOLATING_FILES) + strictSuffix(options, read.unresolved));
+    return {
+        ...base,
+        ok,
+        actual,
+        message,
+        baselinedMatches: excluded,
+        staleBaseline: stale,
+        fileMatches: [...fileCounts].map(([file, count]) => ({ file, count })),
+        matches: report.violations
+            .filter((violation) => shows(violation.file))
+            .slice(0, options.maxSnippets)
+            .map((violation) => ({
+            file: violation.file,
+            line: violation.reference.line,
+            column: violation.reference.column,
+            text: `${order[violation.from]} -> ${order[violation.to]}: ${IMPORT_VERBS[violation.reference.kind]} ${violation.reference.specifier}`,
+            count: 1,
+        })),
+        durationMs: elapsed(startedAt),
     };
 }
 /** Executes a single resolved assertion. */
@@ -674,19 +873,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) {
@@ -700,7 +894,10 @@ export async function runSpecGuard(options) {
     const specFiles = await expandSpecPatterns(options.patterns, root);
     const excludeFiles = new Set(options.includeSpecs ? [] : specFiles.map((file) => path.resolve(file)));
     const directives = [];
+    /** Parsed, validated, and then not run: see ADR-0010. */
+    const withheld = [];
     const errors = [];
+    const inactiveSpecs = [];
     for (const file of specFiles) {
         const relativeFile = toPosix(path.relative(root, file)) || toPosix(file);
         const source = await fs.readFile(file, "utf8").catch((error) => {
@@ -714,8 +911,23 @@ export async function runSpecGuard(options) {
         if (source === null)
             continue;
         const parsed = parseDirectives(source, { file, relativeFile });
-        directives.push(...parsed.directives);
         errors.push(...parsed.errors);
+        const status = parsed.status;
+        if (status && !status.active && !(options.ignoreStatus ?? false)) {
+            withheld.push(...parsed.directives);
+            // Recorded even when it held no directives. "docs/adr/0011.md is a
+            // draft" is worth saying to someone wondering why their new rule has no
+            // effect, and a report that only mentions the documents it happened to
+            // find directives in cannot answer that.
+            inactiveSpecs.push({
+                file: relativeFile,
+                status: status.value,
+                label: status.label,
+                directives: parsed.directives.length,
+            });
+            continue;
+        }
+        directives.push(...parsed.directives);
     }
     const assertions = [];
     for (const directive of directives) {
@@ -725,6 +937,15 @@ export async function runSpecGuard(options) {
         else
             assertions.push(resolved.assertion);
     }
+    // Not in force is not the same as not checked. A withheld directive is still
+    // held to being well-formed, so a draft's typo is found on the day it is
+    // written rather than on the day the ADR is accepted - which is the day
+    // everyone has already agreed the rule is right and stopped looking at it.
+    for (const directive of withheld) {
+        const resolved = resolveDirective(directive, { root, excludeFiles, scope });
+        if ("error" in resolved)
+            errors.push(resolved.error);
+    }
     const engine = createCachedEngine(await resolveEngine(options.engine ?? "auto"));
     const executeOptions = {
         root,
@@ -736,7 +957,7 @@ export async function runSpecGuard(options) {
         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++) {
@@ -756,7 +977,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 });
@@ -764,7 +989,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) {
@@ -784,25 +1009,25 @@ 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,
             passed: results.length - failed,
             failed,
             skipped: assertions.length - results.length,
+            inactive: withheld.length,
         },
         results,
         errors,
         warnings,
+        inactiveSpecs,
         specFiles: specFiles.map((file) => toPosix(path.relative(root, file)) || toPosix(file)),
     };
 }