@descent-vtt/spec-guard 0.6.0 → 0.8.0

package/dist/runner.js

@@ -8,12 +8,13 @@
 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";
+import { checkStructure, createTreeIndex, partnerTemplateIssue, requiredEntryIssue, } from "./structure.js";
 export const DEFAULT_MAX_SNIPPETS = 5;
 export const DEFAULT_CONCURRENCY = 8;
 /**
@@ -307,9 +308,23 @@ export function resolveDirective(directive, context) {
         // 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";
+        // ADR-0013: a structure rule names its subject by naming its claim, and
+        // names exactly one. Two claims in one directive would count two different
+        // things in one number.
+        const structureKind = kind === "assert-structure";
+        const claims = STRUCTURE_CLAIMS.filter((claim) => attributes[claim] !== undefined);
+        if (structureKind && claims.length !== 1) {
+            return fail(claims.length === 0
+                ? '@assert-structure requires one of pattern="...", required="..." or partner="...".'
+                : `@assert-structure makes one claim per directive, got ${claims.join(" and ")}.`);
+        }
+        const subject = structureKind
+            ? claims[0]
+            : kind === "assert-layers" ? "order" : perModule ? "module" : "symbol";
         const symbol = attributes[subject] ?? "";
-        if (kind !== "assert-import-cycle" && symbol.length === 0) {
+        // A list attribute is empty when it lists nothing, whatever its length; a
+        // symbol of one space is a symbol.
+        if (kind !== "assert-import-cycle" && (structureKind ? splitList(symbol).length : symbol.length) === 0) {
             return fail(`@${kind} requires a non-empty ${subject}="..." attribute.`);
         }
         const allowEmpty = parseBoolean(attributes["allow-empty"], "allow-empty");
@@ -332,7 +347,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" || graphKind) {
+        if (kind === "assert-absence" || kind === "assert-import-absence" || graphKind || structureKind) {
             if (attributes["expected"] !== undefined &&
                 attributes["max"] !== undefined) {
                 return fail(`@${kind} accepts either expected="..." or max="...", not both.`);
@@ -371,6 +386,16 @@ export function resolveDirective(directive, context) {
                 }
             }
         }
+        if (structureKind) {
+            return resolveStructure(directive, subject, splitList(symbol), {
+                targets,
+                bounds,
+                allowEmpty,
+                baseline,
+                ratchet,
+                scope: context.scope ?? DEFAULT_SCOPE,
+            });
+        }
         if (isImportKind) {
             const scope = targets.join(", ");
             const excludeGlobs = splitList(attributes["exclude"]);
@@ -477,6 +502,90 @@ export function resolveDirective(directive, context) {
         return fail(error instanceof Error ? error.message : String(error));
     }
 }
+const STRUCTURE_CLAIMS = ["pattern", "required", "partner"];
+/** What each structure claim counts. */
+const STRUCTURE_UNITS = {
+    pattern: { one: "misnamed file", many: "misnamed files" },
+    required: { one: "directory missing an entry", many: "directories missing an entry" },
+    partner: { one: "file without a partner", many: "files without a partner" },
+};
+/**
+ * The rest of an `@assert-structure` directive, once what every rule shares is
+ * read. Throws for a directive that cannot mean what it says, which
+ * `resolveDirective` reports as the directive's error.
+ */
+function resolveStructure(directive, claim, values, shared) {
+    const { attributes } = directive;
+    const required = claim === "required";
+    const globs = splitList(attributes["glob"]);
+    const excludeGlobs = splitList(attributes["exclude"]);
+    // Two attributes that would otherwise be read and ignored, which is a rule
+    // saying something it does not check.
+    if (attributes["dirs"] !== undefined && !required) {
+        throw new Error(`Attribute "dirs" chooses the directories of required="...", and this directive claims ${claim}="...".`);
+    }
+    if (required && globs.length > 0) {
+        throw new Error(`Attribute "glob" chooses files, and required="..." is about directories; dirs="..." chooses those.`);
+    }
+    const dirs = attributes["dirs"]?.trim().replace(/^\.\//, "").replace(/\/+$/, "");
+    if (dirs === "")
+        throw new Error(`Attribute "dirs" must not be empty.`);
+    const issue = values
+        .map((value) => (required ? requiredEntryIssue(value) : claim === "partner" ? partnerTemplateIssue(value) : null))
+        .find((found) => found !== null);
+    if (issue)
+        throw new Error(issue);
+    const scope = shared.targets.join(", ");
+    const matching = globs.length > 0 ? ` matching ${globs.join(", ")}` : "";
+    const claimed = claim === "pattern"
+        ? `files in ${scope}${matching} must be named ${values.join(" or ")}`
+        : claim === "partner"
+            ? `files in ${scope}${matching} must each have a partner ${values.join(" or ")}`
+            : dirs === undefined
+                ? `${scope} must contain ${values.join(", ")}`
+                : `directories matching ${dirs} under ${scope} must contain ${values.join(", ")}`;
+    const allowance = shared.bounds.max === 0 ? "" : `, with ${describeBounds(shared.bounds, STRUCTURE_UNITS[claim])}`;
+    const except = excludeGlobs.length > 0 ? ` (excluding ${excludeGlobs.join(", ")})` : "";
+    return {
+        assertion: {
+            kind: directive.kind,
+            location: directive.location,
+            description: `${claimed}${allowance}${except}`,
+            reason: attributes["reason"],
+            targets: shared.targets,
+            files: [],
+            bounds: shared.bounds,
+            search: {
+                regex: false,
+                word: false,
+                ignoreCase: false,
+                globs,
+                excludeGlobs,
+                // Nothing is read, so there is no comment to leave out.
+                ignoreComments: false,
+                scope: shared.scope,
+                // The spec files are in scope. Every other rule leaves them out so a
+                // text rule does not find its own directive, and a structure rule reads
+                // no text - while a rule about what the ADRs are called is about them.
+                excludeFiles: new Set(),
+            },
+            structure: dirs === undefined ? { claim, values } : { claim, values, dirs },
+            missingTargets: [],
+            allowEmpty: shared.allowEmpty,
+            baseline: shared.baseline,
+            ratchet: shared.ratchet,
+        },
+    };
+}
+/**
+ * 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;
 }
@@ -496,6 +605,7 @@ async function prepareAssertion(assertion, options) {
         targets: assertion.targets,
         files: assertion.files,
         bounds: assertion.bounds,
+        claim: assertion.structure?.claim,
         warnings,
         commentMatches: 0,
         unclassifiedFiles: 0,
@@ -525,6 +635,9 @@ async function prepareAssertion(assertion, options) {
     if (assertion.imports) {
         return executeImportAssertion(assertion, options, base, warnings, startedAt);
     }
+    if (assertion.structure) {
+        return executeStructureAssertion(assertion, assertion.structure, options, base, warnings, startedAt);
+    }
     const existingTargets = [];
     for (const target of assertion.targets) {
         if (await pathExists(path.resolve(options.root, target)))
@@ -532,15 +645,15 @@ async function prepareAssertion(assertion, options) {
         else
             assertion.missingTargets.push(target);
     }
-    if (assertion.missingTargets.length > 0) {
-        warnings.push(`target path${assertion.missingTargets.length === 1 ? "" : "s"} not found: ${assertion.missingTargets.join(", ")}`);
-    }
+    const notFound = missingTargets(assertion.missingTargets);
+    if (assertion.missingTargets.length > 0)
+        warnings.push(notFound.warning);
     if (!options.allowMissingTargets && assertion.missingTargets.length > 0) {
         return {
             ...base,
             ok: false,
             actual: 0,
-            message: `target path${assertion.missingTargets.length === 1 ? " does" : "s do"} not exist: ${assertion.missingTargets.join(", ")}`,
+            message: notFound.failure,
             matches: [],
             durationMs: elapsed(startedAt),
         };
@@ -551,61 +664,138 @@ 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),
+        };
     }
+    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 };
+}
+/**
+ * What a report says about targets that are not there: a warning always, and a
+ * failure unless `--allow-missing-targets` tolerates it. One place for the
+ * words, since every kind of rule that has a target says them.
+ */
+function missingTargets(missing) {
+    const one = missing.length === 1;
     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),
-            };
-        },
+        warning: `target path${one ? "" : "s"} not found: ${missing.join(", ")}`,
+        failure: `target path${one ? " does" : "s do"} not exist: ${missing.join(", ")}`,
     };
 }
