@useinsider/eslint-config 3.0.2 → 4.0.0-beta.2

package/README.md

@@ -1,19 +1,90 @@
 # @useinsider/eslint-config
 
-Shared ESLint 9 flat-config for Insider projects. `useInsider()` takes a single
-scope-keyed config object and returns a `defineConfig([...])` array — one
-entry per file scope you describe. There is no opaque preset list, no
-freeform `config` escape hatch, and no expectation that you spread the result
-into your own array.
-
-The default export is the resolved Promise returned by `useInsider(...)`;
-ESLint 9 awaits it automatically. **Do not `await` it. Do not spread it. Do
-not wrap it in an array.** If you find yourself wanting to append a block,
-that is a sign your scope coverage is incomplete — describe the extra files
-inside `useInsider({...})` instead.
+Shared lint configuration for Insider projects, split across two linters.
+`useInsider()` takes a single scope-keyed config object and returns two
+renderers: `useInsiderESLint()` for ESLint 9 flat config and `useInsiderOXC()`
+for oxlint. Every rule oxlint implements natively is turned **off** on the
+ESLint side and enabled on the oxlint side from the same description, so the
+two configs cannot drift. There is no opaque preset list, no freeform `config`
+escape hatch, and no expectation that you spread either result into your own
+array.
+
+Because ESLint alone would now silently skip every rule oxlint owns, both
+linters must run. `useInsider()` refuses to start if the oxlint config is
+missing.
+
+## The three-file layout
+
+`useInsider()` is called from exactly one module, and each linter's config is
+a thin re-export of its renderer:
+
+```ts
+// insider.lint.ts
+import { useInsider } from '@useinsider/eslint-config';
+
+export const { useInsiderESLint, useInsiderOXC } = useInsider({
+    // scopes go here
+});
+```
+
+```ts
+// eslint.config.ts
+import { useInsiderESLint } from './insider.lint.ts';
+
+export default useInsiderESLint();
+```
+
+```ts
+// oxlint.config.ts
+import { useInsiderOXC } from './insider.lint.ts';
+
+export default await useInsiderOXC();
+```
+
+Then run both:
+
+```bash
+oxlint --disable-nested-config && eslint .
+```
+
+Three constraints this layout is not free to break:
+
+- **The `./insider.lint.ts` import keeps its real extension.** Neither
+  ESLint's loader nor oxlint's applies TypeScript's `.js` → `.ts` specifier
+  rewriting, so `'./insider.lint.js'` does not resolve.
+- **The ESLint config needs a TypeScript extension too** — `eslint.config.ts`
+  or `eslint.config.mts`. ESLint routes those through jiti, which resolves the
+  TypeScript lint module on every supported Node version. A `.js`/`.mjs`/`.cjs`
+  config is loaded by Node directly, so importing `./insider.lint.ts` from one
+  works only where Node's type stripping is unflagged (Node >= 22.18) and dies
+  with `ERR_UNKNOWN_FILE_EXTENSION` on Node 20. Both CLI commands therefore
+  rename an existing JavaScript flat config and delete the original.
+- **The oxlint config must be `oxlint.config.ts` or `oxlint.config.mts`.**
+  oxlint silently ignores `oxlint.config.{cts,js,mjs,cjs}` and falls through
+  to the nearest ancestor config. In a package with no `"type": "module"`,
+  use `.mts` for both generated files to avoid Node's module-type warning.
+- **A TypeScript project needs `allowImportingTsExtensions: true`** in the
+  `tsconfig.json` that covers the layout files, or `tsc` rejects the import
+  with `TS5097`. Both CLI flows offer to set it for you, following `extends`
+  first so a shared base that already carries it is left alone. TypeScript only
+  accepts the flag on a project with `noEmit`, `emitDeclarationOnly` or
+  `rewriteRelativeImportExtensions` — on an emitting project it fails with
+  `TS5096` — so a project that emits is never edited; the CLI explains what to
+  turn on instead.
+- **`oxlint` runs with `--disable-nested-config`.** The emitted config carries
+  options oxlint accepts only in a root config, and a discovered nested config
+  carrying them aborts the whole run. Disabling nested discovery also makes
+  the config's own `ignorePatterns` authoritative. In a monorepo each package
+  runs its own `lint` script, so every config is the root of its own run.
+
+**Do not `await` `useInsiderESLint()`. Do not spread either renderer. Do not
+wrap them in an array.** If you find yourself wanting to append a block, that
+is a sign your scope coverage is incomplete — describe the extra files inside
+`useInsider({...})` instead.
 
 ## Table of Contents
 
