feat: add support for flat configs

[bradzacher]

PR Checklist

• Addresses an existing open issue: fixes ESLint Flat Config Support #7694, ESLint v9 Support #8211
• That issue was marked as accepting prs
• Steps in Contributing were taken

Overview

This PR builds out support for Flat Configs for our project.

Unfortunately supporting both classic and flat configs from the plugin is a bit of a mess, so I took this opportunity to introduce something that we've always wanted - a single entrypoint package for linting users.

The beauty of this new package is that it means that linting users only need to install, update, and think about one package now - which is a big win.

This new package is typescript-eslint and it currently exports the following:

• parser - an alias for @typescript-eslint/parser.
• plugin - an alias for @typescript-eslint/eslint-plugin.
• configs - flat config versions of the configs in @typescript-eslint/eslint-plugin.
• config - a utility function to make it dead simple to use types in flat config files.

Consuming our tooling in a flat config will look something like this:

const tseslint = require('typescript-eslint');
const eslintJs = require('@eslint/js');

module.exports = tseslint.flatConfig(
  // if configuring manually...
  {
    plugins: {
      '@typescript-eslint': tseslint.plugin,
    },
    languageOptions: {
      parser: tseslint.parser,
      // parserOptions: { ... }
    },
    rules: {
      '@typescript-eslint/no-explicit-any': 'error',
    },
  },

  // or using shared configs
  eslintJs.configs.recommended,
  ...tseslint.configs.eslintRecommended,
  ...tseslint.configs.recommended,
  ...tseslint.configs.stylistic,
);

With this PR we are also dogfooding the package as I have migrated our config to a flat config. We're pretty light on shared configs so it's been pretty straight-forward and mostly "compat free". I have a few open TODOs in the config which are marked.

With this new tooling

TODO:

• add documentation for the new package
• add documentation for setting up our tooling with a flat config file
  • Might defer this to a follow-up PR to separate concerns and keep LOC down.
• resolve TODOs in the flat config file
• actually test the flat config file
• update CI/IDE config/scripts to use the flat config
• resolve discussion about what we should alias the plugin as.
  • Options are:
    • @typescript-eslint/ (the current approach in this PR)
    • typescript-eslint/
    • typescript/
    • ts-eslint/
    • ts/

[typescript-eslint]

Thanks for the PR, @bradzacher!

typescript-eslint is a 100% community driven project, and we are incredibly grateful that you are contributing to that community.

The core maintainers work on this in their personal time, so please understand that it may not be possible for them to review your work immediately.

Thanks again!

---

🙏 Please, if you or your company is finding typescript-eslint valuable, help us sustain the project by sponsoring it transparently on https://opencollective.com/typescript-eslint.

[netlify]

✅ Deploy Preview for typescript-eslint ready!

Name	Link
🔨 Latest commit	8713862
🔍 Latest deploy log	https://app.netlify.com/sites/typescript-eslint/deploys/65c2dd379f8dbe0008e92f8d
😎 Deploy Preview	https://deploy-preview-7935--typescript-eslint.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 90 (🟢 up 2 from production) Accessibility: 100 (no change from production) Best Practices: 92 (no change from production) SEO: 98 (no change from production) PWA: 80 (no change from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[JoshuaKGoldberg]

Maybe just config? Cleaner to say & write, and after a year or so most new projects should only/primarily think about flat configs.

[bradzacher]

the problem with calling it config is that you then have both config and configs exported from the package.

It does make things a little confusing?

[JoshuaKGoldberg]

Hmm yeah never mind... 🤔 a tough naming situation.

[bradzacher]

Eh it works fine enough - I added it as is. People will deal with it it's not THAT bad.

[JoshuaKGoldberg]

Status update: this PR is blocked on eslint/eslint#17820. We're waiting for that to be resolved. eslint/eslint#17906 looks very promising and we'll try it out. Note that once we're unblocked, we'll have to limit flat config support to versions of ESLint with that fix in them.

Edit: the fix was merged but only into the v9 alphas. See #7935 (comment).

[bradzacher]

Yeah we're trying to work with them to backport the fix we're waiting for to v8. Once we have it working on v8 then we can start to think about v9.

[bradzacher]

Filed eslint/eslint#17966 - we shall have to wait and see.

[bradzacher]

Question:
What do we think about making this utility enforce a canonical name for plugins?

For example imagine like:

// eslint.config.js
import * as tseslint from '@typescript-eslint/core';

export default tseslint.config(
  {
    '@typescript-eslint': tseslint.plugin,
    // ...
  },
  {

  },
);

Then within the util we could rewrite all configs so that any references to the plugin use the defined namespace, and we rewrite it with pseudocode like:

