@oxlint/migrate 1.41.0 → 1.43.0

package/README.md

@@ -4,7 +4,9 @@
 [![NPM Version](https://img.shields.io/npm/v/%40oxlint%2Fmigrate)](https://www.npmjs.com/package/@oxlint/migrate)
 [![NPM Downloads](https://img.shields.io/npm/dm/%40oxlint%2Fmigrate)](https://www.npmjs.com/package/@oxlint/migrate)
 
-Generates a `.oxlintrc.json` from an existing eslint flat config.
+Generates a `.oxlintrc.json` from an existing ESLint flat config.
+
+See [the Migration Guide in the Oxlint docs](https://oxc.rs/docs/guide/usage/linter/migrate-from-eslint.html) for more information on migrating from ESLint to Oxlint.
 
 ## Usage
 
@@ -12,32 +14,33 @@ Generates a `.oxlintrc.json` from an existing eslint flat config.
 npx @oxlint/migrate <optional-eslint-flat-config-path>
 ```
 
-When no config file provided, the script searches for the default eslint config filenames in the current directory.
+When no config file is provided, the script searches for the default ESLint config filenames in the current directory.
 
 ### Options
 
 | Options                     | Description                                                                                                                                 |
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--merge`                   | \* merge eslint configuration with an existing .oxlintrc.json configuration                                                                 |
-| `--type-aware`              | Include type aware rules, which are supported with `oxlint --type-aware`                                                                    |
+| `--merge`                   | \* merge ESLint configuration with an existing .oxlintrc.json configuration                                                                 |
+| `--type-aware`              | Include type aware rules, which are supported with `oxlint --type-aware` and [oxlint-tsgolint](https://github.com/oxc-project/tsgolint)     |
 | `--with-nursery`            | Include oxlint rules which are currently under development                                                                                  |
 | `--js-plugins`              | \*\* Include ESLint plugins via `jsPlugins` key.                                                                                            |
-| `--output-file <file>`      | The oxlint configuration file where to eslint v9 rules will be written to, default: `.oxlintrc.json`                                        |
-| `--replace-eslint-comments` | Search in the project files for eslint comments and replaces them with oxlint. Some eslint comments are not supported and will be reported. |
+| `--details`                 | List rules that could not be migrated to oxlint                                                                                             |
+| `--output-file <file>`      | The oxlint configuration file where ESLint v9 rules will be written to, default: `.oxlintrc.json`                                           |
+| `--replace-eslint-comments` | Search in the project files for ESLint comments and replaces them with oxlint. Some ESLint comments are not supported and will be reported. |
 
 \* WARNING: When some `categories` are enabled, this tools will enable more rules with the combination of `plugins`.
-Else we need to disable each rule `plugin/categories` combination, which is not covered by your eslint configuration.
+Else we need to disable each rule `plugin/categories` combination, which is not covered by your ESLint configuration.
 This behavior can change in the future.
 
-\*\* WARNING: Tries to guess the plugin name. Should work with most of the plugin names.
+\*\* WARNING: Tries to guess the plugin name. Should work fine with most plugin names, but is not perfect.
 Not every ESLint API is integrated with `oxlint`.
-Tested ESLint Plugins with `oxlint` can be found in this [Oxc Discussion](https://github.com/oxc-project/oxc/discussions/14862).
+Tested ESLint Plugins with `oxlint` can be found in this [Oxc Discussion](https://github.com/oxc-project/oxc/discussions/14862). See the caveats section for more details.
 
 ### User Flow
 
 - Upgrade `oxlint` and `@oxlint/migrate` to the same version.
 - Execute `npx @oxlint/migrate`
-- (Optional): Disable supported rules via [eslint-plugin-oxlint](https://github.com/oxc-project/eslint-plugin-oxlint)
+- (Optional): Disable supported rules via [eslint-plugin-oxlint](https://github.com/oxc-project/eslint-plugin-oxlint), if you have any rules you need that aren't in Oxlint yet.
 
 ### TypeScript ESLint Configuration Files
 
@@ -66,3 +69,64 @@ pnpm vitest
 ```shell
 pnpm manual-test
 ```
+
+## Caveats
+
+The migration tool has been tested to work quite well for simple ESLint flat config files. It has also been tested to work correctly for the large majority of complex flat config files. However, there may be some edge cases where the migration is not perfect, or the behavior of Oxlint itself differs from ESLint.
+
+Here are some known caveats to be aware of:
+
+**`settings` field not migrated**
+
+The `settings` field (e.g. for setting the React version) is not migrated to the oxlint config yet. You may need to copy it over manually if you have any settings specified.
+
+Not all `settings` options are supported by oxlint, and so rule behavior in certain edge-cases may differ. See [the Settings docs](https://oxc.rs/docs/guide/usage/linter/config-file-reference.html#settings) for more info.
+
+**Local ESLint Plugins imported via path are not migrated**
+
+The `--js-plugins` flag cannot migrate ESLint plugins from file paths in the same repo currently (e.g. if you have `../eslint-plugin-myplugin` in your `eslint.config.mjs`). You will need to copy them over into the `jsPlugins` manually. See [the JS Plugins docs]() for more info.
+
+**`globals` field with large number of values**
+
+If you end up with a very large list of values for the `globals` field, it's likely because your version of the `globals` npm package is older (or newer!) than the one used in `@oxlint/migrate`.
+
+You can generally fix this by updating the `globals` package to the latest version so we can recognize the relevant globals and handle it as a simple `env` field.
+
+For example, this is a good `.oxlintrc.json` and means the globals used by your ESLint config were recognized:
+
+```jsonc
+{
+  "env": {
+    "browser": true,
+  },
+}
+```
+
+And this is bad:
+
+```jsonc
+{
+  "globals": {
+    "window": "readonly",
+    "document": "readonly",
+    "navigator": "readonly",
+    // ...and a few hundred more
+  },
+}
+```
+
+**Oxlint can potentially lint more files by default**
+
+If you extend certain ESLint configs (e.g. the airbnb config), they can disable many - or even all - rules for specific files or file types. And this is not always obvious to the end-user.
+
+Depending on how this is implemented by the given config, these behaviors may not migrate to your Oxlint config. If you see certain files that you do not want to run Oxlint on which the migrator did not handle, you can add the relevant patterns to the `ignorePatterns` field in `.oxlintrc.json`.
+
+**Not all ESLint plugins will work with JS Plugins**
+
+The JS Plugins API supports almost all ESLint v9+ plugins for linting JS/TS/JSX/TSX files, but there are still some minor holes in support. See the [JS Plugins documentation](https://oxc.rs/docs/guide/usage/linter/js-plugins.html) for specifics.
+
+For example, if you currently use `eslint-plugin-prettier`, it will not work as a JS Plugin, as we do not support custom parsers for JS Plugins. To replace the functionality of `eslint-plugin-prettier`, you can use `prettier --check` in CI and/or your git pre-commit hooks to ensure code formatting is enforced.
+
+You could also consider [replacing Prettier with Oxfmt](https://oxc.rs/docs/guide/usage/formatter/migrate-from-prettier.html).
+
+Note that `eslint-config-prettier` is different from the prettier plugin, and _will_ be migrated fine, as it's just a config to disable formatting-related ESLint rules, not an actual plugin.

package/dist/bin/oxlint-migrate.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { i as rules_exports, n as preFixForJsPlugins, r as nurseryRules, t as src_default } from "../src-BNblTDrB.mjs";
+import { a as rules_exports, i as nurseryRules, n as preFixForJsPlugins, r as isOffValue, t as src_default } from "../src-BMWXAQvA.mjs";
 import { program } from "commander";
 import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import path from "node:path";
@@ -17,9 +17,9 @@ const FLAT_CONFIG_FILENAMES = [
 	"eslint.config.mts",
 	"eslint.config.cts"
 ];
-const getAutodetectedEslintConfigName = (cwd$1) => {
+const getAutodetectedEslintConfigName = (cwd) => {
 	for (const filename of FLAT_CONFIG_FILENAMES) {
-		const filePath = path.join(cwd$1, filename);
+		const filePath = path.join(cwd, filename);
 		if (existsSync(filePath)) return filePath;
 	}
 };
@@ -40,7 +40,7 @@ const loadESLintConfig = async (filePath) => {
 
 //#endregion
 //#region package.json
-var version = "1.41.0";
+var version = "1.43.0";
 
 //#endregion
 //#region src/walker/comments/replaceRuleDirectiveComment.ts
@@ -211,8 +211,8 @@ function partialAstroSourceTextLoader(sourceText) {
 			pos = frontmatterEndDelimiter + 3;
 		}
 	}
-	results.push(...extractScriptBlocks(sourceText, pos, Number.MAX_SAFE_INTEGER, false).map((sourceText$1) => {
-		return Object.assign(sourceText$1, {
+	results.push(...extractScriptBlocks(sourceText, pos, Number.MAX_SAFE_INTEGER, false).map((sourceText) => {
+		return Object.assign(sourceText, {
 			lang: `ts`,
 			sourceType: `module`
 		});
@@ -227,7 +227,7 @@ const getComments = (absoluteFilePath, partialSourceText, options) => {
 		lang: partialSourceText.lang,
 		sourceType: partialSourceText.sourceType
 	});
-	if (parserResult.errors.length > 0) options.reporter?.report(`${absoluteFilePath}: failed to parse`);
+	if (parserResult.errors.length > 0) options.reporter?.addWarning(`${absoluteFilePath}: failed to parse`);
 	return parserResult.comments;
 };
 function replaceCommentsInSourceText(absoluteFilePath, partialSourceText, options) {
@@ -241,7 +241,7 @@ function replaceCommentsInSourceText(absoluteFilePath, partialSourceText, option
 		}
 	} catch (error) {
 		if (error instanceof Error) {
-			options.reporter?.report(`${absoluteFilePath}, char offset ${comment.start + partialSourceText.offset}: ${error.message}`);
+			options.reporter?.addWarning(`${absoluteFilePath}, char offset ${comment.start + partialSourceText.offset}: ${error.message}`);
 			continue;
 		}
 		throw error;
@@ -258,13 +258,13 @@ function replaceCommentsInFile(absoluteFilePath, fileContent, options) {
 
 //#endregion
 //#region src/walker/index.ts
-const walkAndReplaceProjectFiles = (projectFiles, readFileSync$1, writeFile$1, options) => {
+const walkAndReplaceProjectFiles = (projectFiles, readFileSync, writeFile, options) => {
 	return Promise.all(projectFiles.map((file) => {
-		const sourceText = readFileSync$1(file);
+		const sourceText = readFileSync(file);
 		if (!sourceText) return Promise.resolve();
 		const newSourceText = replaceCommentsInFile(file, sourceText, options);
 		if (newSourceText === sourceText) return Promise.resolve();
-		return writeFile$1(file, newSourceText);
+		return writeFile(file, newSourceText);
 	}));
 };
 
@@ -281,20 +281,18 @@ const getAllProjectFiles = () => {
 //#endregion
 //#region src/reporter.ts
 var DefaultReporter = class {
-	reports = /* @__PURE__ */ new Set();
+	warnings = /* @__PURE__ */ new Set();
 	skippedRules = new Map([
 		["nursery", /* @__PURE__ */ new Set()],
 		["type-aware", /* @__PURE__ */ new Set()],
-		["unsupported", /* @__PURE__ */ new Set()]
+		["unsupported", /* @__PURE__ */ new Set()],
+		["js-plugins", /* @__PURE__ */ new Set()]
 	]);
-	report(message) {
-		this.reports.add(message);
+	addWarning(message) {
+		this.warnings.add(message);
 	}
-	remove(message) {
-		this.reports.delete(message);
-	}
-	getReports() {
-		return Array.from(this.reports);
+	getWarnings() {
+		return Array.from(this.warnings);
 	}
 	markSkipped(rule, category) {
 		this.skippedRules.get(category)?.add(rule);
@@ -306,6 +304,7 @@ var DefaultReporter = class {
 		const result = {
 			nursery: [],
 			"type-aware": [],
+			"js-plugins": [],
 			unsupported: []
 		};
 		for (const [category, rules] of this.skippedRules) result[category] = Array.from(rules);
@@ -313,6 +312,92 @@ var DefaultReporter = class {
 	}
 };
 
+//#endregion
+//#region bin/output-formatter.ts
+const CATEGORY_METADATA = {
+	nursery: {
+		label: "Nursery",
+		description: "Experimental:"
+	},
+	"type-aware": {
+		label: "Type-aware",
+		description: "Requires TS info:"
+	},
+	"js-plugins": {
+		label: "JS Plugins",
+		description: "Requires JS plugins:"
+	},
+	unsupported: { label: "Unsupported" }
+};
+const MAX_LABEL_LENGTH = Math.max(...Object.values(CATEGORY_METADATA).map((meta) => meta.label.length));
+/**
+* Formats a category summary as either inline (with example) or vertical list
+*/
+function formatCategorySummary(count, category, rules, showAll) {
+	const meta = CATEGORY_METADATA[category];
+	if (!showAll) {
+		const maxRules = 3;
+		const exampleList = rules.slice(0, maxRules).join(", ");
+		const suffix = count > maxRules ? ", and more" : "";
+		const prefix = meta.description ? `${meta.description} ` : "";
+		return `     - ${String(count).padStart(3)} ${meta.label.padEnd(MAX_LABEL_LENGTH)} (${prefix}${exampleList}${suffix})\n`;
+	}
+	let output = `     - ${count} ${meta.label}\n`;
+	for (const rule of rules) output += `       - ${rule}\n`;
+	return output;
+}
+/**
+* Detects which CLI flags are missing and could enable more rules
+*/
+function detectMissingFlags(byCategory, cliOptions) {
+	const missingFlags = [];
+	if (byCategory.nursery.length > 0 && !cliOptions.withNursery) missingFlags.push("--with-nursery");
+	if (byCategory["type-aware"].length > 0 && !cliOptions.typeAware) missingFlags.push("--type-aware");
+	if (byCategory["js-plugins"].length > 0 && !cliOptions.jsPlugins) missingFlags.push("--js-plugins");
+	return missingFlags;
+}
+/**
+* Formats the complete migration output message
+*/
+function formatMigrationOutput(data) {
+	let output = "";
+	const showAll = data.cliOptions.details || false;
+	if (data.enabledRulesCount === 0) output += `\n⚠️ ${data.outputFileName} created with no rules enabled.\n`;
+	else output += `\n✨ ${data.outputFileName} created with ${data.enabledRulesCount} rules.\n`;
+	const byCategory = data.skippedRulesByCategory;
+	const nurseryCount = byCategory.nursery.length;
+	const typeAwareCount = byCategory["type-aware"].length;
+	const unsupportedCount = byCategory.unsupported.length;
+	const jsPluginsCount = byCategory["js-plugins"].length;
+	const totalSkipped = nurseryCount + typeAwareCount + unsupportedCount + jsPluginsCount;
+	if (totalSkipped > 0) {
+		output += `\n   Skipped ${totalSkipped} rules:\n`;
+		if (nurseryCount > 0) output += formatCategorySummary(nurseryCount, "nursery", byCategory.nursery, showAll);
+		if (typeAwareCount > 0) output += formatCategorySummary(typeAwareCount, "type-aware", byCategory["type-aware"], showAll);
+		if (jsPluginsCount > 0) output += formatCategorySummary(jsPluginsCount, "js-plugins", byCategory["js-plugins"], showAll);
+		if (unsupportedCount > 0) output += formatCategorySummary(unsupportedCount, "unsupported", byCategory.unsupported, showAll);
+		if (!showAll) {
+			const maxExamples = 3;
+			if (nurseryCount > maxExamples || typeAwareCount > maxExamples || unsupportedCount > maxExamples || jsPluginsCount > maxExamples) output += `\n     Tip: Use --details to see the full list.\n`;
+		}
+		const missingFlags = detectMissingFlags(byCategory, data.cliOptions);
+		if (missingFlags.length > 0) {
+			const eslintConfigArg = data.eslintConfigPath ? ` ${path.basename(data.eslintConfigPath)}` : "";
+			output += `\n👉 Re-run with flags to include more:\n`;
+			output += `     npx @oxlint/migrate${eslintConfigArg} ${missingFlags.join(" ")}\n`;
+		}
+	}
+	if (data.enabledRulesCount > 0) {
+		output += `\n🚀 Next:\n`;
+		output += `     npx oxlint .\n`;
+	}
+	return output;
+}
+function displayMigrationResult(outputMessage, warnings) {
+	console.log(outputMessage);
+	for (const warning of warnings) console.warn(warning);
+}
+
 //#endregion
 //#region bin/oxlint-migrate.ts
 const cwd = process.cwd();
@@ -323,7 +408,22 @@ const getFileContent = (absoluteFilePath) => {
 		return;
 	}
 };
-program.name("oxlint-migrate").version(version).argument("[eslint-config]", "The path to the eslint v9 config file").option("--output-file <file>", "The oxlint configuration file where to eslint v9 rules will be written to", ".oxlintrc.json").option("--merge", "Merge eslint configuration with an existing .oxlintrc.json configuration", false).option("--with-nursery", "Include oxlint rules which are currently under development", false).option("--replace-eslint-comments", "Search in the project files for eslint comments and replaces them with oxlint. Some eslint comments are not supported and will be reported.").option("--type-aware", "Includes supported type-aware rules. Needs the same flag in `oxlint` to enable it.").option("--js-plugins", "Tries to convert unsupported oxlint plugins with `jsPlugins`.").action(async (filePath) => {
+/**
+* Count enabled rules (excluding "off" rules) from both rules and overrides
+*/
+const countEnabledRules = (config) => {
+	const enabledRules = /* @__PURE__ */ new Set();
+	if (config.rules) {
+		for (const [ruleName, ruleValue] of Object.entries(config.rules)) if (!isOffValue(ruleValue)) enabledRules.add(ruleName);
+	}
+	if (config.overrides && Array.isArray(config.overrides)) {
+		for (const override of config.overrides) if (override.rules) {
+			for (const [ruleName, ruleValue] of Object.entries(override.rules)) if (!isOffValue(ruleValue)) enabledRules.add(ruleName);
+		}
+	}
+	return enabledRules.size;
+};
+program.name("oxlint-migrate").version(version).argument("[eslint-config]", "The path to the eslint v9 config file").option("--output-file <file>", "The oxlint configuration file where to eslint v9 rules will be written to", ".oxlintrc.json").option("--merge", "Merge eslint configuration with an existing .oxlintrc.json configuration", false).option("--with-nursery", "Include oxlint rules which are currently under development", false).option("--replace-eslint-comments", "Search in the project files for eslint comments and replaces them with oxlint. Some eslint comments are not supported and will be reported.").option("--type-aware", "Includes supported type-aware rules. Needs the same flag in `oxlint` to enable it.").option("--js-plugins", "Tries to convert unsupported oxlint plugins with `jsPlugins`.").option("--details", "List rules that could not be migrated to oxlint.", false).action(async (filePath) => {
 	const cliOptions = program.opts();
 	const oxlintFilePath = path.join(cwd, cliOptions.outputFile);
 	const reporter = new DefaultReporter();
@@ -335,7 +435,7 @@ program.name("oxlint-migrate").version(version).argument("[eslint-config]", "The
 		jsPlugins: !!cliOptions.jsPlugins
 	};
 	if (cliOptions.replaceEslintComments) {
-		await walkAndReplaceProjectFiles(await getAllProjectFiles(), (filePath$1) => getFileContent(filePath$1), (filePath$1, content) => writeFile(filePath$1, content, "utf-8"), options);
+		await walkAndReplaceProjectFiles(await getAllProjectFiles(), (filePath) => getFileContent(filePath), (filePath, content) => writeFile(filePath, content, "utf-8"), options);
 		return;
 	}
 	if (filePath === void 0) filePath = getAutodetectedEslintConfigName(cwd);
@@ -352,7 +452,19 @@ program.name("oxlint-migrate").version(version).argument("[eslint-config]", "The
 	const oxlintConfig = "default" in eslintConfigs ? await src_default(eslintConfigs.default, config, options) : await src_default(eslintConfigs, config, options);
 	if (existsSync(oxlintFilePath)) renameSync(oxlintFilePath, `${oxlintFilePath}.bak`);
 	writeFileSync(oxlintFilePath, JSON.stringify(oxlintConfig, null, 2));
-	for (const report of reporter.getReports()) console.warn(report);
+	const enabledRulesCount = countEnabledRules(oxlintConfig);
+	displayMigrationResult(formatMigrationOutput({
+		outputFileName: cliOptions.outputFile,
+		enabledRulesCount,
+		skippedRulesByCategory: reporter.getSkippedRulesByCategory(),
+		cliOptions: {
+			withNursery: !!cliOptions.withNursery,
+			typeAware: !!cliOptions.typeAware,
+			details: !!cliOptions.details,
+			jsPlugins: !!cliOptions.jsPlugins
+		},
+		eslintConfigPath: filePath
+	}), reporter.getWarnings());
 });
 program.parse();