@titannio/webtoolkit-cli 1.3.0

package/dist/dev-watch.js

@@ -0,0 +1,184 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { createServer } from 'node:net';
+import { buildPackageManagerCommand, resolveSpawnSpec } from './process.js';
+const isWindows = process.platform === 'win32';
+export function resolveDevWatchSpawnSpec(command, commandArgs) {
+    const resolved = resolveSpawnSpec(command, commandArgs);
+    return { ...resolved, detached: !isWindows };
+}
+function spawnCommand(command, commandArgs, options = {}) {
+    const resolved = resolveDevWatchSpawnSpec(command, commandArgs);
+    return spawn(resolved.command, resolved.args, { ...options, detached: resolved.detached });
+}
+function getArgValue(args, name) {
+    const prefix = `--${name}=`;
+    return args.find((arg) => arg.startsWith(prefix))?.slice(prefix.length) ?? null;
+}
+function getSelectedApps(runtime, args) {
+    const appsArg = getArgValue(args, 'apps');
+    if (!appsArg)
+        return [...(runtime.config.devWatch?.defaultApps ?? [])];
+    return appsArg.split(',').map((app) => app.trim()).filter(Boolean);
+}
+function checkPortAvailability(port, host) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.unref();
+        server.once('error', (error) => resolve({ available: false, error, host, port }));
+        server.listen({ host, port }, () => {
+            server.close((error) => resolve({ available: !error, error: error ?? undefined, host, port }));
+        });
+    });
+}
+function getPortFromEndpoint(endpoint) {
+    const bracketedIpv6Match = endpoint.match(/\]:(\d+)$/u);
+    if (bracketedIpv6Match)
+        return Number(bracketedIpv6Match[1]);
+    const separatorIndex = endpoint.lastIndexOf(':');
+    if (separatorIndex === -1)
+        return null;
+    const port = Number(endpoint.slice(separatorIndex + 1));
+    return Number.isInteger(port) ? port : null;
+}
+export function parseWindowsNetstatListeningPids(output, port) {
+    const pids = new Set();
+    for (const line of String(output ?? '').split(/\r?\n/u)) {
+        const parts = line.trim().split(/\s+/u);
+        if (parts.length < 4 || parts[0] !== 'TCP')
+            continue;
+        const state = parts[parts.length - 2];
+        const pid = Number(parts[parts.length - 1]);
+        if (state === 'LISTENING' && Number.isInteger(pid) && getPortFromEndpoint(parts[1]) === port) {
+            pids.add(pid);
+        }
+    }
+    return [...pids].sort((left, right) => left - right);
+}
+function listListeningPidsByPort(port) {
+    if (isWindows) {
+        for (const command of ['netstat.exe', 'netstat']) {
+            const result = spawnSync(command, ['-ano', '-p', 'tcp'], { encoding: 'utf8', windowsHide: true });
+            if (!result.error && result.status === 0)
+                return parseWindowsNetstatListeningPids(result.stdout, port);
+        }
+        return [];
+    }
+    const result = spawnSync('lsof', ['-ti', `TCP:${port}`, '-sTCP:LISTEN'], { encoding: 'utf8', windowsHide: true });
+    if (result.error || result.status !== 0)
+        return [];
+    return result.stdout.split(/\r?\n/u).map((value) => Number(value.trim())).filter((pid) => Number.isInteger(pid));
+}
+function stopProcessTree(pid) {
+    if (isWindows) {
+        const result = spawnSync('taskkill.exe', ['/pid', String(pid), '/t', '/f'], { stdio: 'pipe', windowsHide: true });
+        return !result.error && result.status === 0;
+    }
+    try {
+        process.kill(pid, 'SIGTERM');
+        return true;
+    }
+    catch (error) {
+        return error.code === 'ESRCH';
+    }
+}
+async function stopExistingListenersOnPort(port, displayName, graceMs) {
+    const pids = listListeningPidsByPort(port);
+    if (pids.length === 0)
+        return [];
+    console.warn(`Stopping existing ${displayName} listener(s) on port ${port}: PID ${pids.join(', ')}`);
+    for (const pid of pids)
+        stopProcessTree(pid);
+    await new Promise((resolve) => setTimeout(resolve, graceMs));
+    return listListeningPidsByPort(port);
+}
+async function ensurePortsAvailable(apps, host) {
+    const results = await Promise.all(apps.map(async ({ key, definition }) => ({
+        key,
+        definition,
+        probe: await checkPortAvailability(definition.port, host),
+    })));
+    const blockedApps = results.filter(({ probe }) => !probe.available);
+    if (blockedApps.length === 0)
+        return true;
+    console.error('DEV port preflight failed.\n');
+    for (const { definition, probe } of blockedApps) {
+        const reason = probe.error?.code ?? probe.error?.message ?? 'unknown error';
+        console.error(`- ${definition.displayName}: ${probe.host}:${probe.port} (${reason})`);
+    }
+    return false;
+}
+function stopChildTree(child) {
+    if (child.exitCode !== null || child.signalCode !== null || typeof child.pid !== 'number')
+        return;
+    if (isWindows) {
+        spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { stdio: 'ignore', windowsHide: true });
+        return;
+    }
+    try {
+        process.kill(-child.pid, 'SIGTERM');
+    }
+    catch {
+        child.kill('SIGTERM');
+    }
+}
+function runWatch(runtime, selectedApps, silent) {
+    const children = [];
+    let shuttingDown = false;
+    function shutdown(exitCode) {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        for (const child of children)
+            stopChildTree(child);
+        process.exitCode = exitCode;
+    }
+    for (const { key, definition } of selectedApps) {
+        if (!definition.filter)
+            throw new Error(`devWatch app "${key}" must define filter to run watch mode.`);
+        const extraArgs = silent ? ['--', '--logLevel', 'warn'] : [];
+        const commandSpec = buildPackageManagerCommand(runtime.config.packageManager, ['--filter', definition.filter, 'run', 'dev:skip-check', ...extraArgs]);
+        const child = spawnCommand(commandSpec.command, commandSpec.args ?? [], { stdio: 'inherit', cwd: runtime.cwd });
+        children.push(child);
+        child.on('error', (error) => {
+            console.error(`[${key.toUpperCase()}] ${error.message}`);
+            shutdown(1);
+        });
+        child.on('exit', (code, signal) => {
+            if (shuttingDown)
+                return;
+            const exitCode = code ?? (signal ? 1 : 0);
+            if (exitCode !== 0)
+                console.error(`[${key.toUpperCase()}] exited with ${signal ?? code}`);
+            shutdown(exitCode);
+        });
+    }
+    process.on('SIGINT', () => shutdown(130));
+    process.on('SIGTERM', () => shutdown(143));
+}
+export async function runDevWatch(runtime, rawArgs) {
+    const config = runtime.config.devWatch;
+    if (!config?.apps || !config.defaultApps?.length)
+        throw new Error('devWatch.apps and devWatch.defaultApps are not configured.');
+    const silent = rawArgs.includes('--silent');
+    const checkOnly = rawArgs.includes('--check-only');
+    const includeBackend = rawArgs.includes('--include-backend');
+    const backendApp = config.backendApp ?? 'backend';
+    const selectedKeys = [...(includeBackend && checkOnly ? [backendApp] : []), ...getSelectedApps(runtime, rawArgs)];
+    const unknownApps = selectedKeys.filter((app) => !config.apps[app]);
+    if (unknownApps.length > 0)
+        throw new Error(`Unknown dev app(s): ${unknownApps.join(', ')}`);
+    const selectedApps = selectedKeys.map((key) => ({ key, definition: config.apps[key] }));
+    if (checkOnly && selectedKeys.includes(backendApp)) {
+        const backend = config.apps[backendApp];
+        const remainingPids = await stopExistingListenersOnPort(backend.port, backend.displayName, config.backendPortCleanupGraceMs ?? 1500);
+        if (remainingPids.length > 0) {
+            throw new Error(`Could not stop existing ${backend.displayName} listener(s) on port ${backend.port}: PID ${remainingPids.join(', ')}`);
+        }
+    }
+    const portsAvailable = await ensurePortsAvailable(selectedApps, config.host ?? '127.0.0.1');
+    if (!portsAvailable)
+        process.exit(1);
+    if (checkOnly)
+        return;
+    runWatch(runtime, selectedApps.filter(({ key }) => key !== backendApp), silent);
+}

