@descent-vtt/spec-guard 0.6.0 → 0.7.0

package/dist/rules.js

@@ -0,0 +1,153 @@
+/**
+ * Which rules govern a path, decided from the specs alone.
+ *
+ * Pure. Nothing here reads the codebase: whether an assertion's scope reaches a
+ * path is arithmetic on the assertion's own `target`, `exclude` and `glob`, the
+ * run's skipped directory names, and the path's extension. That is the whole
+ * reason a query can answer in milliseconds - and it is also a claim, that the
+ * arithmetic agrees with the walk the assertion would really make. The suite
+ * holds it to that claim by comparing the two over real trees; ADR-0012 lists
+ * the three things arithmetic cannot see.
+ *
+ * A file is governed or it is not. A directory is governed when some file under
+ * it could be, and "could" is doing work: whether `glob="*.py"` matches anything
+ * in `src/` is a question about files that are not read here. The rule is shown
+ * with its filters rather than being guessed away.
+ */
+import path from 'node:path';
+import { createExcludeMatcher, createGlobMatcher } from './glob.js';
+import { isGraphFile } from './graph.js';
+import { ANALYSABLE_EXTENSIONS } from './imports.js';
+import { layerMatcher } from './layers.js';
+/** Whether `child` is `parent` or lies under it. */
+export function within(child, parent) {
+    return parent === '.' || child === parent || child.startsWith(`${parent}/`);
+}
+/** Whether the file-reading part of an assertion can read this file at all. */
+function readable(kind, relativePath) {
+    if (kind === 'assert-import-cycle')
+        return isGraphFile(relativePath);
+    if (kind === 'assert-import-absence' || kind === 'assert-import-count' || kind === 'assert-layers') {
+        return ANALYSABLE_EXTENSIONS.has(path.posix.extname(relativePath));
+    }
+    return true;
+}
+/**
+ * Whether the walk from `target` would step into a skipped directory on its way
+ * to `relativePath`.
+ *
+ * Only the directories below the target count, which is how the walk behaves: it
+ * never checks the name of the directory it was started in, so
+ * `target="node_modules/pkg"` is searched and `target="src"` does not reach
+ * `src/node_modules`.
+ */
+function skippedOnTheWay(target, relativePath, options, isFile) {
+    // A target that is the path itself leaves this empty, and it splits into one
+    // empty name - which no skipped directory has.
+    const directories = path.posix.relative(target, relativePath).split('/');
+    if (isFile)
+        directories.pop();
+    return directories.some((name) => options.scope.skippedDirectories.has(name));
+}
+/**
+ * Whether an assertion's scope reaches a path.
+ *
+ * For a file, exactly what the walk would do: under a target, not excluded, not
+ * inside a skipped directory, matched by `glob`, not one of the spec files, and
+ * in a language the assertion reads. For a directory, whether any of that could
+ * be true of something under it.
+ */
+export function governs(assertion, query) {
+    if (assertion.kind === 'assert-present') {
+        return assertion.files.some((file) => (query.shape === 'file' ? file === query.path : within(file, query.path)));
+    }
+    const options = assertion.search;
+    const excluded = createExcludeMatcher(options.excludeGlobs);
+    if (query.shape === 'file') {
+        return (assertion.targets.some((target) => within(query.path, target) && !skippedOnTheWay(target, query.path, options, true)) &&
+            !excluded(query.path) &&
+            createGlobMatcher(options.globs)(query.path) &&
+            !options.excludeFiles.has(query.absolutePath) &&
+            readable(assertion.kind, query.path));
+    }
+    return assertion.targets.some((target) => {
+        // The directory is inside the target: everything under it is walked unless
+        // the directory itself is skipped or excluded - and an excluded directory
+        // excludes all of its contents, because `exclude` tests every ancestor.
+        if (within(query.path, target)) {
+            return !skippedOnTheWay(target, query.path, options, false) && !excluded(query.path);
+        }
+        // The target is inside the directory: its files are under the directory.
+        return within(target, query.path) && !excluded(target);
+    });
+}
+/**
+ * Where a path sits in a layer order.
+ *
+ * For a directory, the layer that matches the directory itself - which then
+ * matches every file under it, since a layer is an `exclude`-style pattern and
+ * those test every ancestor. A directory no layer matches may still hold files
+ * that one does, and is reported as belonging to none rather than guessed at.
+ */
+export function layerPosition(order, relativePath) {
+    const indices = layerMatcher(order)(relativePath);
+    const matches = indices.map((index) => order[index]);
+    if (indices.length !== 1)
+        return { layer: null, position: null, matches, mayImport: [], mustNotImport: [] };
+    const index = indices[0];
+    return {
+        layer: order[index],
+        position: index + 1,
+        matches,
+        mayImport: order.slice(0, index + 1),
+        mustNotImport: order.slice(index + 1),
+    };
+}
+/**
+ * A rule as a report shows it, optionally as it applies to one path.
+ *
+ * Every field is what the directive said, resolved - never a default invented
+ * for display. A text rule reports its `glob` even when empty, because "every
+ * file" is a statement about scope a reader should not have to infer.
+ */
+export function viewRule(assertion, document, query) {
+    const view = {
+        document: document.file,
+        line: assertion.location.line,
+        kind: assertion.kind,
+        description: assertion.description,
+        reason: assertion.reason ?? null,
+        inForce: document.inForce,
+        bounds: assertion.bounds,
+    };
+    if (assertion.kind === 'assert-present')
+        return { ...view, files: assertion.files };
+    const options = assertion.search;
+    const baseline = query ? assertion.baseline.filter((entry) => within(entry.path, query.path)) : assertion.baseline;
+    const scoped = { ...view, targets: assertion.targets, exclude: options.excludeGlobs };
+    if (assertion.imports === undefined) {
+        return {
+            ...scoped,
+            glob: options.globs,
+            symbol: assertion.symbol,
+            regex: options.regex,
+            word: options.word,
+            ignoreCase: options.ignoreCase,
+            comments: options.ignoreComments ? 'ignore' : 'include',
+            baseline,
+        };
+    }
+    const types = assertion.imports.includeTypes ? 'include' : 'ignore';
+    if (assertion.kind === 'assert-import-cycle')
+        return { ...scoped, types };
+    if (assertion.layers === undefined)
+        return { ...scoped, modules: assertion.imports.modules, types, baseline };
+    return {
+        ...scoped,
+        order: assertion.layers,
+        types,
+        baseline,
+        ...(query ? { position: layerPosition(assertion.layers, query.path) } : {}),
+    };
+}
+//# sourceMappingURL=rules.js.map

