@rtorcato/js-tooling 2.17.1 → 2.18.0

package/dist/cli/commands/doctor.js

@@ -89,6 +89,24 @@ const FILE_CHECKS = [
         matcher: /@rtorcato\/js-tooling\/commitlint\/config/,
         optional: true,
     },
+    {
+        check: 'Oxlint',
+        candidates: ['.oxlintrc.json', 'oxlintrc.json'],
+        // Oxlint configs are project-owned (extends from npm packages isn't
+        // reliably supported), so any well-formed file counts as ok.
+        expected: 'is a valid Oxlint configuration',
+        matcher: /"(rules|plugins|categories|extends)"/,
+        optional: true,
+        hint: 'Run `npx @rtorcato/js-tooling copy oxlint` to scaffold',
+    },
+    {
+        check: 'Changesets',
+        candidates: ['.changeset/config.json'],
+        expected: 'is a valid Changesets configuration',
+        matcher: /"(changelog|access|baseBranch)"/,
+        optional: true,
+        hint: 'Run `npx @rtorcato/js-tooling copy changesets` to scaffold',
+    },
 ];
 async function checkFile(dir, spec) {
     for (const candidate of spec.candidates) {
@@ -451,7 +469,25 @@ async function checkSemanticRelease(dir, pkg) {
             break;
         }
     }
+    const hasChangesets = await fs.pathExists(path.join(dir, '.changeset', 'config.json'));
+    // Conflict: both semantic-release and Changesets configured.
+    if ((inPkg || configFile) && hasChangesets) {
+        return {
+            check: 'semantic-release',
+            status: 'drift',
+            detail: 'both semantic-release and Changesets are configured',
+            hint: 'Pick one release tool — remove either the semantic-release config or the .changeset/ directory',
+        };
+    }
     if (!inPkg && !configFile) {
+        // Changesets present — treat semantic-release as intentionally not used.
+        if (hasChangesets) {
+            return {
+                check: 'semantic-release',
+                status: 'ok',
+                detail: 'using Changesets (.changeset/config.json) instead',
+            };
+        }
         return {
             check: 'semantic-release',
             status: isPrivate ? 'optional-missing' : 'drift',

package/dist/cli/commands/fix.js

@@ -1,5 +1,7 @@
 import path from 'node:path';
+import os from 'node:os';
 import chalk from 'chalk';
+import { createPatch } from 'diff';
 import fs from 'fs-extra';
 import inquirer from 'inquirer';
 import { generateSemanticReleaseConfig } from '../generators/build.js';
@@ -202,6 +204,28 @@ const FIXERS = [
             return { filesWritten: ['release.config.mjs'] };
         },
     },
+    {
+        target: 'changesets',
+        description: 'Scaffold .changeset/config.json (alternative to semantic-release)',
+        appliesTo: ['Changesets'],
+        outputs: ['.changeset/config.json'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const result = await copyPreset('changesets', targetDir);
+            return { filesWritten: [result.target] };
+        },
+    },
+    {
+        target: 'oxlint',
+        description: 'Scaffold .oxlintrc.json (additive to Biome/ESLint)',
+        appliesTo: ['Oxlint'],
+        outputs: ['.oxlintrc.json'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            const result = await copyPreset('oxlint', targetDir);
+            return { filesWritten: [result.target] };
+        },
+    },
     {
         target: 'github-actions',
         description: 'Scaffold .github/workflows/ci.yml',
@@ -464,6 +488,117 @@ export function listFixers() {
         canFixDrift: f.canFixDrift ?? false,
     }));
 }
