Skip to content

chore(lint): migrate to oxlint and oxfmt - #1117

Open
EhabY wants to merge 9 commits into
mainfrom
chore/oxc-lint-format-migration
Open

EhabY wants to merge 9 commits into
mainfrom
chore/oxc-lint-format-migration

Conversation

@EhabY

@EhabY EhabY commented Sep 16, 2026

Copy link
Copy Markdown
Collaborator

What and why

Move linting to Oxlint and formatting to Oxfmt, keeping a small residual ESLint for what Oxlint cannot do (import-x/order, Markdown, package.json).

Benchmarks

Interleaved A/B against main on the same host, minimum of 3–5 rounds, corroborated in CPU time. Negative Δ is faster.

Case main branch Δ
CI lint job (typecheck + format + lint) 26.3s 5.2s −80%
pnpm lint cold 17.1s 4.8s −72%
pnpm lint at default heap crash (OOM, exit 134) passes fixed
pnpm format:check cold 3.22s 0.30s −91%
pnpm typecheck (root + test) 5.43s 0.95s −83%
pnpm lint warm 0.94s 2.86s +204%

Real CI agrees: Lint went from 94s on main to 39s here (run 35145079125).

The warm regression. Oxlint and Oxfmt have no cache, so warm local lint is genuinely slower than cached ESLint. Two mitigations, both applied or documented:

  • Thread capping (perf(lint)): both tools default to nproc threads; above ~32 cores the per-thread startup outweighs the parallelism. Capping at 8 cut oxlint 4.0s→2.1s and oxfmt 1.8s→0.23s on a 128-core box, and is a no-op on CI (4 vCPU) and typical laptops. Upstream: oxc#21672.
  • JS plugins: the rest is a fixed ~400ms load plus per-file AST bridging in the react-x plugin, inherent to the bridge. Editor latency is unaffected; the Oxc LSP measures 60ms init and <1ms diagnostics on didChange.

Rule coverage

I diffed every rule enabled on main against the effective rules here, per file, using --print-config. Everything left out is accounted for:

Rule Status
@eslint-react/no-leaked-conditional-rendering Genuine loss (type-aware, can't run as a JS plugin). All 4 reported sites were already safe and are now explicit ternaries; 2 no-restricted-syntax selectors cover numeric JSX &&.
curly Inert on main: eslint-config-prettier set it to 0, so it never ran. Enabling it fresh fails on 69 pre-existing sites, so it stays off rather than blocking this PR.
@typescript-eslint/prefer-optional-chain Nursery-only in Oxlint; not enabled.
no-undef Oxlint omits it; tsc + strict mode covers it.
import-x/no-unresolved Redundant; tsc reports TS2307 and runs earlier in CI.
import-x/no-relative-packages Replaced by tsconfig rootDir, which is stricter (catches even valid cross-package relative imports).
no-dupe-args, no-octal Superseded by strict mode.
react-hooks/config, react-hooks/gating Structurally inert: no react-compiler settings and no gating options are configured.
no-useless-assignment Recovered via the already-loaded eslint-js plugin.

React regression, found and fixed. The migration tool copied disable-conflict-eslint-plugin-react-hooks's react-hooks/*: off entries across as react/* (Oxlint's own namespace), silently disabling @eslint-react rules with no replacement. fix(lint) restores the 17 natively-implemented rules at their previous severities and loads the other 52 from @eslint-react as a JS plugin aliased react-x; a probe with a conditional hook, missing key, leaked fetch, and nested component reports the same 5 findings as main.

Upstream workarounds