package/dist/environment.d.ts

@@ -0,0 +1,10 @@
+import type { WebToolkitCliConfig } from './config.js';
+type Runtime = {
+    cwd: string;
+    config: WebToolkitCliConfig;
+};
+export declare function readRequiredPnpmVersion(repoRoot: string): string;
+export declare function prepareCorepackPnpm(runtime: Runtime, repoRoot: string, version: string): void;
+export declare function runEnvBootstrap(runtime: Runtime): void;
+export declare function runEnvDoctor(runtime: Runtime): void;
+export {};

package/dist/environment.js

@@ -0,0 +1,172 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+function findRepoRoot(startDir) {
+    let currentDir = startDir;
+    while (true) {
+        if (fs.existsSync(path.join(currentDir, 'package.json')) && fs.existsSync(path.join(currentDir, 'pnpm-workspace.yaml')))
+            return currentDir;
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir)
+            throw new Error('Could not find repo root from the current working directory.');
+        currentDir = parentDir;
+    }
+}
+export function readRequiredPnpmVersion(repoRoot) {
+    const packageJson = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+    const packageManager = String(packageJson.packageManager || '');
+    if (!packageManager.startsWith('pnpm@'))
+        throw new Error(`Expected packageManager to start with pnpm@ but found ${JSON.stringify(packageManager)}.`);
+    const version = packageManager.slice('pnpm@'.length).trim();
+    if (!version || version.includes(' ') || version === 'latest' || version === '11') {
+        throw new Error(`packageManager must pin an exact pnpm version, but found ${JSON.stringify(packageManager)}.`);
+    }
+    return version;
+}
+function resolveNodeSiblingBinary(baseName) {
+    const binaryName = process.platform === 'win32' ? `${baseName}.cmd` : baseName;
+    const candidate = path.join(path.dirname(process.execPath), binaryName);
+    return fs.existsSync(candidate) ? candidate : binaryName;
+}
+function buildEnv(repoRoot, runtime) {
+    return {
+        ...process.env,
+        COREPACK_HOME: path.join(repoRoot, runtime.config.environment?.corepackHome ?? '.corepack'),
+    };
+}
+function spawnTool(command, args, repoRoot, runtime, options = {}) {
+    const useShell = process.platform === 'win32';
+    const direct = command === process.execPath || command.toLowerCase().endsWith('.exe');
+    if (!useShell || direct) {
+        return spawnSync(command, args, { cwd: repoRoot, env: buildEnv(repoRoot, runtime), shell: false, ...options });
+    }
+    return spawnSync([command, ...args].map(quoteForShell).join(' '), { cwd: repoRoot, env: buildEnv(repoRoot, runtime), shell: true, ...options });
+}
+function quoteForShell(value) {
+    if (/^[A-Za-z0-9_./:=+-]+$/u.test(value))
+        return value;
+    return `"${String(value).replace(/"/gu, '""')}"`;
+}
+function captureCommand(command, args, repoRoot, runtime) {
+    const result = spawnTool(command, args, repoRoot, runtime, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' });
+    if (result.status !== 0) {
+        const detail = String(result.stderr || result.stdout || '').trim();
+        throw new Error(`Command failed: ${command} ${args.join(' ')}${detail ? `\n${detail}` : ''}`);
+    }
+    return String(result.stdout).trim();
+}
+function runCommand(command, args, repoRoot, runtime) {
+    const result = spawnTool(command, args, repoRoot, runtime, { stdio: 'inherit' });
+    if (result.status !== 0)
+        throw new Error(`Command failed: ${command} ${args.join(' ')}`);
+}
+function assertNodeMajor(runtime) {
+    const required = runtime.config.environment?.requiredNodeMajor;
+    if (!required)
+        return;
+    const major = Number(process.versions.node.split('.')[0]);
+    if (major !== required)
+        throw new Error(`Expected Node ${required}.x but found ${process.versions.node}.`);
+}
+function walkRepo(currentDir, onFile) {
+    for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+        if (['.git', 'node_modules', '.pnpm-store', '.turbo', 'dist'].includes(entry.name))
+            continue;
+        const entryPath = path.join(currentDir, entry.name);
+        if (entry.isDirectory())
+            walkRepo(entryPath, onFile);
+        else if (entry.isFile())
+            onFile(entryPath);
+    }
+}
+function readTrimmedFile(filePath) {
+    return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8').trim() : '';
+}
+export function prepareCorepackPnpm(runtime, repoRoot, version) {
+    if (!version || version.includes(' ') || version === 'latest' || version === '11') {
+        throw new Error(`packageManager must pin an exact pnpm version, but found ${JSON.stringify(`pnpm@${version}`)}.`);
+    }
+    const corepack = resolveNodeSiblingBinary('corepack');
+    runCommand(corepack, ['enable'], repoRoot, runtime);
+    runCommand(corepack, ['prepare', `pnpm@${version}`, '--activate'], repoRoot, runtime);
+}
+export function runEnvBootstrap(runtime) {
+    const repoRoot = findRepoRoot(runtime.cwd);
+    const requiredPnpmVersion = readRequiredPnpmVersion(repoRoot);
+    const nodeInstallDir = path.dirname(process.execPath);
+    const npmCliPath = path.join(nodeInstallDir, 'node_modules', 'npm', 'bin', 'npm-cli.js');
+    assertNodeMajor(runtime);
+    if (!fs.existsSync(npmCliPath))
+        throw new Error(`npm CLI was not found under the active Node installation: ${npmCliPath}`);
+    const corepack = resolveNodeSiblingBinary('corepack');
+    if (!fs.existsSync(corepack)) {
+        console.info('Corepack was not found in the active Node installation. Installing it via npm...');
+        runCommand(process.execPath, [npmCliPath, 'install', '--global', '--force', 'corepack'], repoRoot, runtime);
+    }
+    prepareCorepackPnpm(runtime, repoRoot, requiredPnpmVersion);
+    console.info(`Node: ${process.versions.node}`);
+    console.info(`npm: ${captureCommand(process.execPath, [npmCliPath, '--version'], repoRoot, runtime)}`);
+    console.info(`pnpm: ${captureCommand(resolveNodeSiblingBinary('pnpm'), ['--version'], repoRoot, runtime)}`);
+    console.info(`node path: ${process.execPath}`);
+    console.info(`npm path: ${npmCliPath}`);
+    console.info(`pnpm path: ${resolveNodeSiblingBinary('pnpm')}`);
+    console.info(`repo root: ${repoRoot}`);
+}
+export function runEnvDoctor(runtime) {
+    const repoRoot = findRepoRoot(runtime.cwd);
+    const requiredNodeMajor = runtime.config.environment?.requiredNodeMajor;
+    const requiredPnpmVersion = readRequiredPnpmVersion(repoRoot);
+    const failures = [];
+    if (requiredNodeMajor && Number(process.versions.node.split('.')[0]) !== requiredNodeMajor) {
+        failures.push(`Expected Node ${requiredNodeMajor}.x but found ${process.versions.node}.`);
+    }
+    if (requiredNodeMajor && readTrimmedFile(path.join(repoRoot, '.nvmrc')) !== String(requiredNodeMajor)) {
+        failures.push(`.nvmrc must be ${requiredNodeMajor}.`);
+    }
+    if (requiredNodeMajor && readTrimmedFile(path.join(repoRoot, '.node-version')) !== String(requiredNodeMajor)) {
+        failures.push(`.node-version must be ${requiredNodeMajor}.`);
+    }
+    try {
+        const pnpmVersion = captureCommand(resolveNodeSiblingBinary('pnpm'), ['--version'], repoRoot, runtime);
+        if (pnpmVersion !== requiredPnpmVersion)
+            failures.push(`Expected pnpm ${requiredPnpmVersion} but found ${pnpmVersion}.`);
+    }
+    catch (error) {
+        failures.push(error.message);
+    }
+    const packageLockfiles = [];
+    const yarnLockfiles = [];
+    const extraPnpmLockfiles = [];
+    walkRepo(repoRoot, (filePath) => {
+        const relativePath = path.relative(repoRoot, filePath).split(path.sep).join('/');
+        const basename = path.basename(filePath);
+        if (basename === 'package-lock.json')
+            packageLockfiles.push(relativePath);
+        if (basename === 'yarn.lock')
+            yarnLockfiles.push(relativePath);
+        if (basename === 'pnpm-lock.yaml' && relativePath !== 'pnpm-lock.yaml')
+            extraPnpmLockfiles.push(relativePath);
+    });
+    if (packageLockfiles.length > 0)
+        failures.push(`Unexpected package-lock.json files: ${packageLockfiles.join(', ')}`);
+    if (yarnLockfiles.length > 0)
+        failures.push(`Unexpected yarn.lock files: ${yarnLockfiles.join(', ')}`);
+    if (extraPnpmLockfiles.length > 0)
+        failures.push(`Unexpected nested pnpm-lock.yaml files: ${extraPnpmLockfiles.join(', ')}`);
+    let currentDir = path.dirname(repoRoot);
+    while (true) {
+        const parentNodeModules = path.join(currentDir, 'node_modules');
+        if (fs.existsSync(parentNodeModules))
+            failures.push(`Parent node_modules detected outside repo root: ${parentNodeModules}`);
+        const nextDir = path.dirname(currentDir);
+        if (nextDir === currentDir)
+            break;
+        currentDir = nextDir;
+    }
+    if (failures.length > 0) {
+        for (const failure of failures)
+            console.error(`- ${failure}`);
+        process.exit(1);
+    }
+    console.info('Environment doctor passed.');
+}