+/**
+ * Holds a structure rule to the tree, by name. ADR-0013.
+ *
+ * Four things fail before any count is read, because each is a rule that would
+ * otherwise pass without checking what it says: a missing target, a `required`
+ * target that is a file, a partner template that names the file itself, and a
+ * scope holding nothing.
+ */
+async function executeStructureAssertion(assertion, query, options, base, warnings, startedAt) {
+    const search = assertion.search;
+    const check = await checkStructure(query, {
+        targets: assertion.targets,
+        globs: search.globs,
+        excludeGlobs: search.excludeGlobs,
+        scope: search.scope,
+    }, options.tree);
+    assertion.missingTargets.push(...check.missing);
+    const notFound = missingTargets(check.missing);
+    if (check.missing.length > 0)
+        warnings.push(notFound.warning);
+    const files = check.notDirectories;
+    const self = check.selfPartner;
+    const failure = !options.allowMissingTargets && check.missing.length > 0
+        ? notFound.failure
+        : files.length > 0
+            ? `required="..." is about directories, and ${files.length === 1 ? "this target is a file" : "these targets are files"}: ${files.join(", ")}`
+            : self !== undefined
+                ? `partner template ${self.template} names ${self.file} itself, so every file would be its own partner`
+                : check.inspected === 0 && !options.allowEmptyScope && !assertion.allowEmpty
+                    ? `no ${query.claim === "required" ? "directories were selected" : "files were inspected"}, so this assertion verified nothing (${EMPTY_SCOPE_HINT})`
+                    : null;
+    const fileCounts = new Map(check.violations.map((violation) => [violation.path, 1]));
+    const { excluded, stale, shows } = applyBaseline(assertion.baseline, fileCounts);
+    const staleFailure = assertion.ratchet === "two-sided" && stale.length > 0;
+    const gaps = check.scope.skipped.length;
+    const strictFailure = options.strictTargets && gaps > 0;
+    const actual = check.violations.length - excluded;
+    return {
+        ...base,
+        ok: failure === null && satisfies(actual, assertion.bounds) && !staleFailure && !strictFailure,
+        actual,
+        message: failure ??
+            describeOutcome(assertion.bounds, actual, { excluded, stale: staleFailure ? stale : [], gaps: strictFailure ? gaps : 0 }, STRUCTURE_UNITS[query.claim]),
+        baselinedMatches: excluded,
+        staleBaseline: stale,
+        fileMatches: [...fileCounts].map(([file, count]) => ({ file, count })),
+        // No line and no column: what is wrong is the path itself.
+        matches: check.violations
+            .filter((violation) => shows(violation.path))
+            .slice(0, options.maxSnippets)
+            .map((violation) => ({ file: violation.path, line: 0, column: 0, text: violation.text, count: 1 })),
+        scope: check.scope,
+        durationMs: elapsed(startedAt),
+    };
+}
+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",
@@ -631,17 +821,28 @@ async function executeImportAssertion(assertion, options, base, warnings, starte
         else
             assertion.missingTargets.push(target);
     }
-    if (assertion.missingTargets.length > 0) {
-        warnings.push(`target path${assertion.missingTargets.length === 1 ? "" : "s"} not found: ${assertion.missingTargets.join(", ")}`);
-    }
+    const notFound = missingTargets(assertion.missingTargets);
+    if (assertion.missingTargets.length > 0)
+        warnings.push(notFound.warning);
     // 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
+        ? notFound.failure
+        : 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 +850,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 +890,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 +1090,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
@@ -956,6 +1147,7 @@ export async function runSpecGuard(options) {
         maxSnippets,
         imports: createImportIndex(),
         hasFiles: createScopeProbe(),
+        tree: createTreeIndex(root),
     };
     const results = [];
     if (options.failFast) {
@@ -1028,7 +1220,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