eval-quality 2.0.0 → 3.1.0

package/dist/gates/gate-config.js

@@ -0,0 +1,251 @@
+// The configuration a consumer writes for the gates it has chosen to run, and
+// the loader every published gate reads it through.
+//
+// One JSON file in the consumer's repository, `eval-quality.config.json` at the
+// repository root by default and any path `--config` names. The top level is an
+// object keyed by gate name, and it carries only the gates the consumer has
+// chosen to run: configuring a gate is what opts into it, so a repository
+// adopting one gate never reads, writes, or understands the others. That is the
+// format's own property and the schema's own description states it.
+//
+// A gate invoked with no configuration for it refuses by name. There is no
+// fallback to this package's own values, which sit in this repository's own
+// `eval-quality.config.json` like anyone else's. `check-doc-invocations.mjs` and
+// `audit-lockfile-age.mjs` set the register: fail closed on an absent or
+// malformed value, and say what was expected.
+//
+// The loader reads and rewrites nothing. It validates one named section per
+// call, so a malformed section for a gate the caller is not running never blocks
+// the gate it is running.
+//
+// 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 { readFile } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+import { z } from 'zod';
+import { DependencyDirectionSection } from './check-dependency-direction.js';
+import { FieldOwnershipSection } from './lineage-ownership.js';
+import { PackageBoundarySection } from './package-boundary.js';
+/** The file a consumer writes, resolved against the directory the gate runs in. */
+export const DEFAULT_CONFIG_FILE = 'eval-quality.config.json';
+/**
+ * The gates this build publishes, in the order the usage text lists them.
+ *
+ * Three of the five keep their schema in the gate module rather than here, so
+ * that a module reachable only after `typescript` has been probed still declares
+ * its own section. Importing those schemas is safe on any load path: each of the
+ * three reaches `typescript` through a dynamic import and nothing else.
+ */
+export const GATE_NAMES = [
+    'lockfile-age',
+    'licences',
+    'dependency-direction',
+    'package-boundary',
+    'field-ownership',
+];
+/**
+ * The audit window when a configuration names none, in days.
+ *
+ * A duration and not a date, which is what keeps it out of the class of settings
+ * a hand maintains: a cutoff date goes stale the day after it is written and a
+ * window never does. It matches `.npmrc`'s `min-release-age`, which filters
+ * resolution and fails open on a lockfile already carrying a young entry; this
+ * audit is what closes that.
+ */
+export const LOCKFILE_WINDOW_DAYS_DEFAULT = 7;
+const NonEmpty = z.string().min(1);
+/**
+ * An SPDX short identifier, for the allowlist and for a tolerance's one added
+ * identifier. The charset admits `MIT`, `Apache-2.0`, `0BSD` and
+ * `LGPL-3.0-or-later`, and refuses `@` and `/`, so a `name@version` pin cannot
+ * be written here. Both settings name a licence; a version pin would be a value
+ * a hand maintains in step with the dependency graph.
+ */
+const SpdxIdentifier = NonEmpty.regex(/^[A-Za-z0-9][A-Za-z0-9.+-]*$/, 'is not an SPDX short identifier: this setting takes identifiers such as MIT or Apache-2.0, and a package-and-version pin is not one');
+const LockfileAgeSection = z
+    .strictObject({
+    lockfiles: z
+        .array(NonEmpty)
+        .min(1)
+        .describe('Every lockfile to audit, repository-relative. One invocation covers all of them.'),
+    windowDays: z
+        .int()
+        .min(1)
+        .default(LOCKFILE_WINDOW_DAYS_DEFAULT)
+        .describe('How old an entry has to be, in days, and at least 1. A duration, so nothing here goes stale as time passes. Zero puts the cutoff at the instant of the run, admits a package published that same instant, and still reports that every entry was published before the cutoff.'),
+})
+    .describe("Fails on a locked entry published inside the window, on metadata that could not be fetched, and on an entry whose resolved URL is not that entry's own tarball on the npm registry.");
+/**
+ * The per-lockfile split, keyed by lockfile path. `also` extends the top-level
+ * allowlist instead of restating it, so the two lists cannot drift apart: there
+ * is one allowlist and one delta.
+ */
+const LicencePolicy = z.strictObject({
+    label: NonEmpty.describe('What a reader of CI output sees beside the result, so two policies can never be confused.'),
+    reason: NonEmpty.describe('Why this lockfile may allow more than the others. A policy that widens the allowlist says so in the file that widens it.'),
+    also: z
+        .array(SpdxIdentifier)
+        .min(1)
+        .describe('Identifiers this lockfile allows on top of the allowlist.'),
+});
+/**
+ * A scoped exception: a family of packages named by prefix, the one identifier
+ * the allowlist gains inside that family, and the condition under which the
+ * exception holds at all. It is narrower than an allowlist entry, which applies
+ * to every package in the lockfile and carries no condition.
+ */
+const LicenceTolerance = z.strictObject({
+    reason: NonEmpty.describe('Why the exception is sound. It is printed on every run that uses it.'),
+    lockfiles: z
+        .array(NonEmpty)
+        .min(1)
+        .describe('The lockfiles this exception applies to, and no others.'),
+    prefix: NonEmpty.describe('The package-name prefix the exception covers. A prefix, so no version is pinned here.'),
+    license: SpdxIdentifier.describe('The one identifier this exception adds to the allowlist, for this family of packages alone. The expression is then read by the rule every other entry is read by, so an AND still needs every operand covered and a WITH compound still has to be listed exactly.'),
+    optional: z
+        .boolean()
+        .default(true)
+        .describe('Whether the exception is limited to entries npm recorded as optional.'),
+    marker: z
+        .strictObject({ file: NonEmpty, contains: NonEmpty })
+        .optional()
+        .describe('The exception holds only while this file carries this text. An absent or unreadable file withdraws it.'),
+});
+const LicencesSection = z
+    .strictObject({
+    lockfiles: z
+        .array(NonEmpty)
+        .min(1)
+        .describe('Every lockfile to scan, repository-relative. One invocation covers all of them.'),
+    allowlist: z
+        .array(SpdxIdentifier)
+        .min(1)
+        .describe('The identifiers every entry is held against. Required: an absent allowlist would either fail everything or silently permit everything, and this gate does neither.'),
+    policies: z
+        .record(NonEmpty, LicencePolicy)
+        .optional()
+        .describe('Per-lockfile additions, keyed by lockfile path. A lockfile with no entry here is held against the allowlist alone.'),
+    tolerances: z
+        .array(LicenceTolerance)
+        .optional()
+        .describe('Scoped exceptions, each carrying its own reason.'),
+})
+    // `policies` is keyed by lockfile path and every tolerance names the lockfiles
+    // it applies to, both by the same string `lockfiles` names them by. A value
+    // matching no declared lockfile loads clean and applies to nothing, so a typo
+    // like "pacakge-lock.json" reads as a policy that was written and never runs.
+    // Keeping those three lists in step by hand is the class of setting this format
+    // does not have, so a name matching nothing is refused here.
+    .superRefine((section, ctx) => {
+    const declared = new Set(section.lockfiles);
+    const requireDeclared = (named, path) => {
+        if (declared.has(named))
+            return;
+        ctx.addIssue({
+            code: 'custom',
+            path,
+            message: `names "${named}", which is not one of the lockfiles this section declares: ${section.lockfiles.join(', ')}`,
+        });
+    };
+    for (const key of Object.keys(section.policies ?? {})) {
+        requireDeclared(key, ['policies', key]);
+    }
+    section.tolerances?.forEach((tolerance, index) => {
+        tolerance.lockfiles.forEach((named, position) => {
+            requireDeclared(named, ['tolerances', index, 'lockfiles', position]);
+        });
+    });
+})
+    .describe("Holds every locked entry's licence expression against an allowlist of SPDX identifiers, and fails on an entry whose resolved URL is not that entry's own tarball on the npm registry.");
+/**
+ * The whole document, as one schema. It is where the format states its own
+ * incremental-adoption property, and its one consumer is `check-doc-claims.ts`,
+ * which parses the documented example through it so the page a consumer copies
+ * is held to the format it describes.
+ *
+ * The loader never uses it. Validating the document whole would block a gate
+ * the caller is running on a gate it is not, which is the opposite of the
+ * property this object describes.
+ */
+export const GateConfiguration = z
+    .object({
+    'lockfile-age': LockfileAgeSection.optional(),
+    licences: LicencesSection.optional(),
+    'dependency-direction': DependencyDirectionSection.optional(),
+    'package-boundary': PackageBoundarySection.optional(),
+    'field-ownership': FieldOwnershipSection.optional(),
+})
+    .describe("The gates this repository has chosen to run, keyed by gate name. Incremental adoption is structural: the file carries only the gates you have adopted, and configuring a gate is what opts into it. A gate you invoke with no section here refuses by name; it falls back to nobody else's values.");
+const refuse = (message) => ({
+    kind: 'refused',
+    message,
+});
+/** Which other gates the file does configure, so a refusal says what is there. */
+const otherGates = (gate, document) => {
+    const present = GATE_NAMES.filter((name) => name !== gate && document[name] !== undefined);
+    return present.length === 0
+        ? 'it configures no gate at all'
+        : `it configures ${present.join(', ')}`;
+};
+const renderIssues = (error) => error.issues
+    .map((issue) => {
+    const at = issue.path.length === 0 ? '(the section itself)' : issue.path.join('.');
+    return `  ${at}: ${issue.message}`;
+})
+    .join('\n');
+/**
+ * Four refusals, each its own because the repair is different: the file is not
+ * there, the file is not JSON, the file configures some other gate, and the
+ * section is there and wrong. Every one names the file and the gate.
+ */
+async function findSection(gate, options) {
+    const cwd = options.cwd ?? process.cwd();
+    const named = options.configPath ?? DEFAULT_CONFIG_FILE;
+    const path = isAbsolute(named) ? named : resolve(cwd, named);
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return refuse(`${path} does not exist, and the ${gate} gate is configured there; write the file, or name another with --config <path>`);
+        }
+        return refuse(`${path} could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        return refuse(`${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return refuse(`${path} is not a JSON object; the top level is an object keyed by gate name, and the ${gate} gate reads its "${gate}" key`);
+    }
+    const document = parsed;
+    const section = document[gate];
+    if (section === undefined) {
+        return refuse(`${path} declares no "${gate}" section, and ${otherGates(gate, document)}; configuring a gate is what opts into it, so add a "${gate}" object to run this one`);
+    }
+    return { kind: 'found', path, raw: section };
+}
+async function loadSection(gate, schema, options) {
+    const found = await findSection(gate, options);
+    if (found.kind === 'refused')
+        return found;
+    const result = schema.safeParse(found.raw);
+    if (!result.success) {
+        return refuse(`${found.path}'s "${gate}" section is malformed:\n${renderIssues(result.error)}`);
+    }
+    return {
+        kind: 'section',
+        path: found.path,
+        section: result.data,
+    };
+}
+export const loadLockfileAgeConfig = (options = {}) => loadSection('lockfile-age', LockfileAgeSection, options);
+export const loadLicencesConfig = (options = {}) => loadSection('licences', LicencesSection, options);
+export const loadDependencyDirectionConfig = (options = {}) => loadSection('dependency-direction', DependencyDirectionSection, options);
+export const loadPackageBoundaryConfig = (options = {}) => loadSection('package-boundary', PackageBoundarySection, options);
+export const loadFieldOwnershipConfig = (options = {}) => loadSection('field-ownership', FieldOwnershipSection, options);

