@useinsider/eslint-config 4.0.0-beta.1 → 4.0.0-beta.3

package/README.md

@@ -27,8 +27,8 @@ export const { useInsiderESLint, useInsiderOXC } = useInsider({
 });
 ```
 
-```js
-// eslint.config.mjs
+```ts
+// eslint.config.ts
 import { useInsiderESLint } from './insider.lint.ts';
 
 export default useInsiderESLint();
@@ -52,6 +52,13 @@ 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"`,
@@ -59,7 +66,11 @@ Three constraints this layout is not free to break:
 - **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.
+  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
@@ -83,7 +94,9 @@ is a sign your scope coverage is incomplete — describe the extra files inside
   - [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)
@@ -105,14 +118,17 @@ npx @useinsider/eslint-config
 The CLI walks an interactive prompt (project type, language, framework, test
 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, sets
-`"lint": "oxlint --disable-nested-config && eslint ."` in your `package.json`,
-and offers to add `allowImportingTsExtensions: true` to your `tsconfig.json`.
-That last 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}`:
+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 `eslint.config.{js,mjs,cjs}` — v3's scope-keyed call or
+v1's `useInsider({ preset, config })` — or a legacy `.eslintrc.{js,cjs}`:
 
 ```bash
 npx @useinsider/eslint-config migrate [path]
@@ -121,11 +137,25 @@ npx @useinsider/eslint-config migrate [path]
 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.
+both linter configs become thin re-exports.
+
+A **v3** config takes the shorter route. v4 accepts the same options v3 did,
+so the call is re-housed rather than re-rendered: the file is copied into
+`insider.lint.*` byte-for-byte and only the export statement changes to
+`export const { useInsiderESLint, useInsiderOXC } = useInsider({ ... })`. Your
+comments, `satisfies` clauses, computed values and formatting survive. An
+`await` on the call and an array wrapping it are dropped, since `useInsider()`
+is synchronous in v4 and returns the two renderers. Shapes with nowhere to go
+in a lint module are refused by name rather than half-migrated: more than one
+`useInsider()` call, a default export mixing the call with hand-written
+flat-config blocks, a `defineConfig()` wrapper, and a call reached through a
+variable. An `.eslintignore` beside a v3 config is left alone — flat config
+never read it, and the re-housed call is not rewritten to fold it in.
+
+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
@@ -432,8 +462,51 @@ silenceRules(['no-magic-numbers']);
 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:
 
@@ -441,6 +514,37 @@ this automatically:
 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
@@ -509,7 +613,8 @@ What changes:
   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.
+  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:

package/dist/builders/scopeBlocks.d.ts

@@ -44,5 +44,11 @@ declare const scopeMap: {
 };
 export type ScopeName = keyof typeof scopeMap;
 export declare function isScopeName(key: string): key is ScopeName;
+/**
+ * Every scope name `useInsider()` accepts, for error messages that have to spell the options out.
+ * @example
+ * scopeNames().includes('typescriptNode'); // true
+ */
+export declare function scopeNames(): ScopeName[];
 export declare function buildScopeBlocks(scope: ScopeName, entries: readonly ScopeEntry[]): Promise<Linter.Config[]>;
 export {};