@descent-vtt/spec-guard 0.7.0 → 0.9.0

package/dist/runner.js

@@ -5,15 +5,16 @@
  * number, an unknown boolean or a path escaping the root is an error, never a
  * silently-passing assertion. A spec that lies is worse than no spec at all.
  */
-import { promises as fs } from "node:fs";
 import path from "node:path";
 import { comparePaths, createCachedEngine, enumerateCandidates, passKey, resolveEngine, runSearches, ANY_FILE_PROBE, ROOT_TARGETS, } from "./engine.js";
 import { createExcludeMatcher, toPosix } from "./glob.js";
+import { nodeIo } from "./io.js";
 import { buildGraph, cyclicComponents, edgeKey, isGraphFile, witness, } from "./graph.js";
 import { ANALYSABLE_EXTENSIONS, createImportIndex, resolveModule, } from "./imports.js";
 import { checkLayers } from "./layers.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;
 /**
@@ -242,7 +243,7 @@ export function applyBaseline(entries, fileCounts) {
  * answer. Without the cache the probe measured about 0.9 ms per assertion,
  * which is small until a spec has two hundred of them.
  */
-export function createScopeProbe() {
+export function createScopeProbe(io = nodeIo) {
     const cache = new Map();
     return (request) => {
         const key = JSON.stringify([
@@ -255,7 +256,7 @@ export function createScopeProbe() {
         if (!pending) {
             // The walk abandons at the first file it finds, so proving a scope is
             // populated costs a couple of directory reads rather than a traversal.
-            pending = enumerateCandidates(request, ANY_FILE_PROBE).then((enumeration) => enumeration.files.length > 0);
+            pending = enumerateCandidates(request, ANY_FILE_PROBE, io).then((enumeration) => enumeration.files.length > 0);
             cache.set(key, pending);
         }
         return pending;
@@ -294,7 +295,6 @@ export function resolveDirective(directive, context) {
                     targets: [],
                     files,
                     bounds: { min: files.length, max: files.length },
-                    missingTargets: [],
                     // A file list is never empty here: resolution rejects that above.
                     allowEmpty: true,
                     baseline: [],
@@ -307,9 +307,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 +346,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 +385,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"]);
@@ -423,7 +447,6 @@ export function resolveDirective(directive, context) {
                     },
                     imports: { modules: perModule ? splitList(symbol) : [], includeTypes },
                     ...(kind === "assert-layers" ? { layers } : {}),
-                    missingTargets: [],
                     allowEmpty,
                     baseline,
                     ratchet,
@@ -466,7 +489,6 @@ export function resolveDirective(directive, context) {
                 files: [],
                 bounds,
                 search,
-                missingTargets: [],
                 allowEmpty,
                 baseline,
                 ratchet,
@@ -477,6 +499,80 @@ 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 },
+            allowEmpty: shared.allowEmpty,
+            baseline: shared.baseline,
+            ratchet: shared.ratchet,
+        },
+    };
+}
 /**
  * The spec files a search must not count, as absolute paths.
  *
@@ -486,8 +582,23 @@ export function resolveDirective(directive, context) {
 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;
+async function pathExists(io, candidate) {
+    return (await io.stat(candidate)) !== null;
+}
+/**
+ * The targets that exist and the ones that do not, in the order written.
+ *
+ * Returned rather than recorded on the assertion, which is what execution used
+ * to do: the second execution of a rule then named each missing target twice.
+ * A watch session executes its rules again and again (ADR-0014).
+ */
+async function partitionTargets(targets, options) {
+    const existing = [];
+    const missing = [];
+    for (const target of targets) {
+        (await pathExists(options.io, path.resolve(options.root, target)) ? existing : missing).push(target);
+    }
+    return { existing, missing };
 }
 /**
  * Resolves everything about an assertion that does not need a search, and
@@ -505,6 +616,7 @@ async function prepareAssertion(assertion, options) {
         targets: assertion.targets,
         files: assertion.files,
         bounds: assertion.bounds,
+        claim: assertion.structure?.claim,
         warnings,
         commentMatches: 0,
         unclassifiedFiles: 0,
@@ -516,7 +628,7 @@ async function prepareAssertion(assertion, options) {
     if (assertion.kind === "assert-present") {
         const missing = [];
         for (const file of assertion.files) {
-            if (!(await pathExists(path.resolve(options.root, file))))
+            if (!(await pathExists(options.io, path.resolve(options.root, file))))
                 missing.push(file);
         }
         const actual = assertion.files.length - missing.length;
@@ -534,22 +646,19 @@ async function prepareAssertion(assertion, options) {
     if (assertion.imports) {
         return executeImportAssertion(assertion, options, base, warnings, startedAt);
     }
-    const existingTargets = [];
-    for (const target of assertion.targets) {
-        if (await pathExists(path.resolve(options.root, target)))
-            existingTargets.push(target);
-        else
-            assertion.missingTargets.push(target);
+    if (assertion.structure) {
+        return executeStructureAssertion(assertion, assertion.structure, options, base, warnings, startedAt);
     }
-    if (assertion.missingTargets.length > 0) {
-        warnings.push(`target path${assertion.missingTargets.length === 1 ? "" : "s"} not found: ${assertion.missingTargets.join(", ")}`);
-    }
-    if (!options.allowMissingTargets && assertion.missingTargets.length > 0) {
+    const { existing: existingTargets, missing } = await partitionTargets(assertion.targets, options);
+    const notFound = missingTargets(missing);
+    if (missing.length > 0)
+        warnings.push(notFound.warning);
+    if (!options.allowMissingTargets && missing.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),
         };
@@ -617,6 +726,72 @@ async function prepareAssertion(assertion, options) {
     };
     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 {
+        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);
+    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,
@@ -643,16 +818,10 @@ const IMPORT_VERBS = {
  */
 async function executeImportAssertion(assertion, options, base, warnings, startedAt) {
     const query = assertion.imports;
-    const existingTargets = [];
-    for (const target of assertion.targets) {
-        if (await pathExists(path.resolve(options.root, target)))
-            existingTargets.push(target);
-        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 { existing: existingTargets, missing: absent } = await partitionTargets(assertion.targets, options);
+    const notFound = missingTargets(absent);
+    if (absent.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.
@@ -665,12 +834,12 @@ async function executeImportAssertion(assertion, options, base, warnings, starte
             root: options.root,
             targets: existingTargets,
             options: assertion.search,
-        });
+        }, undefined, options.io);
     // 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(", ")}`
+    const missing = !options.allowMissingTargets && absent.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
@@ -910,18 +1079,15 @@ export async function executeAssertion(assertion, options) {
 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) {
-    const startedAt = performance.now();
-    const root = path.resolve(options.root ?? process.cwd());
-    const maxSnippets = options.maxSnippets ?? DEFAULT_MAX_SNIPPETS;
-    const strictTargets = options.strictTargets ?? false;
-    const allowMissingTargets = options.allowMissingTargets ?? false;
-    const allowEmptyScope = options.allowEmptyScope ?? false;
+/**
+ * Resolves what a set of specs asks for, reading nothing.
+ *
+ * The first half of `runSpecGuard`, moved out so that a watch session plans
+ * each run the way a run does rather than by a copy of it (ADR-0014).
+ */
+export function planRun(specs, root, options) {
     const scope = createScope(options.defaultSkips ?? true);
-    const specs = await readSpecs(options.patterns, root);
-    const specFiles = specs.files;
-    const excludeFiles = specExclusions(specFiles, options.includeSpecs ?? false);
+    const excludeFiles = specExclusions(specs.files, options.includeSpecs ?? false);
     const directives = [];
     /** Parsed, validated, and then not run: see ADR-0010. */
     const withheld = [];
@@ -966,16 +1132,59 @@ export async function runSpecGuard(options) {
         if ("error" in resolved)
             errors.push(resolved.error);
     }
+    return { root, specFiles: specs.files, assertions, withheld: withheld.length, errors, inactiveSpecs };
+}
+/**
+ * A run's report, from its plan and the results of the rules it executed.
+ *
+ * The last part of `runSpecGuard`, shared with a watch session for the same
+ * reason as `planRun`.
+ */
+export function reportRun(plan, results, engine, startedAt) {
+    const warnings = engine.fallbacks.map((message) => `ripgrep failed, fell back to the JavaScript engine (${message})`);
+    // Errors arrive in two waves (parse, then resolve); readers expect file order.
+    const errors = [...plan.errors].sort((a, b) => a.location.relativeFile === b.location.relativeFile
+        ? a.location.line - b.location.line
+        : comparePaths(a.location.relativeFile, b.location.relativeFile));
+    const failed = results.filter((result) => !result.ok).length;
+    return {
+        ok: failed === 0 && errors.length === 0,
+        root: plan.root,
+        engine: warnings.length > 0 ? "javascript" : engine.name,
+        durationMs: elapsed(startedAt),
+        summary: {
+            specs: plan.specFiles.length,
+            total: results.length,
+            passed: results.length - failed,
+            failed,
+            skipped: plan.assertions.length - results.length,
+            inactive: plan.withheld,
+        },
+        results,
+        errors,
+        warnings,
+        inactiveSpecs: plan.inactiveSpecs,
+        specFiles: plan.specFiles.map((file) => specPath(plan.root, file)),
+    };
+}
+/** Reads, parses and executes every directive found in the given spec files. */
+export async function runSpecGuard(options) {
+    const startedAt = performance.now();
+    const root = path.resolve(options.root ?? process.cwd());
+    const plan = planRun(await readSpecs(options.patterns, root), root, options);
+    const assertions = plan.assertions;
     const engine = createCachedEngine(await resolveEngine(options.engine ?? "auto"));
     const executeOptions = {
         root,
+        io: nodeIo,
         engine,
-        allowMissingTargets,
-        strictTargets,
-        allowEmptyScope,
-        maxSnippets,
+        allowMissingTargets: options.allowMissingTargets ?? false,
+        strictTargets: options.strictTargets ?? false,
+        allowEmptyScope: options.allowEmptyScope ?? false,
+        maxSnippets: options.maxSnippets ?? DEFAULT_MAX_SNIPPETS,
         imports: createImportIndex(),
         hasFiles: createScopeProbe(),
+        tree: createTreeIndex(root),
     };
     const results = [];
     if (options.failFast) {
@@ -1025,30 +1234,6 @@ export async function runSpecGuard(options) {
         };
         await Promise.all(Array.from({ length: concurrency }, worker));
     }
-    const warnings = engine.fallbacks.map((message) => `ripgrep failed, fell back to the JavaScript engine (${message})`);
-    // 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
-        : 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: 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) => specPath(root, file)),
-    };
+    return reportRun(plan, results, engine, startedAt);
 }
 //# sourceMappingURL=runner.js.map