package/dist/gates/gates-cli.js

@@ -0,0 +1,410 @@
+#!/usr/bin/env node
+/**
+ * The `bin` entry for the published gates: one binary, dispatching on
+ * `argv[2]`, over the gate names `gate-config.ts` publishes.
+ *
+ * It is the only file in the gate surface that reads `process.argv` or writes to
+ * a stream, so its whole body is turning a configuration section into a report
+ * and a report into `process.exitCode`. A gate returns its report or raises a
+ * coded error; the stream and the exit code are this file's alone.
+ *
+ * `process.exit` is called nowhere, for the reason `src/cli/main.ts` records:
+ * exiting truncates a pending stdout write, and a gate over a large lockfile
+ * writes more than a pipe buffer holds.
+ *
+ * Every path a configuration names resolves against the directory that
+ * configuration file sits in, so a configuration file is self-contained and a
+ * consumer can keep one outside the repository root and still have it mean what
+ * it says.
+ *
+ * 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 binary fails at load.
+ */
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import process from 'node:process';
+import { auditLockfileAge, LOCKFILE_SHAPE_ERROR, } from './audit-lockfile-age.mjs';
+import { runDependencyDirection } from './check-dependency-direction.js';
+import { checkLicenses } from './check-licenses.mjs';
+import { DEFAULT_CONFIG_FILE, GATE_NAMES, loadDependencyDirectionConfig, loadFieldOwnershipConfig, loadLicencesConfig, loadLockfileAgeConfig, loadPackageBoundaryConfig, } from './gate-config.js';
+import { runFieldOwnership, TYPESCRIPT_UNAVAILABLE, } from './lineage-ownership.js';
+import { runPackageBoundary, SCAN_PATH_ERROR, SCAN_UNREADABLE, } from './package-boundary.js';
+const EXIT_OK = 0;
+/** The gate ran and found what it exists to find. */
+const EXIT_GATE_FAILED = 1;
+/**
+ * sysexits.h EX_USAGE, the same number `src/cli/exit-codes.ts` assigns and for
+ * the same reason: the caller repairs it by changing what it passed. This build
+ * roots at `scripts/`, so it cannot import that module; a test case holds the
+ * two numbers equal.
+ */
+const EXIT_USAGE = 64;
+const BINARY = 'eval-quality-gates';
+/**
+ * One line per gate. Keyed by `GateName`, so publishing a gate without
+ * describing it here is a type error and the usage text cannot go stale.
+ */
+const GATE_SUMMARY = {
+    'lockfile-age': "every locked entry's registry publication age, against a window you declare",
+    licences: "every locked entry's licence, against an allowlist of identifiers you declare",
+    'dependency-direction': 'every import in the trees you name, against a layer graph you declare',
+    'package-boundary': 'every line your package would publish, against the patterns you forbid',
+    'field-ownership': 'every write to a field you own, against the modules you let write it',
+};
+/** The widest gate name, plus the two spaces that separate it from its summary. */
+const GATE_COLUMN = Math.max(...GATE_NAMES.map((gate) => gate.length)) + 2;
+const GATE_LINES = GATE_NAMES.map((gate) => `  ${gate.padEnd(GATE_COLUMN)}${GATE_SUMMARY[gate]}`).join('\n');
+const USAGE = `Usage:
+  ${BINARY} <gate> [--config <path>]
+
+${GATE_LINES}
+
+  --config <path>  the configuration file; ${DEFAULT_CONFIG_FILE} in the working directory by default
+  --help, -h       this text
+
+Each gate reads its own section of that file, and configuring a gate is what
+opts into it. A gate invoked with no section refuses by name and falls back to
+nothing. Every path a section names is relative to the configuration file.
+
+dependency-direction and field-ownership read your source with the TypeScript
+scanner, so those two need the optional peer dependency "typescript". Install it
+only if you run one of them; each refuses by name when it is absent.
+
+Exit codes: ${EXIT_OK} the gate passed, ${EXIT_GATE_FAILED} the gate failed, ${EXIT_USAGE} a usage or configuration error.`;
+const writeOut = (line) => {
+    process.stdout.write(`${line}\n`);
+};
+const writeDiagnostic = (line) => {
+    process.stderr.write(`${line}\n`);
+};
+/** A refusal the caller repairs by editing its configuration, so it takes 64. */
+class ConfigurationError extends Error {
+}
+const usageError = (message) => ({
+    kind: 'usage-error',
+    message,
+});
+const isGate = (token) => GATE_NAMES.includes(token);
+/** `--flag=value`, split on the first `=` so a value may contain one. */
+function splitFlag(token) {
+    const equals = token.indexOf('=');
+    if (equals === -1)
+        return { flag: token, inline: null };
+    return { flag: token.slice(0, equals), inline: token.slice(equals + 1) };
+}
+function parseArguments(argv) {
+    const first = argv[0];
+    if (first === undefined) {
+        return usageError(`no gate given; expected one of ${GATE_NAMES.join(', ')}`);
+    }
+    if (first === '--help' || first === '-h' || first === 'help') {
+        return { kind: 'help' };
+    }
+    if (!isGate(first)) {
+        return usageError(`unknown gate "${first}"; expected one of ${GATE_NAMES.join(', ')}`);
+    }
+    let configPath = null;
+    const rest = argv.slice(1);
+    for (let index = 0; index < rest.length;) {
+        const token = rest[index];
+        if (token === '--help' || token === '-h')
+            return { kind: 'help' };
+        const { flag, inline } = splitFlag(token);
+        if (flag !== '--config') {
+            return usageError(`unknown flag "${token}" for ${first}`);
+        }
+        let value;
+        if (inline !== null) {
+            value = inline;
+        }
+        else {
+            const next = rest[index + 1];
+            if (next === undefined)
+                return usageError('--config requires a value');
+            // A flag-shaped token is the next flag, so the space form treats it as a
+            // missing value. A path beginning with "-" is what the equals form is for.
+            if (next.length > 1 && next.startsWith('-')) {
+                return usageError(`--config requires a value, but the next token is "${next}"; use --config=${next} for a path that begins with "-"`);
+            }
+            value = next;
+        }
+        if (value === '')
+            return usageError('--config was given an empty value');
+        if (configPath !== null && configPath !== value) {
+            return usageError(`--config given twice with different values, "${configPath}" and "${value}"`);
+        }
+        configPath = value;
+        index += inline === null ? 2 : 1;
+    }
+    return { kind: 'run', gate: first, configPath };
+}
+/**
+ * A lockfile the configuration named. A path that is not there is a
+ * configuration error and says which setting named it, because the repair is in
+ * the file rather than in the tree.
+ */
+async function readLockfile(root, relative, configFile, gate) {
+    const path = resolve(root, relative);
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        const code = error.code;
+        const detail = code === 'ENOENT'
+            ? 'does not exist'
+            : `could not be read: ${error instanceof Error ? error.message : String(error)}`;
+        throw new ConfigurationError(`${path} ${detail}; ${configFile}'s "${gate}" section names it under lockfiles`);
+    }
+}
+async function runLockfileAge(configFile, root, section) {
+    const now = new Date();
+    // The line `.github/actions/audit-lockfile-age/action.yml` greps for: a
+    // clock-parsing bug that made every entry look permanently old would
+    // otherwise be invisible.
+    writeOut(`Effective clock: ${now.toISOString()}`);
+    let passed = true;
+    for (const relative of section.lockfiles) {
+        const lockfile = await readLockfile(root, relative, configFile, 'lockfile-age');
+        const report = (await auditLockfileAge({
+            lockfile,
+            now,
+            windowDays: section.windowDays,
+            source: relative,
+        }));
+        if (report.youngEntries.length === 0 &&
+            report.unfetchableEntries.length === 0 &&
+            report.offRegistryEntries.length === 0) {
+            writeOut(`lockfile-age ${relative}: passed, ${report.entries.length} entrie(s), all published before ${report.cutoff.toISOString()}.`);
+            continue;
+        }
+        passed = false;
+        if (report.offRegistryEntries.length > 0) {
+            writeDiagnostic(`\nlockfile-age ${relative}: failed closed, ${report.offRegistryEntries.length} entrie(s) do not resolve to the npm registry:`);
+            for (const entry of report.offRegistryEntries) {
+                writeDiagnostic(`  - ${entry.name}@${entry.version} resolved=${JSON.stringify(entry.resolved ?? null)} (${entry.path})`);
+            }
+        }
+        if (report.unfetchableEntries.length > 0) {
+            writeDiagnostic(`\nlockfile-age ${relative}: failed closed, could not fetch publish metadata for ${report.unfetchableEntries.length} entrie(s):`);
+            for (const entry of report.unfetchableEntries) {
+                writeDiagnostic(`  - ${entry.name}@${entry.version} (${entry.path})`);
+            }
+        }
+        if (report.youngEntries.length > 0) {
+            writeDiagnostic(`\nlockfile-age ${relative}: ${report.youngEntries.length} entrie(s) published inside the ${section.windowDays}-day window (cutoff ${report.cutoff.toISOString()}):`);
+            for (const entry of report.youngEntries) {
+                writeDiagnostic(`  - ${entry.name}@${entry.version} published ${entry.publishedAt} (${entry.path})`);
+            }
+        }
+    }
+    return passed;
+}
+/** A tolerance holds only while its marker does, so the file is read on every run. */
+async function markerHolds(root, marker) {
+    if (marker === undefined)
+        return true;
+    try {
+        const text = await readFile(resolve(root, marker.file), 'utf8');
+        return text.includes(marker.contains);
+    }
+    catch {
+        return false;
+    }
+}
+async function runLicences(configFile, root, section) {
+    let passed = true;
+    for (const relative of section.lockfiles) {
+        const lockfile = await readLockfile(root, relative, configFile, 'licences');
+        const policy = section.policies?.[relative];
+        const allowlist = policy === undefined
+            ? section.allowlist
+            : [...section.allowlist, ...policy.also];
+        const label = policy === undefined ? 'the allowlist' : policy.label;
+        const applicable = [];
+        for (const tolerance of section.tolerances ?? []) {
+            if (!tolerance.lockfiles.includes(relative))
+                continue;
+            if (!(await markerHolds(root, tolerance.marker)))
+                continue;
+            applicable.push(tolerance);
+        }
+        const report = checkLicenses(lockfile, {
+            allowlist,
+            label,
+            tolerances: applicable,
+            source: relative,
+        });
+        if (report.violations.length === 0) {
+            writeOut(`licences ${relative}: passed against ${label}, ${report.entryCount} entrie(s), all allowlisted.`);
+            if (policy !== undefined)
+                writeOut(`  ${label}: ${policy.reason}`);
+            if (report.tolerated.length > 0) {
+                writeOut(`  tolerated: ${report.tolerated.join(', ')}`);
+                for (const reason of report.toleranceReasons) {
+                    writeOut(`  because: ${reason}`);
+                }
+            }
+            continue;
+        }
+        passed = false;
+        writeDiagnostic(`\nlicences ${relative}: ${report.violations.length} entrie(s) outside ${label}:`);
+        for (const violation of report.violations) {
+            writeDiagnostic(`  - ${violation.name}@${violation.version}: license=${JSON.stringify(violation.license)}${violation.reason ? ` (${violation.reason})` : ''}`);
+            writeDiagnostic(`    dependency path: ${violation.dependencyPath}`);
+        }
+    }
+    return passed;
+}
+/** The order every violation report prints in, so two runs read the same. */
+const byFileThenLine = (violations) => [...violations].sort((a, b) => a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1);
+/**
+ * The direction gate writes to no stream and hands back what to print, so this
+ * is the whole mapping. `summary` is written on every outcome, including a clean
+ * one and a report-only one, which is what stops a report-only run being silent:
+ * a green run that printed nothing is the vacuous pass report-only mode exists
+ * to prevent.
+ *
+ * The violation lines go to stdout under report-only and to stderr otherwise.
+ * Report-only output is the thing the run was for, and a caller that redirects
+ * stderr away should still get it.
+ */
+async function runDirection(configPath, root, section) {
+    const outcome = await runDependencyDirection({ section, root, configPath });
+    if (outcome.kind === 'refused') {
+        writeDiagnostic(`${BINARY}: ${outcome.message}`);
+        return EXIT_USAGE;
+    }
+    writeOut(outcome.summary);
+    const write = outcome.reportOnly ? writeOut : writeDiagnostic;
+    for (const line of outcome.lines)
+        write(line);
+    return outcome.failed ? EXIT_GATE_FAILED : EXIT_OK;
+}
+async function runBoundary(root, section) {
+    const report = await runPackageBoundary(root, section, 'package-boundary');
+    if (report.violations.length === 0) {
+        const where = report.counts
+            .map((count) => `${count.files} from ${count.path}`)
+            .join(', ');
+        writeOut(`package-boundary: ${report.scanned} entr(ies) scanned, 0 violations (${where})`);
+        return EXIT_OK;
+    }
+    writeDiagnostic(`\npackage-boundary: ${report.violations.length} violation(s) across ${report.scanned} scanned entr(ies):`);
+    for (const violation of byFileThenLine(report.violations)) {
+        writeDiagnostic(`  ${violation.file}:${violation.line} [${violation.pattern}] ${violation.text}`);
+        writeDiagnostic(`    ${violation.reason}`);
+    }
+    return EXIT_GATE_FAILED;
+}
+async function runOwnership(root, section) {
+    const report = await runFieldOwnership(root, section, 'field-ownership');
+    if (report.violations.length === 0) {
+        writeOut(`field-ownership: ${report.scanned} file(s) scanned, 0 violations`);
+        return EXIT_OK;
+    }
+    writeDiagnostic(`\nfield-ownership: ${report.violations.length} violation(s) across ${report.scanned} scanned file(s):`);
+    for (const violation of byFileThenLine(report.violations)) {
+        writeDiagnostic(`  ${violation.file}:${violation.line} ${violation.subject}: ${violation.rule}`);
+    }
+    return EXIT_GATE_FAILED;
+}
+async function run(invocation) {
+    if (invocation.kind === 'help') {
+        writeOut(USAGE);
+        return EXIT_OK;
+    }
+    if (invocation.kind === 'usage-error') {
+        writeDiagnostic(`${BINARY}: usage: ${invocation.message}`);
+        writeDiagnostic(USAGE);
+        return EXIT_USAGE;
+    }
+    const options = { configPath: invocation.configPath ?? undefined };
+    const refused = (message) => {
+        writeDiagnostic(`${BINARY}: ${invocation.gate}: ${message}`);
+        return EXIT_USAGE;
+    };
+    switch (invocation.gate) {
+        case 'lockfile-age': {
+            const loaded = await loadLockfileAgeConfig(options);
+            if (loaded.kind === 'refused')
+                return refused(loaded.message);
+            const passed = await runLockfileAge(loaded.path, dirname(loaded.path), loaded.section);
+            return passed ? EXIT_OK : EXIT_GATE_FAILED;
+        }
+        case 'licences': {
+            const loaded = await loadLicencesConfig(options);
+            if (loaded.kind === 'refused')
+                return refused(loaded.message);
+            const passed = await runLicences(loaded.path, dirname(loaded.path), loaded.section);
+            return passed ? EXIT_OK : EXIT_GATE_FAILED;
+        }
+        case 'dependency-direction': {
+            const loaded = await loadDependencyDirectionConfig(options);
+            if (loaded.kind === 'refused')
+                return refused(loaded.message);
+            return runDirection(loaded.path, dirname(loaded.path), loaded.section);
+        }
+        case 'package-boundary': {
+            const loaded = await loadPackageBoundaryConfig(options);
+            if (loaded.kind === 'refused')
+                return refused(loaded.message);
+            return runBoundary(dirname(loaded.path), loaded.section);
+        }
+        case 'field-ownership': {
+            const loaded = await loadFieldOwnershipConfig(options);
+            if (loaded.kind === 'refused')
+                return refused(loaded.message);
+            return runOwnership(dirname(loaded.path), loaded.section);
+        }
+    }
+    // Exhaustive over `GateName`: a gate added to `GATE_NAMES` with no arm above
+    // is a type error here rather than a binary that names it in its usage text
+    // and does nothing when invoked.
+    const unhandled = invocation.gate;
+    throw new Error(`no dispatch arm for the gate "${String(unhandled)}"`);
+}
+/**
+ * The refusals a gate raises as a coded error rather than as a return value,
+ * and the exit each takes.
+ *
+ * A lockfile or a path the configuration named and the tree does not have is a
+ * configuration error, so it takes the usage code: the repair is in the file.
+ * So is an absent optional peer dependency. A tree the scan could not read to
+ * the end takes the gate's own failure code instead, because that gate ran and
+ * refused rather than being misinvoked.
+ *
+ * Sharing one code across the two would let "scanned nothing" and "found
+ * nothing" answer a caller the same way, which is the pass these refusals exist
+ * to stop.
+ */
+const CODED_EXITS = new Map([
+    [LOCKFILE_SHAPE_ERROR, EXIT_USAGE],
+    [SCAN_PATH_ERROR, EXIT_USAGE],
+    [TYPESCRIPT_UNAVAILABLE, EXIT_USAGE],
+    [SCAN_UNREADABLE, EXIT_GATE_FAILED],
+]);
+async function main(argv) {
+    try {
+        process.exitCode = await run(parseArguments(argv));
+    }
+    catch (error) {
+        if (error instanceof ConfigurationError) {
+            writeDiagnostic(`${BINARY}: ${error.message}`);
+            process.exitCode = EXIT_USAGE;
+            return;
+        }
+        const code = error !== null && typeof error === 'object'
+            ? error.code
+            : undefined;
+        const mapped = typeof code === 'string' ? CODED_EXITS.get(code) : undefined;
+        if (mapped !== undefined) {
+            writeDiagnostic(`${BINARY}: ${error.message}`);
+            process.exitCode = mapped;
+            return;
+        }
+        writeDiagnostic(error instanceof Error ? (error.stack ?? error.message) : String(error));
+        process.exitCode = EXIT_GATE_FAILED;
+    }
+}
+await main(process.argv.slice(2));