biome-to-oxc 1.4.0 → 2.0.0

package/README.md

@@ -28,17 +28,27 @@ Current capabilities:
 ✅ **Preserves Representable Setup**
 
 - Ignore patterns, override file globs, and override exclusions
-- `.biomeignore` patterns migrated into Oxlint `ignorePatterns` (compatibility alias)
+- Negated `includes` exceptions (`!pattern`), translated into `ignorePatterns` for both tools
+- `.biomeignore` patterns migrated into the Oxlint **and** Oxfmt `ignorePatterns`. Biome 2.x does
+  not read `.biomeignore` itself, so this deliberately narrows scope; the migration says so
 - Linter configuration overrides
 - Formatter configuration overrides when they can be represented as Oxfmt file-glob overrides
 - JavaScript globals
 - Rule severities (`error`/`warn`/`off`; `info` and `on` are accepted with explicit lossy-mapping warnings)
 - Explicit `printWidth` handling (no silent changes)
-- Custom output-directory glob rebasing so generated configs keep source-relative paths
+- The set of formatted files: Oxfmt-only formats (YAML, TOML, Markdown) are excluded, and
+  `sortPackageJson` is pinned off, so migrating never reformats files Biome left alone
+
+✅ **Refuses to Lose Behaviour Silently**
+
+Anything the generated configs provably do not reproduce is recorded as a **semantic loss** and
+listed under `losses` in the report. Losses make the migration report `success: false` and block
+both `--delete` and removal of the `@biomejs/biome` dependency, so a lossy conversion can never
+leave a project without a working linter or formatter. Resolve the listed losses and re-run.
 
 Positive-only Biome `files`/`linter`/`formatter` include selection has no direct Oxc config
-equivalent. The migration reports this explicitly; pass equivalent paths to the Oxc CLI or review
-the generated ignore configuration before removing Biome.
+equivalent and is reported as a loss; pass equivalent paths to the Oxc CLI or review the generated
+ignore configuration before removing Biome.
 
 ### Advanced Features
 
@@ -207,11 +217,14 @@ npx biome-to-oxc --report migration-report.json
 # Print the migration report to stdout as JSON
 npx biome-to-oxc --json
 
-# Migrate with custom output directory
-npx biome-to-oxc --output-dir ./config
+# Migrate with a custom output directory.
+# Oxlint and Oxfmt resolve config globs inside the config file's own directory and reject `..`,
+# so the output directory must be the Biome project root or an ancestor of it. A directory below
+# the project root is rejected whenever the migration would emit any glob.
+npx biome-to-oxc --output-dir ../shared-config
 
 # Rewritten scripts explicitly load configs placed outside the package root
-npx biome-to-oxc --output-dir ./config --update-scripts
+npx biome-to-oxc --output-dir ../shared-config --update-scripts
 
 # Migrate without creating backups
 npx biome-to-oxc --no-backup
@@ -341,16 +354,24 @@ npx oxlint --type-aware --type-check
 
 ## Known Limitations
 
-- Not all Biome rules have direct Oxlint equivalents (warnings will be shown)
+- Not all Biome rules have direct Oxlint equivalents (reported as semantic losses)
 - Some advanced Biome features may not be supported
 - Biome recommended/all presets and group-level severities are approximated with Oxlint categories;
-  preset membership is not identical between the tools
+  preset membership is not identical between the tools. This approximation is reported as a warning
+  rather than a loss, because it applies to essentially every migration
 - Positive-only Biome include selection cannot be encoded directly in Oxlint/Oxfmt config files
+- Generated config globs are resolved inside the config file's directory, so `--output-dir` must
+  point at the Biome project root or an ancestor of it
+- `formatter.lineEnding: "auto"` has no Oxfmt equivalent (Oxfmt always writes LF)
+- Lockfiles are not regenerated. When dependencies change, the report names the lockfile and the
+  install command needed before any frozen-lockfile install
 - Oxlint overrides cannot carry category presets; explicit override rules are migrated and category
   presets are reported for manual review
 - Oxfmt is in beta; review formatting changes before replacing the existing formatter
-- Type-aware linting requires TypeScript 7 and `oxlint-tsgolint`; 59 of the 61 targeted
-  typescript-eslint rules are currently implemented
+- Overlapping `overrides` are migrated as-is. Biome and Oxfmt both merge matching overrides field
+  by field with later entries winning, so the two agree; a conformance test pins this
+- Type-aware linting is stable as of `oxlint-tsgolint` v7 and requires TypeScript 7; 59 of the 61
+  targeted typescript-eslint rules are currently implemented
 - CSS and JSON formatter overrides are mapped but may need manual review
 - Prettier plugin support is not available in Oxfmt
 - Some Biome rules still require JS plugin fallback until native rule parity is available

