feat: add types for flat config files

[bradzacher]

Overview

Adds in strict type definitions for the new "flat config" style config.
I took the time to do a little bit of refactoring to attempt to share as many types as possible and better organise things.
In particular I tried to move things a little so everything didn't hang off the Linter namespace like before.

I believe I got everything right - it was pieced together from the docs. Sadly there is no json schema like with classic configs and the validation function is quite loose - so some of it is pieced together based on past config structure.
Feel free to eyeball the docs and compare them to make sure I got it right.

This change should be completely backwards-compatible - please flag if you think I made any incompatible changes though.

TODO - https://eslint.org/docs/latest/extend/plugins#metadata-in-plugins

[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	e63dfb9
🔍 Latest deploy log	https://app.netlify.com/sites/typescript-eslint/deploys/65511358cecdb5000832db2c
😎 Deploy Preview	https://deploy-preview-7273--typescript-eslint.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 99 (no change 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.

[nx-cloud]

☁️ Nx Cloud Report

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

📂 See all runs for this branch

---

✅ Successfully ran 35 targets

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

---

Sent with 💌 from NxCloud.

[JoshuaKGoldberg]

OK! From what I can tell, this is a very accurate and good representation of how things will be in the new world. But, as you mentioned in the description, this is all conjecture and guessing. I think we'd want some response to eslint/eslint#17391 eslint/eslint#17242 and/or an explicit review from someone on ESLint core. 🤷

[JoshuaKGoldberg]

@bradzacher now that eslint/eslint#17640 is merged, are there any changes you want to make here?

[karlhorky]

@JoshuaKGoldberg @bradzacher while we wait for the PR merge + release, is it possible to publish a WIP version of this to npm? Or is there another easy way for package authors to help test out these new types in their projects? (before this PR is merged)

Eg. some prerelease tag like 7.0.0-flat-config-types.0 or similar?

[karlhorky]

Workaround

For now, I'm using @types/eslint, which has the Linter.FlatConfig export:

/** @type {import('eslint').Linter.FlatConfig} */
const config = {
};

export default config;

Types aren't as nice as the @typescript-eslint/util types, but it works so far for now...

[JoshuaKGoldberg]

Or is there another easy way for package authors to help test out these new types in their projects? (before this PR is merged)

https://typescript-eslint.io/contributing/local-development -> https://typescript-eslint.io/contributing/local-development/local-linking would be the right way.

Looks like this has some merge conflicts right now. Were it not for those and builds on main being broken (#7899) I'd merge as-is.

[bradzacher]

One of the reasons I hadn't pushed forward with this was I was trying to decide if I should build some features for typing the config or not.

There's a whole project around that so might be worth just not doing it for the moment.

[karlhorky]

features for typing the config

There's a whole project around that

I assume you mean eslint-define-config by @Shinigami92 ?

Alternative: I have been using the types directly with JSDoc and the experience hasn't been too bad.

[bradzacher]

Yes, like that but built in.
I spent a while musing on this idea but I ultimately got stuck on trying to make it truly safe.
Sadly the way that flat configs are defined are just not compatible with true type safety.

For example this is a valid config

import foo from 'eslint-plugin-foo';
import bar from 'eslint-plugin-bar';

export default [
  { plugins: {foo} }, 
  {
    files: ["path1"],
    plugins: {bar}, 
  }, 
  {
    rules: {
      // foo/* rules are available here
      // but not bar/* rules
    },
  },
];

And you can see how the generics just don't work because config merging. So we'd need to go with a less sound approach (which is fine enough but not ideal).

There's also the complicated thing of renaming plugins which would need to be handled. EG

import foo from 'eslint-plugin-foo';

export default [
  { 
    files: ["path1"],
    plugins: {foo},
    rules: {
      // eslint-plugin-foo rules are available as foo/*
    },
  }, 
  {
    files: ["path2"],
    plugins: {foobar: foo},
    rules: {
      // eslint-plugin-foo rules are available as foobar/*
    },
  },
  {
    rules: {
      // eslint-plugin-foo rules are NOT available here
    },
  },
];

There's a lot of sadness with the flat config design as it was intended to be a very dynamic DSL -- which ofc sucks to strictly type.
"The first rule of strict types is don't do highly dynamic JS bullshit."

---

The other thing I was looking at was our schema generation tooling. To make type-safe configs work we would want a way to auto-generate types for the plugin based on the json schemas. We now have that tooling but we don't have it designed for public consumption - or even published.

Theres a lot of work to do to define this space as a general solution that any plugin at all can easily leverage and users can "just use".

---

Which is a long and rambly confirmation that this probably just needs to land as-is and the type-safe rule configs can come later.

[JoshuaKGoldberg]

cc @bradzacher - GitHub won't let me request your review on your own PR (because nobody has ever swapped author/reviewer role on a PR, ever) but I think I got it merged from main all right.

[JoshuaKGoldberg]

oop - @bradzacher if you want to send another PR I should be able to review before our auto-release today

(I'm about to step out but will be back soon)

[bradzacher]

I think that just specifying RuleCreateFunction might be dead for flat configs?
I know it's deprecated I just don't know if it's dead dead.

[bradzacher]

🤷‍♂️ was just drive by commenting before i went to bed.
i'd forgotten what I'd even put in this pr TBH heh.
anything older than a month is mostly deleted from my memory #toddlerdadlife

[JoshuaKGoldberg]

Well, this is released in https://github.com/typescript-eslint/typescript-eslint/releases/tag/v6.11.0 (cc @karlhorky). If folks don't like it we can always fix it up 😄

[karlhorky]

Hmm... just trying out @typescript-eslint/utils@6.11.0 now, and I'm having trouble getting my JSDoc imports working

I first tried this:

/** @type {import('@typescript-eslint/utils').TSESLint.Linter.Config[]} */
const config = [
  { 
    plugins: {
      '@next/next': next,
    },
    ...
  },
  ...

But this resulted in the error that the type of plugins doesn't match the eslintrc-style config (string[]):

Type '{ '@next/next': ESLint.Plugin; '@typescript-eslint': ESLint.Plugin; 'jsx-a11y': ESLint.Plugin; 'jsx-expressions': ESLint.Plugin; 'react-hooks': ESLint.Plugin; ... 5 more ...; upleveled: ESLint.Plugin; }' is not assignable to type 'string[]'.
  Object literal may only specify known properties, and ''@next/next'' does not exist in type 'string[]'.

There was no FlatConfig exposed on import('@typescript-eslint/utils').TSESLint.Linter directly, so another option I tried was to try to import the FlatConfig namespace directly from dist/ts-eslint/Config.js, but I think this doesn't work either:

/** @type {import('./node_modules/@typescript-eslint/utils/dist/ts-eslint/Config.js').FlatConfig[]} */

This resulted in a different error:

Namespace '"/Users/k/p/eslint-config-upleveled/node_modules/@typescript-eslint/utils/dist/ts-eslint/Config"' has no exported member 'FlatConfig'.

---

Is there a better way to import this type for usage in my shared config?

[bradzacher]

@karlhorky you should be able to use

import('@typescript-eslint/utils/ts-eslint').FlatConfig.ConfigArray

[karlhorky]

Thanks! Switched over here:

• upleveled/eslint-config-upleveled@a3830a4

Still some manual work needed (see below), but looks like it's working 🙌

• extra .d.ts files including a custom type for configs.recommended on ESLint plugins
• casting (eg. for conditional modification of the config) - satisfies would be nicer to use here to allow TS to infer that these things are not undefined, but I was unable to get @satisfies in JSDoc working