@rtorcato/js-tooling 2.9.0 → 2.11.0

package/dist/cli/commands/doctor.js

@@ -1,7 +1,8 @@
 import path from 'node:path';
 import chalk from 'chalk';
 import fs from 'fs-extra';
-import { getFixTargetForCheck } from './fix-targets.js';
+import { LOCKFILE_VERSION, readLockfile } from '../utils/lockfile.js';
+import { declinedInLock, getFixTargetForCheck } from './fix-targets.js';
 const PACKAGE = '@rtorcato/js-tooling';
 const NODE_MIN_MAJOR = 22;
 const NODE_LTS_REQUIREMENTS = {
@@ -231,6 +232,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 +580,56 @@ 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',
+    };
+}
+function checkLockfile(lock) {
+    if (!lock) {
+        return {
+            check: 'lockfile',
+            status: 'optional-missing',
+            detail: 'no .js-tooling.json — doctor cannot tell intentional opt-outs from drift',
+            hint: 'Run `npx @rtorcato/js-tooling fix lockfile` to record current choices',
+        };
+    }
+    if (lock.version > LOCKFILE_VERSION) {
+        return {
+            check: 'lockfile',
+            status: 'drift',
+            detail: `.js-tooling.json version ${lock.version} is newer than this CLI supports (v${LOCKFILE_VERSION})`,
+            hint: 'Upgrade @rtorcato/js-tooling to a release that supports this lockfile version',
+        };
+    }
+    return {
+        check: 'lockfile',
+        status: 'ok',
+        detail: `.js-tooling.json v${lock.version} (written by ${lock.writtenBy})`,
+    };
+}
 async function checkGitLabCI(dir) {
     for (const candidate of ['.gitlab-ci.yml', '.gitlab-ci.yaml']) {
         if (await fs.pathExists(path.join(dir, candidate))) {
@@ -505,9 +650,11 @@ async function checkGitLabCI(dir) {
 export async function runDoctor(dir) {
     const targetDir = path.resolve(dir);
     const pkg = await readPackageJson(targetDir);
+    const lock = await readLockfile(targetDir);
     const results = [];
     results.push(evaluateNodeVersion(process.version));
     results.push(checkPackageJson(pkg));
+    results.push(checkLockfile(lock));
     results.push(checkEnginesNode(pkg));
     results.push(await checkEditorConfig(targetDir));
     results.push(await checkNodeVersionPin(targetDir));
@@ -516,6 +663,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 +672,22 @@ 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));
+    // Lockfile-driven demotion: if the lock records an intentional opt-out for a
+    // check that's currently optional-missing, demote it to ok with a clear detail.
+    if (lock) {
+        return results.map((r) => {
+            if (r.status !== 'optional-missing')
+                return r;
+            if (!declinedInLock(lock, r.check))
+                return r;
+            return {
+                check: r.check,
+                status: 'ok',
+                detail: 'intentionally declined (.js-tooling.json)',
+            };
+        });
+    }
     return results;
 }
 const STATUS_ICONS = {

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

@@ -11,13 +11,110 @@ 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',
+    lockfile: 'lockfile',
+    '.js-tooling.json': 'lockfile',
 };
 export function getFixTargetForCheck(checkName) {
     return FIX_TARGETS[checkName] ?? null;
 }
+/**
+ * For a given doctor check name, returns true when the lockfile records that
+ * the user intentionally opted out of the tool that check covers. Used by
+ * doctor to demote `optional-missing` to `ok` and by fix to print a conflict
+ * warning before overriding the recorded choice.
+ */
+export function declinedInLock(lock, checkName) {
+    if (!lock)
+        return false;
+    const c = lock.config;
+    switch (checkName) {
+        case 'TypeScript':
+            return c.typescript?.enabled === false;
+        case 'Biome':
+            return c.linting?.tool !== 'biome' && c.linting?.tool !== 'both';
+        case 'ESLint':
+            return c.linting?.tool !== 'eslint' && c.linting?.tool !== 'both';
+        case 'Prettier':
+            return c.formatting?.tool !== 'prettier';
+        case 'Vitest':
+            return c.testing?.framework !== 'vitest';
+        case 'Commitlint':
+            return c.commitLint === false;
+        case 'Husky':
+        case 'lint-staged':
+        case 'Husky pre-push':
+            return c.gitHooks === false;
+        case 'verify script':
+            // Verify is derived from other tools; only "declined" if none of typecheck/lint/test are enabled.
+            return (c.typescript?.enabled === false &&
+                c.linting?.tool === 'none' &&
+                c.testing?.framework === 'none');
+        case 'semantic-release':
+            return c.semanticRelease === false;
+        case 'Dependabot':
+        case 'CodeQL':
+            return c.securityAutomation === false;
+        default:
+            return false;
+    }
+}
+/**
+ * When a fixer is about to scaffold a tool, return the patch to apply to the
+ * lockfile's recorded choices so intent stays in sync with reality. Returns
+ * null when the target either doesn't change any recorded choice (e.g. the
+ * `verify` fixer is derived, or `engines` writes a universal field) or when
+ * the lockfile already reflects the change.
+ */
+export function lockfilePatchForTarget(target, lock) {
+    const c = lock.config;
+    switch (target) {
+        case 'biome':
+            if (c.linting.tool === 'biome' || c.linting.tool === 'both')
+                return null;
+            return {
+                linting: { tool: 'biome' },
+                formatting: { tool: 'biome' },
+            };
+        case 'eslint':
+            if (c.linting.tool === 'eslint' || c.linting.tool === 'both')
+                return null;
+            return {
+                linting: { tool: 'eslint', eslintConfig: c.linting.eslintConfig ?? 'base' },
+                formatting: { tool: 'prettier' },
+            };
+        case 'prettier':
+            if (c.formatting.tool === 'prettier')
+                return null;
+            return { formatting: { tool: 'prettier' } };
+        case 'vitest':
+            if (c.testing.framework === 'vitest')
+                return null;
+            return {
+                testing: { framework: 'vitest', environment: c.testing.environment ?? 'node' },
+            };
+        case 'commitlint':
+            return c.commitLint ? null : { commitLint: true };
+        case 'husky':
+            return c.gitHooks ? null : { gitHooks: true };
+        case 'semantic-release':
+            return c.semanticRelease ? null : { semanticRelease: true };
+        case 'dependabot':
+        case 'codeql':
+            return c.securityAutomation ? null : { securityAutomation: true };
+        case 'tsconfig':
+            return c.typescript.enabled ? null : { typescript: { enabled: true, config: 'base' } };
+        case 'treeshake-check':
+            return c.treeshakeCheck ? null : { treeshakeCheck: true };
+        default:
+            return null;
+    }
+}

package/dist/cli/commands/fix.js

@@ -3,14 +3,18 @@ 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 { generateCodeQLWorkflow, generateDependabotConfig } from '../generators/security.js';
 import { generateVitestConfig } from '../generators/testing.js';
+import { generateTreeshakeCheck, inferSubpathsFromExports } from '../generators/treeshake.js';
 import { copyPreset } from '../utils/copy-preset.js';
+import { LOCKFILE_NAME, readLockfile, updateLockfileConfig, writeLockfile, } from '../utils/lockfile.js';
 import { runDoctor } from './doctor.js';
+import { declinedInLock, lockfilePatchForTarget } from './fix-targets.js';
 function inferProjectConfig(pkg) {
     const deps = {
         ...(pkg?.dependencies ?? {}),
@@ -124,9 +128,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 +141,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 +285,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',
@@ -266,6 +346,23 @@ const FIXERS = [
             return { filesWritten: ['package.json'] };
         },
     },
+    {
+        target: 'lockfile',
+        description: `Scaffold ${LOCKFILE_NAME} recording current tool choices`,
+        appliesTo: ['lockfile'],
+        outputs: [LOCKFILE_NAME],
+        riskLevel: 'safe-add',
+        canFixDrift: false,
+        async run({ targetDir, pkg }) {
+            if (!pkg) {
+                console.log(chalk.yellow('   no package.json found — skipping'));
+                return { filesWritten: [] };
+            }
+            const config = inferProjectConfig(pkg);
+            await writeLockfile(targetDir, config);
+            return { filesWritten: [LOCKFILE_NAME] };
+        },
+    },
 ];
 export function getFixers() {
     return FIXERS;
@@ -283,17 +380,27 @@ function logTargets() {
         console.log(`  ${chalk.green('●')} ${chalk.bold(f.target)}: ${chalk.gray(f.description)}`);
     }
 }
-async function applyFixer(fixer, result, targetDir, pkg, dryRun, silent) {
+async function applyFixer(fixer, result, targetDir, pkg, lock, dryRun, silent) {
     if (dryRun) {
         if (!silent) {
             console.log(chalk.cyan(`  [dry-run] would write: ${fixer.outputs.join(', ')}`));
         }
         return { filesWritten: [], dryRun: true };
     }
-    const { filesWritten } = await fixer.run({ targetDir, pkg, result });
+    const { filesWritten } = await fixer.run({ targetDir, pkg, result, lock });
     if (!silent && filesWritten.length > 0) {
         console.log(chalk.green(`  ✅ wrote ${filesWritten.join(', ')}`));
     }
+    // Auto-resync the lockfile when a fix changes a recorded choice.
+    if (lock && fixer.target !== 'lockfile') {
+        const patch = lockfilePatchForTarget(fixer.target, lock);
+        if (patch) {
+            const ok = await updateLockfileConfig(targetDir, patch);
+            if (ok && !silent) {
+                console.log(chalk.dim(`     ↻ ${LOCKFILE_NAME} updated to reflect the new choice`));
+            }
+        }
+    }
     return { filesWritten, dryRun: false };
 }
 function promptMessageFor(fixer, result) {
@@ -322,8 +429,11 @@ async function confirmApply(fixer, result, assumeYes) {
     ]);
     return confirm === true;
 }
-function recordFor(target, check, doctorStatus, status, filesWritten) {
-    return { target, check, status, doctorStatus, filesWritten };
+function recordFor(target, check, doctorStatus, status, filesWritten, lockfileConflict = false) {
+    const base = { target, check, status, doctorStatus, filesWritten };
+    if (lockfileConflict)
+        base.lockfileConflict = true;
+    return base;
 }
 export async function fixCommand(target, options = {}) {
     const targetDir = path.resolve(options.directory ?? process.cwd());
@@ -333,8 +443,18 @@ export async function fixCommand(target, options = {}) {
     const assumeYes = options.yes === true || json;
     const silent = json;
     const pkg = await readPackageJson(targetDir);
+    const lock = await readLockfile(targetDir);
     const results = await runDoctor(targetDir);
     const actions = [];
+    const noteLockConflict = (check) => {
+        if (!lock)
+            return false;
+        const conflict = declinedInLock(lock, check);
+        if (conflict && !silent) {
+            console.log(chalk.yellow(`  ⚠ ${LOCKFILE_NAME} says this tool was declined — applying anyway will update the lockfile to reflect the new choice.`));
+        }
+        return conflict;
+    };
     const emitJson = (resolvedTarget) => {
         const payload = { directory: targetDir, target: resolvedTarget, actions };
         console.log(JSON.stringify(payload, null, 2));
@@ -358,7 +478,12 @@ export async function fixCommand(target, options = {}) {
         }
         const result = results.find((r) => fixer.appliesTo.includes(r.check)) ??
             { check: fixer.appliesTo[0] ?? fixer.target, status: 'missing', detail: '' };
-        if (result.status === 'ok') {
+        // A check that's `ok` because the lockfile records an opt-out should still be
+        // fixable when the user explicitly targets it — treat it as optional-missing
+        // so the override + lockfile resync paths run.
+        const lockfileDemoted = lock !== null && declinedInLock(lock, result.check);
+        const effectiveResult = result.status === 'ok' && lockfileDemoted ? { ...result, status: 'optional-missing' } : result;
+        if (effectiveResult.status === 'ok') {
             actions.push(recordFor(fixer.target, result.check, 'ok', 'already-ok', []));
             if (json)
                 return emitJson(fixer.target);
@@ -366,18 +491,19 @@ export async function fixCommand(target, options = {}) {
             return;
         }
         if (!silent) {
-            console.log(chalk.cyan(`\n🔧 ${fixer.target} — ${chalk.bold(result.check)} is ${result.status}\n`));
+            console.log(chalk.cyan(`\n🔧 ${fixer.target} — ${chalk.bold(result.check)} is ${effectiveResult.status}\n`));
         }
-        const ok = await confirmApply(fixer, result, assumeYes);
+        const conflict = noteLockConflict(result.check);
+        const ok = await confirmApply(fixer, effectiveResult, assumeYes);
         if (!ok) {
-            actions.push(recordFor(fixer.target, result.check, result.status, 'skipped', []));
+            actions.push(recordFor(fixer.target, result.check, effectiveResult.status, 'skipped', [], conflict));
             if (json)
                 return emitJson(fixer.target);
             console.log(chalk.gray('   skipped\n'));
             return;
         }
-        const outcome = await applyFixer(fixer, result, targetDir, pkg, dryRun, silent);
-        actions.push(recordFor(fixer.target, result.check, result.status, outcome.dryRun ? 'dry-run' : 'applied', outcome.filesWritten));
+        const outcome = await applyFixer(fixer, effectiveResult, targetDir, pkg, lock, dryRun, silent);
+        actions.push(recordFor(fixer.target, result.check, effectiveResult.status, outcome.dryRun ? 'dry-run' : 'applied', outcome.filesWritten, conflict));
         if (json)
             return emitJson(fixer.target);
         console.log();
@@ -408,16 +534,17 @@ export async function fixCommand(target, options = {}) {
         if (!silent) {
             console.log(`  ${chalk.bold(result.check)} (${result.status}) → ${fixer.target}`);
         }
+        const conflict = noteLockConflict(result.check);
         const ok = await confirmApply(fixer, result, assumeYes);
         if (!ok) {
-            actions.push(recordFor(fixer.target, result.check, result.status, 'skipped', []));
+            actions.push(recordFor(fixer.target, result.check, result.status, 'skipped', [], conflict));
             if (!silent)
                 console.log(chalk.gray('    skipped'));
             skippedCount++;
             continue;
         }
-        const outcome = await applyFixer(fixer, result, targetDir, pkg, dryRun, silent);
-        actions.push(recordFor(fixer.target, result.check, result.status, outcome.dryRun ? 'dry-run' : 'applied', outcome.filesWritten));
+        const outcome = await applyFixer(fixer, result, targetDir, pkg, lock, dryRun, silent);
+        actions.push(recordFor(fixer.target, result.check, result.status, outcome.dryRun ? 'dry-run' : 'applied', outcome.filesWritten, conflict));
         appliedCount++;
     }
     if (json)

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)) {
@@ -147,7 +151,7 @@ export function validateProjectConfig(input) {
     return { valid: errors.length === 0, errors };
 }
 export function computeFileList(config) {
-    const files = ['package.json'];
+    const files = ['package.json', '.js-tooling.json'];
     files.push('.editorconfig', '.nvmrc', 'knip.json');
     if (config.typescript.enabled) {
         files.push('tsconfig.json', 'reset.d.ts');
@@ -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

@@ -4,6 +4,7 @@ import fs from 'fs-extra';
 import inquirer from 'inquirer';
 import { generateConfigs } from '../generators/index.js';
 import { installDependencies } from '../utils/install.js';
+import { LOCKFILE_NAME, writeLockfile } from '../utils/lockfile.js';
 import { buildPresetConfig, computeFileList, CONFIG_SCHEMA, PRESET_NAMES, validateProjectConfig, } from './setup-presets.js';
 async function resolveConfig(options) {
     if (options.config && options.preset) {
@@ -55,6 +56,7 @@ export async function setupProject(options) {
         }
         console.log(chalk.cyan('\n📝 Generating configuration files...\n'));
         await generateConfigs(config, targetDir);
+        await writeLockfile(targetDir, config);
         if (!options.skipInstall) {
             console.log(chalk.cyan('\n📦 Installing dependencies...\n'));
             await installDependencies(config, targetDir);
@@ -188,6 +190,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 +248,7 @@ async function promptForConfig() {
         semanticRelease: answers.semanticRelease || false,
         securityAutomation: answers.securityAutomation ?? false,
         bundler: answers.bundler || 'none',
+        treeshakeCheck: answers.treeshakeCheck || false,
     };
 }
 function showNextSteps(config, _targetDir) {
@@ -256,6 +266,7 @@ function showNextSteps(config, _targetDir) {
     if (config.gitHooks) {
         steps.push('🪝 Commit your changes to test the git hooks');
     }
+    steps.push(`🔒 ${LOCKFILE_NAME} records your setup choices — doctor uses it to suppress intentional opt-outs`);
     steps.push('📖 Check the generated README.md for more details');
     steps.forEach((step, index) => {
         console.log(`  ${index + 1}. ${step}`);
@@ -290,6 +301,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/dist/cli/utils/lockfile.js

@@ -0,0 +1,54 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import packageJson from '../../../package.json' with { type: 'json' };
+import { validateProjectConfig } from '../commands/setup-presets.js';
+export const LOCKFILE_NAME = '.js-tooling.json';
+export const LOCKFILE_VERSION = 1;
+const LOCKFILE_SCHEMA_URL = 'https://rtorcato.github.io/js-tooling/schemas/lockfile.json';
+export async function readLockfile(dir) {
+    const filepath = path.join(dir, LOCKFILE_NAME);
+    if (!(await fs.pathExists(filepath)))
+        return null;
+    try {
+        const raw = (await fs.readJson(filepath));
+        if (typeof raw !== 'object' || raw === null)
+            return null;
+        const obj = raw;
+        if (typeof obj.version !== 'number')
+            return null;
+        if (typeof obj.config !== 'object' || obj.config === null)
+            return null;
+        return obj;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeLockfile(dir, config) {
+    const { valid, errors } = validateProjectConfig(config);
+    if (!valid) {
+        throw new Error(`Refusing to write invalid lockfile:\n  - ${errors.join('\n  - ')}`);
+    }
+    const filepath = path.join(dir, LOCKFILE_NAME);
+    const lockfile = {
+        $schema: LOCKFILE_SCHEMA_URL,
+        version: LOCKFILE_VERSION,
+        config,
+        writtenBy: `@rtorcato/js-tooling@${packageJson.version}`,
+        writtenAt: new Date().toISOString(),
+    };
+    await fs.writeJson(filepath, lockfile, { spaces: 2 });
+    return filepath;
+}
+/**
+ * Patch a subset of a lockfile's config in place, preserving everything else.
+ * Returns true when the file was rewritten, false when no lockfile exists.
+ */
+export async function updateLockfileConfig(dir, patch) {
+    const existing = await readLockfile(dir);
+    if (!existing)
+        return false;
+    const merged = { ...existing.config, ...patch };
+    await writeLockfile(dir, merged);
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/js-tooling",
-	"version": "2.9.0",
+	"version": "2.11.0",
 	"description": "JavaScript and TypeScript tooling for Node.js, React, Next.js, and Vitest.",
 	"type": "module",
 	"keywords": [
@@ -170,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",
@@ -180,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",
@@ -188,7 +188,7 @@
 		"commitizen": "^4.3.1",
 		"conventional-changelog-conventionalcommits": "^9.3.1",
 		"cz-conventional-changelog": "^3.3.0",
-		"esbuild": "^0.25.11",
+		"esbuild": "^0.28.0",
 		"esbuild-node-externals": "^1.22.0",
 		"eslint": "9.38.0",
 		"eslint-plugin-import": "^2.32.0",