package/dist/bin/biome-to-oxc.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { i as readJsonFile, n as DefaultReporter, r as findClosestPackageJson, t as migrate } from "../src-B1tF4LEv.mjs";
+import { i as readJsonFile, n as DefaultReporter, r as findClosestPackageJson, t as migrate } from "../src-CYMpPpfK.mjs";
 import { realpath } from "node:fs/promises";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -19,7 +19,6 @@ const MigrationOptionsSchema = z.object({
 	delete: z.boolean().default(false),
 	noBackup: z.boolean().default(false),
 	updateScripts: z.boolean().default(false),
-	dom: z.boolean().default(false),
 	verbose: z.boolean().default(false),
 	typeAware: z.boolean().default(false),
 	typeCheck: z.boolean().default(false),
@@ -63,14 +62,16 @@ async function runCli(argv, runtimeOptions = {}) {
 			}
 			return 2;
 		}
-		const report = await migrate({
+		const migrationOptions = {
 			...validationResult.data,
 			signal: runtimeOptions.signal
-		}, new DefaultReporter({
+		};
+		const reporter = new DefaultReporter({
 			verbose: validationResult.data.verbose && !parsedCliOptions.json,
 			stdout,
 			stderr
-		}));
+		});
+		const report = await migrate(migrationOptions, reporter);
 		if (parsedCliOptions.json) stdout.write(`${JSON.stringify(report, null, 2)}\n`);
 		else if (report.success) writeHumanSuccessSummary(report, validationResult.data.dryRun, stdout);
 		return report.success ? 0 : 1;
@@ -105,7 +106,7 @@ function createCommand(packageMetadata, streams) {
 		writeOut: (chunk) => {
 			streams.stdout.write(chunk);
 		}
-	}).option("-c, --config <path>", "Path to biome.json or biome.jsonc").option("-o, --output-dir <path>", "Output directory for generated configs").option("--dry-run", "Show what would be done without making changes").option("--delete", "Delete legacy Biome files after migration (biome.json/biome.jsonc and .biomeignore)").option("--no-backup", "Skip backup of existing config files").option("--update-scripts", "Update package.json scripts to use oxlint/oxfmt").addOption(new Option("--dom").hideHelp()).option("--type-aware", "Include type-aware linting guidance and dependencies").option("--type-check", "Enable strict typed linting mode (implies --type-aware)").addOption(new Option("--type-aware-profile <profile>", "Type-aware profile: standard (--type-aware) or strict (--type-aware --type-check)").choices(["standard", "strict"]).default("standard")).addOption(new Option("--fix-strategy <strategy>", "Fix mode for rewritten scripts: safe | suggestions | dangerous").choices([
+	}).option("-c, --config <path>", "Path to biome.json or biome.jsonc").option("-o, --output-dir <path>", "Output directory for generated configs").option("--dry-run", "Show what would be done without making changes").option("--delete", "Delete legacy Biome files after migration (biome.json/biome.jsonc and .biomeignore)").option("--no-backup", "Skip backup of existing config files").option("--update-scripts", "Update package.json scripts to use oxlint/oxfmt").option("--type-aware", "Include type-aware linting guidance and dependencies").option("--type-check", "Enable strict typed linting mode (implies --type-aware)").addOption(new Option("--type-aware-profile <profile>", "Type-aware profile: standard (--type-aware) or strict (--type-aware --type-check)").choices(["standard", "strict"]).default("standard")).addOption(new Option("--fix-strategy <strategy>", "Fix mode for rewritten scripts: safe | suggestions | dangerous").choices([
 		"safe",
 		"suggestions",
 		"dangerous"
@@ -113,7 +114,8 @@ function createCommand(packageMetadata, streams) {
 	return command;
 }
 async function loadCliPackageMetadata() {
-	const packageManifestPath = await findClosestPackageJson(dirname(fileURLToPath(import.meta.url)));
+	const packageDirectory = dirname(fileURLToPath(import.meta.url));
+	const packageManifestPath = await findClosestPackageJson(packageDirectory);
 	if (!packageManifestPath) throw new Error("Unable to locate the CLI package manifest.");
 	return readJsonFile(packageManifestPath, CliPackageMetadataSchema, `CLI package manifest at ${packageManifestPath}`);
 }
@@ -128,7 +130,6 @@ function normalizeMigrationOptions(options) {
 		delete: options.delete,
 		noBackup: options.backup === false,
 		updateScripts: options.updateScripts,
-		dom: options.dom,
 		verbose: options.verbose,
 		typeAware,
 		typeCheck,

package/dist/src/index.d.mts

@@ -16,6 +16,8 @@ interface BiomeConfig {
 interface BiomeFilesConfig {
   include?: string[];
   includes?: string[];
+  /** Negated `includes` entries (`!pattern`), split out during normalization. */
+  exclude?: string[];
   ignore?: string[];
   ignoreUnknown?: boolean;
   maxSize?: number;
@@ -31,6 +33,8 @@ interface BiomeLinterConfig {
   enabled?: boolean;
   include?: string[];
   includes?: string[];
+  /** Negated `includes` entries (`!pattern`), split out during normalization. */
+  exclude?: string[];
   ignore?: string[];
   rules?: BiomeLinterRules;
 }
@@ -55,11 +59,13 @@ interface BiomeFormatterConfig {
   enabled?: boolean;
   include?: string[];
   includes?: string[];
+  /** Negated `includes` entries (`!pattern`), split out during normalization. */
+  exclude?: string[];
   ignore?: string[];
   formatWithErrors?: boolean;
   indentStyle?: 'tab' | 'space';
   indentWidth?: number;
-  lineEnding?: 'lf' | 'crlf' | 'cr';
+  lineEnding?: 'lf' | 'crlf' | 'cr' | 'auto';
   lineWidth?: number;
   attributePosition?: 'auto' | 'multiline';
   bracketSpacing?: boolean;
@@ -82,7 +88,7 @@ interface BiomeJavaScriptConfig {
     bracketSpacing?: boolean;
     indentStyle?: 'tab' | 'space';
     indentWidth?: number;
-    lineEnding?: 'lf' | 'crlf' | 'cr';
+    lineEnding?: 'lf' | 'crlf' | 'cr' | 'auto';
     lineWidth?: number;
     [key: string]: unknown;
   };
@@ -101,7 +107,7 @@ interface BiomeJsonConfig {
     enabled?: boolean;
     indentStyle?: 'tab' | 'space';
     indentWidth?: number;
-    lineEnding?: 'lf' | 'crlf' | 'cr';
+    lineEnding?: 'lf' | 'crlf' | 'cr' | 'auto';
     lineWidth?: number;
     trailingCommas?: 'none' | 'all';
   };
@@ -117,7 +123,7 @@ interface BiomeCssConfig {
     enabled?: boolean;
     indentStyle?: 'tab' | 'space';
     indentWidth?: number;
-    lineEnding?: 'lf' | 'crlf' | 'cr';
+    lineEnding?: 'lf' | 'crlf' | 'cr' | 'auto';
     lineWidth?: number;
     quoteStyle?: 'single' | 'double';
   };
@@ -128,6 +134,8 @@ interface BiomeCssConfig {
 interface BiomeOverride {
   include?: string[];
   includes?: string[];
+  /** Negated `includes` entries (`!pattern`), split out during normalization. */
+  exclude?: string[];
   ignore?: string[];
   linter?: BiomeLinterConfig;
   formatter?: BiomeFormatterConfig;
@@ -298,7 +306,6 @@ interface MigrationOptions {
   delete?: boolean;
   noBackup?: boolean;
   updateScripts?: boolean;
-  dom?: boolean;
   verbose?: boolean;
   typeAware?: boolean;
   typeCheck?: boolean;
@@ -338,21 +345,45 @@ interface PackageUpdateSummary {
   dependenciesRemoved: PackageDependencyRemoval[];
   devDependencies: PackageDevDependencyChange[];
   changed: boolean;
+  /** Lockfile that dependency changes invalidated, when one was detected. */
+  lockfile?: LockfileStatus;
+}
+interface LockfileStatus {
+  path: string;
+  /** Command that regenerates the lockfile from the updated manifest. */
+  installCommand: string;
+  /** True when this run changed dependencies, so the lockfile no longer matches. */
+  stale: boolean;
 }
 interface MigrationReport {
+  /**
+   * True when the migration wrote every requested change without errors AND the
+   * generated configuration is a complete replacement for the Biome setup.
+   * A migration with semantic losses reports `success: false` because the project
+   * still depends on behaviour that Oxc does not reproduce.
+   */
   success: boolean;
   warnings: string[];
   errors: string[];
+  /** Source behaviour the generated target configs provably do not reproduce. */
+  losses: string[];
   suggestions: string[];
   packageJson?: PackageUpdateSummary;
   summary: {
     biomeConfigPath: string;
     oxlintConfigPath: string;
     oxfmtConfigPath: string;
+    /** Distinct Biome source rules that produced at least one Oxlint rule. */
     rulesConverted: number;
+    /** Distinct Biome source rules with no Oxlint equivalent. */
     rulesSkipped: number;
+    /** Oxlint rule entries emitted (one source rule can emit several). */
+    oxlintRulesEmitted: number;
     overridesConverted: number;
+    /** Oxfmt overrides derived from Biome `overrides` entries. */
     formatterOverridesConverted: number;
+    /** Oxfmt overrides synthesized to carry per-language Biome formatter settings. */
+    formatterLanguageOverrides: number;
   };
   detectedIntegrations?: {
     turborepo?: boolean;
@@ -360,16 +391,38 @@ interface MigrationReport {
     prettier?: boolean;
     typescript?: boolean;
   };
+  cleanup?: CleanupOutcome;
+}
+interface CleanupOutcome {
+  /** Whether `--delete` was requested. */
+  requested: boolean;
+  /** Whether legacy Biome files were (or in dry-run, would be) removed. */
+  performed: boolean;
+  /** Why cleanup was withheld, when it was requested but not performed. */
+  blockedReason?: string;
+  /** Legacy Biome files removed, or that would be removed in dry-run. */
+  files: string[];
 }
 interface Reporter {
   warn(message: string): void;
   error(message: string): void;
   info(message: string): void;
+  /**
+   * Records a semantic-loss diagnostic: source behaviour that the generated target
+   * configuration provably does not reproduce.
+   *
+   * Unlike {@link Reporter.warn}, a loss blocks destructive cleanup (`--delete`) and
+   * removal of the Biome dependency, because the migrated project is not yet a
+   * complete replacement for the Biome setup. Losses are also recorded as warnings so
+   * that existing warning consumers keep seeing them.
+   */
+  loss(message: string): void;
   getWarnings(): string[];
   getErrors(): string[];
+  getLosses(): string[];
 }
 //#endregion
 //#region src/index.d.ts
 declare function migrate(options?: MigrationOptions, reporter?: Reporter): Promise<MigrationReport>;
 //#endregion
-export { BiomeConfig, BiomeCssConfig, BiomeFilesConfig, BiomeFormatterConfig, BiomeJavaScriptConfig, BiomeJsonConfig, BiomeLinterConfig, BiomeLinterRules, BiomeOverride, BiomeRuleGroup, BiomeRuleSeverity, BiomeRuleSeverityValue, BiomeVcsConfig, FixStrategy, MigrationOptions, MigrationReport, OxfmtConfig, OxfmtOverride, OxlintBuiltinPlugin, OxlintConfig, OxlintJsPlugin, OxlintOverride, OxlintRuleSeverity, OxlintSettings, PackageDependencyRemoval, PackageDevDependencyChange, PackageScriptUpdate, PackageUpdateSummary, Reporter, TypeAwareProfile, migrate };
+export { BiomeConfig, BiomeCssConfig, BiomeFilesConfig, BiomeFormatterConfig, BiomeJavaScriptConfig, BiomeJsonConfig, BiomeLinterConfig, BiomeLinterRules, BiomeOverride, BiomeRuleGroup, BiomeRuleSeverity, BiomeRuleSeverityValue, BiomeVcsConfig, CleanupOutcome, FixStrategy, LockfileStatus, MigrationOptions, MigrationReport, OxfmtConfig, OxfmtOverride, OxlintBuiltinPlugin, OxlintConfig, OxlintJsPlugin, OxlintOverride, OxlintRuleSeverity, OxlintSettings, PackageDependencyRemoval, PackageDevDependencyChange, PackageScriptUpdate, PackageUpdateSummary, Reporter, TypeAwareProfile, migrate };

package/dist/src/index.mjs

@@ -1,2 +1,2 @@
-import { t as migrate } from "../src-B1tF4LEv.mjs";
+import { t as migrate } from "../src-CYMpPpfK.mjs";
 export { migrate };