@rivi-software/workers-bundle-check 0.0.0-stage → 0.1.0

package/dist/check.js

@@ -0,0 +1,233 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { findServedSourceMaps, readAssets } from "./assets.js";
+import { describeRule, findForbidden, findStaleRules, validateRules, } from "./forbidden.js";
+import { describePattern, isPackageName } from "./modules.js";
+import { allows, describeAllowed, findSecrets, SECRET_PATTERNS, validateAllowedSecrets, validateSecretPatterns, } from "./secrets.js";
+import { decodeMappings, display, readSourceMap, realPath, renderedSources, sourceAt, } from "./source-map.js";
+/** Thrown by {@link checkWorkerBundle} when it finds problems: they are in `report.problems`. */
+export class WorkerBundleCheckError extends Error {
+    report;
+    constructor(report) {
+        const count = report.problems.length;
+        super([
+            `The Worker bundle check found ${count} problem${count === 1 ? "" : "s"}:`,
+            ...report.problems.map((problem) => `  ${problem.message}`),
+        ].join("\n"));
+        this.name = "WorkerBundleCheckError";
+        this.report = report;
+    }
+}
+/**
+ * Checks a Worker's build: no forbidden module or marker in the Worker, no source map among the
+ * assets Wrangler would serve, and no value shaped like a secret in either. Resolves to the
+ * report when it finds nothing; rejects with a {@link WorkerBundleCheckError} that lists the
+ * problems otherwise. Run it after the build.
+ */
+export async function checkWorkerBundle(options) {
+    const report = await inspect(options);
+    if (report.problems.length)
+        throw new WorkerBundleCheckError(report);
+    return report;
+}
+/** The Worker's files that can carry a secret: scripts, markup and data. */
+const TEXT = /\.(?:[cm]?js|json|html?|css|txt|xml|svg|webmanifest)$/i;
+const SCRIPT = /\.[cm]?js$/i;
+/**
+ * Served files the secret check passes over: source maps, which are a problem of their own, and
+ * binary formats. It reads any other served file, such as a stray `.env`, and passes over one
+ * that holds a NUL byte near its start.
+ */
+const NOT_TEXT = /\.(?:map|png|jpe?g|gif|webp|avif|ico|bmp|tiff?|woff2?|ttf|otf|eot|mp[34]|m4a|aac|og[ag]|wav|flac|webm|mov|avi|wasm|zip|gz|br|zst|tar|pdf|bin)$/i;
+async function inspect(options) {
+    const given = path.resolve(options.cwd ?? ".");
+    const cwd = realPath(given) ?? given;
+    const serverDir = path.resolve(cwd, options.serverDir);
+    const assetsDir = options.assetsDir === undefined ? undefined : path.resolve(cwd, options.assetsDir);
+    const rules = options.forbidden ?? [];
+    const allowed = options.allowedSecrets ?? [];
+    const patterns = [...SECRET_PATTERNS, ...(options.secretPatterns ?? [])];
+    validateRules(rules);
+    validateAllowedSecrets(allowed);
+    validateSecretPatterns(options.secretPatterns ?? []);
+    const show = (file) => display(file, cwd);
+    const problems = [];
+    const texts = new Map();
+    const text = (file) => {
+        let found = texts.get(file);
+        if (!found)
+            texts.set(file, (found = readFile(file, "utf8")));
+        return found;
+    };
+    /**
+     * A file with its modules, when it is a script with a source map. A Worker's map must be
+     * readable; a served asset's only names where a secret comes from, so an unreadable one is
+     * passed over.
+     */
+    const read = async (file, asset = false) => {
+        const code = await text(file);
+        const sourceMap = SCRIPT.test(file)
+            ? await readSourceMap(file, code, cwd).catch((error) => {
+                if (asset)
+                    return undefined;
+                throw error;
+            })
+            : undefined;
+        if (!sourceMap)
+            return { file, path: show(file), code };
+        const mappings = decodeMappings(sourceMap.map.mappings);
+        const modules = new Map();
+        for (const [source, bytes] of renderedSources(code, mappings)) {
+            const name = sourceMap.modules[source];
+            if (name)
+                modules.set(name, (modules.get(name) ?? 0) + bytes);
+        }
+        return { file, path: show(file), code, sourceMap, mappings, modules };
+    };
+    // The Worker: every file in its build output, but the assets when they are inside it.
+    const entries = await readdir(serverDir, { recursive: true, withFileTypes: true }).catch((error) => {
+        if (error.code === "ENOENT")
+            throw new Error(`There is no Worker build at ${show(serverDir)}: run the build first.`);
+        throw error;
+    });
+    const inAssets = (file) => assetsDir !== undefined && !path.relative(assetsDir, file).startsWith("..");
+    const serverFiles = entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => path.join(entry.parentPath, entry.name))
+        .filter((file) => !inAssets(file))
+        .sort();
+    const workerFiles = await Promise.all(serverFiles.filter((file) => SCRIPT.test(file)).map((file) => read(file)));
+    if (!workerFiles.length)
+        throw new Error(`${show(serverDir)} holds no JavaScript. Pass the directory the Worker's build writes its modules to, such as dist/server.`);
+    // Forbidden modules and markers.
+    if (rules.some((rule) => rule.module !== undefined))
+        for (const file of workerFiles)
+            if (!file.modules)
+                problems.push({
+                    kind: "missing-source-map",
+                    file: file.path,
+                    message: `${file.path} has no source map, so the rules cannot see the modules in it. Build the Worker with source maps.`,
+                });
+    for (const finding of findForbidden(workerFiles, rules)) {
+        if (finding.kind === "forbidden-marker")
+            problems.push({
+                ...finding,
+                message: `${finding.file} contains the marker ${describePattern(finding.rule.marker)}, which is forbidden: ${finding.rule.reason}.`,
+            });
+        else {
+            const [largest] = finding.modules;
+            const count = finding.modules.length;
+            const total = finding.modules.reduce((sum, module) => sum + module.bytes, 0);
+            problems.push({
+                ...finding,
+                message: count === 1
+                    ? `${finding.file} holds ${largest.path} (${kB(largest.bytes)}), which ${describePattern(finding.rule.module)} forbids: ${finding.rule.reason}.`
+                    : `${finding.file} holds ${count} modules (${kB(total)}) that ${describePattern(finding.rule.module)} forbids: ${finding.rule.reason}. The largest is ${largest.path} (${kB(largest.bytes)}).`,
+            });
+        }
+    }
+    const skip = [serverDir, ...(assetsDir === undefined ? [] : [assetsDir])];
+    for (const { rule, part } of await findStaleRules(workerFiles, rules, cwd, skip))
+        problems.push({
+            kind: "stale-rule",
+            rule,
+            part,
+            message: `The rule against ${describeRule(rule)} guards nothing: ${staleReason(rule, part)}. Update the rule or remove it.`,
+        });
+    // The assets Wrangler would serve.
+    const assets = assetsDir === undefined
+        ? undefined
+        : await readAssets(assetsDir).catch((error) => {
+            if (error.code === "ENOENT")
+                throw new Error(`There are no assets at ${show(assetsDir)}: run the build first.`);
+            throw error;
+        });
+    const assetsIgnore = assetsDir === undefined ? "" : show(path.join(assetsDir, ".assetsignore"));
+    for (const { kind, file } of await findServedSourceMaps(assets?.served ?? [], text))
+        problems.push(kind === "served-source-map"
+            ? {
+                kind,
+                file: show(file),
+                message: `${show(file)} is a source map Wrangler would serve: leave it out with ${assetsIgnore}, or delete it before the deploy.`,
+            }
+            : {
+                kind,
+                file: show(file),
+                message: `${show(file)} would be served with its source map inline. Build it with external or hidden source maps.`,
+            });
+    // Values shaped like secrets, in the Worker and in what the assets serve.
+    const plain = async (file) => ({
+        file,
+        path: show(file),
+        code: await text(file),
+    });
+    const scanned = [
+        ...workerFiles,
+        ...(await Promise.all(serverFiles.filter((file) => TEXT.test(file) && !SCRIPT.test(file)).map(plain))),
+        ...(await Promise.all((assets?.served ?? [])
+            .filter(({ file }) => !NOT_TEXT.test(file))
+            .map(({ file }) => plain(file)))).filter(({ code }) => !code.slice(0, 8000).includes("\0")),
+    ];
+    const used = new Set();
+    let allowedCount = 0;
+    for (const scannedFile of scanned) {
+        const findings = findSecrets(scannedFile.code, patterns);
+        if (!findings.length)
+            continue;
+        // A served script's map is read only to name where a value comes from.
+        const file = workerFiles.includes(scannedFile)
+            ? scannedFile
+            : await read(scannedFile.file, true);
+        for (const finding of findings) {
+            const source = file.mappings && file.sourceMap
+                ? sourceAt(file.mappings, finding.line - 1, finding.column)
+                : -1;
+            const module = source >= 0 ? file.sourceMap.modules[source] : undefined;
+            const covering = allowed.filter((entry) => allows(entry, finding, module));
+            if (covering.length) {
+                for (const entry of covering)
+                    used.add(entry);
+                allowedCount++;
+                continue;
+            }
+            problems.push({
+                kind: "secret",
+                file: file.path,
+                name: finding.name,
+                fingerprint: finding.fingerprint,
+                line: finding.line,
+                ...(module === undefined ? {} : { module }),
+                message: `${file.path}:${finding.line} holds a value shaped like a ${finding.name}${module === undefined ? "" : `, from ${module}`} (fingerprint ${finding.fingerprint}).`,
+            });
+        }
+    }
+    for (const entry of allowed)
+        if (!used.has(entry))
+            problems.push({
+                kind: "stale-allowed-secret",
+                allowed: entry,
+                message: `The allowed secret with ${describeAllowed(entry)} (${entry.reason}) matches no finding. Remove it.`,
+            });
+    return {
+        serverDir: show(serverDir),
+        workerFiles: workerFiles.map((file) => file.path),
+        modules: new Set(workerFiles.flatMap((file) => [...(file.modules?.keys() ?? [])])).size,
+        ...(assetsDir === undefined ? {} : { assetsDir: show(assetsDir) }),
+        servedAssets: assets?.served.length ?? 0,
+        ignoredAssets: assets?.ignored.length ?? 0,
+        allowedSecrets: allowedCount,
+        problems,
+    };
+}
+function staleReason(rule, part) {
+    if (part === "module")
+        return isPackageName(rule.module)
+            ? `no package ${describePattern(rule.module)} is installed`
+            : `no file matches ${describePattern(rule.module)}`;
+    return rule.module === undefined
+        ? `no file of the project, outside node_modules, contains ${describePattern(rule.marker)}`
+        : `no file that ${describePattern(rule.module)} matches contains ${describePattern(rule.marker)}`;
+}
+function kB(bytes) {
+    return bytes < 1000 ? `${bytes} B` : `${(bytes / 1000).toFixed(1)} kB`;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from "./run-cli.js";
+/** `workers-bundle-check [--config <file>] [--server <dir>] [--assets <dir>]` (./run-cli.ts). */
+process.exitCode = await runCli(process.argv.slice(2).filter((arg) => arg !== "--"));

package/dist/forbidden.d.ts

@@ -0,0 +1,65 @@
+import { type ModulePattern } from "./modules.js";
+/**
+ * What the Worker must not carry, and why. A rule names a module, a marker, or both; the Worker
+ * breaks it when it holds either.
+ */
+export type ForbiddenRule = {
+    /** The modules the Worker must not hold: a package name, a glob or a regular expression. */
+    module?: ModulePattern;
+    /**
+     * A string or regular expression the Worker's code must not contain, such as a string only
+     * dev code has. It finds code that no source map names.
+     */
+    marker?: string | RegExp;
+    /** Why, for the report: `test-only`, `import single icons`. */
+    reason: string;
+};
+/** A built JavaScript file of the Worker. */
+export type WorkerFile = {
+    /** Its path, as reports show it. */
+    path: string;
+    code: string;
+    /** The bytes of code each module renders in it, by module path; undefined without a map. */
+    modules?: ReadonlyMap<string, number>;
+};
+/** A module the Worker holds, and the bytes of code it renders there. */
+export type BundledModule = {
+    path: string;
+    bytes: number;
+};
+/** A forbidden rule the Worker breaks, in one of its files. */
+export type ForbiddenFinding = {
+    kind: "forbidden-module";
+    rule: ForbiddenRule;
+    file: string;
+    modules: BundledModule[];
+} | {
+    kind: "forbidden-marker";
+    rule: ForbiddenRule;
+    file: string;
+};
+/** The part of a rule that matches nothing the project has. */
+export type StaleRule = {
+    rule: ForbiddenRule;
+    part: "module" | "marker";
+};
+/** Throws when a rule names neither a module nor a marker, or has no reason. */
+export declare function validateRules(rules: readonly ForbiddenRule[]): void;
+/** Whether `code` contains the marker. */
+export declare function hasMarker(code: string, marker: string | RegExp): boolean;
+/** Each rule the Worker's files break, per file. */
+export declare function findForbidden(files: readonly WorkerFile[], rules: readonly ForbiddenRule[]): ForbiddenFinding[];
+/**
+ * The rule parts that match nothing: a guard that matches nothing guards nothing, so the list
+ * stays current. The Worker should hold none of what the rules name, so a rule is checked
+ * against the project instead (see {@link projectFiles}):
+ * - a module pattern, against the project's files: a package name needs the package installed,
+ *   and a glob or regular expression needs a file it matches
+ * - a marker, against the text of the files its rule's module pattern matches; without one,
+ *   against the project's own files under `cwd`, outside `node_modules`
+ *
+ * A part the Worker matches is never stale.
+ */
+export declare function findStaleRules(files: readonly WorkerFile[], rules: readonly ForbiddenRule[], cwd: string, skip: readonly string[]): Promise<StaleRule[]>;
+/** A rule as reports name it: its reason and what it forbids. */
+export declare function describeRule(rule: ForbiddenRule): string;

package/dist/forbidden.js

@@ -0,0 +1,116 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { describePattern, isPackageName, moduleMatcher, projectFiles, stateless, } from "./modules.js";
+/** Throws when a rule names neither a module nor a marker, or has no reason. */
+export function validateRules(rules) {
+    for (const rule of rules) {
+        if (rule.module === undefined && rule.marker === undefined)
+            throw new TypeError(`A forbidden rule names neither a module nor a marker: ${show(rule)}.`);
+        if (!rule.reason?.trim())
+            throw new TypeError(`A forbidden rule has no reason: ${show(rule)}.`);
+    }
+}
+function show(rule) {
+    return JSON.stringify(rule, (_, value) => value instanceof RegExp ? String(value) : value);
+}
+/** Whether `code` contains the marker. */
+export function hasMarker(code, marker) {
+    return typeof marker === "string" ? code.includes(marker) : stateless(marker).test(code);
+}
+/** Each rule the Worker's files break, per file. */
+export function findForbidden(files, rules) {
+    const findings = [];
+    for (const rule of rules) {
+        const matches = rule.module === undefined ? undefined : moduleMatcher(rule.module);
+        for (const file of files) {
+            const modules = matches
+                ? [...(file.modules ?? [])]
+                    .filter(([modulePath]) => matches(modulePath))
+                    .map(([modulePath, bytes]) => ({ path: modulePath, bytes }))
+                    .sort((a, b) => b.bytes - a.bytes || a.path.localeCompare(b.path))
+                : [];
+            if (modules.length)
+                findings.push({ kind: "forbidden-module", rule, file: file.path, modules });
+            if (rule.marker !== undefined && hasMarker(file.code, rule.marker))
+                findings.push({ kind: "forbidden-marker", rule, file: file.path });
+        }
+    }
+    return findings;
+}
+/** Files read for a marker: code and the text formats that carry it. */
+const TEXT = /\.(?:[cm]?[jt]sx?|json|vue|svelte|astro|html?)$/i;
+/**
+ * The rule parts that match nothing: a guard that matches nothing guards nothing, so the list
+ * stays current. The Worker should hold none of what the rules name, so a rule is checked
+ * against the project instead (see {@link projectFiles}):
+ * - a module pattern, against the project's files: a package name needs the package installed,
+ *   and a glob or regular expression needs a file it matches
+ * - a marker, against the text of the files its rule's module pattern matches; without one,
+ *   against the project's own files under `cwd`, outside `node_modules`
+ *
+ * A part the Worker matches is never stale.
+ */
+export async function findStaleRules(files, rules, cwd, skip) {
+    const pending = [];
+    for (const rule of rules) {
+        const matches = rule.module === undefined ? undefined : moduleMatcher(rule.module);
+        const inWorker = matches !== undefined &&
+            files.some((file) => [...(file.modules?.keys() ?? [])].some(matches));
+        const module = rule.module !== undefined &&
+            !inWorker &&
+            !(typeof rule.module === "string" &&
+                isPackageName(rule.module) &&
+                installed(rule.module, cwd));
+        const marker = rule.marker !== undefined && !files.some((file) => hasMarker(file.code, rule.marker));
+        if (module || marker)
+            pending.push({ rule, matches, module, marker });
+    }
+    const open = () => pending.some((entry) => entry.module || entry.marker);
+    if (open())
+        for await (const { path: modulePath, file } of projectFiles(cwd, skip)) {
+            let text;
+            const read = () => (text ??= TEXT.test(file)
+                ? readFile(file, "utf8").catch(() => undefined)
+                : Promise.resolve(undefined));
+            for (const entry of pending) {
+                const named = entry.matches?.(modulePath);
+                if (entry.module && named)
+                    entry.module = false;
+                if (!entry.marker)
+                    continue;
+                const own = !entry.matches &&
+                    !modulePath.startsWith("../") &&
+                    !/(?:^|\/)node_modules\//.test(modulePath);
+                if (!named && !own)
+                    continue;
+                const code = await read();
+                if (code !== undefined && hasMarker(code, entry.rule.marker))
+                    entry.marker = false;
+            }
+            if (!open())
+                break;
+        }
+    return pending.flatMap(({ rule, module, marker }) => [
+        ...(module ? [{ rule, part: "module" }] : []),
+        ...(marker ? [{ rule, part: "marker" }] : []),
+    ]);
+}
+/** Whether a package is installed where Node would find it from `cwd`, or in pnpm's store. */
+function installed(name, cwd) {
+    for (let dir = cwd;; dir = path.dirname(dir)) {
+        for (const base of ["node_modules", "node_modules/.pnpm/node_modules"])
+            if (existsSync(path.join(dir, base, name, "package.json")))
+                return true;
+        if (dir === path.dirname(dir))
+            return false;
+    }
+}
+/** A rule as reports name it: its reason and what it forbids. */
+export function describeRule(rule) {
+    const parts = [
+        rule.module === undefined ? undefined : `module ${describePattern(rule.module)}`,
+        rule.marker === undefined ? undefined : `marker ${describePattern(rule.marker)}`,
+    ].filter(Boolean);
+    return `${parts.join(" and ")} (${rule.reason})`;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { checkWorkerBundle, WorkerBundleCheckError, type WorkerBundleCheckOptions, type WorkerBundleProblem, type WorkerBundleReport, } from "./check.js";
+export { type BundledModule, type ForbiddenRule } from "./forbidden.js";
+export { type ModulePattern } from "./modules.js";
+export { type AllowedSecret, SECRET_PATTERNS, type SecretPattern } from "./secrets.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { checkWorkerBundle, WorkerBundleCheckError, } from "./check.js";
+export { SECRET_PATTERNS } from "./secrets.js";

package/dist/modules.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Which modules a rule names:
+ * - a package name, such as `msw` or `@faker-js/faker`: every module in that package, wherever it
+ *   is installed
+ * - a glob, such as `src/mocks/**` or `**\/icons/all.js`: the module paths it matches
+ * - a regular expression: the module paths it matches
+ *
+ * A module path is relative to the check's `cwd`, with `/` between segments. The leading `../` of
+ * a module outside `cwd` is left out before matching, so `node_modules/…` in a monorepo's root
+ * matches as `node_modules/…`.
+ */
+export type ModulePattern = string | RegExp;
+/** Whether a module pattern is a package name. */
+export declare function isPackageName(pattern: ModulePattern): boolean;
+/** A test for module paths: whether `pattern` names the module. */
+export declare function moduleMatcher(pattern: ModulePattern): (modulePath: string) => boolean;
+/** A copy of a regular expression without the `g` and `y` flags, whose `test` keeps state. */
+export declare function stateless(regExp: RegExp): RegExp;
+/** A pattern or marker as reports show it. */
+export declare function describePattern(pattern: string | RegExp): string;
+/** A file of the project: its module path and its absolute real path. */
+export type ProjectFile = {
+    path: string;
+    file: string;
+};
+/**
+ * Every file the project has, for the check of stale rules: the files under `cwd`, and those in
+ * the `node_modules` of each directory above it, where a monorepo installs its packages. It
+ * follows symlinked directories, each real directory once, and names each file by its real path,
+ * as bundlers do. It skips `.git` and the directories in `skip`, the build's output.
+ */
+export declare function projectFiles(cwd: string, skip: readonly string[]): AsyncGenerator<ProjectFile>;

package/dist/modules.js

@@ -0,0 +1,83 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { Minimatch } from "minimatch";
+import { posixRelative, realPath } from "./source-map.js";
+/** npm's rules for a package name, which never holds a glob character. */
+const PACKAGE_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+/** Whether a module pattern is a package name. */
+export function isPackageName(pattern) {
+    return typeof pattern === "string" && PACKAGE_NAME.test(pattern);
+}
+/** A test for module paths: whether `pattern` names the module. */
+export function moduleMatcher(pattern) {
+    if (pattern instanceof RegExp) {
+        const regExp = stateless(pattern);
+        return (modulePath) => regExp.test(matchable(modulePath));
+    }
+    if (isPackageName(pattern)) {
+        const segment = `/node_modules/${pattern}/`;
+        return (modulePath) => `/${matchable(modulePath)}`.includes(segment);
+    }
+    const glob = new Minimatch(pattern.replace(/^\.\//, ""), { dot: true });
+    return (modulePath) => glob.match(matchable(modulePath));
+}
+/** A module path without the `../` that leads outside `cwd`. */
+function matchable(modulePath) {
+    return modulePath.replace(/^(?:\.\.\/)+/, "");
+}
+/** A copy of a regular expression without the `g` and `y` flags, whose `test` keeps state. */
+export function stateless(regExp) {
+    return regExp.global || regExp.sticky
+        ? new RegExp(regExp.source, regExp.flags.replace(/[gy]/g, ""))
+        : regExp;
+}
+/** A pattern or marker as reports show it. */
+export function describePattern(pattern) {
+    return typeof pattern === "string" ? JSON.stringify(pattern) : String(pattern);
+}
+/**
+ * Every file the project has, for the check of stale rules: the files under `cwd`, and those in
+ * the `node_modules` of each directory above it, where a monorepo installs its packages. It
+ * follows symlinked directories, each real directory once, and names each file by its real path,
+ * as bundlers do. It skips `.git` and the directories in `skip`, the build's output.
+ */
+export async function* projectFiles(cwd, skip) {
+    const skipped = new Set(skip.map((dir) => realPath(dir) ?? dir));
+    const seen = new Set();
+    const queue = [];
+    const visit = (dir) => {
+        if (dir && !seen.has(dir) && !skipped.has(dir)) {
+            seen.add(dir);
+            queue.push(dir);
+        }
+    };
+    visit(realPath(cwd));
+    for (let dir = path.dirname(cwd);; dir = path.dirname(dir)) {
+        visit(realPath(path.join(dir, "node_modules")));
+        if (dir === path.dirname(dir))
+            break;
+    }
+    for (let index = 0; index < queue.length; index++) {
+        const dir = queue[index];
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (entry.name === ".git")
+                continue;
+            const file = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                visit(file);
+            else if (entry.isFile())
+                yield { path: posixRelative(cwd, file), file };
+            else if (entry.isSymbolicLink()) {
+                const target = await stat(file).catch(() => undefined);
+                const resolved = target && realPath(file);
+                if (!resolved)
+                    continue;
+                if (target.isDirectory())
+                    visit(resolved);
+                else if (target.isFile())
+                    yield { path: posixRelative(cwd, resolved), file: resolved };
+            }
+        }
+    }
+}

package/dist/run-cli.d.ts

@@ -0,0 +1,12 @@
+/** The configuration files the command looks for in the current directory, in this order. */
+export declare const CONFIG_FILES: string[];
+export declare const USAGE = "Usage: workers-bundle-check [--config <file>] [--server <dir>] [--assets <dir>]\n\nChecks a Worker's build: no forbidden module or marker in the Worker, no source\nmap among the assets Wrangler would serve, and no value shaped like a secret.\nRun it after the build.\n\n  --config   A module whose default export holds the options. Default: the\n             first of workers-bundle-check.config.ts, .mts, .js, .mjs and .json\n             that exists. A JSON file holds no regular expressions.\n  --server   The Worker's build output, such as dist/server (the option serverDir)\n  --assets   Its static assets directory, such as dist/client (the option assetsDir)\n\nPaths are relative to the current directory.";
+type Context = {
+    /** The directory paths are relative to. */
+    cwd: string;
+    log: (line: string) => void;
+    error: (line: string) => void;
+};
+/** Runs `workers-bundle-check` with `args` and returns its exit code. */
+export declare function runCli(args: string[], context?: Context): Promise<number>;
+export {};

package/dist/run-cli.js

@@ -0,0 +1,100 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import { checkWorkerBundle, } from "./check.js";
+/** The configuration files the command looks for in the current directory, in this order. */
+export const CONFIG_FILES = [
+    "workers-bundle-check.config.ts",
+    "workers-bundle-check.config.mts",
+    "workers-bundle-check.config.js",
+    "workers-bundle-check.config.mjs",
+    "workers-bundle-check.config.json",
+];
+export const USAGE = `Usage: workers-bundle-check [--config <file>] [--server <dir>] [--assets <dir>]
+
+Checks a Worker's build: no forbidden module or marker in the Worker, no source
+map among the assets Wrangler would serve, and no value shaped like a secret.
+Run it after the build.
+
+  --config   A module whose default export holds the options. Default: the
+             first of workers-bundle-check.config.ts, .mts, .js, .mjs and .json
+             that exists. A JSON file holds no regular expressions.
+  --server   The Worker's build output, such as dist/server (the option serverDir)
+  --assets   Its static assets directory, such as dist/client (the option assetsDir)
+
+Paths are relative to the current directory.`;
+/** Runs `workers-bundle-check` with `args` and returns its exit code. */
+export async function runCli(args, context = { cwd: process.cwd(), log: console.log, error: console.error }) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args,
+            strict: true,
+            options: {
+                config: { type: "string" },
+                server: { type: "string" },
+                assets: { type: "string" },
+                help: { type: "boolean", short: "h" },
+            },
+        }));
+    }
+    catch (error) {
+        context.error(`${error instanceof Error ? error.message : error}\n\n${USAGE}`);
+        return 2;
+    }
+    if (values.help) {
+        context.log(USAGE);
+        return 0;
+    }
+    try {
+        const found = values.config
+            ? path.resolve(context.cwd, values.config)
+            : CONFIG_FILES.map((file) => path.join(context.cwd, file)).find((file) => existsSync(file));
+        if (values.config && !existsSync(found)) {
+            context.error(`There is no configuration file at ${values.config}.`);
+            return 2;
+        }
+        const config = found ? await loadConfig(found) : {};
+        const serverDir = values.server ?? config.serverDir;
+        if (!serverDir) {
+            context.error(`Name the Worker's build output: --server <dir>, or serverDir in ${found ? path.relative(context.cwd, found) : CONFIG_FILES[0]}.\n\n${USAGE}`);
+            return 2;
+        }
+        const report = await checkWorkerBundle({
+            ...config,
+            cwd: path.resolve(context.cwd, config.cwd ?? "."),
+            serverDir,
+            assetsDir: values.assets ?? config.assetsDir,
+        });
+        for (const line of summary(report, config))
+            context.log(line);
+        return 0;
+    }
+    catch (error) {
+        context.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+/** The options a configuration file's default export holds. */
+async function loadConfig(file) {
+    const config = file.endsWith(".json")
+        ? JSON.parse(await readFile(file, "utf8"))
+        : (await import(pathToFileURL(file).href)).default;
+    if (!config || typeof config !== "object" || Array.isArray(config))
+        throw new Error(`${file} must export the options as its default export: { serverDir, … }.`);
+    return config;
+}
+/** What a passing check read, line by line. */
+function summary(report, config) {
+    const rules = config.forbidden?.length ?? 0;
+    const files = report.workerFiles.length;
+    const lines = [
+        `${report.serverDir}: ${files} file${files === 1 ? "" : "s"} and ${report.modules} module${report.modules === 1 ? "" : "s"}, none that ${rules} forbidden rule${rules === 1 ? "" : "s"} name.`,
+    ];
+    if (report.assetsDir !== undefined)
+        lines.push(`${report.assetsDir}: ${report.servedAssets} file${report.servedAssets === 1 ? "" : "s"} served and ${report.ignoredAssets} left out, no source map among them.`);
+    lines.push(`No value shaped like a secret${report.allowedSecrets ? `, but the ${report.allowedSecrets} allowed` : ""}.`);
+    return lines;
+}