package/dist/guard-registry.d.ts

@@ -0,0 +1 @@
+export declare const builtinGuards: Readonly<Record<string, string>>;

package/dist/guard-registry.js

@@ -0,0 +1,17 @@
+export const builtinGuards = {
+    any: 'any-guard.js',
+    'assert-no-tests-in-dist': 'assert-no-tests-in-dist.js',
+    'code-pattern': 'code-pattern-guard.js',
+    'dal-service-repository': 'dal-service-repository-check.js',
+    'dependency-cruiser': 'dependency-cruiser-guard.js',
+    documentation: 'documentation-guard.js',
+    'internal-link': 'internal-link-guard.js',
+    mojibake: 'check-mojibake.js',
+    'package-surface': 'package-surface-guard.js',
+    'rebuild-preflight': 'rebuild-preflight.js',
+    'repository-hygiene': 'repository-hygiene-guard.js',
+    schema: 'schema-guard.js',
+    'singleton-deps': 'singleton-deps-guard.js',
+    tsconfig: 'tsconfig-guard.js',
+    'workspace-manifest': 'workspace-manifest-guard.js',
+};

package/dist/guard-runner.d.ts

@@ -0,0 +1,4 @@
+export { builtinGuards } from './guard-registry.js';
+export declare function printGuardHelp(): void;
+export declare function executeBuiltinGuard(name: string, args: string[], cwd: string): number;
+export declare function runBuiltinGuard(name: string, args: string[], cwd: string): void;

