eslint-try-rules 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025- Dieter Oberkofler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# eslint-try-rules
+
+`eslint-try-rules` is a CLI tool designed to help developers incrementally adopt stricter ESLint rules. It allows you to test a set of rules against your codebase and generates a report showing which files would fail, without actually modifying your existing ESLint configuration.
+
+## Features
+
+- **Test Rules in Isolation:** Run specific rules against your project to see their impact.
+- **Support for JSON and JSONC:** Load rules from standard JSON or JSON files with comments.
+- **Progress Tracking:** Real-time progress bar with ETA during linting.
+- **Detailed Reports:** Generates a colored CLI summary and a comprehensive HTML report.
+- **Flexible Sorting:** Sort results by rule ID or by severity (total errors + warnings).
+- **ESLint 9+ Support:** Built for the new ESLint Flat Config system.
+- **Safe Adoption:** No changes are made to your existing `eslint.config.js`.
+
+## Installation
+
+You can run it directly using `npx`:
+
+```bash
+npx eslint-try-rules --rules try-rules.json
+```
+
+Or install it globally:
+
+```bash
+npm install -g eslint-try-rules
+```
+
+Or as a development dependency in your project:
+
+```bash
+npm install -D eslint-try-rules
+```
+
+## Usage
+
+Create a `try-rules.json` (or `.jsonc`) file with the rules you want to test:
+
+```json
+{
+  "@typescript-eslint/no-explicit-any": "error",
+  "curly": "error"
+}
+```
+
+Run the tool:
+
+```bash
+eslint-try-rules --rules try-rules.json
+```
+
+### Try the Example
+
+You can run an example against this project's own source code:
+
+```bash
+npm run example
+```
+
+This uses the rules defined in `example/try-rules.jsonc`.
+
+### Options
+
+- `--rules <path>`: (Required) Path to the JSON/JSONC file containing the rules to test.
+- `--config <path>`: (Optional) Path to your project's ESLint configuration file (e.g., `eslint.config.js`).
+- `--sort <rule|severity>`: (Optional) Sort results by rule ID (default) or by severity (total errors + warnings).
+
+## Output
+
+The tool provides:
+1.  **CLI Report:** A summary of errors and warnings per rule, including file locations.
+2.  **HTML Report:** A detailed, interactive HTML report saved as `eslint-incremental-report.html`.
+
+## Development
+
+### Build
+```bash
+npm run build
+```
+
+### Lint
+```bash
+npm run lint
+```
+
+### Test
+```bash
+npm run test
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,8 @@
+//#region src/index.d.ts
+/**
+ * Main execution.
+ * @returns {Promise<void>}
+ */
+declare const main: () => Promise<void>;
+//#endregion
+export { main };

package/dist/index.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { runLint } from "./lint.mjs";
+import { generateHtml } from "./report-html.mjs";
+import { printConsoleReport } from "./report-console.mjs";
+import { parseRulesFile } from "./rules.mjs";
+import { writeFileSync } from "node:fs";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { Command } from "commander";
+import ansis from "ansis";
+
+//#region src/index.ts
+/**
+* Main execution.
+* @returns {Promise<void>}
+*/
+const main = async () => {
+	const start = performance.now();
+	const program = new Command();
+	program.name("eslint-try-rules").description("Try stricter ESLint rules on your codebase.").argument("[patterns...]", "Files/directories/globs to lint.", ["."]).requiredOption("--rules <path>", "Path to a JSON/JSONC file containing the ESLint rules to test.").option("--config <path>", "Path to your project's ESLint configuration file.").option("--sort <type>", "Sort results by \"rule\" (default) or \"severity\" (errors + warnings).", "rule");
+	program.parse();
+	const options = program.opts();
+	const patterns = program.args;
+	const cwd = process.cwd();
+	if (options.sort !== "rule" && options.sort !== "severity") throw new Error("Invalid sort option. Use \"rule\" or \"severity\".");
+	const rules = parseRulesFile(path.resolve(cwd, options.rules));
+	console.log(`${ansis.bold.blue("ℹ")} Starting eslint-try-rules for ${ansis.bold(String(Object.keys(rules).length))} rules...\n`);
+	const finalResults = await runLint(cwd, rules, patterns, options.config ? path.resolve(cwd, options.config) : void 0);
+	printConsoleReport(finalResults, options.sort);
+	const html = generateHtml(finalResults);
+	const outPath = path.resolve(cwd, "eslint-incremental-report.html");
+	writeFileSync(outPath, html, "utf8");
+	const durationMs = (performance.now() - start) / 1e3;
+	console.log(`${ansis.bold.green("✔")} Report generated in ${ansis.bold(durationMs.toFixed(2))}s: ${ansis.underline(`file://${outPath}`)}`);
+};
+/* v8 ignore start */
+if (process.argv[1] === import.meta.filename || process.argv[1]?.endsWith("index.mjs")) try {
+	await main();
+} catch (error) {
+	if (error instanceof Error) console.error(`\n${ansis.red.bold("✖")} ${error.message}`);
+	else console.error(`\n${ansis.red.bold("✖")} Unknown error`, error);
+	process.exit(1);
+}
+/* v8 ignore stop */
+
+//#endregion
+export { main };

package/dist/lint.mjs

@@ -0,0 +1,112 @@
+import path from "node:path";
+import { ESLint } from "eslint";
+import cliProgress from "cli-progress";
+import { glob } from "tinyglobby";
+
+//#region src/lint.ts
+/**
+* Creates a rule filter for ESLint.
+* @param {Record<string, unknown>} rules - The rules to filter.
+* @returns {(rule: {ruleId: string}) => boolean} The filter function.
+*/
+const createRuleFilter = (rules) => ({ ruleId }) => Object.prototype.hasOwnProperty.call(rules, ruleId);
+/**
+* Runs ESLint on the codebase with the provided rules.
+* @param {string} cwd - The current working directory.
+* @param {Record<string, unknown>} rules - The rules to test.
+* @param {string[]} patterns - The file patterns to lint.
+* @param {string} [configFile] - Optional path to the ESLint config file.
+* @returns {Promise<RuleResult[]>} The linting results.
+*/
+const runLint = async (cwd, rules, patterns, configFile) => {
+	const eslint = new ESLint({
+		cwd,
+		cache: false,
+		overrideConfigFile: configFile,
+		overrideConfig: [{ rules }],
+		ruleFilter: createRuleFilter(rules)
+	});
+	console.log("Searching for files...");
+	const allFiles = await glob(patterns.map((p) => {
+		if (p === ".") return "**/*.{js,mjs,cjs,ts,mts,cts,tsx,jsx}";
+		if (!p.includes("*") && !p.includes("?") && !p.includes("[") && !p.includes("{")) return path.join(p, "**/*.{js,mjs,cjs,ts,mts,cts,tsx,jsx}");
+		return p;
+	}), {
+		cwd,
+		ignore: [
+			"**/node_modules/**",
+			"**/dist/**",
+			"**/coverage/**"
+		],
+		absolute: true
+	});
+	const filesToLint = [];
+	for (const file of allFiles) if (!await eslint.isPathIgnored(file)) filesToLint.push(file);
+	if (filesToLint.length === 0) {
+		console.log("No files found to lint.");
+		return [];
+	}
+	const progressBar = new cliProgress.SingleBar({
+		format: "Linting | {bar} | {percentage}% | {value}/{total} Files | ETA: {eta}s",
+		barCompleteChar: "█",
+		barIncompleteChar: "░",
+		hideCursor: true
+	});
+	progressBar.start(filesToLint.length, 0);
+	const allResults = [];
+	const chunkSize = 10;
+	for (let i = 0; i < filesToLint.length; i += chunkSize) {
+		const chunk = filesToLint.slice(i, i + chunkSize);
+		const chunkResults = await eslint.lintFiles(chunk);
+		allResults.push(...chunkResults);
+		progressBar.update(Math.min(i + chunkSize, filesToLint.length));
+	}
+	progressBar.stop();
+	return processResults(cwd, rules, allResults);
+};
+/**
+* Processes ESLint results into RuleResult format.
+* @param {string} cwd - Current working directory.
+* @param {Record<string, unknown>} rules - Rules tested.
+* @param {ESLint.LintResult[]} results - Results from ESLint.
+* @returns {RuleResult[]} Processed results.
+*/
+const processResults = (cwd, rules, results) => {
+	const ruleMap = /* @__PURE__ */ new Map();
+	for (const ruleId of Object.keys(rules)) ruleMap.set(ruleId, {
+		ruleId,
+		config: rules[ruleId],
+		errors: 0,
+		warnings: 0,
+		fixable: 0,
+		details: []
+	});
+	for (const res of results) for (const msg of res.messages) {
+		const rId = msg.ruleId ?? "unknown";
+		let rr = ruleMap.get(rId);
+		if (!rr) {
+			rr = {
+				ruleId: rId,
+				config: "unknown",
+				errors: 0,
+				warnings: 0,
+				fixable: 0,
+				details: []
+			};
+			ruleMap.set(rId, rr);
+		}
+		if (msg.severity === 2) rr.errors++;
+		else rr.warnings++;
+		if (msg.fix !== void 0) rr.fixable++;
+		rr.details.push({
+			filePath: path.relative(cwd, res.filePath),
+			line: msg.line,
+			column: msg.column,
+			message: msg.message
+		});
+	}
+	return [...ruleMap.values()].filter((r) => r.errors > 0 || r.warnings > 0);
+};
+
+//#endregion
+export { runLint };

package/dist/report-console.mjs

@@ -0,0 +1,66 @@
+import ansis from "ansis";
+
+//#region src/report-console.ts
+/**
+* Sorts rule results by ruleId.
+* @param {RuleResult} a - First result.
+* @param {RuleResult} b - Second result.
+* @returns {number} Comparison result.
+*/
+const sortByRuleId = (a, b) => a.ruleId.localeCompare(b.ruleId);
+/**
+* Sorts rule results by severity (errors + warnings).
+* @param {RuleResult} a - First result.
+* @param {RuleResult} b - Second result.
+* @returns {number} Comparison result.
+*/
+const sortBySeverity = (a, b) => {
+	const totalA = a.errors + a.warnings;
+	const totalB = b.errors + b.warnings;
+	if (totalA !== totalB) return totalB - totalA;
+	return sortByRuleId(a, b);
+};
+/**
+* Sorts message details by file path.
+* @param {MessageDetail} a - First detail.
+* @param {MessageDetail} b - Second detail.
+* @returns {number} Comparison result.
+*/
+const sortByFilePath = (a, b) => a.filePath.localeCompare(b.filePath);
+/**
+* Outputs the results to the console.
+* @param {RuleResult[]} results - The results to output.
+* @param {SortOption} sortOption - The sorting criteria.
+*/
+const printConsoleReport = (results, sortOption) => {
+	const finalResults = [...results].toSorted((a, b) => {
+		if (sortOption === "severity") return sortBySeverity(a, b);
+		return sortByRuleId(a, b);
+	});
+	let totalErrors = 0;
+	let totalWarnings = 0;
+	let totalFixable = 0;
+	console.log("\n" + ansis.bold.cyan("--- CLI Report ---"));
+	for (const r of finalResults) {
+		totalErrors += r.errors;
+		totalWarnings += r.warnings;
+		totalFixable += r.fixable;
+		const sortedDetails = r.details.toSorted(sortByFilePath);
+		const stats = [];
+		if (r.errors > 0) stats.push(ansis.red(`${r.errors} errors`));
+		if (r.warnings > 0) stats.push(ansis.yellow(`${r.warnings} warnings`));
+		if (r.fixable > 0) stats.push(ansis.green(`${r.fixable} fixable`));
+		console.log(`\n${ansis.bold(r.ruleId)} (${stats.join(" | ")})`);
+		for (const d of sortedDetails) console.log(`  ${ansis.dim("->")} ${ansis.blue(d.filePath)}:${ansis.magenta(String(d.line))}:${ansis.magenta(String(d.column))} ${ansis.dim("-")} ${d.message}`);
+	}
+	console.log("\n" + ansis.cyan("------------------"));
+	const totals = [
+		ansis.red.bold(`${totalErrors} errors`),
+		ansis.yellow.bold(`${totalWarnings} warnings`),
+		ansis.green.bold(`${totalFixable} fixable`)
+	].join(" | ");
+	console.log(`${ansis.bold("Totals")} | ${totals}\n`);
+};
+
+//#endregion
+export { printConsoleReport };

package/dist/report-html.mjs

@@ -0,0 +1,73 @@
+//#region src/report-html.ts
+const TITLE = "ESLint try rules";
+/**
+* Escapes HTML characters.
+* @param {string} str - The string to escape.
+* @returns {string} The escaped string.
+*/
+const escapeHtml = (str) => str.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+/**
+* Generates HTML report.
+* @param {RuleResult[]} results - The results to include in the report.
+* @returns {string} The generated HTML.
+*/
+const generateHtml = (results) => {
+	let totalErr = 0;
+	let totalWarn = 0;
+	let totalFix = 0;
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="UTF-8">
+	<title>${TITLE}</title>
+	<style>
+		body { font-family: sans-serif; margin: 2rem; }
+		table { border-collapse: collapse; width: 100%; }
+		th, td { border: 1px solid #ddd; padding: 8px; text-align: right; vertical-align: top; }
+		th:first-child, td:first-child, th:nth-child(2), td:nth-child(2) { text-align: left; }
+		ul { margin: 0; padding-left: 20px; font-size: 0.9em; }
+		tfoot { font-weight: bold; background: #eee; }
+	</style>
+</head>
+<body>
+	<h1>${TITLE}</h1>
+	<table>
+		<thead>
+			<tr><th>Rule</th><th>Config</th><th>Errors</th><th>Warnings</th><th>Fixable</th></tr>
+		</thead>
+		<tbody>
+			${results.map((r) => {
+		totalErr += r.errors;
+		totalWarn += r.warnings;
+		totalFix += r.fixable;
+		const confStr = escapeHtml(JSON.stringify(r.config ?? "N/A"));
+		let detailsRow = "";
+		let toggleIcon = "<span style=\"color:#ccc;\">&#x25B6;</span>";
+		if (r.details.length > 0) {
+			detailsRow = `<tr style="display:none;background:#f9f9f9;"><td colspan="5"><ul>${r.details.map((d) => `<li><code>${escapeHtml(d.filePath)}:${d.line}:${d.column}</code> - ${escapeHtml(d.message)}</li>`).join("")}</ul></td></tr>`;
+			toggleIcon = `<span style="cursor:pointer;" onclick="const r=this.closest('tr').nextElementSibling;r.style.display=r.style.display==='none'?'table-row':'none';this.innerHTML=r.style.display==='none'?'&#x25B6;':'&#x25BC;'">&#x25B6;</span>`;
+		}
+		return `<tr>
+				<td>${toggleIcon} ${escapeHtml(r.ruleId)}</td>
+				<td><code>${confStr}</code></td>
+				<td>${r.errors}</td>
+				<td>${r.warnings}</td>
+				<td>${r.fixable}</td>
+			</tr>\n\t\t\t\t${detailsRow}`;
+	}).join("\n				")}
+		</tbody>
+		<tfoot>
+			<tr>
+				<td colspan="2">Totals</td>
+				<td>${totalErr}</td>
+				<td>${totalWarn}</td>
+				<td>${totalFix}</td>
+			</tr>
+		</tfoot>
+	</table>
+</body>
+</html>`;
+};
+
+//#endregion
+export { generateHtml };

package/dist/rules.mjs

@@ -0,0 +1,30 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import stripJsonComments from "strip-json-comments";
+import { z } from "zod";
+
+//#region src/rules.ts
+/**
+* The Zod schema for the rules file.
+*/
+const RulesSchema = z.record(z.string(), z.unknown());
+/**
+* Parses the rules file.
+* @param {string} filePath - Path to the rules file (JSON or JSONC).
+* @returns {Record<string, unknown>} The parsed rules.
+* @throws {Error} If the file cannot be read or parsed.
+*/
+const parseRulesFile = (filePath) => {
+	try {
+		const content = readFileSync(path.resolve(filePath), "utf8");
+		const json = JSON.parse(stripJsonComments(content));
+		return RulesSchema.parse(json);
+	} catch (error) {
+		if (error instanceof z.ZodError) throw new Error(`Invalid rules format: ${error.message}`);
+		if (error instanceof SyntaxError) throw new Error(`Failed to parse rules JSON: ${error.message}`);
+		throw error;
+	}
+};
+
+//#endregion
+export { parseRulesFile };

package/package.json

@@ -0,0 +1,70 @@
+{
+	"name": "eslint-try-rules",
+	"version": "0.1.0",
+	"type": "module",
+	"license": "MIT",
+	"author": "Dieter Oberkofler",
+	"files": [
+		"dist"
+	],
+	"keywords": [
+		"eslint",
+		"rules"
+	],
+	"bin": {
+		"eslint-try-rules": "./dist/index.mjs"
+	},
+	"scripts": {
+		"dev": "tsdown --watch",
+		"build": "tsdown",
+		"prepublishOnly": "npm run build",
+		"lint": "eslint --no-cache . && tsc && prettier --check .",
+		"test": "vitest run --coverage",
+		"example": "tsx src/index.ts src --rules example/try-rules.jsonc",
+		"ci": "npm run lint && npm run build && npm run test",
+		"create-changelog": "conventional-changelog --release-count=0",
+		"pack-local": "rm -f *.tgz && npm run build && npm pack"
+	},
+	"main": "./dist/index.mjs",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": "./dist/index.mjs",
+		"./package.json": "./package.json"
+	},
+	"engines": {
+		"node": ">=22.12.0"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git://github.com/doberkofler/eslint-try-rules.git"
+	},
+	"homepage": "https://github.com/doberkofler/eslint-try-rules#readme",
+	"devDependencies": {
+		"@eslint/js": "^9.31.0",
+		"@types/node": "^25.3.0",
+		"@vitest/coverage-v8": "^4.0.18",
+		"@vitest/eslint-plugin": "^1.6.9",
+		"conventional-changelog": "^7.1.1",
+		"eslint": "^9.31.0",
+		"eslint-plugin-jsdoc": "^62.6.1",
+		"eslint-plugin-regexp": "^3.0.0",
+		"eslint-plugin-unicorn": "^63.0.0",
+		"globals": "^17.3.0",
+		"prettier": "^3.8.1",
+		"tsdown": "^0.20.3",
+		"tsx": "^4.21.0",
+		"typescript": "^5.9.3",
+		"typescript-eslint": "^8.56.0",
+		"vitest": "^4.0.18"
+	},
+	"dependencies": {
+		"@types/cli-progress": "^3.11.6",
+		"ansis": "^4.2.0",
+		"cli-progress": "^3.12.0",
+		"commander": "^14.0.3",
+		"strip-json-comments": "^5.0.3",
+		"tinyglobby": "^0.2.15",
+		"zod": "^4.3.6"
+	}
+}