package/dist/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"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"}

package/dist/runner.d.ts

@@ -57,6 +57,15 @@ export interface RunOptions {
      * default, because the point of reading the status is to honour it.
      */
     ignoreStatus?: boolean;
+    /**
+     * Which resolved assertions to execute. Every one, when unset.
+     *
+     * For a caller that wants the rules governing a few paths rather than all of
+     * them - the MCP server's `check_architecture`. An assertion that is not
+     * selected is not executed and not counted; it is still resolved, so a
+     * malformed directive is an error whatever is selected.
+     */
+    select?: (assertion: Assertion) => boolean;
 }
 export interface RunResult extends RunReport {
     /** Spec files that were executed, relative to root. */
@@ -107,6 +116,13 @@ export declare function resolveDirective(directive: Directive, context: ResolveC
 } | {
     error: DirectiveError;
 };
+/**
+ * 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 declare function specExclusions(specFiles: readonly string[], includeSpecs: boolean): ReadonlySet<string>;
 export interface ExecuteOptions {
     root: string;
     engine: Engine;

package/dist/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EASL,KAAK,MAAM,EACX,KAAK,gBAAgB,EACrB,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAWrB,OAAO,EAIL,KAAK,WAAW,EAEjB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EACf,aAAa,EAEb,SAAS,EACT,cAAc,EAId,SAAS,EAIT,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,+DAA+D;IAC/D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,uEAAuE;IACvE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC;CAC5C;AAED,MAAM,WAAW,SAAU,SAAQ,SAAS;IAC1C,uDAAuD;IACvD,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAE,MAA0B,GAAG,MAAM,CAE5E;AAyND;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACtC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAA;CAAE,CAsBrF;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,IAAI,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAoB/E;AAiBD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC,oEAAoE;IACpE,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,cAAc,GACtB;IAAE,SAAS,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,cAAc,CAAA;CAAE,CAyPtD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,YAAY,EAAE,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,CAEvG;AAMD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,OAAO,CAAC;IAC7B,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,OAAO,EAAE,WAAW,CAAC;IACrB,2DAA2D;IAC3D,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACxD;AA6iBD,4CAA4C;AAC5C,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,eAAe,CAAC,CAI1B;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED,gFAAgF;AAChF,wBAAsB,YAAY,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAyK1E"}

package/dist/runner.js

@@ -8,11 +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 { checkLayers } from "./layers.js";
-import { parseDirectives } from "./parser.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;
@@ -477,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;
 }
@@ -551,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",
@@ -637,11 +656,22 @@ 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,
-    });
+    //
+    // 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.
@@ -649,7 +679,7 @@ async function executeImportAssertion(assertion, options, base, warnings, starte
     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) {
+    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.
@@ -689,9 +719,7 @@ async function executeImportAssertion(assertion, options, base, warnings, starte
         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,
+        missing,
     };
     if (cycles)
         return finishCycles(assertion, options, base, warnings, startedAt, read);
@@ -891,50 +919,42 @@ 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 = [];
     /** Parsed, validated, and then not run: see ADR-0010. */
     const withheld = [];
-    const errors = [];
+    const errors = [...specs.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) => {
-            errors.push({
-                location: { file, relativeFile, line: 1, column: 1 },
-                raw: "",
-                message: `Unable to read spec file: ${error instanceof Error ? error.message : String(error)}`,
-            });
-            return null;
-        });
-        if (source === null)
-            continue;
-        const parsed = parseDirectives(source, { file, relativeFile });
-        errors.push(...parsed.errors);
-        const status = parsed.status;
-        if (status && !status.active && !(options.ignoreStatus ?? false)) {
-            withheld.push(...parsed.directives);
+    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: relativeFile,
+                file: document.relativeFile,
                 status: status.value,
                 label: status.label,
-                directives: parsed.directives.length,
+                directives: document.directives.length,
             });
             continue;
         }
-        directives.push(...parsed.directives);
+        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
@@ -1028,7 +1048,7 @@ export async function runSpecGuard(options) {
         errors,
         warnings,
         inactiveSpecs,
-        specFiles: specFiles.map((file) => toPosix(path.relative(root, file)) || toPosix(file)),
+        specFiles: specFiles.map((file) => specPath(root, file)),
     };
 }
 //# sourceMappingURL=runner.js.map