@descent-vtt/spec-guard 0.5.1 → 0.7.0

package/dist/runner.js

@@ -8,9 +8,11 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { comparePaths, createCachedEngine, enumerateCandidates, passKey, resolveEngine, runSearches, ANY_FILE_PROBE, ROOT_TARGETS, } from "./engine.js";
-import { createExcludeMatcher, expandSpecPatterns, toPosix } from "./glob.js";
+import { createExcludeMatcher, toPosix } from "./glob.js";
+import { buildGraph, cyclicComponents, edgeKey, isGraphFile, witness, } from "./graph.js";
 import { ANALYSABLE_EXTENSIONS, createImportIndex, resolveModule, } from "./imports.js";
-import { parseDirectives } from "./parser.js";
+import { checkLayers } from "./layers.js";
+import { readSpecs, specPath } from "./specs.js";
 import { createScope, DEFAULT_SCOPE, EMPTY_LEDGER, } from "./scope.js";
 export const DEFAULT_MAX_SNIPPETS = 5;
 export const DEFAULT_CONCURRENCY = 8;
@@ -78,21 +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)}`;
-    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) {
@@ -150,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`);
     }
@@ -299,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");
@@ -325,7 +332,7 @@ export function resolveDirective(directive, context) {
         const rawTargets = splitList(attributes["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.`);
@@ -374,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,
@@ -397,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,
@@ -452,6 +477,15 @@ export function resolveDirective(directive, context) {
         return fail(error instanceof Error ? error.message : String(error));
     }
 }
+/**
+ * The spec files a search must not count, as absolute paths.
+ *
+ * A spec names the symbol it forbids, so without this every absence rule would
+ * find itself. Empty under `--include-specs`.
+ */
+export function specExclusions(specFiles, includeSpecs) {
+    return new Set(includeSpecs ? undefined : specFiles.map((file) => path.resolve(file)));
+}
 async function pathExists(candidate) {
     return (await fs.stat(candidate).catch(() => null)) !== null;
 }
@@ -526,61 +560,71 @@ async function prepareAssertion(assertion, options) {
         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),
-            };
-        }
+    // Every target missing, and that tolerated, leaves nothing to search - and
+    // must not be handed to the engine as an empty target list, which the engine
+    // reads, by contract, as the root. It used to be: a rule on a deleted
+    // `src/auth` searched the whole repository, where `min="1"` could pass on a
+    // test file. Found by holding `spec-guard query` to the walk; see ADR-0012.
+    const nothingLeft = existingTargets.length === 0;
+    if (!options.allowEmptyScope && !assertion.allowEmpty && (nothingLeft || !(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,
-        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.
-            //
-            // 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(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: elapsed(startedAt),
-            };
-        },
+    const 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.
+        //
+        // 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(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: elapsed(startedAt),
+        };
     };
+    return nothingLeft ? finish(NOTHING_SEARCHED) : { request, finish };
 }
+const NOTHING_SEARCHED = {
+    count: 0,
+    commentMatches: 0,
+    unclassifiedFiles: 0,
+    matches: [],
+    fileCounts: new Map(),
+    scope: EMPTY_LEDGER,
+};
 /** How each kind of reference is spelled in a report snippet. */
 const IMPORT_VERBS = {
     import: "import",
@@ -612,13 +656,30 @@ async function executeImportAssertion(assertion, options, base, warnings, starte
     // 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,
-        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) {
+    //
+    // And no walk at all when every target is missing: an empty target list is
+    // the root to the engine, as the text rules above found out.
+    const enumeration = existingTargets.length === 0
+        ? { files: [] }
+        : await enumerateCandidates({
+            root: options.root,
+            targets: existingTargets,
+            options: assertion.search,
+        });
+    // Why a missing target fails the assertion, or null when it does not. Decided
+    // before scope, so a rule whose only target is gone says so rather than that
+    // its scope is empty - which is true, and not the thing to fix.
+    const missing = !options.allowMissingTargets && assertion.missingTargets.length > 0
+        ? `target path${assertion.missingTargets.length === 1 ? " does" : "s do"} not exist: ${assertion.missingTargets.join(", ")}`
+        : null;
+    // 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 && missing === null && !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.
@@ -628,35 +689,58 @@ 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: 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,
+    };
+    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}`,
@@ -664,31 +748,23 @@ 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 })),
@@ -696,6 +772,127 @@ async function executeImportAssertion(assertion, options, base, warnings, starte
         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. */
 export async function executeAssertion(assertion, options) {
     const prepared = await prepareAssertion(assertion, options);
@@ -722,34 +919,53 @@ export async function runSpecGuard(options) {
     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 specs = await readSpecs(options.patterns, root);
+    const specFiles = specs.files;
+    const excludeFiles = specExclusions(specFiles, options.includeSpecs ?? false);
     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) => {
-            errors.push({
-                location: { file, relativeFile, line: 1, column: 1 },
-                raw: "",
-                message: `Unable to read spec file: ${error instanceof Error ? error.message : String(error)}`,
+    /** Parsed, validated, and then not run: see ADR-0010. */
+    const withheld = [];
+    const errors = [...specs.errors];
+    const inactiveSpecs = [];
+    for (const document of specs.documents) {
+        if (!document.inForce && !(options.ignoreStatus ?? false)) {
+            // A document is only ever out of force because of a status it declares.
+            const status = document.status;
+            withheld.push(...document.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: document.relativeFile,
+                status: status.value,
+                label: status.label,
+                directives: document.directives.length,
             });
-            return null;
-        });
-        if (source === null)
             continue;
-        const parsed = parseDirectives(source, { file, relativeFile });
-        directives.push(...parsed.directives);
-        errors.push(...parsed.errors);
+        }
+        directives.push(...document.directives);
     }
     const assertions = [];
     for (const directive of directives) {
         const resolved = resolveDirective(directive, { root, excludeFiles, scope });
         if ("error" in resolved)
             errors.push(resolved.error);
-        else
+        // Selection happens after resolution, so a directive that is not selected
+        // is still held to being well-formed - the same bargain ADR-0010 strikes
+        // for a document that is not in force.
+        else if (options.select?.(resolved.assertion) ?? true)
             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,
@@ -826,11 +1042,13 @@ export async function runSpecGuard(options) {
             passed: results.length - failed,
             failed,
             skipped: assertions.length - results.length,
+            inactive: withheld.length,
         },
         results,
         errors,
         warnings,
-        specFiles: specFiles.map((file) => toPosix(path.relative(root, file)) || toPosix(file)),
+        inactiveSpecs,
+        specFiles: specFiles.map((file) => specPath(root, file)),
     };
 }
 //# sourceMappingURL=runner.js.map