[Fix] flatConfigs types: remove nonexistent stage-0; add type tests

The root index.d.ts declared `flatConfigs['stage-0']`, but the runtime
`flatConfigs` object in src/index.js has no `stage-0` key, so the types
promised a defined flat config that is `undefined` at runtime.

Also adds a type-test suite (wired into `test-types`) locking in that
`flatConfigs`/`configs` and their entries are non-optional, fully-typed
`Linter.FlatConfig`/`Linter.LegacyConfig` values, matching the README
flat-config examples.

Fixes #3169.

Author: KAMRONBEK

CHANGELOG.md

@@ -22,6 +22,7 @@ This change log adheres to standards from [Keep a CHANGELOG](https://keepachange
 - [`no-unused-modules`]: normalize path separators so `listFilesWithNodeFs` glob matching works on Windows ([#3230], thanks [@ljharb])
 - [`no-unused-modules`]: honor the flat config's global `ignores` in the `listFilesWithNodeFs` fallback, restoring parity with the file set ESLint lints ([#3230], thanks [@ljharb])
 - [`no-deprecated`], [`namespace`]: route `declaredScope` through the `getScope` compat shim instead of the removed `context.getScope()` (ESLint 9+) ([#3230], thanks [@ljharb])
+- [types] remove `stage-0` from the `flatConfigs` types, since it does not exist at runtime, and add type tests for the plugin's exports ([#3169], thanks [@KAMRONBEK])
 
 ### Changed
 - [Refactor] [`order`]: extract the ESLint 10 token/comment compatibility shims into a reusable `getTokenOrComment` util ([#3230], thanks [@captaindonald])
@@ -1220,6 +1221,7 @@ for info on changes for earlier releases.
 [#3191]: https://github.com/import-js/eslint-plugin-import/pull/3191
 [#3173]: https://github.com/import-js/eslint-plugin-import/pull/3173
 [#3172]: https://github.com/import-js/eslint-plugin-import/pull/3172
+[#3169]: https://github.com/import-js/eslint-plugin-import/issues/3169
 [#3167]: https://github.com/import-js/eslint-plugin-import/pull/3167
 [#3166]: https://github.com/import-js/eslint-plugin-import/pull/3166
 [#3152]: https://github.com/import-js/eslint-plugin-import/pull/3152
@@ -1980,6 +1982,7 @@ for info on changes for earlier releases.
 [@justinanastos]: https://github.com/justinanastos
 [@jwbth]: https://github.com/jwbth
 [@k15a]: https://github.com/k15a
+[@KAMRONBEK]: https://github.com/KAMRONBEK
 [@kentcdodds]: https://github.com/kentcdodds
 [@kevin940726]: https://github.com/kevin940726
 [@kgregory]: https://github.com/kgregory

index.d.ts

@@ -19,7 +19,6 @@ declare const plugin: ESLint.Plugin & {
     'recommended': Linter.FlatConfig;
     'errors': Linter.FlatConfig;
     'warnings': Linter.FlatConfig;
-    'stage-0': Linter.FlatConfig;
     'react': Linter.FlatConfig;
     'react-native': Linter.FlatConfig;
     'electron': Linter.FlatConfig;

package.json

@@ -37,7 +37,7 @@
     "test-example:legacy": "cd examples/legacy && npm install && npm run lint",
     "test-example:flat": "cd examples/flat && npm install && npm run lint",
     "test-example:v9": "cd examples/v9 && npm install && npm run lint",
-    "test-types": "npx --package typescript@latest tsc --noEmit index.d.ts",
+    "test-types": "npx --package typescript@latest tsc --noEmit index.d.ts && npx --package typescript@latest tsc -p tests/types",
     "prepublishOnly": "safe-publish-latest && npm run build",
     "prepublish": "not-in-publish || npm run prepublishOnly",
     "preupdate:eslint-docs": "npm run build",

tests/types/index.test-d.ts

@@ -0,0 +1,44 @@
+// Type tests for the root `index.d.ts` (see #3169).
+// Compiled by `npm run test-types` via `tests/types/tsconfig.json`;
+// never executed at runtime.
+
+import importPlugin from 'eslint-plugin-import';
+import { ESLint, Linter, Rule } from 'eslint';
+
+type IsAny<T> = 0 extends 1 & T ? true : false;
+
+// the plugin object itself is a usable, fully-typed ESLint plugin
+const plugin: ESLint.Plugin = importPlugin;
+
+// `flatConfigs` and its entries must not be optional or `any` (#3169)
+const flatConfigsNotAny: IsAny<typeof importPlugin.flatConfigs> = false;
+const recommendedNotAny: IsAny<typeof importPlugin.flatConfigs.recommended> = false;
+
+// the README flat-config examples: every flat config is a defined `Linter.FlatConfig`
+const flatConfigs: Linter.FlatConfig[] = [
+  importPlugin.flatConfigs.recommended,
+  importPlugin.flatConfigs.errors,
+  importPlugin.flatConfigs.warnings,
+  importPlugin.flatConfigs.react,
+  importPlugin.flatConfigs['react-native'],
+  importPlugin.flatConfigs.electron,
+  importPlugin.flatConfigs.typescript,
+];
+
+// @ts-expect-error `stage-0` only exists in the legacy `configs`, not in `flatConfigs`
+importPlugin.flatConfigs['stage-0'];
+
+// the legacy configs are eslintrc-style configs, including `stage-0`
+const legacyConfigs: Linter.LegacyConfig[] = [
+  importPlugin.configs.recommended,
+  importPlugin.configs.errors,
+  importPlugin.configs.warnings,
+  importPlugin.configs['stage-0'],
+  importPlugin.configs.react,
+  importPlugin.configs['react-native'],
+  importPlugin.configs.electron,
+  importPlugin.configs.typescript,
+];
+
+// every rule is a fully-typed rule module
+const orderRule: Rule.RuleModule = importPlugin.rules.order;

tests/types/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "strict": true,
+    "esModuleInterop": true,
+    "noEmit": true,
+    "types": [],
+    "paths": {
+      "eslint-plugin-import": ["../../index.d.ts"]
+    }
+  },
+  "files": ["index.test-d.ts"]
+}