@rtorcato/js-tooling 2.10.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 = {
@@ -606,6 +607,29 @@ async function checkTreeshakeSetup(dir, pkg) {
         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))) {
@@ -626,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));
@@ -647,6 +673,21 @@ export async function runDoctor(dir) {
     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

@@ -20,7 +20,101 @@ export const FIX_TARGETS = {
     '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

@@ -8,11 +8,13 @@ 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 { 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 ?? {}),
@@ -344,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;
@@ -361,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) {
@@ -400,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());
@@ -411,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));
@@ -436,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);
@@ -444,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();
@@ -486,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

@@ -151,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');

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);
@@ -264,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}`);

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.10.0",
+	"version": "2.11.0",
 	"description": "JavaScript and TypeScript tooling for Node.js, React, Next.js, and Vitest.",
 	"type": "module",
 	"keywords": [
@@ -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",