for config in configs {
  const pair = config.plugins.entries().find(plugin.value)
  if pair && pair.key !== plugin.key {
    pair.key = plugin.key
    config.rules.keys().replace(`${pair.key}/`, `${plugin.key}/`)
  }
}

Pros: fixes the "multiple namespace problem"
Cons: rewrites user configs, includes some complexity.

WDYT?

Alternate forms:

• more explicit object form like config({ plugins: { ... }, configs: [ ... ] })
• a util function form like config.withPlugins({ ..plugins.. })(..configs[]) (where config(..configs[]) acts without explicit enforcement)

[JoshuaKGoldberg]

I like the idea at first glance, but suspect it should be done in a follow-up issue so that the ESLint folks can provide input too.

[bradzacher]

Based on the discussions we've had (eslint/eslint#17766) - this is fully intended behaviour and it doesn't look like they intend to change that?

[JoshuaKGoldberg]

Oh I mean more on input for direction of the checking.

Plus splitting it out will make it easier to reference it when complaining about the name aliasing being allowed 😄

[woutermont]

@bradzacher, just want to make sure you saw eslint/eslint#17820 (comment):

[Is the issue with null overrides] only a problem for the convenience config, or does it pop up elsewhere too?

To unblock the stalemate, might it be an idea to temporarily use false instead of null to communicate that disabling override?

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit 8713862. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

✅ Successfully ran 33 targets

• nx test eslint-plugin
• nx test typescript-estree
• nx test type-utils
• nx test utils
• nx test visitor-keys
• nx run types:build
• nx test typescript-eslint
• nx run repo-tools:postinstall-script
• nx test scope-manager
• nx test repo-tools
• nx test rule-schema-to-typescript-types
• nx test parser
• nx test eslint-plugin-tslint
• nx test eslint-plugin --coverage=false
• nx run-many --target=build --parallel --exclude=website --exclude=website-eslint
• nx test ast-spec
• nx test eslint-plugin-internal
• nx run-many --target=lint --parallel
• nx test visitor-keys --coverage=false
• nx run integration-tests:test
• nx test typescript-estree --coverage=false
• nx run-many --target=typecheck --parallel
• nx test utils --coverage=false
• nx test type-utils --coverage=false
• nx test ast-spec --coverage=false
• nx test eslint-plugin-internal --coverage=false
• nx test scope-manager --coverage=false
• nx test typescript-eslint --coverage=false
• nx test parser --coverage=false
• nx test eslint-plugin-tslint --coverage=false
• nx test rule-schema-to-typescript-types --coverage=false
• nx test repo-tools --coverage=false
• nx run repo-tools:generate-configs

---

Sent with 💌 from NxCloud.

[bradzacher]

nrwl/nx#21405

[bradzacher]

@JoshuaKGoldberg - this is now truly ready for review (passing ci!!!)
Some initial docs are included as the package's docs.

[JoshuaKGoldberg]

Whoohoo!! 🥳

This looks great to me. There are a few points that could be taken as followups (docs, tests, a bit of style) but nothing IMO that should block this being merged. Awesome job!

[JoshuaKGoldberg]

[Docs] This should be added to sidebar.base.js so it shows up & has a sidebar.

[bradzacher]

UGH. We should automate this somehow.

[JoshuaKGoldberg]

[Style] If they're unused, why bother including them?

Suggested change

	`export default (_plugin: FlatConfig.Plugin, _parser: FlatConfig.Parser): FlatConfig.Config => (${flatConfigJson});`,
	`export default (): FlatConfig.Config => (${flatConfigJson});`,

Here, and the unused import above?

[bradzacher]

cos it sets things up to have a consistent API shape - which is nice in case we do change things in future.

I.e. it means we can blindly write

configs: {
    all: allConfig(plugin, parser),
    base: baseConfig(plugin, parser),
    disableTypeChecked: disableTypeCheckedConfig(plugin, parser),
    eslintRecommended: eslintRecommendedConfig(plugin, parser),
    recommended: recommendedConfig(plugin, parser),
    recommendedTypeChecked: recommendedTypeCheckedConfig(plugin, parser),
    strict: strictConfig(plugin, parser),
    strictTypeChecked: strictTypeCheckedConfig(plugin, parser),
    stylistic: stylisticConfig(plugin, parser),
    stylisticTypeChecked: stylisticTypeCheckedConfig(plugin, parser),
}

rather than having to maintain which ones get args and which don't.

[JoshuaKGoldberg]

[Non-Actionable] Heh, good catch...

[bradzacher]

DAMN YOU AMERICANS SPELLING THINGS WRONG

[JoshuaKGoldberg]

IT'S NOT OUR FAULT WE DON'T HAVE AUSTRALIAN COFFEE