package/dist/guard-runner.js

@@ -0,0 +1,36 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { builtinGuards } from './guard-registry.js';
+export { builtinGuards } from './guard-registry.js';
+function getGuardsDir() {
+    return path.join(path.dirname(fileURLToPath(import.meta.url)), 'guards');
+}
+export function printGuardHelp() {
+    console.info('Usage: webtoolkit guard <name> [args]');
+    console.info('');
+    console.info('Builtin guards:');
+    for (const name of Object.keys(builtinGuards).sort()) {
+        console.info(`  ${name}`);
+    }
+}
+export function executeBuiltinGuard(name, args, cwd) {
+    const guardFile = Object.hasOwn(builtinGuards, name) ? builtinGuards[name] : undefined;
+    if (!guardFile) {
+        throw new Error(`Unknown builtin guard "${name}". Available guards: ${Object.keys(builtinGuards).sort().join(', ')}.`);
+    }
+    const result = spawnSync(process.execPath, [path.join(getGuardsDir(), guardFile), ...args], {
+        cwd,
+        env: {
+            ...process.env,
+            FORCE_COLOR: '1',
+        },
+        stdio: 'inherit',
+    });
+    if (result.error)
+        throw result.error;
+    return result.status ?? 1;
+}
+export function runBuiltinGuard(name, args, cwd) {
+    process.exit(executeBuiltinGuard(name, args, cwd));
+}

