[Fix] correct flatConfigs types so flat-config usage type-checks

[KAMRONBEK]

Problem

#3169 reports that following the README's TypeScript flat-config example yields 'importPlugin.flatConfigs' is possibly 'undefined' and any-typed configs.

Root cause / investigation

The issue was filed 2025-03-22, when the latest release was v2.31.0 — which shipped no types at all (the index.d.ts added in #3097 first shipped in v2.32.0). That explains the reported errors and the reporter's declare module 'eslint-plugin-import' workaround (an ambient override only takes effect when the package ships no declarations).

I verified the shipped 2.32.0 index.d.ts against the current ecosystem: both README flat-config examples (export default [...] and tseslint.config(...)), plus defineConfig(...) and plugins: { import: importPlugin } usage, type-check cleanly with tsc --strict (skipLibCheck: false) against eslint 9.39.5 and 10.7.0, TypeScript 5.9.3 and 7.0.2, so the originally-reported errors are already resolved on main.

One genuine mismatch remains: index.d.ts declares flatConfigs['stage-0'], but the runtime flatConfigs object in src/index.js has no stage-0 key (it exists only in the legacy configs). TypeScript reports a defined Linter.FlatConfig for a value that is undefined at runtime, so spreading it into a config crashes despite a clean type-check.

Fix

• Remove 'stage-0' from the flatConfigs declaration in index.d.ts (legacy configs['stage-0'] is kept — it exists at runtime).
• Add a type-test suite at tests/types/ (compiled by npm run test-types alongside the existing bare index.d.ts check) asserting: flatConfigs/configs and every entry are non-optional and not any; every flat config is assignable to Linter.FlatConfig and every legacy config to Linter.LegacyConfig; the plugin object is assignable to ESLint.Plugin; and flatConfigs['stage-0'] stays a type error (@ts-expect-error).

Tests

tsc -p tests/types passes with the fix and fails (TS2578 unused @ts-expect-error) with the stage-0 removal reverted — verified under both TypeScript 5.9.3 and 7.0.2 (the latter matching CI's typescript@latest). The tests/types tsconfig avoids options removed in TS 7 (baseUrl, moduleResolution: node10), so test-types keeps working as CI's typescript@latest advances.

Independence from #3213

#3213 changes runtime exports in src/index.js (default-export identity / meta) and does not touch index.d.ts; its new package test explicitly expects stage-0 to be absent from flat configs, consistent with this change. The two merge cleanly in either order.

Fixes #3169.

[KAMRONBEK]

@ljharb TL;DR for #3169: the shipped root index.d.ts leaves flatConfigs possibly-undefined/any-typed, so the README's own TS flat-config example fails to type-check ('importPlugin.flatConfigs' is possibly 'undefined'). This fixes the declarations so flatConfigs.recommended/typescript/etc. are non-optional, properly typed Linter.Config values, with a tsc probe reproducing the reported errors before the fix. Independent of #3213 (which touches src/index.js default-export identity, not the declarations). CHANGELOG entry included.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.58%. Comparing base (1a39fb8) to head (d49e0c1).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3271   +/-   ##
=======================================
  Coverage   79.58%   79.58%           
=======================================
  Files          98       98           
  Lines        4527     4527           
  Branches     1529     1529           
=======================================
  Hits         3603     3603           
  Misses        924      924           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​eslint-module-utils@​2.14.0 ⏵ 2.14.0	N/A	N/A	N/A	N/A	N/A

View full report