Both guarded by test/unit/oxlintConfig.test.ts:

  1. Extglob patterns silently match nothing (oxc#21525). The tool emitted **/*.stories.@(ts|tsx|...), leaving every Storybook rule inert. Brace globs instead.
  2. JS plugin specifiers don't resolve: absolute paths embed pnpm peer hashes; bare names don't resolve for ESM-only plugins. Root-relative paths, asserted to exist by the test.

Also: no-restricted-imports patterns understand only ** and literal paths, not single *, so the UI guard is "../../../**".

Formatting

22 files reformat from exactly two divergence classes, both deterministic and idempotent: union types expand to leading-pipe style (known upstream divergence, oxc#25841) and one yield operand is parenthesised. Prettier stays a devDependency because Oxfmt delegates Markdown/YAML to it internally.

TypeScript 7

TS 7 has no programmatic API and typescript-eslint refuses to load against it, so they run side-by-side per the official guidance: typescript aliased to @typescript/typescript6 (API, tsc6) and @typescript/native to typescript@^7 (the tsc binary). This also fixes the default-heap OOM: the full type-aware ESLint config exceeded the default heap, and dropping that config removes the need for --max-old-space-size.

Reviewer checklist

  • Keeping ESLint for import-x/order is acceptable (the alternative is a 153-file sortImports reformat)
  • The 22-file reformat in style(format) is formatting-only
  • The side-by-side TypeScript setup beats waiting for typescript-eslint TS7 support
  • The warm-loop cost (no cache) is acceptable
  • Capping threads at 8 is preferred to tool defaults

This PR was generated by Coder Agents.

Run Oxlint for all JS/TS/TSX linting, including type-aware rules via
oxlint-tsgolint, and reduce ESLint to the three things Oxlint cannot do:
`import-x/order`, Markdown, and `package.json`.

`eslint-plugin-oxlint` reads `.oxlintrc.json` and turns off every rule
Oxlint already covers, so the two stages never disagree.

Notes on `.oxlintrc.json`, which is generated from the previous ESLint
config with several fixes applied:

- `overrides[].files` do not support extglob alternatives such as
  `@(ts|tsx)`. The migration tool emits `**/*.stories.@(ts|tsx|js|jsx|mjs|cjs)`
  from eslint-plugin-storybook, which silently matches nothing and leaves
  every Storybook rule inert (oxc-project/oxc#21525). Brace globs are used
  instead.
- JS plugin specifiers are relative to the repo root. Absolute paths through
  the pnpm store embed peer-dependency hashes that change on every dependency
  bump, and bare package names do not resolve for ESM-only plugins.
- The architecture guards (`ContextManager`, `CommandManager`,
  `vscodeProposed.env.remoteAuthority`) are kept via
  `oxlint-plugin-eslint`'s `no-restricted-syntax`, with two additions that
  catch numeric operands in JSX `&&` (the case
  `@eslint-react/no-leaked-conditional-rendering` covered).
- The 60 `package-json/*` rules the migration tool generated were dropped:
  Oxlint only lints source extensions, so they can never run.

`packages/ui` keeps its boundary two ways now. `rootDir` in its tsconfig
makes a file reaching outside the package a compile error, which is
structural and covers cases a lint rule misses. The lint guard stays as
defence in depth and needs `"../../../**"` rather than `"../../../*"`,
because Oxlint's pattern matching does not implement single-star wildcards.

Reducing ESLint to these rules also removes the need to raise
`--max-old-space-size`: the full type-aware config needed more than the
default heap and aborted with an out-of-memory error. Both that and the
default heap limit reproduce on the previous commit.

Two `eslint-disable` comments became `oxlint-disable`, since Oxlint now owns
`no-console` and `no-explicit-any`.

`test/unit/oxlintConfig.test.ts` guards the extglob and plugin-path
regressions.
Replace `{value && <Element />}` with ternaries in the four places the
left-hand operand is not provably boolean.

`@eslint-react/no-leaked-conditional-rendering` flagged non-boolean
operands here, but it requires type information, so it cannot run as an
Oxlint JS plugin. It also only reports number, bigint, and NaN operands:
strings and plain booleans are allowed on React 18 and later, so these
four sites were already safe. Making them explicit keeps the intent
obvious and means dropping the rule costs no coverage.
Replace Prettier with Oxfmt for formatting and drop the `--cache` flags,
which Oxfmt does not support.

`.oxfmtrc.json` comes from `oxfmt --migrate prettier`, which reads
`.prettierrc.json` and `.prettierignore` and preserves the verbatim-write
exclusions for golden snapshots and generated VS Code themes. The
`*.jsonc` override could not be migrated automatically and is written by
hand. `printWidth` stays at 80 to match the previous output. `sortImports`
is left off: it reorders imports differently from `import-x/order` and is
not a drop-in.

This reformats 22 files. Both differences are formatting-only, and output
is deterministic and idempotent:

- Union types are expanded to leading-pipe style. This is a known
  divergence, oxfmt currently matches Prettier 3.4 rather than 3.9
  (oxc-project/oxc#25841).
- One `yield` operand in `src/telemetry/export/writers/json.ts` is wrapped
  in parentheses.

Prettier stays a devDependency: Oxfmt delegates Markdown, HTML, YAML, and
Vue to it internally, and the residual ESLint config still formats against
it.
Use TypeScript 7 for typechecking while keeping the TypeScript 6 API
available to typescript-eslint, which refuses to load against TypeScript 7
(its peer range is `>=4.8.4 <6.1.0`, and support is still tracked upstream).

Following the official side-by-side guidance:

- `typescript` is aliased to `@typescript/typescript6`, which re-exports the
  6.0 API that typescript-eslint consumes. Its binary is `tsc6`.
- `@typescript/native` is aliased to `typescript@^7`, providing the `tsc`
  binary used by `pnpm typecheck` and editors.

Measured on this repo: typechecking the root config drops from 1701ms to
371ms, and the test config from 3768ms to 903ms.

tsgolint already embeds the TypeScript 7 engine, so Oxlint's type-aware
rules were already running on it; this brings `pnpm typecheck` onto the same
engine. When TypeScript 7 ships an API, drop `@typescript/native` and point
`typescript` back at a single version.
The migration tool turned 12 React rules off. `eslint-plugin-react-hooks`'s
`disable-conflict-eslint-plugin-react-hooks` preset sets `react-hooks/*` to
off because `@eslint-react` ships the same rules; the tool copied those
disables across as `react/*`, which is Oxlint's own plugin namespace. The
effect was that `@eslint-react`'s rules were disabled and nothing replaced
them.

Concretely, rules like `rules-of-hooks`, `static-components`,
`no-missing-key`, `no-nested-component-definitions` and
`web-api-no-leaked-fetch` stopped reporting. A planted conditional hook and a
missing list key were caught on the previous commit and silently passed here.

Restore them two ways:

- Rules Oxlint implements natively are set to the severities the previous
  config used.
- The 52 rules it does not implement are loaded from `@eslint-react` as a JS
  plugin aliased `react-x`. All 52 were verified to load and report.

`no-leaked-conditional-rendering` is the only rule that needs type
information, so it cannot run as a JS plugin and stays dropped.

`eslint-js/no-useless-assignment` is added since the plugin is already
loaded: Oxlint omits the rule, and the JS plugin implements it.

Rule coverage per file is now within 4-8 rules of the previous ESLint config,
and every remaining difference is accounted for.
Both tools default to one thread per core. Thread startup is a fixed
per-thread cost, so on machines with many cores it outweighs the parallelism
it buys. Measured on this repo (511 files) on a 128-core machine:

| | default | capped |
| --- | --- | --- |
| oxlint --type-aware | 4.0s | 2.1s |
| oxfmt --check | 1.8s | 0.23s |

Degradation starts above roughly 32 cores. From 2 to 16 cores the cap makes
no measurable difference, because the default already equals it, and CI
runners (4 vCPU) detect 4 either way, so this only affects large dev boxes.

The value is capped rather than pinned, so smaller machines and CI keep
their own optimal thread count instead of being pushed into an
oversubscribed one. A fixed number would have made a 2-core machine 1.6x
slower.

The helper script is run through Node rather than a `$(...)` substitution in
the npm scripts, so it behaves identically on Windows.

Warm `pnpm lint` drops from 4.5s to 2.9s and `pnpm format:check` from 1.8s
to 0.31s. Upstream tracking: oxc-project/oxc#21672.
Tighten the wording added in the oxlint/oxfmt migration: drop em-dashes,
trim wordy sentences, and shorten the thread-cap comment in run-oxc.mjs
to the load-bearing facts.

Fix the TypeScript 7 announcement URL in CONTRIBUTING.md, which was
missing the /typescript/ path segment.
- Remove comments from .vscode/settings.json
- Condense comments in packages/ui/tsconfig.json and pnpm-workspace.yaml
- Use block comments in scripts/run-oxc.mjs
- Document why sortPackageJson is disabled in .oxfmtrc.json
- Drop ignorePatterns for paths nothing generates (.nyc_output, .claude,
  pnpm-debug.log)
- Remove redundant empty rules object from .oxlintrc.json
- Slim test/unit/oxlintConfig.test.ts by inlining single-use helpers
- Trim the eslint-plugin-oxlint implementation detail from AGENTS.md
Switch .oxlintrc.json from an explicit 59-rule list to
categories.correctness: error, keeping only the 7 rules not in the
category. This enables 36 additional rules; fix the 5 findings:

- treeTransition.ts: spread on string breaks emoji code points
- cliManager.ts: spread on AxiosHeaders loses class prototype
- deploymentManager.test.ts, loginCoordinator.test.ts: spread on class
  in vi.mock drops prototype
- localJsonlSink.test.ts: toSorted() without comparator sorts
  lexicographically

Extract the react/react-x override into .oxlintrc.react.json via
oxlint extends.
@EhabY
EhabY marked this pull request as ready for review September 17, 2026 13:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant