@rtorcato/js-tooling 2.8.1 → 2.10.0

package/dist/cli/commands/doctor.js

@@ -231,6 +231,100 @@ async function checkHusky(dir, pkg) {
         hint: 'Run `pnpm add -D husky && pnpm exec husky init` to enable git hooks',
     };
 }
+async function checkHuskyPrePush(dir, pkg) {
+    const huskyDir = await fs.pathExists(path.join(dir, '.husky'));
+    if (!huskyDir) {
+        // If husky isn't in use, pre-push is not relevant
+        return {
+            check: 'Husky pre-push',
+            status: 'optional-missing',
+            detail: 'husky not configured',
+            hint: 'Run `npx @rtorcato/js-tooling fix husky` to enable git hooks (includes pre-push)',
+        };
+    }
+    const hookPath = path.join(dir, '.husky', 'pre-push');
+    if (!(await fs.pathExists(hookPath))) {
+        return {
+            check: 'Husky pre-push',
+            status: 'optional-missing',
+            detail: 'no .husky/pre-push',
+            hint: 'Run `npx @rtorcato/js-tooling fix husky` to scaffold a pre-push hook that runs `pnpm verify`',
+        };
+    }
+    const contents = await fs.readFile(hookPath, 'utf-8');
+    if (/\bpnpm\s+verify\b/.test(contents)) {
+        return {
+            check: 'Husky pre-push',
+            status: 'ok',
+            detail: '.husky/pre-push runs `pnpm verify`',
+        };
+    }
+    // Pre-push exists but doesn't call pnpm verify
+    const scripts = pkg?.scripts ?? {};
+    if (!scripts.verify) {
+        return {
+            check: 'Husky pre-push',
+            status: 'drift',
+            detail: '.husky/pre-push exists but no `verify` script in package.json',
+            hint: 'Run `npx @rtorcato/js-tooling fix verify` to add a verify script, then `fix husky` to align the hook',
+        };
+    }
+    return {
+        check: 'Husky pre-push',
+        status: 'drift',
+        detail: '.husky/pre-push exists but does not call `pnpm verify`',
+        hint: 'Run `npx @rtorcato/js-tooling fix husky` to align the hook with `pnpm verify`',
+    };
+}
+async function checkVerifyScript(dir, pkg) {
+    if (!pkg) {
+        return {
+            check: 'verify script',
+            status: 'missing',
+            detail: 'no package.json',
+        };
+    }
+    const scripts = pkg.scripts ?? {};
+    const body = scripts.verify;
+    if (!body) {
+        return {
+            check: 'verify script',
+            status: 'optional-missing',
+            detail: 'no `verify` script in package.json',
+            hint: 'Run `npx @rtorcato/js-tooling fix verify` to add a unified `pnpm verify` script',
+        };
+    }
+    // Lenient: only flag drift when an enabled tool is clearly absent from the script body.
+    const deps = {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {}),
+    };
+    const missing = [];
+    if (scripts.typecheck && !/\btypecheck\b/.test(body))
+        missing.push('typecheck');
+    if ((scripts.check || deps['@biomejs/biome']) && !/\b(check|biome|lint)\b/.test(body)) {
+        missing.push('lint/check');
+    }
+    if ((deps.vitest || scripts.test) && !/(vitest|jest|test:e2e|pnpm\s+test)/.test(body)) {
+        missing.push('tests');
+    }
+    const hasTreeshakeApp = await fs.pathExists(path.join(dir, 'apps', 'treeshake-check', 'check.mjs'));
+    if (hasTreeshakeApp && !/\btreeshake\b/.test(body))
+        missing.push('treeshake');
+    if (missing.length > 0) {
+        return {
+            check: 'verify script',
+            status: 'drift',
+            detail: `\`verify\` script is missing: ${missing.join(', ')}`,
+            hint: 'Run `npx @rtorcato/js-tooling fix verify` to regenerate the verify chain',
+        };
+    }
+    return {
+        check: 'verify script',
+        status: 'ok',
+        detail: `\`verify\` = ${body}`,
+    };
+}
 const LINT_STAGED_FILES = [
     '.lintstagedrc',
     '.lintstagedrc.json',
@@ -485,6 +579,33 @@ async function checkCodeQL(dir) {
         hint: 'Run `npx @rtorcato/js-tooling fix codeql` to scaffold CodeQL security scanning',
     };
 }
+async function checkTreeshakeSetup(dir, pkg) {
+    const appCheckPath = path.join(dir, 'apps', 'treeshake-check', 'check.mjs');
+    if (await fs.pathExists(appCheckPath)) {
+        return {
+            check: 'Tree-shake check',
+            status: 'ok',
+            detail: 'apps/treeshake-check/check.mjs found',
+        };
+    }
+    // Only nudge libraries that actually claim tree-shaking via multi-subpath exports + sideEffects: false.
+    const exports = pkg?.exports ?? {};
+    const subpaths = Object.keys(exports).filter((k) => k !== '.' && k.startsWith('./') && !k.includes('*'));
+    const sideEffectsFree = pkg?.sideEffects === false;
+    if (subpaths.length < 2 || !sideEffectsFree) {
+        return {
+            check: 'Tree-shake check',
+            status: 'ok',
+            detail: 'not applicable (single-export or has side effects)',
+        };
+    }
+    return {
+        check: 'Tree-shake check',
+        status: 'optional-missing',
+        detail: `package exports ${subpaths.length} subpaths with sideEffects: false but no apps/treeshake-check/`,
+        hint: 'Run `npx @rtorcato/js-tooling fix treeshake-check` to scaffold an esbuild metafile assertion',
+    };
+}
 async function checkGitLabCI(dir) {
     for (const candidate of ['.gitlab-ci.yml', '.gitlab-ci.yaml']) {
         if (await fs.pathExists(path.join(dir, candidate))) {
@@ -516,6 +637,8 @@ export async function runDoctor(dir) {
     }
     results.push(await checkHusky(targetDir, pkg));
     results.push(await checkLintStaged(targetDir, pkg));
+    results.push(await checkVerifyScript(targetDir, pkg));
+    results.push(await checkHuskyPrePush(targetDir, pkg));
     results.push(await checkSemanticRelease(targetDir, pkg));
     results.push(await checkKnip(targetDir, pkg));
     results.push(await checkSizeLimit(targetDir, pkg));
@@ -523,6 +646,7 @@ export async function runDoctor(dir) {
     results.push(await checkDependabot(targetDir));
     results.push(await checkCodeQL(targetDir));
     results.push(await checkGitLabCI(targetDir));
+    results.push(await checkTreeshakeSetup(targetDir, pkg));
     return results;
 }
 const STATUS_ICONS = {

package/dist/cli/commands/fix-targets.js

@@ -11,9 +11,12 @@ export const FIX_TARGETS = {
     Commitlint: 'commitlint',
     Husky: 'husky',
     'lint-staged': 'husky',
+    'Husky pre-push': 'husky',
+    'verify script': 'verify',
     'semantic-release': 'semantic-release',
     knip: 'knip',
     'size-limit': 'size-limit',
+    'Tree-shake check': 'treeshake-check',
     'GitHub Actions': 'github-actions',
     Dependabot: 'dependabot',
     CodeQL: 'codeql',

package/dist/cli/commands/fix.js

@@ -3,10 +3,12 @@ import chalk from 'chalk';
 import fs from 'fs-extra';
 import inquirer from 'inquirer';
 import { generateSemanticReleaseConfig } from '../generators/build.js';
-import { generateCommitlintConfig, generateHuskyConfig } from '../generators/git.js';
+import { generateCommitlintConfig, generateHuskyConfig, generatePrePushHook, } from '../generators/git.js';
 import { generateGitHubActions } from '../generators/github-actions.js';
 import { generateESLintConfig, generatePrettierConfig } from '../generators/linting.js';
 import { ensureEnginesNode, generateEditorConfig, generateKnipConfig, generateNvmrc, generateSizeLimitConfig, } from '../generators/misc.js';
+import { composeVerifyScriptFromPkg } from '../generators/package-json.js';
+import { generateTreeshakeCheck, inferSubpathsFromExports } from '../generators/treeshake.js';
 import { generateCodeQLWorkflow, generateDependabotConfig } from '../generators/security.js';
 import { generateVitestConfig } from '../generators/testing.js';
 import { copyPreset } from '../utils/copy-preset.js';
@@ -124,9 +126,9 @@ const FIXERS = [
     },
     {
         target: 'husky',
-        description: 'Set up Husky + lint-staged',
-        appliesTo: ['Husky', 'lint-staged'],
-        outputs: ['.husky/pre-commit', 'package.json (lint-staged field)'],
+        description: 'Set up Husky + lint-staged (and a `pnpm verify` pre-push hook)',
+        appliesTo: ['Husky', 'lint-staged', 'Husky pre-push'],
+        outputs: ['.husky/pre-commit', '.husky/pre-push', 'package.json (lint-staged field)'],
         riskLevel: 'safe-merge',
         canFixDrift: true,
         async run({ targetDir, pkg }) {
@@ -137,7 +139,46 @@ const FIXERS = [
             const generated = updated['lint-staged'] ?? {};
             updated['lint-staged'] = { ...generated, ...existingLintStaged };
             await fs.writeJson(pkgPath, updated, { spaces: 2 });
-            return { filesWritten: ['.husky/pre-commit', 'package.json'] };
+            const filesWritten = ['.husky/pre-commit', 'package.json'];
+            const scripts = updated.scripts ?? {};
+            if (scripts.verify) {
+                await generatePrePushHook(targetDir);
+                filesWritten.push('.husky/pre-push');
+            }
+            return { filesWritten };
+        },
+    },
+    {
+        target: 'verify',
+        description: 'Add a unified `verify` script (typecheck && lint && tests) to package.json',
+        appliesTo: ['verify script'],
+        outputs: ['package.json (scripts.verify)'],
+        riskLevel: 'safe-merge',
+        canFixDrift: true,
+        async run({ targetDir, pkg }) {
+            const pkgPath = path.join(targetDir, 'package.json');
+            if (!pkg) {
+                console.log(chalk.yellow('   no package.json found — skipping'));
+                return { filesWritten: [] };
+            }
+            const includeTreeshake = await fs.pathExists(path.join(targetDir, 'apps', 'treeshake-check', 'check.mjs'));
+            const verify = composeVerifyScriptFromPkg(pkg, { includeTreeshake });
+            if (!verify) {
+                console.log(chalk.gray('   not enough tools enabled to compose a verify chain — skipping (need 2+ of typecheck/lint/tests)'));
+                return { filesWritten: [] };
+            }
+            const updated = { ...pkg };
+            const scripts = { ...(updated.scripts ?? {}) };
+            scripts.verify = verify;
+            if (includeTreeshake && !scripts.treeshake) {
+                scripts.treeshake = 'pnpm --filter=*treeshake-check run check';
+                if (!scripts.pretreeshake) {
+                    scripts.pretreeshake = scripts.build ? 'pnpm build' : 'echo "no build step"';
+                }
+            }
+            updated.scripts = scripts;
+            await fs.writeJson(pkgPath, updated, { spaces: 2 });
+            return { filesWritten: ['package.json'] };
         },
     },
     {
@@ -242,6 +283,43 @@ const FIXERS = [
             return { filesWritten: ['.size-limit.json'] };
         },
     },
+    {
+        target: 'treeshake-check',
+        description: 'Scaffold apps/treeshake-check — esbuild + metafile assertion that one subpath bundles cleanly',
+        appliesTo: ['Tree-shake check'],
+        outputs: [
+            'apps/treeshake-check/package.json',
+            'apps/treeshake-check/check.mjs',
+            'apps/treeshake-check/src/entry.ts',
+        ],
+        riskLevel: 'safe-add',
+        canFixDrift: false,
+        async run({ targetDir, pkg }) {
+            if (!pkg) {
+                console.log(chalk.yellow('   no package.json found — skipping'));
+                return { filesWritten: [] };
+            }
+            const workspaceName = pkg.name ?? null;
+            if (!workspaceName) {
+                console.log(chalk.yellow('   package.json has no `name` — skipping'));
+                return { filesWritten: [] };
+            }
+            const { allCandidates, defaultAllowed } = inferSubpathsFromExports(pkg);
+            if (allCandidates.length < 2 || !defaultAllowed) {
+                console.log(chalk.yellow('   package.json does not expose ≥2 subpath exports — tree-shake check needs multiple subpaths to be meaningful. Skipping.'));
+                return { filesWritten: [] };
+            }
+            const allowedSubpath = defaultAllowed;
+            const forbiddenSubpaths = allCandidates.filter((s) => s !== allowedSubpath);
+            const written = await generateTreeshakeCheck(targetDir, {
+                workspaceName,
+                allowedSubpath,
+                forbiddenSubpaths,
+            });
+            console.log(chalk.dim(`   Wired '${allowedSubpath}' as allowed; forbidden = [${forbiddenSubpaths.join(', ')}]. Edit apps/treeshake-check/check.mjs to tune.`));
+            return { filesWritten: written };
+        },
+    },
     {
         target: 'package-json',
         description: 'Add @rtorcato/js-tooling to devDependencies',

package/dist/cli/commands/setup-presets.js

@@ -127,9 +127,13 @@ export const CONFIG_SCHEMA = {
         semanticRelease: { type: 'boolean' },
         securityAutomation: { type: 'boolean' },
         bundler: { type: 'string', enum: ['tsup', 'esbuild', 'vite', 'none'] },
+        treeshakeCheck: { type: 'boolean' },
     },
 };
-const ALLOWED_KEYS = new Set(CONFIG_SCHEMA.required);
+const ALLOWED_KEYS = new Set([
+    ...CONFIG_SCHEMA.required,
+    ...Object.keys(CONFIG_SCHEMA.properties),
+]);
 export function validateProjectConfig(input) {
     const errors = [];
     if (typeof input !== 'object' || input === null || Array.isArray(input)) {
@@ -188,6 +192,9 @@ export function computeFileList(config) {
         files.push('vite.config.ts');
     if (config.semanticRelease)
         files.push('release.config.mjs');
+    if (config.treeshakeCheck && config.projectType === 'library') {
+        files.push('apps/treeshake-check/package.json', 'apps/treeshake-check/check.mjs', 'apps/treeshake-check/src/entry.ts');
+    }
     files.push('README.md');
     return files;
 }

package/dist/cli/commands/setup.js

@@ -188,6 +188,13 @@ async function promptForConfig() {
             default: (answers) => answers.projectType === 'library',
             when: (answers) => answers.projectType === 'library',
         },
+        {
+            type: 'confirm',
+            name: 'treeshakeCheck',
+            message: '🌳 Add a tree-shake verification check (apps/treeshake-check)?',
+            default: false,
+            when: (answers) => answers.projectType === 'library',
+        },
         {
             type: 'confirm',
             name: 'securityAutomation',
@@ -239,6 +246,7 @@ async function promptForConfig() {
         semanticRelease: answers.semanticRelease || false,
         securityAutomation: answers.securityAutomation ?? false,
         bundler: answers.bundler || 'none',
+        treeshakeCheck: answers.treeshakeCheck || false,
     };
 }
 function showNextSteps(config, _targetDir) {
@@ -290,6 +298,9 @@ function collectSkippedFixSuggestions(config) {
     if (config.testing.framework === 'none') {
         suggestions.push('Run `npx @rtorcato/js-tooling fix vitest` to add a test runner');
     }
+    if (config.projectType === 'library' && !config.treeshakeCheck) {
+        suggestions.push('Run `npx @rtorcato/js-tooling fix treeshake-check` to add an esbuild-based tree-shake assertion');
+    }
     suggestions.push('Run `npx @rtorcato/js-tooling doctor` any time to audit drift');
     return suggestions;
 }

package/dist/cli/generators/git.js

@@ -1,5 +1,14 @@
 import fs from 'fs-extra';
 import path from 'node:path';
+export const PRE_PUSH_HOOK_CONTENT = `echo "🔍 Running pre-push verify..."
+pnpm verify
+STATUS=$?
+if [ $STATUS -ne 0 ]; then
+  echo "❌ Verify failed — push aborted."
+  exit 1
+fi
+echo "✅ Verify passed — pushing."
+`;
 export async function generateGitConfigs(config, targetDir) {
     if (config.gitHooks) {
         await generateHuskyConfig(config, targetDir);
@@ -22,6 +31,18 @@ npx lint-staged
 `;
     await fs.writeFile(preCommitPath, preCommitContent);
     await fs.chmod(preCommitPath, 0o755);
+    // Pre-push hook — only when the package.json already has a `verify` script.
+    // In the setup flow, generatePackageJson runs before this and writes verify
+    // when 2+ tools are enabled. In the `fix husky` path, a pre-existing verify
+    // script is what unlocks the hook.
+    const pkgPath = path.join(targetDir, 'package.json');
+    if (await fs.pathExists(pkgPath)) {
+        const pkg = (await fs.readJson(pkgPath));
+        const scripts = pkg.scripts ?? {};
+        if (scripts.verify) {
+            await generatePrePushHook(targetDir);
+        }
+    }
     // Commit-msg hook (if commitlint is enabled)
     if (config.commitLint) {
         const commitMsgPath = path.join(huskyDir, 'commit-msg');
@@ -52,6 +73,13 @@ npx --no -- commitlint --edit $1
     };
     await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
 }
+export async function generatePrePushHook(targetDir) {
+    const huskyDir = path.join(targetDir, '.husky');
+    await fs.ensureDir(huskyDir);
+    const prePushPath = path.join(huskyDir, 'pre-push');
+    await fs.writeFile(prePushPath, PRE_PUSH_HOOK_CONTENT);
+    await fs.chmod(prePushPath, 0o755);
+}
 export async function generateCommitlintConfig(targetDir) {
     const commitlintConfigPath = path.join(targetDir, 'commitlint.config.mjs');
     const commitlintConfig = `export { default } from '@rtorcato/js-tooling/commitlint/config'

package/dist/cli/generators/index.js

@@ -10,6 +10,7 @@ import { generatePackageJson } from './package-json.js';
 import { generateReadme } from './readme.js';
 import { generateSecurityConfigs } from './security.js';
 import { generateTestingConfigs } from './testing.js';
+import { generateTreeshakeCheck, inferSubpathsFromExports } from './treeshake.js';
 import { generateTSConfig } from './tsconfig.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -45,6 +46,19 @@ export async function generateConfigs(config, targetDir) {
     if (config.bundler !== 'none') {
         await generateBuildConfigs(config, targetDir);
     }
+    // Tree-shake verification check (libraries only, when opted-in)
+    if (config.treeshakeCheck && config.projectType === 'library') {
+        const pkgPath = path.join(targetDir, 'package.json');
+        const pkg = (await fs.readJson(pkgPath));
+        const { allCandidates, defaultAllowed } = inferSubpathsFromExports(pkg);
+        if (defaultAllowed && allCandidates.length >= 2) {
+            await generateTreeshakeCheck(targetDir, {
+                workspaceName: config.projectName,
+                allowedSubpath: defaultAllowed,
+                forbiddenSubpaths: allCandidates.filter((s) => s !== defaultAllowed),
+            });
+        }
+    }
     // Generate README
     await generateReadme(config, targetDir);
     // Copy ts-reset if TypeScript is enabled

package/dist/cli/generators/package-json.js

@@ -6,6 +6,7 @@ export async function generatePackageJson(config, targetDir) {
     if (await fs.pathExists(packageJsonPath)) {
         existingPackageJson = await fs.readJson(packageJsonPath);
     }
+    const includeTreeshake = Boolean(config.treeshakeCheck && config.projectType === 'library');
     const packageJson = {
         name: config.projectName,
         version: '0.1.0',
@@ -13,7 +14,7 @@ export async function generatePackageJson(config, targetDir) {
         type: 'module',
         ...existingPackageJson,
         scripts: {
-            ...getScripts(config),
+            ...getScripts(config, { includeTreeshake }),
             ...existingPackageJson?.scripts,
         },
         dependencies: {
@@ -44,7 +45,7 @@ export async function generatePackageJson(config, targetDir) {
     }
     await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
 }
-function getScripts(config) {
+function getScripts(config, opts = {}) {
     const scripts = {};
     // TypeScript scripts
     if (config.typescript.enabled) {
@@ -99,8 +100,67 @@ function getScripts(config) {
     if (config.semanticRelease) {
         scripts['release'] = 'semantic-release';
     }
+    if (opts.includeTreeshake) {
+        scripts['pretreeshake'] = scripts['build'] ? 'pnpm build' : 'echo "no build step"';
+        scripts['treeshake'] = 'pnpm --filter=*treeshake-check run check';
+    }
+    const verify = composeVerifyScript(config, opts);
+    if (verify) {
+        scripts['verify'] = verify;
+    }
     return scripts;
 }
+export function composeVerifyScript(config, opts = {}) {
+    const cmds = [];
+    if (config.typescript.enabled)
+        cmds.push('pnpm typecheck');
+    if (config.linting.tool === 'biome' || config.linting.tool === 'both') {
+        cmds.push('pnpm check');
+    }
+    else if (config.linting.tool === 'eslint') {
+        cmds.push('pnpm lint');
+    }
+    if (config.testing.framework === 'vitest') {
+        cmds.push('pnpm exec vitest run');
+    }
+    else if (config.testing.framework === 'jest') {
+        cmds.push('pnpm test --ci');
+    }
+    else if (config.testing.framework === 'playwright') {
+        cmds.push('pnpm test:e2e');
+    }
+    if (opts.includeTreeshake)
+        cmds.push('pnpm treeshake');
+    return cmds.length >= 2 ? cmds.join(' && ') : null;
+}
+/**
+ * Derive the verify chain from a real package.json's scripts + deps.
+ * Used by `fix verify`, where we shouldn't assume tools beyond what the
+ * project actually has.
+ */
+export function composeVerifyScriptFromPkg(pkg, opts = {}) {
+    const scripts = pkg.scripts ?? {};
+    const deps = {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {}),
+    };
+    const cmds = [];
+    if (scripts.typecheck || deps.typescript)
+        cmds.push('pnpm typecheck');
+    if (scripts.check)
+        cmds.push('pnpm check');
+    else if (scripts.lint && !scripts.check)
+        cmds.push('pnpm lint');
+    if (deps.vitest)
+        cmds.push('pnpm exec vitest run');
+    else if (deps.jest)
+        cmds.push('pnpm test --ci');
+    else if (deps['@playwright/test'])
+        cmds.push('pnpm test:e2e');
+    if (opts.includeTreeshake)
+        cmds.push('pnpm treeshake');
+    return cmds.length >= 2 ? cmds.join(' && ') : null;
+}
 function getDependencies(config) {
     const deps = {};
     // TypeScript

package/dist/cli/generators/treeshake.js

@@ -0,0 +1,113 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+/**
+ * Inspect package.exports and return non-root subpath candidates (e.g. './foo' → 'foo').
+ * Skips '.', types-only entries, and wildcard patterns ('./*').
+ */
+export function inferSubpathsFromExports(pkg) {
+    const exports = pkg?.exports;
+    if (!exports || typeof exports !== 'object') {
+        return { allCandidates: [], defaultAllowed: null };
+    }
+    const candidates = [];
+    for (const key of Object.keys(exports)) {
+        if (key === '.' || !key.startsWith('./'))
+            continue;
+        if (key.includes('*'))
+            continue;
+        const trimmed = key.replace(/^\.\//, '');
+        if (!trimmed)
+            continue;
+        candidates.push(trimmed);
+    }
+    return {
+        allCandidates: candidates,
+        defaultAllowed: candidates[0] ?? null,
+    };
+}
+function renderCheckScript(opts) {
+    const allowed = JSON.stringify([opts.allowedSubpath]);
+    const forbidden = JSON.stringify(opts.forbiddenSubpaths, null, '\t');
+    return `import { build } from 'esbuild'
+
+const ALLOWED_MODULES = ${allowed}
+
+const FORBIDDEN_MODULES = ${forbidden}
+
+const result = await build({
+\tentryPoints: ['src/entry.ts'],
+\tbundle: true,
+\tformat: 'esm',
+\tplatform: 'browser',
+\tconditions: ['import', 'browser'],
+\twrite: false,
+\tmetafile: true,
+\tminify: false,
+})
+
+const inputs = Object.keys(result.metafile.inputs)
+const distInputs = inputs.filter((p) => p.includes('/dist/'))
+const leaks = distInputs.filter((p) =>
+\tFORBIDDEN_MODULES.some((m) => new RegExp(\`/dist/\${m}/\`).test(p))
+)
+const allowed = distInputs.filter((p) =>
+\tALLOWED_MODULES.some((m) => new RegExp(\`/dist/\${m}/\`).test(p))
+)
+
+const bundleBytes = result.outputFiles?.[0]?.contents.byteLength ?? 0
+
+console.log(\`Bundle size: \${bundleBytes} bytes\`)
+console.log(\`dist inputs in bundle (\${distInputs.length}):\`)
+for (const p of distInputs) console.log(\`  \${p}\`)
+
+if (leaks.length > 0) {
+\tconsole.error('\\n❌ Tree-shaking leak — forbidden modules in the bundle:')
+\tfor (const p of leaks) console.error(\`  \${p}\`)
+\tprocess.exit(1)
+}
+
+if (allowed.length === 0) {
+\tconsole.error(
+\t\t'\\n❌ Expected at least one allowed-subpath input — entry may have failed to resolve.'
+\t)
+\tprocess.exit(1)
+}
+
+console.log('\\n✅ Tree-shaking OK — only allowed inputs present.')
+`;
+}
+function renderEntry(workspaceName, allowedSubpath) {
+    return `export * from '${workspaceName}/${allowedSubpath}'\n`;
+}
+export async function generateTreeshakeCheck(targetDir, opts) {
+    const appDir = opts.appDir ?? 'apps/treeshake-check';
+    const root = path.join(targetDir, appDir);
+    await fs.ensureDir(path.join(root, 'src'));
+    const pkgName = `${opts.workspaceName.replace(/^@/, '').replace(/\//g, '-')}-treeshake-check`;
+    const packageJson = {
+        name: pkgName,
+        version: '0.0.0',
+        private: true,
+        type: 'module',
+        scripts: {
+            check: 'node check.mjs',
+        },
+        dependencies: {
+            [opts.workspaceName]: 'workspace:*',
+        },
+        devDependencies: {
+            esbuild: '^0.28.0',
+        },
+    };
+    const checkPath = path.join(root, 'check.mjs');
+    const entryPath = path.join(root, 'src', 'entry.ts');
+    const pkgPath = path.join(root, 'package.json');
+    await fs.writeJson(pkgPath, packageJson, { spaces: 2 });
+    await fs.writeFile(checkPath, renderCheckScript(opts));
+    await fs.writeFile(entryPath, renderEntry(opts.workspaceName, opts.allowedSubpath));
+    return [
+        path.join(appDir, 'package.json'),
+        path.join(appDir, 'check.mjs'),
+        path.join(appDir, 'src', 'entry.ts'),
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/js-tooling",
-	"version": "2.8.1",
+	"version": "2.10.0",
 	"description": "JavaScript and TypeScript tooling for Node.js, React, Next.js, and Vitest.",
 	"type": "module",
 	"keywords": [
@@ -63,6 +63,10 @@
 		"tooling/vitest/vitest.setup.d.mts",
 		"tooling/vitest/jsdom-shims.mjs",
 		"tooling/vitest/jsdom-shims.d.mts",
+		"tooling/tests/exports-resolution.mjs",
+		"tooling/tests/exports-resolution.d.mts",
+		"tooling/tests/ssr-safety.mjs",
+		"tooling/tests/ssr-safety.d.mts",
 		"tooling/tsup/index.ts",
 		"tooling/biome/biome.json",
 		"tooling/semantic-release/*.mjs",
@@ -142,6 +146,14 @@
 		"./semantic-release/docker": {
 			"types": "./tooling/semantic-release/docker.d.mts",
 			"import": "./tooling/semantic-release/docker.mjs"
+		},
+		"./tests/exports-resolution": {
+			"types": "./tooling/tests/exports-resolution.d.mts",
+			"import": "./tooling/tests/exports-resolution.mjs"
+		},
+		"./tests/ssr-safety": {
+			"types": "./tooling/tests/ssr-safety.d.mts",
+			"import": "./tooling/tests/ssr-safety.mjs"
 		}
 	},
 	"dependencies": {
@@ -158,7 +170,7 @@
 		"@eslint/js": "^9.38.0",
 		"@ianvs/prettier-plugin-sort-imports": "^4.4.2",
 		"@next/eslint-plugin-next": "^16.2.7",
-		"@playwright/test": "^1.56.1",
+		"@playwright/test": "^1.60.0",
 		"@semantic-release/changelog": "^6.0.3",
 		"@semantic-release/commit-analyzer": "^13.0.1",
 		"@semantic-release/exec": "^7.1.0",
@@ -168,7 +180,7 @@
 		"@semantic-release/release-notes-generator": "^14.1.1",
 		"@total-typescript/ts-reset": "0.6.1",
 		"@types/fs-extra": "^11.0.4",
-		"@types/node": "^25.9.1",
+		"@types/node": "^25.9.2",
 		"@typescript-eslint/eslint-plugin": "^8.46.2",
 		"@typescript-eslint/parser": "^8.46.2",
 		"@vitejs/plugin-react": "^5.1.0",

package/tooling/tests/exports-resolution.d.mts

@@ -0,0 +1,14 @@
+export interface ExportsResolutionTestOptions {
+	/** Absolute path to the package.json whose `exports` map will be validated. */
+	packageJsonPath: string
+	/** Absolute path to the source directory whose subfolders are cross-checked. */
+	srcDir: string
+	/** Folder names under `srcDir` to skip (e.g., `'tests'`, `'common'`). */
+	excludeDirs?: string[]
+}
+
+/**
+ * Asserts that a package.json `exports` map stays in sync with its source folders.
+ * Call from a Vitest test file; generates one describe block plus one it per folder.
+ */
+export function runExportsResolutionTest(options: ExportsResolutionTestOptions): void

package/tooling/tests/exports-resolution.mjs

@@ -0,0 +1,68 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Asserts that a package.json `exports` map stays in sync with its source folders.
+ *
+ * For every folder under `srcDir` (excluding `excludeDirs`), the package.json must
+ * expose a matching `./<name>` subpath export. Conversely, every subpath in the
+ * `exports` map (other than `.`) must point at a folder that exists in `srcDir`.
+ *
+ * Call this from a Vitest test file; it generates one `describe` block plus one
+ * `it` per folder, so failures pinpoint the drift.
+ *
+ * @example
+ * ```ts
+ * // src/tests/exports-resolution.test.ts
+ * import { fileURLToPath } from 'node:url'
+ * import { runExportsResolutionTest } from '@rtorcato/js-tooling/tests/exports-resolution'
+ *
+ * runExportsResolutionTest({
+ * 	packageJsonPath: fileURLToPath(new URL('../../package.json', import.meta.url)),
+ * 	srcDir: fileURLToPath(new URL('../', import.meta.url)),
+ * 	excludeDirs: ['tests'],
+ * })
+ * ```
+ *
+ * @param {object} options
+ * @param {string} options.packageJsonPath Absolute path to the package.json under test.
+ * @param {string} options.srcDir Absolute path to the source folder whose subdirectories should be cross-checked.
+ * @param {string[]} [options.excludeDirs] Folder names under `srcDir` to skip (e.g., `tests`, `common`).
+ */
+export function runExportsResolutionTest({ packageJsonPath, srcDir, excludeDirs = [] }) {
+	const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'))
+
+	if (!pkg.exports || typeof pkg.exports !== 'object') {
+		throw new Error(`exports-resolution: package.json at ${packageJsonPath} has no exports map`)
+	}
+
+	const exportSubpaths = new Set(
+		Object.keys(pkg.exports)
+			.filter((k) => k !== '.')
+			.map((k) => k.replace(/^\.\//, ''))
+	)
+
+	const excluded = new Set(excludeDirs)
+	const moduleDirs = readdirSync(srcDir, { withFileTypes: true })
+		.filter((d) => d.isDirectory() && !excluded.has(d.name))
+		.map((d) => d.name)
+		.sort()
+
+	describe('package.json exports map', () => {
+		it('has at least one module', () => {
+			expect(moduleDirs.length).toBeGreaterThan(0)
+		})
+
+		for (const dir of moduleDirs) {
+			it(`exposes ./${dir}`, () => {
+				expect(exportSubpaths.has(dir)).toBe(true)
+			})
+		}
+
+		it('has no exports entries pointing at missing src/ folders', () => {
+			const moduleDirSet = new Set(moduleDirs)
+			const orphans = [...exportSubpaths].filter((k) => !moduleDirSet.has(k))
+			expect(orphans).toEqual([])
+		})
+	})
+}

package/tooling/tests/ssr-safety.d.mts

@@ -0,0 +1,14 @@
+export interface SsrSafetyTestOptions {
+	/** Absolute path to the source directory. */
+	srcDir: string
+	/** Folder names under `srcDir` to skip (e.g., `'tests'`, `'common'`). */
+	excludeDirs?: string[]
+	/** Entry filename inside each folder. Default: `'index.ts'`. */
+	moduleEntry?: string
+}
+
+/**
+ * Asserts that every module folder under `srcDir` can be imported in a Node
+ * environment without throwing. Call from a Vitest test file.
+ */
+export function runSsrSafetyTest(options: SsrSafetyTestOptions): void

package/tooling/tests/ssr-safety.mjs

@@ -0,0 +1,53 @@
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Asserts that every module folder under `srcDir` can be imported in a Node
+ * environment without throwing (no DOM, no `window`, no `document`).
+ *
+ * For each folder under `srcDir` (excluding `excludeDirs`), the helper resolves
+ * `<srcDir>/<name>/<moduleEntry>` and `await import(...)` it. If the import
+ * throws or the module accesses a missing global at top level, the test fails.
+ *
+ * Use this as a contract test for libraries that promise SSR safety — i.e., that
+ * importing a module is always safe even when its underlying API isn't available.
+ *
+ * @example
+ * ```ts
+ * // src/tests/ssr-safety.test.ts (run with vitest --environment node)
+ * import { fileURLToPath } from 'node:url'
+ * import { runSsrSafetyTest } from '@rtorcato/js-tooling/tests/ssr-safety'
+ *
+ * runSsrSafetyTest({
+ * 	srcDir: fileURLToPath(new URL('../', import.meta.url)),
+ * 	excludeDirs: ['tests'],
+ * })
+ * ```
+ *
+ * @param {object} options
+ * @param {string} options.srcDir Absolute path to the source folder.
+ * @param {string[]} [options.excludeDirs] Folder names under `srcDir` to skip.
+ * @param {string} [options.moduleEntry] Entry filename inside each folder. Default: `'index.ts'`.
+ */
+export function runSsrSafetyTest({ srcDir, excludeDirs = [], moduleEntry = 'index.ts' }) {
+	const excluded = new Set(excludeDirs)
+	const moduleDirs = readdirSync(srcDir, { withFileTypes: true })
+		.filter((d) => d.isDirectory() && !excluded.has(d.name))
+		.map((d) => d.name)
+		.sort()
+
+	describe('SSR safety', () => {
+		it('has at least one module', () => {
+			expect(moduleDirs.length).toBeGreaterThan(0)
+		})
+
+		for (const dir of moduleDirs) {
+			it(`imports ./${dir}/${moduleEntry} without throwing`, async () => {
+				const moduleUrl = pathToFileURL(join(srcDir, dir, moduleEntry)).href
+				await expect(import(moduleUrl)).resolves.toBeDefined()
+			})
+		}
+	})
+}