eval-quality 3.0.0 → 3.1.0

package/dist/gates/audit-lockfile-age.mjs

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+// Audits every registry entry in package-lock.json for supply-chain freshness.
+//
+// .npmrc's `min-release-age=7` only filters *resolution*: a young package already sitting in a
+// committed lockfile installs cleanly under `npm ci` regardless of that setting (a verified fail-open
+// in this repo's history, see ARCHITECTURE-SPINE.md#Stack). This script re-checks every locked
+// version's real registry publish timestamp and fails closed: on a young entry, on metadata that
+// could not be fetched after retries, or on an entry whose `resolved` is not the registry tarball for
+// that entry's own name and version (a relabelled lockfile entry pointing `resolved` at a mirror, or
+// at another package on the registry itself, would otherwise sail through).
+//
+// These flags are the pre-install path: `.github/actions/audit-lockfile-age`
+// runs this before `npm ci`, so nothing here may import from `node_modules`. A
+// consumer runs the same audit through `eval-quality-gates lockfile-age`, which
+// reads its lockfiles and its window out of a configuration file.
+//
+// Usage:
+//   node scripts/audit-lockfile-age.mjs [--lockfile <path>] [--window-days <n>] [--now <RFC3339>]
+//
+// --now lets a canary pin the clock to a fixed offset from a fixture entry's real publish date, so the
+// fixture never rots as real time passes. Ordinary runs omit it and audit against the real wall clock.
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+// The window this script's own flags default to. `gate-config.ts` declares the
+// same default for the configured path as `LOCKFILE_WINDOW_DAYS_DEFAULT`, and
+// `tests/architecture/published-gates.test.ts` holds the two equal. The number
+// is declared twice because this file runs before `npm ci` in CI and so may
+// import nothing from `node_modules`, where the schema that carries the other
+// one lives.
+export const WINDOW_DAYS_DEFAULT = 7;
+const CONCURRENCY = 8;
+const MAX_RETRIES = 3;
+const RETRY_BASE_MS = 300;
+const FETCH_TIMEOUT_MS = 15_000;
+const REGISTRY_PREFIX = 'https://registry.npmjs.org/';
+/**
+ * `error.code` on the refusal a caller repairs by pointing the gate at a real
+ * lockfile. `check-licenses.mjs` exports the same string and
+ * `tests/architecture/published-gates.test.ts` holds the two equal, for the
+ * reason `WINDOW_DAYS_DEFAULT` is declared twice.
+ */
+export const LOCKFILE_SHAPE_ERROR = 'EVAL_QUALITY_LOCKFILE_SHAPE';
+function refuseLockfileShape(message) {
+    const error = new Error(message);
+    error.code = LOCKFILE_SHAPE_ERROR;
+    return error;
+}
+// The one URL the public registry serves `name@version` from. A scoped name's
+// tarball basename is the segment after the slash, so `@scope/pkg` at 1.0.0 is
+// `https://registry.npmjs.org/@scope/pkg/-/pkg-1.0.0.tgz`.
+function registryTarballUrl(name, version) {
+    const basename = name.startsWith('@')
+        ? name.slice(name.indexOf('/') + 1)
+        : name;
+    return `${REGISTRY_PREFIX}${name}/-/${basename}-${version}.tgz`;
+}
+function parseArgs(argv) {
+    const args = {
+        lockfile: 'package-lock.json',
+        windowDays: WINDOW_DAYS_DEFAULT,
+        now: null,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--lockfile')
+            args.lockfile = argv[++i];
+        else if (arg === '--window-days')
+            args.windowDays = Number(argv[++i]);
+        else if (arg === '--now')
+            args.now = argv[++i];
+        else
+            throw new Error(`Unknown argument: ${arg}`);
+    }
+    return args;
+}
+// "node_modules/foo" -> "foo"; "node_modules/@scope/foo" -> "@scope/foo";
+// "node_modules/a/node_modules/@scope/b" -> "@scope/b" (nested/duplicate installs).
+function packageNameFromPath(pkgPath) {
+    const segments = pkgPath.split('node_modules/');
+    return segments[segments.length - 1].replace(/\/$/, '');
+}
+function registryUrlForName(name) {
+    const encoded = name.startsWith('@')
+        ? `${name.split('/')[0]}/${encodeURIComponent(name.split('/')[1])}`
+        : encodeURIComponent(name);
+    return `${REGISTRY_PREFIX}${encoded}`;
+}
+// A non-retryable 4xx (other than 429) means the request itself is wrong - e.g. a 404 for a name that
+// does not exist on the registry - and retrying just wastes the retry budget for no benefit. 5xx, 429,
+// and network/timeout errors are transient and worth retrying with backoff.
+class NonRetryableFetchError extends Error {
+}
+async function fetchWithRetry(url, attempts = MAX_RETRIES) {
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            const res = await fetch(url, {
+                signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            });
+            if (res.ok)
+                return await res.json();
+            if (res.status !== 429 && res.status < 500) {
+                throw new NonRetryableFetchError(`HTTP ${res.status}`);
+            }
+            throw new Error(`HTTP ${res.status}`);
+        }
+        catch (err) {
+            lastError = err;
+            if (err instanceof NonRetryableFetchError)
+                break;
+            if (attempt < attempts) {
+                await new Promise((resolve) => setTimeout(resolve, RETRY_BASE_MS * attempt));
+            }
+        }
+    }
+    throw lastError;
+}
+// One registry request per unique package NAME (not per lockfile entry): the response carries a
+// `time` map covering every published version, so every locked version of that package is checked
+// from a single fetch.
+async function fetchTimeMap(name) {
+    const meta = await fetchWithRetry(registryUrlForName(name));
+    return meta.time ?? {};
+}
+async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let cursor = 0;
+    async function worker() {
+        while (cursor < items.length) {
+            const current = cursor++;
+            results[current] = await fn(items[current], current);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}
+function collectLockedEntries(lockfile, source) {
+    // Every entry is read from `packages`, which npm writes from lockfileVersion 2 onward. Defaulting
+    // it to {} turned an npm 6 lockfile, or a path naming something that is not a lockfile at all, into
+    // a run that reported success over zero entries: a gate that scanned nothing, in the words of a
+    // gate that passed.
+    const packages = lockfile?.packages;
+    if (packages === null ||
+        typeof packages !== 'object' ||
+        Array.isArray(packages)) {
+        throw refuseLockfileShape(`audit-lockfile-age: ${source} carries no "packages" object (lockfileVersion ${JSON.stringify(lockfile?.lockfileVersion ?? null)}); every entry is read from there, so this run would have passed over nothing. npm writes "packages" from lockfileVersion 2 onward.`);
+    }
+    return Object.entries(packages)
+        .filter(([pkgPath, meta]) => pkgPath !== '' && meta.version && !meta.link)
+        .map(([pkgPath, meta]) => ({
+        path: pkgPath,
+        // meta.name (present on aliased entries, e.g. `"node_modules/foo": {"name": "bar", ...}`
+        // for an `npm:bar@x` alias) is the package actually installed. Falling back to the
+        // path-derived name would audit "foo" - a name that was never fetched - against "bar"'s
+        // lockfile version, checking the wrong package entirely.
+        name: meta.name ?? packageNameFromPath(pkgPath),
+        version: meta.version,
+        resolved: meta.resolved,
+    }));
+}
+/**
+ * `readTimeMap` is the one effect this function performs, named so a caller can
+ * supply the registry's answers itself. It defaults to the real fetch, so a
+ * caller that wants the registry gets it by saying nothing, and a case that
+ * wants a fixed answer runs offline.
+ *
+ * `source` is the path this lockfile was read from, named in the refusal a
+ * document without a `packages` object earns.
+ */
+export async function auditLockfileAge({ lockfile, now, windowDays, source = 'the lockfile', readTimeMap = fetchTimeMap, }) {
+    if (!Number.isFinite(windowDays) || windowDays < 1) {
+        throw new Error(`windowDays must be at least 1, got: ${windowDays}; a window of zero admits a package published this instant and still reports that every entry was published before the cutoff`);
+    }
+    const cutoff = new Date(now.getTime() - windowDays * 24 * 60 * 60 * 1000);
+    const entries = collectLockedEntries(lockfile, source);
+    // An entry whose `resolved` is not the registry tarball for its own name and version did not come
+    // from where an age check against npmjs.org assumes. A lockfile edit can point `resolved` at a
+    // mirror, or at another package on the registry itself, while the name and version this gate reads
+    // still name the harmless one; `npm ci` fetches `resolved` and checks `integrity` against whatever
+    // comes back, so the substituted tarball installs. Pinning the host alone left that second shape
+    // open. Fail closed on the mismatch: the age of a package the install never fetches establishes nothing.
+    const offRegistryEntries = [];
+    const registryEntries = [];
+    for (const entry of entries) {
+        if (entry.resolved === registryTarballUrl(entry.name, entry.version)) {
+            registryEntries.push(entry);
+        }
+        else {
+            offRegistryEntries.push(entry);
+        }
+    }
+    const uniqueNames = [...new Set(registryEntries.map((e) => e.name))];
+    const timeMaps = new Map();
+    const fetchFailures = new Set();
+    await mapWithConcurrency(uniqueNames, CONCURRENCY, async (name) => {
+        try {
+            timeMaps.set(name, await readTimeMap(name));
+        }
+        catch {
+            fetchFailures.add(name);
+        }
+    });
+    const youngEntries = [];
+    const unfetchableEntries = [];
+    for (const entry of registryEntries) {
+        if (fetchFailures.has(entry.name)) {
+            unfetchableEntries.push(entry);
+            continue;
+        }
+        const publishedAt = timeMaps.get(entry.name)?.[entry.version];
+        if (!publishedAt) {
+            unfetchableEntries.push(entry);
+            continue;
+        }
+        const publishedDate = new Date(publishedAt);
+        if (Number.isNaN(publishedDate.getTime())) {
+            // An unparseable timestamp must not silently compare as "not young" (Date comparisons
+            // against an Invalid Date are always false) - that would fetch metadata, find it useless,
+            // and pass anyway. Treat it the same as metadata that could not be fetched at all.
+            unfetchableEntries.push(entry);
+            continue;
+        }
+        if (publishedDate > cutoff) {
+            youngEntries.push({ ...entry, publishedAt });
+        }
+    }
+    return {
+        cutoff,
+        entries,
+        youngEntries,
+        unfetchableEntries,
+        offRegistryEntries,
+    };
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const now = args.now ? new Date(args.now) : new Date();
+    if (Number.isNaN(now.getTime())) {
+        throw new Error(`--now is not a valid RFC3339 timestamp: ${args.now}`);
+    }
+    console.log(`Effective clock: ${now.toISOString()}`);
+    const lockfile = JSON.parse(await readFile(args.lockfile, 'utf8'));
+    const { cutoff, entries, youngEntries, unfetchableEntries, offRegistryEntries, } = await auditLockfileAge({
+        lockfile,
+        now,
+        windowDays: args.windowDays,
+        source: args.lockfile,
+    });
+    if (youngEntries.length === 0 &&
+        unfetchableEntries.length === 0 &&
+        offRegistryEntries.length === 0) {
+        console.log(`Lockfile age audit passed: ${entries.length} entries, all published before ${cutoff.toISOString()}.`);
+        return;
+    }
+    if (offRegistryEntries.length > 0) {
+        console.error(`\nFailed closed: ${offRegistryEntries.length} entrie(s) do not resolve to their own registry tarball:`);
+        for (const entry of offRegistryEntries) {
+            console.error(`  - ${entry.name}@${entry.version} resolved=${JSON.stringify(entry.resolved ?? null)}, expected ${registryTarballUrl(entry.name, entry.version)} (${entry.path})`);
+        }
+    }
+    if (unfetchableEntries.length > 0) {
+        console.error(`\nFailed closed: could not fetch publish metadata for ${unfetchableEntries.length} entrie(s):`);
+        for (const entry of unfetchableEntries) {
+            console.error(`  - ${entry.name}@${entry.version} (${entry.path})`);
+        }
+    }
+    if (youngEntries.length > 0) {
+        console.error(`\nAge violation: ${youngEntries.length} entrie(s) published inside the ${args.windowDays}-day window (cutoff ${cutoff.toISOString()}):`);
+        for (const entry of youngEntries) {
+            console.error(`  - ${entry.name}@${entry.version} published ${entry.publishedAt} (${entry.path})`);
+        }
+    }
+    process.exitCode = 1;
+}
+// pathToFileURL percent-encodes the same way import.meta.url does (spaces, non-ASCII, etc.); a raw
+// `file://${process.argv[1]}` template comparison silently mismatches on such paths, so main() never
+// runs and the script exits 0 with no output: a gate switched off while looking idle.
+//
+// process.argv[1] is undefined where there is no script path at all, which is every `node -e`, every
+// `--input-type=module` evaluation, and the REPL. pathToFileURL throws ERR_INVALID_ARG_TYPE on
+// undefined, so without this guard the module cannot be imported from any of them, and it ships in
+// `dist/gates/` where a consumer does exactly that.
+const entryPoint = process.argv[1];
+if (entryPoint !== undefined &&
+    import.meta.url === pathToFileURL(entryPoint).href) {
+    main().catch((err) => {
+        // A refusal the caller repairs by pointing the gate at a real lockfile says so in one line; a
+        // stack trace for it is noise.
+        const detail = err.code === LOCKFILE_SHAPE_ERROR
+            ? err.message
+            : (err.stack ?? String(err));
+        console.error(detail);
+        process.exitCode = 1;
+    });
+}

package/dist/gates/check-dependency-direction.js

@@ -0,0 +1,303 @@
+// The dependency-direction gate: its configuration format, its refusals, and
+// the entry the gates binary calls.
+//
+// The layer graph used to live in this repository's code, as eight literal
+// prefix tests and a `switch` per source layer. Here it is the consumer's data,
+// so a repository adopting this gate declares its own trees, its own layers and
+// its own edges, and nothing of eval-quality's architecture reaches it.
+//
+// Nothing in this module reaches `typescript`. That is deliberate and load
+// bearing: the scanner needs `typescript/unstable/ast` at runtime, `typescript`
+// is an optional peer dependency, and a static import of the scanner here would
+// make a consumer without it fail at module load with a resolver stack instead
+// of the named refusal below. The scanner is reached through a dynamic import,
+// after the peer is probed.
+//
+// Run by `node` directly: Node's type stripping erases types only, so no
+// TypeScript enum, namespace, parameter property, or non-type re-export may
+// appear in this file or anything it imports, or the gate fails at load.
+import { z } from 'zod';
+import { discoverSourceFiles } from './discover-source-files.js';
+/** The gate's key in the configuration file, and the token the binary dispatches on. */
+export const DEPENDENCY_DIRECTION_GATE = 'dependency-direction';
+/**
+ * How many violations this repository's own tree reports when the two layer
+ * rows whose prefixes nest are swapped. It is stated in the schema's own
+ * description and asserted by `tests/architecture/dependency-direction.test.ts`,
+ * so the ordering property below is a measured fact rather than a warning.
+ */
+export const ORDERING_WITNESS_VIOLATIONS = 78;
+/** The optional peer is absent. The consumer repairs it by installing it, so it takes the usage code. */
+export const TYPESCRIPT_PEER_MISSING = 'EVAL_QUALITY_TYPESCRIPT_PEER_MISSING';
+/** A declared scan root could not be walked. Also a usage code: nothing was scanned, so nothing was answered. */
+export const DIRECTION_SCAN_ERROR = 'EVAL_QUALITY_DIRECTION_SCAN_ERROR';
+const NonEmpty = z.string().min(1);
+/**
+ * A repository-relative POSIX path. No leading slash, no backslash, no `.` or
+ * `..` segment: every path in this section is resolved against the directory the
+ * configuration file sits in, and a path that can climb out of it would make the
+ * declared scan roots a suggestion.
+ */
+const RelativePath = NonEmpty.refine((value) => {
+    // One trailing slash is how a prefix layer says "this directory"; everything
+    // else about the shape is refused.
+    const body = value.endsWith('/') ? value.slice(0, -1) : value;
+    return (body.length > 0 &&
+        !body.startsWith('/') &&
+        !body.includes('\\') &&
+        !body
+            .split('/')
+            .some((part) => part === '.' || part === '..' || part === ''));
+}, 'is not a repository-relative POSIX path: a leading slash, a backslash, an empty segment, and a "." or ".." segment are all refused');
+const Extension = NonEmpty.regex(/^\.[A-Za-z0-9]+$/, 'is not a file extension: write it with its leading dot, as ".ts" or ".cjs"');
+const LayerName = NonEmpty.regex(/^[a-z][a-z0-9-]*$/, 'is not a layer name: lowercase letters, digits and hyphens, starting with a letter');
+const ScanRoot = z
+    .strictObject({
+    path: RelativePath.describe('A directory to walk, repository-relative. Its whole subtree is scanned.'),
+    extensions: z
+        .array(Extension)
+        .min(1)
+        .default(['.ts'])
+        .describe('Which files under this root are read. A root is a directory plus its extensions rather than a glob, so "every .cjs file under src/" is one root and needs no glob language to say.'),
+})
+    .describe('One tree to scan, and the file extensions to read inside it.');
+const Unrestricted = z.strictObject({ policy: z.literal('unrestricted') });
+const DenyExternals = z.strictObject({
+    policy: z.literal('deny'),
+    rule: NonEmpty.describe('What a reader is told when this layer imports an external module. Your sentence, printed verbatim: the reason a layer holds no external dependency belongs to your architecture.'),
+});
+const AllowExternals = z.strictObject({
+    policy: z.literal('allow'),
+    modules: z
+        .array(NonEmpty)
+        .min(1)
+        .describe('The specifiers this layer may import, matched by exact string equality. "zod" admits "zod" and refuses "zod/v4" and "zod-to-json-schema", so a subpath is a separate entry you write out.'),
+    rule: NonEmpty.describe('What a reader is told when this layer imports something outside that list. Printed verbatim.'),
+});
+const ExternalPolicy = z
+    .discriminatedUnion('policy', [Unrestricted, DenyExternals, AllowExternals])
+    .describe('What this layer may reach outside the scanned trees. "unrestricted" admits everything and is the default. "deny" refuses every external module and runtime builtin. "allow" admits the listed specifiers and no others.');
+const LayerRule = z
+    .strictObject({
+    name: LayerName.describe('How the other layers name this one in their "imports" lists.'),
+    match: z
+        .enum(['exact', 'prefix'])
+        .describe('"exact" matches one file by its whole path. "prefix" matches every file under a directory, and its path ends with "/".'),
+    path: RelativePath.describe('The path this layer matches: a file path for "exact", a directory path ending in "/" for "prefix".'),
+    label: NonEmpty.optional().describe('How this layer is named in a violation line. Defaults to the layer name.'),
+    imports: z
+        .array(LayerName)
+        .describe('Every layer this one may import, named in full. Name this layer here when it may import itself: an implicit self-edge would be a permission nobody wrote down and nobody can find. An unlisted layer is denied.'),
+    externals: ExternalPolicy.default({ policy: 'unrestricted' }),
+})
+    .describe('One layer: what it matches, what it may import, what it may reach outside.');
+const ImportExemption = z
+    .strictObject({
+    file: RelativePath.describe('The one file the exemption covers.'),
+    module: NonEmpty.describe('The external specifier that file may reach, by exact string equality.'),
+    binding: NonEmpty.regex(/^[A-Za-z_$][A-Za-z0-9_$]*$/, 'is not an identifier').describe('The single named binding the import clause may carry. `{ binding }` and `{ binding as other }` are the whole clause; a default or namespace binding beside it pulls in the rest of the module and is not the exemption.'),
+    rule: NonEmpty.describe('What a reader is told when that file reaches that module any other way. It is its own sentence, so a narrow exemption reads as a narrow exemption in the report.'),
+})
+    .describe('One file, one external module, one named binding. The exemption reaches a static import declaration and nothing else: a re-export and a dynamic import of the same module are refused, because neither can be held to a binding list.');
+const PurityScope = z
+    .strictObject({
+    layers: z
+        .array(LayerName)
+        .min(1)
+        .describe('The layers held to the bans below.'),
+    awaitRule: NonEmpty.describe('What a reader is told when an await appears in a purity-scoped layer.'),
+    asyncFunctionRule: NonEmpty.describe('What a reader is told when an async function appears in a purity-scoped layer.'),
+    newDateRule: NonEmpty.describe('What a reader is told when `new Date` appears in a purity-scoped layer.'),
+    members: z
+        .array(z.strictObject({
+        member: NonEmpty.regex(/^[A-Za-z_$][A-Za-z0-9_$]*\.[A-Za-z_$][A-Za-z0-9_$]*$/, 'is not an `object.member` pair').describe('The ambient read, as `object.member`.'),
+        rule: NonEmpty.describe('What a reader is told when it appears.'),
+    }))
+        .default([])
+        .describe('Ambient reads banned in these layers. A global such as `crypto` or `performance` needs no import, so no import rule can see it and only this table can.'),
+})
+    .describe('Layers that must stay pure. `await`, an async function, `new Date`, and each listed ambient read are refused inside them.');
+/**
+ * The section a consumer writes. Exported for `gate-config.ts` to compose into
+ * the whole document, and for `check-doc-claims.ts` to parse the documented
+ * example through.
+ */
+export const DependencyDirectionSection = z
+    .strictObject({
+    roots: z
+        .array(ScanRoot)
+        .min(1)
+        .describe('The trees this gate walks. Nothing outside them is read.'),
+    layers: z
+        .array(LayerRule)
+        .min(1)
+        .describe('THE LAYERS ARE AN ORDERED LIST AND THE FIRST MATCH WINS. Narrower prefixes are listed before the wider ones that contain them, because every file under "src/core/schemas/" also sits under "src/core/" and only the order decides which rules it is held to. In this repository\'s own configuration, swapping those two rows reports ' +
+        String(ORDERING_WITNESS_VIOLATIONS) +
+        ' violations where there are none today. This is a list rather than an object keyed by layer name for that reason alone: a map has no order, and normalising this into one, or sorting it, silently rewrites the graph it describes. A layer that a row before it already matches in full is refused here, so the mistake is a configuration error rather than a quiet re-layering.'),
+    exemptions: z
+        .array(ImportExemption)
+        .default([])
+        .describe("Per-file holes in a layer's external policy, each naming the one module and the one binding it opens."),
+    purity: PurityScope.optional().describe('Absent means no layer is held to the purity bans.'),
+    commonjs: z
+        .enum(['forbid', 'check'])
+        .default('forbid')
+        .describe('"forbid" refuses `require()` and `import x = require()` outright, which is what an ESM-only tree wants. "check" reads a literal `require()` specifier as an edge and holds it to the same layer rules, which is what a tree with CommonJS files needs: the alternative of ignoring them would scan a .cjs tree, find no import statement in it, and report a clean pass over a file it never read an edge from.'),
+    reportOnly: z
+        .boolean()
+        .default(false)
+        .describe('true prints the violations and exits 0. It is declared here rather than passed as a flag so that "we are still counting" is a committed line a reviewer sees and a one-line diff turns off, instead of an invocation detail nobody reading the repository can find. The run still prints its count, including zero, and still fails at 64 when a declared root yielded no files, so a green report-only run can never mean the gate scanned nothing.'),
+})
+    .superRefine((section, ctx) => {
+    const issue = (path, message) => {
+        ctx.addIssue({ code: 'custom', path, message });
+    };
+    // A root inside another root would read every file under the inner one
+    // twice, once under each root's extension list, and report every violation
+    // in it twice.
+    section.roots.forEach((root, index) => {
+        section.roots.forEach((other, otherIndex) => {
+            if (index === otherIndex)
+                return;
+            if (`${root.path}/`.startsWith(`${other.path}/`)) {
+                issue(['roots', index, 'path'], `"${root.path}" sits inside the root "${other.path}"; declare the outer root once and list every extension it reads`);
+            }
+        });
+    });
+    const underARoot = (path) => section.roots.some((root) => path === root.path || path.startsWith(`${root.path}/`));
+    const names = new Set();
+    section.layers.forEach((layer, index) => {
+        if (names.has(layer.name)) {
+            issue(['layers', index, 'name'], `"${layer.name}" is declared twice`);
+        }
+        names.add(layer.name);
+        if (layer.match === 'prefix' && !layer.path.endsWith('/')) {
+            issue(['layers', index, 'path'], `"${layer.path}" is a prefix match and has to end with "/", so that a layer at "src/core/" never claims "src/core-experimental/x.ts"`);
+        }
+        if (layer.match === 'exact' && layer.path.endsWith('/')) {
+            issue(['layers', index, 'path'], `"${layer.path}" is an exact match on one file and may not end with "/"`);
+        }
+        if (!underARoot(layer.path.replace(/\/$/, ''))) {
+            issue(['layers', index, 'path'], `"${layer.path}" sits under none of the declared roots, so it can never match a scanned file`);
+        }
+        // The ordering property, enforced rather than documented: a row whose
+        // every match is already claimed by an earlier row never fires, and the
+        // files it was written for are silently held to the earlier row's rules.
+        section.layers.slice(0, index).forEach((earlier, earlierIndex) => {
+            if (earlier.match !== 'prefix')
+                return;
+            if (!layer.path.startsWith(earlier.path))
+                return;
+            issue(['layers', index, 'path'], `"${layer.path}" is unreachable: layers[${earlierIndex}] "${earlier.name}" matches "${earlier.path}" and every path under it, and it is listed first. Move "${layer.name}" above it.`);
+        });
+    });
+    section.layers.forEach((layer, index) => {
+        layer.imports.forEach((target, position) => {
+            if (names.has(target))
+                return;
+            issue(['layers', index, 'imports', position], `names "${target}", which is not a declared layer: ${[...names].join(', ')}`);
+        });
+    });
+    // A layer is matched by walking the list in order, which is what makes an
+    // exemption on an unrestricted layer dead configuration rather than a
+    // harmless extra: that layer already admits every module.
+    section.exemptions.forEach((exemption, index) => {
+        const layer = section.layers.find((candidate) => candidate.match === 'exact'
+            ? candidate.path === exemption.file
+            : exemption.file.startsWith(candidate.path));
+        if (layer === undefined) {
+            issue(['exemptions', index, 'file'], `"${exemption.file}" matches no declared layer, so nothing holds it and the exemption opens nothing`);
+            return;
+        }
+        if (layer.externals.policy === 'unrestricted') {
+            issue(['exemptions', index, 'file'], `"${exemption.file}" sits in the layer "${layer.name}", whose externals are unrestricted, so this exemption grants what that layer already allows`);
+        }
+    });
+    section.purity?.layers.forEach((name, position) => {
+        if (names.has(name))
+            return;
+        issue(['purity', 'layers', position], `names "${name}", which is not a declared layer: ${[...names].join(', ')}`);
+    });
+})
+    .describe('Holds every import, re-export, dynamic import and triple-slash reference directive in the trees you declare against a layer graph you declare, and holds your pure layers to a ban on await, async functions, `new Date`, and the ambient reads you list.');
+const refuse = (code, message) => ({
+    kind: 'refused',
+    code,
+    message,
+});
+/**
+ * The scanner needs `typescript/unstable/ast`, and `typescript` is an optional
+ * peer dependency so that a consumer running the other gates installs nothing.
+ * Probing it by name is what turns a resolver stack trace into a sentence naming
+ * the dependency and the gate that wanted it.
+ *
+ * `load` is injectable so a test can exercise the refusal without uninstalling
+ * the package the test runner itself needs.
+ */
+export async function probeTypeScript(load = () => import('typescript/unstable/ast')) {
+    try {
+        await load();
+        return { ok: true };
+    }
+    catch (error) {
+        if (error.code !== 'ERR_MODULE_NOT_FOUND') {
+            throw error;
+        }
+        return {
+            ok: false,
+            message: `the ${DEPENDENCY_DIRECTION_GATE} gate reads your source with the TypeScript scanner, and the optional peer dependency "typescript" is not installed here. Install it (npm install --save-dev typescript), or drop the "${DEPENDENCY_DIRECTION_GATE}" section from your configuration to stop invoking this gate. No other gate needs it.`,
+        };
+    }
+}
+const orderViolations = (violations) => [...violations].sort((a, b) => a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1);
+/**
+ * Runs the gate and returns what to print and what to exit with. It writes to no
+ * stream: the binary owns every write, and `summary` is the one line it always
+ * writes, so no outcome of this gate can be silent.
+ */
+export async function runDependencyDirection(options) {
+    const { section, root, configPath } = options;
+    const peer = await probeTypeScript();
+    if (!peer.ok)
+        return refuse(TYPESCRIPT_PEER_MISSING, peer.message);
+    const { compileGraph, scanSources } = await import('./dependency-direction.js');
+    let files;
+    try {
+        files = await discoverSourceFiles(root, section.roots);
+    }
+    catch (error) {
+        return refuse(DIRECTION_SCAN_ERROR, `${DEPENDENCY_DIRECTION_GATE}: ${error instanceof Error ? error.message : String(error)}; ${configPath}'s "${DEPENDENCY_DIRECTION_GATE}" section declares the roots`);
+    }
+    let graph;
+    try {
+        graph = compileGraph(section);
+    }
+    catch (error) {
+        return refuse(DIRECTION_SCAN_ERROR, `${configPath}'s "${DEPENDENCY_DIRECTION_GATE}" section could not be compiled into a layer graph: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const violations = orderViolations(scanSources(files, graph));
+    const lines = violations.map((violation) => `  ${violation.file}:${violation.line} "${violation.specifier}": ${violation.rule}`);
+    const scope = `${violations.length} violation(s) across ${files.size} scanned file(s)`;
+    if (section.reportOnly) {
+        return {
+            kind: 'report',
+            reportOnly: true,
+            failed: false,
+            scannedFiles: files.size,
+            violations,
+            summary: `${DEPENDENCY_DIRECTION_GATE}: report-only, ${scope}; this run did not fail. Set "reportOnly": false in ${configPath} to make it.`,
+            lines,
+        };
+    }
+    return {
+        kind: 'report',
+        reportOnly: false,
+        failed: violations.length > 0,
+        scannedFiles: files.size,
+        violations,
+        summary: violations.length === 0
+            ? `${DEPENDENCY_DIRECTION_GATE}: passed, ${files.size} file(s) scanned across ${section.roots.length} root(s), 0 violations.`
+            : `${DEPENDENCY_DIRECTION_GATE}: ${scope}:`,
+        lines,
+    };
+}