package/dist/guards/any-guard.d.ts

@@ -0,0 +1,16 @@
+import { Project } from 'ts-morph';
+import type { AnyGuardConfig } from '../config.js';
+export type AnyOccurrence = {
+    line: number;
+    column: number;
+    context: string;
+};
+export type AnyFileReport = {
+    filePath: string;
+    occurrences: AnyOccurrence[];
+};
+export declare function findAnyOccurrences(filePath: string, project: Project): AnyOccurrence[];
+export declare function runAnyGuard(options?: {
+    rootDir?: string;
+    config?: AnyGuardConfig;
+}): Promise<number>;

package/dist/guards/any-guard.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Node, Project, SyntaxKind } from 'ts-morph';
+import { BASE_SOURCE_EXCLUDE_PATTERNS, BASE_SOURCE_EXTENSIONS, assertConfiguredScanScope, compilePatterns, hasExtension, isMainModule, loadGuardConfig, resolveProjectPath, } from './guard-config.js';
+const colors = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+};
+function normalizedRelativePath(rootDir, filePath) {
+    return path.relative(rootDir, filePath).replaceAll('\\', '/');
+}
+function isExcluded(rootDir, filePath, patterns) {
+    const relativePath = normalizedRelativePath(rootDir, filePath);
+    return patterns.some((pattern) => pattern.test(relativePath));
+}
+function collectFiles(rootDir, config, excludePatterns) {
+    const files = [];
+    function walk(directory) {
+        if (!fs.existsSync(directory) || !fs.statSync(directory).isDirectory())
+            return;
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            const fullPath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (!isExcluded(rootDir, fullPath, excludePatterns))
+                    walk(fullPath);
+            }
+            else if (entry.isFile() &&
+                hasExtension(fullPath, BASE_SOURCE_EXTENSIONS) &&
+                !isExcluded(rootDir, fullPath, excludePatterns)) {
+                files.push(fullPath);
+            }
+        }
+    }
+    for (const includePath of config.includePaths) {
+        walk(resolveProjectPath(rootDir, includePath));
+    }
+    return files.sort();
+}
+function isInsideJsDoc(node) {
+    return node.getAncestors().some((ancestor) => ancestor.getKindName().startsWith('JSDoc'));
+}
+function isAllowed(node) {
+    for (const ancestor of node.getAncestors()) {
+        if (Node.isJSDocable(ancestor)) {
+            return ancestor.getJsDocs().some((doc) => doc.getText().includes('@anyAllowed'));
+        }
+    }
+    /* v8 ignore next -- parsed nodes always reach a JSDocable source ancestor */
+    return false;
+}
+export function findAnyOccurrences(filePath, project) {
+    const sourceFile = project.addSourceFileAtPath(filePath);
+    const seenPositions = new Set();
+    const occurrences = [];
+    for (const node of sourceFile.getDescendantsOfKind(SyntaxKind.AnyKeyword)) {
+        const position = node.getStart();
+        if (seenPositions.has(position) || isInsideJsDoc(node) || isAllowed(node))
+            continue;
+        seenPositions.add(position);
+        const location = sourceFile.getLineAndColumnAtPos(position);
+        occurrences.push({
+            line: location.line,
+            column: location.column,
+            context: node.getParentOrThrow().getText().replace(/\s+/gu, ' ').slice(0, 120),
+        });
+    }
+    return occurrences;
+}
+export async function runAnyGuard(options = {}) {
+    const rootDir = options.rootDir ?? process.cwd();
+    const config = options.config ?? await loadGuardConfig('any', rootDir);
+    const excludePatterns = compilePatterns(config.excludePatterns, BASE_SOURCE_EXCLUDE_PATTERNS);
+    const files = collectFiles(rootDir, config, excludePatterns);
+    assertConfiguredScanScope({
+        root: rootDir,
+        guardName: 'any',
+        configPath: 'guards.any.includePaths',
+        configuredPaths: config.includePaths,
+        eligibleFiles: files,
+    });
+    console.info(`${colors.bright}${colors.blue}🔍 Running TypeScript any guard...${colors.reset}`);
+    console.info(`${colors.cyan}   • Paths: ${config.includePaths.join(', ')}${colors.reset}`);
+    const project = new Project({ skipAddingFilesFromTsConfig: true });
+    const reports = [];
+    for (const filePath of files) {
+        const occurrences = findAnyOccurrences(filePath, project);
+        if (occurrences.length > 0) {
+            reports.push({
+                filePath: normalizedRelativePath(rootDir, filePath),
+                occurrences,
+            });
+        }
+    }
+    if (reports.length === 0) {
+        console.info(`${colors.green}${colors.bright}✨ Success! No forbidden 'any' usage found outside excluded files.${colors.reset}`);
+        return 0;
+    }
+    const total = reports.reduce((sum, report) => sum + report.occurrences.length, 0);
+    console.error(`${colors.bright}${colors.red}Forbidden 'any' usage found (${total} total):${colors.reset}`);
+    for (const report of reports) {
+        for (const occurrence of report.occurrences) {
+            console.error(`${colors.gray}${report.filePath}:${occurrence.line}:${occurrence.column}${colors.reset} ${occurrence.context}`);
+        }
+    }
+    return 1;
+}
+/* v8 ignore start -- executable adapter */
+if (isMainModule(import.meta.url)) {
+    runAnyGuard().then((code) => {
+        process.exitCode = code;
+    }).catch((error) => {
+        console.error(error.message);
+        process.exitCode = 1;
+    });
+}
+/* v8 ignore stop */