+// Fixer outputs sometimes carry annotations like
+// "package.json (lint-staged field)" — strip them to get a usable filesystem path.
+function outputToRelativePath(output) {
+    return output.split(' ')[0] ?? output;
+}
+function shouldColorise() {
+    // Respect NO_COLOR (https://no-color.org) and chalk's own detection.
+    if (process.env.NO_COLOR && process.env.NO_COLOR !== '')
+        return false;
+    return chalk.level > 0;
+}
+function colorisePatch(patch) {
+    if (!shouldColorise())
+        return patch;
+    return patch
+        .split('\n')
+        .map((line) => {
+        if (line.startsWith('+++') || line.startsWith('---'))
+            return chalk.bold(line);
+        if (line.startsWith('@@'))
+            return chalk.cyan(line);
+        if (line.startsWith('+'))
+            return chalk.green(line);
+        if (line.startsWith('-'))
+            return chalk.red(line);
+        return line;
+    })
+        .join('\n');
+}
+/**
+ * Shadow-run a fixer in a temp copy of the target directory and return per-output
+ * diffs. We copy the real target into tmp so fixers that read existing state
+ * (e.g. husky reading package.json) still produce realistic output.
+ */
+async function previewFixer(fixer, result, targetDir, pkg, lock) {
+    // Pick a tmp root that is NOT inside targetDir. macOS sometimes hands us a
+    // $TMPDIR that lives under the working dir (e.g. when the caller is itself
+    // running inside a tempdir tree), which would make fs.copy fail with
+    // "subdirectory of itself". Fall back to the parent of targetDir if so.
+    const resolvedTarget = path.resolve(targetDir);
+    let tmpRoot = path.resolve(os.tmpdir());
+    if (tmpRoot === resolvedTarget || tmpRoot.startsWith(resolvedTarget + path.sep)) {
+        tmpRoot = path.dirname(resolvedTarget);
+    }
+    const tmpDir = await fs.mkdtemp(path.join(tmpRoot, 'js-tooling-fix-preview-'));
+    try {
+        await fs.copy(targetDir, tmpDir, {
+            filter: (src) => {
+                const rel = path.relative(targetDir, src);
+                if (!rel)
+                    return true;
+                const first = rel.split(path.sep)[0];
+                // Skip large/derived dirs that fixers never touch — keeps preview fast on
+                // big repos.
+                return first !== 'node_modules' && first !== 'dist' && first !== 'build' && first !== '.git';
+            },
+        });
+        await fixer.run({ targetDir: tmpDir, pkg, result, lock });
+        const previews = [];
+        const seen = new Set();
+        for (const output of fixer.outputs) {
+            const rel = outputToRelativePath(output);
+            if (seen.has(rel))
+                continue;
+            seen.add(rel);
+            const tmpPath = path.join(tmpDir, rel);
+            const realPath = path.join(targetDir, rel);
+            if (!(await fs.pathExists(tmpPath)))
+                continue;
+            const newContent = await fs.readFile(tmpPath, 'utf-8');
+            const existed = await fs.pathExists(realPath);
+            const oldContent = existed ? await fs.readFile(realPath, 'utf-8') : '';
+            if (newContent === oldContent) {
+                previews.push({ path: rel, kind: 'unchanged', patch: null });
+                continue;
+            }
+            const patch = createPatch(rel, oldContent, newContent, undefined, undefined, { context: 3 });
+            previews.push({
+                path: rel,
+                kind: existed ? 'modify' : 'create',
+                patch: colorisePatch(patch),
+            });
+        }
+        return previews;
+    }
+    finally {
+        await fs.remove(tmpDir).catch(() => {
+            // Best-effort cleanup; tmp dirs get GC'd by the OS eventually.
+        });
+    }
+}
+function printPreviews(previews) {
+    if (previews.length === 0) {
+        console.log(chalk.gray('  (no preview available — fixer produced no recognisable outputs)'));
+        return;
+    }
+    for (const p of previews) {
+        if (p.kind === 'unchanged') {
+            console.log(chalk.gray(`  ${p.path} — unchanged`));
+            continue;
+        }
+        const label = p.kind === 'create' ? chalk.green('create') : chalk.yellow('modify');
+        console.log(`  ${label} ${chalk.bold(p.path)}`);
+        if (p.patch) {
+            console.log(p.patch
+                .split('\n')
+                .map((l) => `    ${l}`)
+                .join('\n'));
+        }
+    }
+}
 async function applyFixer(fixer, result, targetDir, pkg, lock, dryRun, silent) {
     if (dryRun) {
         if (!silent) {
@@ -526,6 +661,8 @@ export async function fixCommand(target, options = {}) {
     // JSON mode implies --yes so prompts don't corrupt the output stream.
     const assumeYes = options.yes === true || json;
     const silent = json;
+    // Diff preview is interactive-only — suppress in JSON mode.
+    const showDiff = options.diff === true && !json;
     if (options.list) {
         const summary = listFixers();
         if (json) {
@@ -654,6 +791,10 @@ export async function fixCommand(target, options = {}) {
             console.log(chalk.cyan(`\n🔧 ${fixer.target} — ${chalk.bold(result.check)} is ${effectiveResult.status}\n`));
         }
         const conflict = noteLockConflict(result.check);
+        if (showDiff && (fixer.riskLevel ?? 'destructive') !== 'safe-add') {
+            const previews = await previewFixer(fixer, effectiveResult, targetDir, pkg, lock);
+            printPreviews(previews);
+        }
         const ok = await confirmApply(fixer, effectiveResult, assumeYes);
         if (!ok) {
             actions.push(recordFor(fixer.target, result.check, effectiveResult.status, 'skipped', [], conflict));
@@ -695,6 +836,10 @@ export async function fixCommand(target, options = {}) {
             console.log(`  ${chalk.bold(result.check)} (${result.status}) → ${fixer.target}`);
         }
         const conflict = noteLockConflict(result.check);
+        if (showDiff && (fixer.riskLevel ?? 'destructive') !== 'safe-add') {
+            const previews = await previewFixer(fixer, result, targetDir, pkg, lock);
+            printPreviews(previews);
+        }
         const ok = await confirmApply(fixer, result, assumeYes);
         if (!ok) {
             actions.push(recordFor(fixer.target, result.check, result.status, 'skipped', [], conflict));

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

@@ -125,6 +125,8 @@ export const CONFIG_SCHEMA = {
         gitHooks: { type: 'boolean' },
         commitLint: { type: 'boolean' },
         semanticRelease: { type: 'boolean' },
+        changesets: { type: 'boolean' },
+        oxlint: { type: 'boolean' },
         securityAutomation: { type: 'boolean' },
         bundler: { type: 'string', enum: ['tsup', 'esbuild', 'vite', 'none'] },
         treeshakeCheck: { type: 'boolean' },
@@ -192,6 +194,10 @@ export function computeFileList(config) {
         files.push('vite.config.ts');
     if (config.semanticRelease)
         files.push('release.config.mjs');
+    if (config.changesets)
+        files.push('.changeset/config.json');
+    if (config.oxlint)
+        files.push('.oxlintrc.json');
     if (config.treeshakeCheck && config.projectType === 'library') {
         files.push('apps/treeshake-check/package.json', 'apps/treeshake-check/check.mjs', 'apps/treeshake-check/src/entry.ts');
     }

package/dist/cli/commands/setup.js

@@ -146,6 +146,13 @@ async function promptForConfig() {
             },
             when: (answers) => answers.lintingTool === 'eslint' || answers.lintingTool === 'both',
         },
+        {
+            type: 'confirm',
+            name: 'oxlint',
+            message: '🦀 Also run Oxlint alongside (50–100× faster than ESLint)?',
+            default: false,
+            when: (answers) => answers.lintingTool !== 'none',
+        },
         {
             type: 'list',
             name: 'testingFramework',
@@ -184,10 +191,15 @@ async function promptForConfig() {
             when: (answers) => answers.gitHooks,
         },
         {
-            type: 'confirm',
-            name: 'semanticRelease',
-            message: '🚀 Set up semantic release for automated versioning?',
-            default: (answers) => answers.projectType === 'library',
+            type: 'list',
+            name: 'releaseTool',
+            message: '🚀 Automated release tool?',
+            choices: [
+                { name: '📦 semantic-release (commit-message-driven)', value: 'semantic-release' },
+                { name: '📝 Changesets (changeset-file-driven, monorepo-friendly)', value: 'changesets' },
+                { name: '❌ None', value: 'none' },
+            ],
+            default: 'semantic-release',
             when: (answers) => answers.projectType === 'library',
         },
         {
@@ -245,7 +257,9 @@ async function promptForConfig() {
         },
         gitHooks: answers.gitHooks || false,
         commitLint: answers.commitLint || false,
-        semanticRelease: answers.semanticRelease || false,
+        semanticRelease: answers.releaseTool === 'semantic-release',
+        changesets: answers.releaseTool === 'changesets',
+        oxlint: answers.oxlint || false,
         securityAutomation: answers.securityAutomation ?? false,
         bundler: answers.bundler || 'none',
         treeshakeCheck: answers.treeshakeCheck || false,

package/dist/cli/generators/build.js

@@ -14,6 +14,10 @@ export async function generateBuildConfigs(config, targetDir) {
     if (config.semanticRelease) {
         await generateSemanticReleaseConfig(targetDir);
     }
+    // Generate Changesets config (alternative to semantic-release)
+    if (config.changesets) {
+        await generateChangesetsConfig(targetDir);
+    }
 }
 async function generateTsupConfig(targetDir) {
     const tsupConfigPath = path.join(targetDir, 'tsup.config.ts');
@@ -73,3 +77,10 @@ export async function generateSemanticReleaseConfig(targetDir) {
 `;
     await fs.writeFile(releaseConfigPath, releaseConfig);
 }
+export async function generateChangesetsConfig(targetDir) {
+    // Drop the canonical Changesets config into .changeset/config.json. The user
+    // owns this file once it's in their repo; subsequent `pnpm changeset` runs
+    // create per-change markdown files alongside it.
+    const { copyPreset } = await import('../utils/copy-preset.js');
+    await copyPreset('changesets', targetDir);
+}

package/dist/cli/generators/linting.js

@@ -13,6 +13,17 @@ export async function generateLintingConfigs(config, targetDir) {
     if (config.linting.tool === 'eslint') {
         await generatePrettierConfig(targetDir);
     }
+    // Generate Oxlint config (additive — runs alongside Biome/ESLint)
+    if (config.oxlint) {
+        await generateOxlintConfig(targetDir);
+    }
+}
+export async function generateOxlintConfig(targetDir) {
+    // Oxlint's `extends` resolution from npm packages isn't reliably supported,
+    // so we copy the full preset rather than write a thin pointer file (same
+    // pattern as biome.jsonc — the user owns the file once it's in their repo).
+    const { copyPreset } = await import('../utils/copy-preset.js');
+    await copyPreset('oxlint', targetDir);
 }
 export async function generateBiomeConfig(targetDir) {
     const biomeConfigPath = path.join(targetDir, 'biome.jsonc');

package/dist/cli/index.js

@@ -142,6 +142,18 @@ const TOOL_CATALOG = [
         ],
         fixTarget: 'semantic-release',
     },
+    {
+        name: 'Changesets',
+        description: 'Monorepo-friendly release tool (alternative to semantic-release)',
+        exports: ['@rtorcato/js-tooling/changesets'],
+        fixTarget: 'changesets',
+    },
+    {
+        name: 'Oxlint',
+        description: 'Rust-based linter (additive to Biome/ESLint)',
+        exports: ['@rtorcato/js-tooling/oxlint'],
+        fixTarget: 'oxlint',
+    },
     {
         name: 'tsup',
         description: 'TypeScript bundler configuration',
@@ -235,6 +247,7 @@ program
     .option('--json', 'Emit machine-readable JSON output (implies --yes)')
     .option('--list', 'List all registered fix targets and exit')
     .option('--resync', 'Re-scaffold every file recorded in .js-tooling.json')
+    .option('--diff', 'Show a unified diff of each change before confirming')
     .action((target, options) => fixCommand(target, {
     directory: options.directory,
     yes: options.yes,
@@ -242,6 +255,7 @@ program
     json: options.json,
     list: options.list,
     resync: options.resync,
+    diff: options.diff,
 }));
 program.hook('preAction', async (_, actionCommand) => {
     const name = actionCommand.name();

package/dist/cli/utils/copy-preset.js

@@ -6,6 +6,16 @@ export const PRESETS = {
         target: 'biome.json',
         desc: 'Biome formatter and linter configuration',
     },
+    changesets: {
+        source: 'tooling/changesets/config.json',
+        target: '.changeset/config.json',
+        desc: 'Changesets release-tool configuration',
+    },
+    oxlint: {
+        source: 'tooling/oxlint/oxlintrc.json',
+        target: '.oxlintrc.json',
+        desc: 'Oxlint linter configuration (additive to Biome)',
+    },
     tsconfig: {
         source: 'tooling/typescript/tsconfig.base.json',
         target: 'tsconfig.json',

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/js-tooling",
-	"version": "2.17.1",
+	"version": "2.18.0",
 	"description": "JavaScript and TypeScript tooling for Node.js, React, Next.js, and Vitest.",
 	"type": "module",
 	"keywords": [
@@ -9,6 +9,7 @@
 		"eslint"
 	],
 	"author": "Richard Torcato",
+	"packageManager": "pnpm@11.1.3",
 	"sideEffects": false,
 	"license": "MIT",
 	"repository": {
@@ -23,6 +24,8 @@
 		"build": "pnpm build-cli",
 		"build-cli": "rimraf ./dist/cli && tsc --project src/cli/tsconfig.json",
 		"prepublishOnly": "./scripts/fix-bins.sh",
+		"dev": "pnpm --filter @rtorcato/docs dev",
+		"docs:build": "pnpm --filter @rtorcato/docs build",
 		"==================== Common ====================": "",
 		"lint": "pnpm exec biome lint --config-path=tooling/biome/biome.json src scripts",
 		"format": "pnpm exec biome format --config-path=tooling/biome/biome.json src scripts",
@@ -70,6 +73,8 @@
 		"tooling/tests/ssr-safety.d.mts",
 		"tooling/tsup/index.ts",
 		"tooling/biome/biome.json",
+		"tooling/changesets/config.json",
+		"tooling/oxlint/oxlintrc.json",
 		"tooling/typedoc/typedoc.json",
 		"tooling/semantic-release/*.mjs",
 		"tooling/semantic-release/*.d.mts",
@@ -143,6 +148,8 @@
 		},
 		"./tsup": "./tooling/tsup/index.ts",
 		"./biome": "./tooling/biome/biome.json",
+		"./changesets": "./tooling/changesets/config.json",
+		"./oxlint": "./tooling/oxlint/oxlintrc.json",
 		"./typedoc": "./tooling/typedoc/typedoc.json",
 		"./semantic-release": {
 			"types": "./tooling/semantic-release/index.d.mts",
@@ -168,11 +175,13 @@
 	"dependencies": {
 		"chalk": "^5.6.2",
 		"commander": "^14.0.3",
+		"diff": "^9.0.0",
 		"fs-extra": "^11.3.2",
 		"inquirer": "^14.0.2"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.4.16",
+		"@types/diff": "^8.0.0",
 		"@commitlint/cli": "^20.1.0",
 		"@commitlint/config-conventional": "^21.0.2",
 		"@commitlint/types": "^20.0.0",
@@ -215,7 +224,7 @@
 		"tsup": "8.5.1",
 		"typescript": "^5.9.3",
 		"typescript-eslint": "^8.60.0",
-		"vitest": "4.0.3"
+		"vitest": "^4.1.8"
 	},
 	"peerDependencies": {
 		"@biomejs/biome": "^2.0.0",
@@ -232,6 +241,7 @@
 		"@semantic-release/github": "^12.0.8",
 		"@semantic-release/npm": "^13.0.0",
 		"@semantic-release/release-notes-generator": "^14.0.0",
+		"@size-limit/preset-small-lib": "^12.0.0",
 		"@total-typescript/ts-reset": "^0.6.0",
 		"@typescript-eslint/eslint-plugin": "^8.0.0",
 		"@typescript-eslint/parser": "^8.0.0",
@@ -245,7 +255,6 @@
 		"prettier": "^3.0.0",
 		"semantic-release": "^25.0.0",
 		"size-limit": "^12.0.0",
-		"@size-limit/preset-small-lib": "^12.0.0",
 		"ts-jest": "^29.0.0",
 		"tsup": "^8.0.0",
 		"typescript": ">=5.0.0",

package/tooling/changesets/README.md

@@ -0,0 +1,35 @@
+# Changesets preset
+
+Shared [Changesets](https://github.com/changesets/changesets) configuration for projects using `@rtorcato/js-tooling`.
+
+Changesets is a **monorepo-friendly alternative to semantic-release**. The release workflow is the same shape (CI bumps versions, generates a changelog, publishes to npm), but the *intent* is captured in changeset markdown files at PR time rather than parsed from commit messages.
+
+Pick one — Changesets or semantic-release — per repo. The `doctor` check flags repos configured for both.
+
+## Usage
+
+```bash
+npx @rtorcato/js-tooling copy changesets
+```
+
+This scaffolds `.changeset/config.json` from this preset. After that:
+
+```bash
+pnpm changeset           # interactive — author a changeset for the current change
+pnpm changeset version   # consume changesets, bump versions, write CHANGELOG.md
+pnpm changeset publish   # publish to npm
+```
+
+CI typically runs the [Changesets release bot](https://github.com/changesets/action), which opens a "Version Packages" PR when changesets are present and publishes on merge.
+
+## Why pick this over semantic-release
+
+- **Monorepos** — Changesets handles multi-package version bumps in a way semantic-release doesn't out of the box.
+- **Explicit intent** — Authors declare a change's bump level in the changeset file rather than encoding it in commit message conventions, which is more forgiving for human commits.
+- **Pre-release flows** — `--snapshot` and `pre enter <tag>` are first-class.
+
+## Why pick semantic-release instead
+
+- **Single-package repos** — Less ceremony; nothing to author per change.
+- **Strict conventional-commits discipline already in place.**
+- **Existing CI built around the `npm run release` path.**

package/tooling/changesets/config.json

@@ -0,0 +1,11 @@
+{
+	"$schema": "https://unpkg.com/@changesets/config@3.0.5/schema.json",
+	"changelog": "@changesets/cli/changelog",
+	"commit": false,
+	"fixed": [],
+	"linked": [],
+	"access": "public",
+	"baseBranch": "main",
+	"updateInternalDependencies": "patch",
+	"ignore": []
+}

package/tooling/oxlint/README.md

@@ -0,0 +1,25 @@
+# Oxlint preset
+
+Shared [Oxlint](https://oxc.rs/docs/guide/usage/linter.html) configuration for projects using `@rtorcato/js-tooling`.
+
+Oxlint is a Rust-based linter that's 50–100× faster than ESLint. It is intentionally **additive** to Biome — Biome handles formatting and the broad lint baseline, Oxlint adds a faster pass for the type-aware and import rules Biome doesn't cover yet.
+
+## Usage
+
+```bash
+npx @rtorcato/js-tooling copy oxlint
+```
+
+This drops `.oxlintrc.json` at the project root, extending the conventions in this preset. Run it with:
+
+```bash
+pnpm oxlint
+# or
+npx oxlint
+```
+
+## Notes
+
+- Oxlint shares its rule catalog with ESLint's plugins (`typescript`, `unicorn`, `oxc`, `import`), so most ESLint rules you know already work here.
+- The preset disables Biome-overlapping rules to keep CI noise down — Biome stays the source of truth for formatting and the baseline lint set.
+- For projects without Biome, you can run Oxlint standalone and re-enable the `style` and `pedantic` categories.

package/tooling/oxlint/oxlintrc.json

@@ -0,0 +1,28 @@
+{
+	"$schema": "https://raw.githubusercontent.com/oxc-project/oxc/main/npm/oxlint/configuration_schema.json",
+	"categories": {
+		"correctness": "error",
+		"perf": "warn",
+		"suspicious": "warn",
+		"pedantic": "off",
+		"style": "off",
+		"restriction": "off",
+		"nursery": "off"
+	},
+	"plugins": ["typescript", "unicorn", "oxc", "import"],
+	"rules": {
+		"no-console": "warn",
+		"no-debugger": "error",
+		"no-empty": "warn",
+		"no-unused-vars": "off",
+		"@typescript-eslint/no-unused-vars": [
+			"warn",
+			{ "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" }
+		],
+		"unicorn/filename-case": "off",
+		"unicorn/no-null": "off",
+		"unicorn/prevent-abbreviations": "off",
+		"import/no-default-export": "off"
+	},
+	"ignorePatterns": ["node_modules", "dist", "build", "coverage", ".next", "*.d.ts"]
+}