+- [The three-file layout](#the-three-file-layout)
 - [Prerequisites](#prerequisites)
 - [Quick start](#quick-start)
 - [Manual setup](#manual-setup)
@@ -22,6 +93,10 @@ inside `useInsider({...})` instead.
   - [Vue 2 + JavaScript with jQuery globals](#vue-2--javascript-with-jquery-globals)
   - [Strict and spell-checker knobs](#strict-and-spell-checker-knobs)
 - [API reference](#api-reference)
+- [Unused disable directives](#unused-disable-directives)
+- [Lint scripts](#lint-scripts)
+- [Migrating to v4](#migrating-to-v4)
+  - [The guided migration offer](#the-guided-migration-offer)
 - [Migrating from v1.x](#migrating-from-v1x)
 - [First lint after install](#first-lint-after-install)
 - [Troubleshooting](#troubleshooting)
@@ -29,8 +104,9 @@ inside `useInsider({...})` instead.
 
 ## Prerequisites
 
-- Node.js 20+
+- Node.js 24.19+
 - ESLint 9+
+- oxlint 1.83+
 - pnpm, npm, or yarn
 
 ## Quick start
@@ -40,9 +116,16 @@ npx @useinsider/eslint-config
 ```
 
 The CLI walks an interactive prompt (project type, language, framework, test
-runner, jQuery globals, tsconfig layout), installs every required ESLint
-plugin pinned to the versions this package was built against, and writes a
-starter `eslint.config.mjs` at the project root.
+runner, jQuery globals, tsconfig layout), installs every required linter and
+plugin pinned to the versions this package was built against, writes the three
+layout files at the project root, wires oxlint into the script that actually
+invokes ESLint (see [Lint scripts](#lint-scripts)), and offers to add
+`allowImportingTsExtensions: true` to the tsconfig that really governs those
+files. In a solution-style project that is the referenced `tsconfig.node.json`,
+not the root — and if an applicable config already sets the flag, or no tsconfig
+type-checks those files, you are not asked at all. That edit is surgical —
+comments, key order and indentation survive — and declining it prints the exact
+snippet to paste.
 
 To migrate an existing v1 `eslint.config.{js,mjs,cjs}` or a legacy
 `.eslintrc.{js,cjs}`:
@@ -51,20 +134,34 @@ To migrate an existing v1 `eslint.config.{js,mjs,cjs}` or a legacy
 npx @useinsider/eslint-config migrate [path]
 ```
 
-The migrate flow auto-detects the source format. For flat configs it
-parses the v1 file, prints a summary plus any dropped custom rules, asks
-for confirmation, then rewrites the file in place. For legacy `.eslintrc`
-files it writes a fresh `eslint.config.mjs` next to the original (custom
-rules and non-`@useinsider/eslint-config/*` extends are dropped with a
-loud warning so you can review what changed). Legacy `.eslintrc.{json,yml,yaml}`
-are not supported in this release — convert them to `.eslintrc.{js,cjs}` first.
-
-Example output for a Node + TypeScript project:
-
-```js
+The migrate flow auto-detects the source format, prints a summary plus any
+dropped custom rules, asks for confirmation, then splits the config into the
+three-file layout: the `useInsider()` call moves into `insider.lint.*` and
+both linter configs become thin re-exports. Legacy `.eslintrc.{js,cjs}` is
+also handled (custom rules and non-`@useinsider/eslint-config/*` extends are
+dropped with a loud warning so you can review what changed). Legacy
+`.eslintrc.{json,yml,yaml}` are not supported in this release — convert them
+to `.eslintrc.{js,cjs}` first.
+
+Migrate also rewrites your source: an `// eslint-disable-next-line <rule>`
+naming a rule oxlint has taken over becomes `// oxlint-disable-next-line
+<rule>`. This is not cosmetic — the emitted oxlint config refuses the
+`eslint-disable` spelling (see [Unused disable
+directives](#unused-disable-directives)), so an un-migrated comment suppresses
+nothing on either side. A comment listing rules from both sides is split into
+one comment per linter. A `-line` or `-next-line` directive targets one exact
+physical line, so both halves stay on a single line as block comments — a
+newline between them would point the first half at the second instead of at
+the code. Only a whole-file `eslint-disable` is split across two lines. The rewrite reads each
+file's syntax tree and touches only real comment nodes, so a directive spelled
+out inside a string or template literal is left alone.
+
+Example `insider.lint.ts` for a Node + TypeScript project:
+
+```ts
 import { useInsider } from '@useinsider/eslint-config';
 
-export default useInsider({
+export const { useInsiderESLint, useInsiderOXC } = useInsider({
     typescriptNode: [
         {
             files: ['**/*.{ts,tsx}'],
@@ -79,6 +176,7 @@ pins):
 
 - `@useinsider/eslint-config`
 - `eslint`
+- `oxlint`
 - `globals`
 - `typescript`
 - `typescript-eslint`
@@ -92,19 +190,23 @@ or `@vitest/eslint-plugin`).
 Install the package first:
 
 ```bash
-pnpm add -E -D @useinsider/eslint-config
+pnpm add -E -D @useinsider/eslint-config oxlint
 ```
 
-Then create `eslint.config.mjs` and call `useInsider(...)` with the scopes
-your project needs. Each scope holds an array of `{ files, ... }` entries;
-each entry becomes its own flat-config block.
+Then create the [three layout files](#the-three-file-layout) and call
+`useInsider(...)` from `insider.lint.ts` with the scopes your project needs.
+Each scope holds an array of `{ files, ... }` entries; each entry becomes its
+own block in both emitted configs.
+
+Every example below shows the body of `insider.lint.ts`; the two linter
+configs never change.
 
 ### Node + TypeScript
 
-```js
+```ts
 import { useInsider } from '@useinsider/eslint-config';
 
-export default useInsider({
+export const { useInsiderESLint, useInsiderOXC } = useInsider({
     typescriptNode: [
         {
             files: ['**/*.{ts,tsx}'],
@@ -122,10 +224,10 @@ export default useInsider({
 A project using `tsconfig.app.json` for source and `tsconfig.test.json` for
 tests, with `RouterLink` and `RouterView` as globally-registered components.
 
-```js
+```ts
 import { useInsider } from '@useinsider/eslint-config';
 
-export default useInsider({
+export const { useInsiderESLint, useInsiderOXC } = useInsider({
     vue3Typescript: [
         {
             files: ['src/**/*.{ts,tsx,vue}'],
@@ -152,10 +254,10 @@ paths if a single scope needs more than one project reference.
 
 ### Vue 2 + JavaScript with jQuery globals
 
-```js
+```ts
 import { useInsider } from '@useinsider/eslint-config';
 
-export default useInsider({
+export const { useInsiderESLint, useInsiderOXC } = useInsider({
     vue2: [
         { files: ['src/**/*.{js,vue}'] },
     ],
@@ -179,10 +281,10 @@ layered on top of it.
 `strict` and `spellChecker` are flat cross-cutting options. They sit at the
 top level of the config, not inside a scope entry.
 
-```js
+```ts
 import { useInsider } from '@useinsider/eslint-config';
 
-export default useInsider({
+export const { useInsiderESLint, useInsiderOXC } = useInsider({
     typescriptNode: [
         {
             files: ['**/*.{ts,tsx}'],
@@ -247,10 +349,10 @@ Every scope entry shape also accepts two common fields:
 A scope entry with per-entry globals — declare project-specific bindings
 without spreading the `useInsider` return into your own array:
 
-```js
+```ts
 import { useInsider } from '@useinsider/eslint-config';
 
-export default useInsider({
+export const { useInsiderESLint, useInsiderOXC } = useInsider({
     ignores: ['dist', 'coverage'],
     javascriptDom: [
         {
@@ -286,28 +388,239 @@ the language scopes and gets overridden by any of them that also match.
 > `*.config.*` and `eslint.config.*` are already covered by the defaults, so
 > most projects can simply drop the key.
 
-`useInsider` returns `Promise<Linter.Config[]>`. Export it directly — ESLint
-9 resolves the Promise at load time. `useInsider`'s return type carries
-through, so no JSDoc annotation is needed; the `UseInsiderResult` type alias
-is exported for TypeScript callers that wrap `useInsider` in a helper of
-their own.
+`useInsider` is synchronous and returns `{ useInsiderESLint, useInsiderOXC }`.
+`useInsiderESLint()` returns `Promise<Linter.Config[]>` — export it without
+awaiting, ESLint 9 resolves it at load time. `useInsiderOXC()` also returns a
+Promise, and oxlint does *not* await a default export, so `oxlint.config.ts`
+must use top-level `await`. The `UseInsiderResult` type alias is exported for
+TypeScript callers that wrap the renderers in a helper of their own.
+
+Two file-matching differences between the linters are handled for you, but
+worth knowing:
+
+- An unanchored oxlint glob matches at any depth, so `files: ['*.mjs']` would
+  also claim `.husky/install.mjs`. The emitted oxlint config anchors every
+  glob that does not already start with `**`, restoring ESLint's semantics.
+- oxlint discovers a nested `oxlint.config.*` in any subdirectory and lints
+  that directory with it, **ignoring the parent config's `ignorePatterns`**.
+  The generated lint script passes `--disable-nested-config`, which turns that
+  off and makes the root config's `ignorePatterns` authoritative. It is also
+  required rather than optional: the emitted config carries root-only
+  `options`, and oxlint aborts with a config-parse error the moment it
+  discovers those in a nested file — which a monorepo whose packages each ran
+  this CLI always has. Run oxlint once per package, from that package.
+
+## Unused disable directives
+
+Both linters report a disable comment that no longer suppresses anything, and
+each one judges only its own spelling:
+
+- The emitted oxlint config sets `options.reportUnusedDisableDirectives` to
+  `warn`, so a stale `// oxlint-disable-*` is reported.
+- The emitted ESLint config pins
+  `linterOptions.reportUnusedDisableDirectives` to `warn`, so a stale
+  `// eslint-disable-*` is reported.
+
+It also sets `options.respectEslintDisableDirectives: false`, which is what
+makes the pair sound. oxlint judges an `eslint-disable` against the rules *it*
+ran, so with the default (`true`) a comment naming `@cspell/spellchecker`,
+`sonarjs/*`, `@stylistic/*` or `jsdoc/check-tag-names` — every rule the split
+deliberately keeps on the ESLint side — is reported as unused. Refusing the
+`eslint-disable` spelling removes that false positive entirely, at the cost of
+making the ownership split explicit in your source: a rule oxlint owns must be
+suppressed with `oxlint-disable`, a rule ESLint owns with `eslint-disable`.
+`migrate` performs that rewrite for you; an un-migrated comment is reported by
+ESLint as an unused directive, so nothing fails silently.
+
+Neither severity fails the build on its own. Escalate with
+`oxlint --deny-warnings` and `eslint . --max-warnings 0` if you want that.
 
 `silenceRules()` (named export) is also available as a global registration
 hook. Call it at module top level to register rule IDs to demote *before*
 `useInsider` is invoked; the per-call `silenceRules: [...]` option layers
 on top.
 
-```js
+```ts
 import { useInsider, silenceRules } from '@useinsider/eslint-config';
 
 silenceRules(['no-magic-numbers']);
 
-export default useInsider({ /* ... */ });
+export const { useInsiderESLint, useInsiderOXC } = useInsider({ /* ... */ });
+```
+
+## Lint scripts
+
+Both linters have to run, and oxlint has to run *first* — the ESLint side
+turns off every rule oxlint owns, so ESLint alone silently drops those checks.
+The canonical script is:
+
+```json
+{ "scripts": { "lint": "oxlint --disable-nested-config && eslint ." } }
+```
+
+The CLI never replaces a script it did not author. It finds the **one** script
+that really invokes the `eslint` binary and **prepends** oxlint to it, leaving
+the original command verbatim inside the new value. A composed `lint` that fans
+out to a type-check and a stylelint pass is therefore untouched:
+
+```diff
+  "lint":          "run-p lint:type lint:es lint:style",
+  "lint:es":       "npm run lint:es-ci -- --cache",
+- "lint:es-ci":    "NODE_OPTIONS=--max-old-space-size=6144 eslint .",
++ "lint:es-ci":    "oxlint --disable-nested-config && NODE_OPTIONS=--max-old-space-size=6144 eslint .",
+  "lint:style":    "npm run lint:style-ci -- --cache",
+  "lint:type":     "run-p lint:type:app lint:type:test lint:type:node",
 ```
 
+Prepending rather than appending is deliberate: a `--` passthrough
+(`npm run lint:es-ci -- --cache`) lands on the *last* command, so `--cache`
+still reaches ESLint. A script whose name ends in a `--fix` invocation gets
+`oxlint --disable-nested-config --fix`. Every rewrite is printed with its
+previous value.
+
+Exactly one script is rewritten. When several entry points run ESLint —
+`lint`, `lint:fix`, `lint:ci` — prepending to all of them would run oxlint once
+per entry point over the same tree, so the CLI picks the entry point `lint`
+designates (itself, or the leaf it delegates to) and reports the rest with the
+prefix to add if you want oxlint on them too.
+
+If no script invokes `eslint` and a `lint` script already exists, nothing is
+written — the conflict is reported with the command to add by hand.
+
+## Migrating to v4
+
+v4 requires **Node.js 24.19+** (`engines.node` was `>=20` through v3). Check
+your CI images and any repo pinning an older Node before upgrading: npm and
+pnpm warn with `EBADENGINE`, and fail outright under `engine-strict`.
+
+v4 splits the lint run across ESLint and oxlint. Run the CLI to do all of
+this automatically:
+
+```bash
+npx @useinsider/eslint-config migrate
+```
+
+### The guided migration offer
+
+You do not have to know that command exists. Running lint against a v3 config
+under v4 detects the outdated structure and, in an interactive terminal, offers
+to run the migration there and then:
+
+```
+@useinsider/eslint-config: eslint.config.js still uses the v3 single-file layout.
+  /repo/eslint.config.js calls `useInsider()` itself, and
+  insider.lint.ts and oxlint.config.ts are missing.
+
+Starting the guided migration. It shows every change before applying it.
+Skip it with INSIDER_NO_PROMPT=true.
+
+◆  eslint.config.js still uses the v3 single-file layout. Migrate it now?
+│  ● Yes / ○ No
+```
+
+Accepting runs the normal `migrate` flow — same summary, same confirmations —
+and then exits non-zero asking you to re-run lint, because this process already
+loaded the configuration that was just rewritten.
+
+The offer is suppressed, and the failure message leads with the `migrate`
+command instead, whenever prompting would be wrong: under oxlint (whose stdout
+is its report), in CI, without a TTY, with `INSIDER_NO_PROMPT=true`, or with
+`INSIDER_SKIP_CONFIG_VALIDATION=true`.
+
+The directive rewrite is reported as its own step, with the file count shown
+*before* anything is written, so you can take it as a separate commit or
+decline it and run `migrate` again later.
+
+What changes:
+
+- **`eslint-disable` no longer suppresses an oxlint-owned rule. This is the
+  largest behavior change in v4.** The emitted oxlint config sets
+  `options.respectEslintDisableDirectives: false`, so oxlint reads only the
+  `oxlint-disable` spelling. A comment left in the v3 form suppresses nothing,
+  and because ESLint no longer runs that rule it reports the comment as an
+  unused directive rather than failing quietly. `migrate` rewrites the affected
+  comments for you (AST-based — it touches only real comment nodes).
+
+  ```diff
+  - // eslint-disable-next-line no-console -- CLI banner
+  + // oxlint-disable-next-line no-console -- CLI banner
+    console.info(banner);
+  ```
+
+  Rules the split keeps on the ESLint side — `@cspell/*`, `sonarjs/*`,
+  `@stylistic/*`, `jsdoc/check-tag-names`, `no-inner-declarations`, every
+  type-aware `@typescript-eslint` rule — keep the `eslint-disable` spelling.
+  See [Unused disable directives](#unused-disable-directives) for why refusing
+  the eslint spelling is what makes stale-directive reporting sound in both
+  directions.
+
+- **`useInsider()` is now synchronous and returns two renderers.** A v3
+  `export default useInsider({...})` no longer produces a flat-config array.
+
+  ```diff
+  - // eslint.config.mjs
+  - import { useInsider } from '@useinsider/eslint-config';
+  -
+  - export default useInsider({ typescriptNode: [{ files: ['src/**/*.ts'], tsconfigPaths: ['tsconfig.json'] }] });
+  + // insider.lint.ts
+  + import { useInsider } from '@useinsider/eslint-config';
+  +
+  + export const { useInsiderESLint, useInsiderOXC } = useInsider({
+  +     typescriptNode: [{ files: ['src/**/*.ts'], tsconfigPaths: ['tsconfig.json'] }],
+  + });
+  ```
+
+- **Two new sibling files** — `eslint.config.*` and `oxlint.config.*`, each a
+  thin re-export. See [the three-file layout](#the-three-file-layout).
+- **The lint command runs both linters**: `oxlint --disable-nested-config && eslint .`.
+  `--disable-nested-config` is required, not stylistic. Without it oxlint
+  discovers any nested `oxlint.config.*` in the tree and lints that subtree
+  with it, bypassing the root config's `ignorePatterns`. Worse, the emitted
+  config carries `options.*`, which oxlint accepts **only** in a root config —
+  a nested config carrying `options` aborts the whole run, even when its
+  directory is listed in `ignorePatterns`.
+- **Monorepo consumers run oxlint per package.** oxlint has no workspace mode,
+  so each package owns its own three files and its own `lint` script, and each
+  script carries `--disable-nested-config`. Running one oxlint pass from the
+  repo root over sibling packages is not equivalent.
+- **Only `oxlint.config.ts` and `oxlint.config.mts` are discovered.** Any other
+  extension — `.js`, `.mjs`, `.cjs`, `.cts` — is ignored *without a word*, and
+  oxlint falls through to the nearest ancestor config. The config appears live
+  while none of its rules run. `ensureOxlintConfig()` fails the ESLint side
+  when neither accepted filename sits beside the lint module, so the mistake
+  surfaces rather than silently disarming half the rule set.
+- **`oxlint` is version-tracked like `eslint` and `globals`.** A consumer
+  whose installed `oxlint` is older than this package's pin is upgraded
+  automatically on the next lint run, because an older oxlint silently drops
+  whatever rules that release did not yet implement. Opt out with
+  `silenceDependencyWarning(['oxlint'])`.
+- **`tsconfig.json` gains `allowImportingTsExtensions: true`.** `eslint.config.ts`
+  and `oxlint.config.ts` must import the lint module by its real extension —
+  nothing here applies TypeScript's `.js` → `.ts` rewriting — and `tsc` fails
+  with `TS5097` otherwise. The CLI prompts to add it and resolves the full
+  `extends` chain first, so a shared base that already sets it is left alone;
+  declining prints the snippet to paste. A project that emits is never edited —
+  TypeScript rejects the flag there with `TS5096`.
+- **`@typescript-eslint` type-aware rules, `sonarjs`, `@stylistic`, `@cspell`,
+  `jsdoc/check-tag-names` and `no-inner-declarations` stay with ESLint.** Two
+  of those are permanent, for different reasons:
+  - `jsdoc/check-tag-names` is driven by `settings.jsdoc.tagNamePreference`
+    (the TypeScript scopes remap `@desc`/`@callback` onto `@use`/`@watch`), and
+    oxlint has no equivalent of flat-config `settings`.
+  - `no-inner-declarations` is implemented by both, but they disagree on the
+    default for an omitted option: ESLint 9 defaults `blockScopedFunctions` to
+    `allow`, oxlint to `disallow`. Handing oxlint the bare `'error'` would
+    reject every block-scoped function declaration ESLint accepts.
+- **Stale disable directives warn on both sides, and neither fails the build
+  on its own.** Escalate with `oxlint --deny-warnings` and
+  `eslint . --max-warnings 0`.
+
 ## Migrating from v1.x
 
-v2 is a hard break. The summary:
+This section describes the v1 → v2 step. The scope-keyed config object it
+introduces is still the v4 shape; only the wiring around the call changed
+again, which [Migrating to v4](#migrating-to-v4) covers. Do both steps if you
+are coming from v1.
 
 - **`preset: string[]`** → top-level scope properties. The order in the
   v1 `preset` array no longer matters — the new shape has one property per
@@ -365,13 +678,12 @@ v2 is a hard break. The summary:
   paths-targeted strict checks, set `strict: [...]` instead of
   `strict: true`.
 
-- **Shape change**: `useInsider(...)` is now exported directly as the
-  default export, without `await`, without spread, and without an array
-  wrap. ESLint 9 resolves the Promise on load. The old pattern
-  `export default [...await useInsider({...})]` still parses, but the
-  preferred shape is `export default useInsider({...})`. There is no
-  supported override path — describe every glob you want linted inside
-  the call, including jQuery files via the dedicated `jquery` scope.
+- **Shape change**: `useInsider(...)` stopped being an awaited, spreadable
+  array. In v2 it became `export default useInsider({...})`; in v4 it became
+  the renderer destructuring shown in
+  [Migrating to v4](#migrating-to-v4). Either way there is no supported
+  override path — describe every glob you want linted inside the call,
+  including jQuery files via the dedicated `jquery` scope.
 
 - **Removed**: the `preset` array, the `config: Linter.Config` escape
   hatch, and the `config` preset itself. Configuration-file linting is
@@ -381,15 +693,15 @@ v2 is a hard break. The summary:
 - **Kept**: `silenceRules` accepts the same `string[]` shape both as a
   top-level option and via the named `silenceRules()` export.
   `silenceDependencyWarning()` works unchanged. Side-effect lines such as
-  `silenceDependencyWarning(true)` continue to sit above the
-  `export default useInsider({...})` call.
+  `silenceDependencyWarning(true)` continue to sit above the `useInsider(...)`
+  call, now in `insider.lint.*`.
 
 ## First lint after install
 
-The first time you run lint after installing v2, `ensureDependencies` may
-detect that your project's `eslint` or `globals` version is older than the
-pin and auto-install them, exiting with code `1`. Run lint again and it
-will complete normally.
+The first time you run lint after installing, `ensureDependencies` may detect
+that your project's `eslint` or `globals` version is older than the pin and
+auto-install them, exiting with code `1`. Run lint again and it will complete
+normally.
 
 ## Troubleshooting
 
@@ -399,12 +711,12 @@ If you see this error, your project is missing a peer plugin this config
 needs. The error message lists the install command. To silence the warning
 permanently:
 
-```js
+```ts
 import { useInsider, silenceDependencyWarning } from '@useinsider/eslint-config';
 
 silenceDependencyWarning(['@cspell/eslint-plugin', '@stylistic/eslint-plugin']);
 
-export default useInsider({ /* ... */ });
+export const { useInsiderESLint, useInsiderOXC } = useInsider({ /* ... */ });
 ```
 
 Passing `true` silences every warning; that is not recommended because the

package/dist/builders/configFiles.d.ts

@@ -9,4 +9,17 @@ import type { Linter } from 'eslint';
  * `configFiles: string[]` knob.
  */
 export declare const DEFAULT_CONFIG_FILE_GLOBS: readonly string[];
+export declare const LINT_TOPOLOGY_NAME = "insider/lint-topology";
+/**
+ * The three files `useInsider()` requires a consumer to own. They are always linted with
+ * {@link buildLintTopologyBlocks}, independently of the `configFiles` option.
+ */
+export declare const LINT_TOPOLOGY_GLOBS: readonly string[];
+/**
+ * Relaxations the mandated three-file layout needs in order to lint clean. Emitted unconditionally
+ * because the layout exists whether or not the consumer passes `configFiles`.
+ * @example
+ * buildLintTopologyBlocks()[0].rules['import-x/extensions']; // 'off'
+ */
+export declare function buildLintTopologyBlocks(): Linter.Config[];
 export declare function buildConfigFilesBlocks(value: false | string[] | undefined): Linter.Config[];

package/dist/builders/oxlint.d.ts

@@ -0,0 +1,51 @@
+import type { Linter } from 'eslint';
+export declare const OXLINT_SUPPRESSION_NAME = "insider/oxlint-suppression";
+export declare const OXLINT_SFC_EXCEPTION_NAME = "insider/oxlint-suppression-sfc-exception";
+export declare const UNUSED_DIRECTIVE_BLOCK_NAME = "insider/unused-disable-directives";
+export declare const UNUSED_DIRECTIVE_SEVERITY = "warn";
+export declare function isOxlintSuppressionBlock(block: Linter.Config): boolean;
+export interface OxlintOverride {
+    files: string[];
+    excludeFiles?: string[];
+    rules: Record<string, Linter.RuleEntry>;
+}
+export interface OxlintRendererOptions {
+    respectEslintDisableDirectives: boolean;
+    reportUnusedDisableDirectives: typeof UNUSED_DIRECTIVE_SEVERITY;
+}
+export interface OxlintRendererConfig {
+    plugins: string[];
+    categories: Record<string, 'off'>;
+    ignorePatterns?: string[];
+    options: OxlintRendererOptions;
+    rules: Record<string, Linter.RuleEntry>;
+    overrides: OxlintOverride[];
+}
+export declare const OXLINT_DIRECTIVE_OPTIONS: OxlintRendererOptions;
+/**
+ * The always-on ESLint block that makes a stale `eslint-disable` visible. ESLint 9 defaults this to
+ * `warn`, but the split relies on it, so it is pinned rather than inherited.
+ * @example
+ * buildUnusedDirectiveBlocks()[0].linterOptions; // { reportUnusedDisableDirectives: 'warn' }
+ */
+export declare function buildUnusedDirectiveBlocks(): Linter.Config[];
+/**
+ * ESLint blocks that turn off every rule the emitted oxlint config takes over. Rules oxlint cannot
+ * check inside an SFC are suppressed everywhere except `.vue`/`.svelte`/`.astro`, so a Vue consumer
+ * keeps them.
+ * @example
+ * buildOxlintSuppressionBlocks([{ files: ['src/**\/*.ts'], rules: { 'no-var': 'error' } }]);
+ * // [{ files: ['src/**\/*.ts'], rules: { 'no-var': 'off' } }]
+ */
+export declare function buildOxlintSuppressionBlocks(blocks: readonly Linter.Config[]): Linter.Config[];
+export declare function anchorOxlintGlob(glob: string): string;
+export declare function anchorOxlintIgnorePattern(pattern: string): string;
+/**
+ * The oxlint half of the split, derived from the same emitted ESLint blocks the suppression layer
+ * reads. Every oxlint category is pinned off so the config enables exactly the preset's own rules
+ * and nothing oxlint would otherwise turn on by default.
+ * @example
+ * buildOxlintConfig([{ files: ['src/**\/*.ts'], rules: { 'no-var': 'error' } }], ['dist']);
+ * // { plugins: ['eslint'], categories: { correctness: 'off', ... }, ignorePatterns: ['/dist'], ... }
+ */
+export declare function buildOxlintConfig(blocks: readonly Linter.Config[], ignores: readonly string[] | undefined): OxlintRendererConfig;