package/dist/guards/assert-no-tests-in-dist.d.ts

@@ -0,0 +1 @@
+export declare function runNoTestsInDist(inputDirs?: string[], rootDir?: string): Promise<number>;

package/dist/guards/assert-no-tests-in-dist.js

@@ -0,0 +1,56 @@
+import { readdir } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import { isMainModule } from './guard-config.js';
+const forbiddenPattern = /(^|\/)__tests__(\/|$)|\.(test|spec)\.(cjs|mjs|js|jsx|ts|tsx|cts|mts|d\.ts)$/i;
+async function collectFilesRecursively(dir, rootDir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const absolutePath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await collectFilesRecursively(absolutePath, rootDir)));
+            continue;
+        }
+        /* v8 ignore next -- non-file directory entries are intentionally ignored */
+        if (!entry.isFile())
+            continue;
+        const rel = relative(rootDir, absolutePath).replaceAll('\\', '/');
+        files.push(rel);
+    }
+    return files;
+}
+export async function runNoTestsInDist(inputDirs = [], rootDir = process.cwd()) {
+    const outputDirs = inputDirs.length > 0 ? inputDirs : ['dist'];
+    let hasViolations = false;
+    for (const outputDir of outputDirs) {
+        const absoluteOutputDir = resolve(rootDir, outputDir);
+        let files = [];
+        try {
+            files = await collectFilesRecursively(absoluteOutputDir, absoluteOutputDir);
+        }
+        catch (error) {
+            hasViolations = true;
+            console.error(`[dist-check] Could not read ${outputDir}: ${String(error)}`);
+            continue;
+        }
+        const violations = files.filter((file) => forbiddenPattern.test(file));
+        if (violations.length === 0)
+            continue;
+        hasViolations = true;
+        console.error(`[dist-check] Found test artifacts in ${outputDir}:`);
+        for (const file of violations) {
+            console.error(`  - ${file}`);
+        }
+    }
+    return hasViolations ? 1 : 0;
+}
+/* v8 ignore start -- executable adapter */
+if (isMainModule(import.meta.url)) {
+    runNoTestsInDist(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    }).catch((error) => {
+        console.error(error.message);
+        process.exitCode = 1;
+    });
+}
+/* v8 ignore stop */