typescript-eslint · higherorderfunctor · Apr 15, 2024 · Apr 15, 2024 · Apr 19, 2024 · Apr 19, 2024
diff --git a/.cspell.json b/.cspell.json
@@ -49,7 +49,8 @@
   "words": [
     "Airbnb",
     "Airbnb's",
-    "allowdefaultprojectforfiles",
+    "ambiently",
+    "allowdefaultproject",
     "ambiently",
     "Armano",
     "astexplorer",

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -134,6 +134,25 @@ jobs:
         run: yarn stylelint
         working-directory: packages/website
 
+  eslint_v9_tests:
+    name: Run tests on ESLint v9
+    needs: [build]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install
+        uses: ./.github/actions/prepare-install
+        with:
+          node-version: ${{ env.PRIMARY_NODE_VERSION }}
+      - name: Build
+        uses: ./.github/actions/prepare-build
+      - run: yarn add eslint@9
+      - name: Run tests
+        run: yarn test
+        env:
+          CI: true
+
   integration_tests:
     name: Run integration tests on primary Node.js version
     needs: [build]
@@ -148,7 +167,7 @@ jobs:
       - name: Build
         uses: ./.github/actions/prepare-build
 
-      - name: Run integrations tests
+      - name: Run integration tests
         run: yarn test-integration
         env:
           CI: true
@@ -221,8 +240,8 @@ jobs:
           # Sadly 1 day is the minimum
           retention-days: 1
 
-  unit_tests_tsserver:
-    name: Run Unit Tests with Experimental TSServer
+  unit_tests_project_service:
+    name: Run Unit Tests with Project Service
     needs: [build]
     runs-on: ubuntu-latest
     strategy:
@@ -246,7 +265,7 @@ jobs:
         run: npx nx test ${{ matrix.package }} --coverage=false
         env:
           CI: true
-          TYPESCRIPT_ESLINT_EXPERIMENTAL_TSSERVER: true
+          TYPESCRIPT_ESLINT_PROJECT_SERVICE: true
 
   upload_coverage:
     name: Upload Codecov Coverage

diff --git a/README.md b/README.md
@@ -24,9 +24,6 @@
 <p align="center">
 👆
 </p>
-<p align="center">
-  Using ESLint v9? See: <a href="https://github.com/typescript-eslint/typescript-eslint/issues/8211">ESLint v9 Support</a>.
-</p>
 <!-- markdownlint-enable MD033 -->
 
 ## Code Contributors

diff --git a/docs/developers/Custom_Rules.mdx b/docs/developers/Custom_Rules.mdx
@@ -99,6 +99,32 @@ export const rule = createRule<Options, MessageIds>({
 });
 ```
 
+#### Extra Rule Docs Types
+
+By default, rule `meta.docs` is allowed to contain only `description` and `url` as described in [ESLint's Custom Rules > Rule Structure docs](https://eslint.org/docs/latest/extend/custom-rules#rule-structure).
+Additional docs properties may be added as a type argument to `ESLintUtils.RuleCreator`:
+
+```ts
+interface MyPluginDocs {
+  recommended: boolean;
+}
+
+const createRule = ESLintUtils.RuleCreator<MyPluginDocs>(
+  name => `https://example.com/rule/${name}`,
+);
+
+createRule({
+  // ...
+  meta: {
+    docs: {
+      description: '...',
+      recommended: true,
+    },
+    // ...
+  },
+});
+```
+
 ### Undocumented Rules
 
 Although it is generally not recommended to create custom rules without documentation, if you are sure you want to do this you can use the `ESLintUtils.RuleCreator.withoutDocs` function to directly create a rule.

diff --git a/docs/maintenance/Issues.mdx b/docs/maintenance/Issues.mdx
@@ -163,7 +163,7 @@ For enhancements meant to limit which kinds of nodes the rule targets, mark the
 #### 🚀 New Rules
 
 We're generally accepting of new rules that meet the above feature request criteria.
-The biggest exception is rules that can roughly be implemented with [`@typescript-eslint/ban-types`](/rules/ban-types) and/or [`no-restricted-syntax`](https://eslint.org/docs/latest/rules/no-restricted-syntax).
+The biggest exception is rules that can roughly be implemented with [`@typescript-eslint/no-restricted-types`](/rules/no-restricted-types) and/or [`no-restricted-syntax`](https://eslint.org/docs/latest/rules/no-restricted-syntax).
 
 ## Pruning Old Issues
 

diff --git a/docs/packages/Parser.mdx b/docs/packages/Parser.mdx
@@ -35,10 +35,10 @@ The following additional configuration options are available by specifying them
 
 ```ts
 interface ParserOptions {
-  allowAutomaticSingleRunInference?: boolean;
   cacheLifetime?: {
     glob?: number | 'Infinity';
   };
+  disallowAutomaticSingleRunInference?: boolean;
   ecmaFeatures?: {
     jsx?: boolean;
     globalReturn?: boolean;
@@ -54,28 +54,29 @@ interface ParserOptions {
   programs?: import('typescript').Program[];
   project?: string | string[] | boolean | null;
   projectFolderIgnoreList?: string[];
+  projectService?: boolean | ProjectServiceOptions;
   tsconfigRootDir?: string;
   warnOnUnsupportedTypeScriptVersion?: boolean;
-  EXPERIMENTAL_useProjectService?: boolean;
 }
 ```
 
-### `allowAutomaticSingleRunInference`
+### `disallowAutomaticSingleRunInference`
 
-> Default `process.env.TSESTREE_SINGLE_RUN` or `false`.
+> Default `process.env.TSESTREE_SINGLE_RUN` or `true`.
 
-Whether to use common heuristics to infer whether ESLint is being used as part of a single run (as opposed to `--fix` mode or in a persistent session such as an editor extension).
+Whether to stop using common heuristics to infer whether ESLint is being used as part of a single run (as opposed to `--fix` mode or in a persistent session such as an editor extension).
+In other words, typescript-eslint is faster by default, and this option disables an automatic performance optimization.
 
 When typescript-eslint handles TypeScript Program management behind the scenes for [linting with type information](../getting-started/Typed_Linting.mdx), this distinction is important for performance.
 There is significant overhead to managing TypeScript "Watch" Programs needed for the long-running use-case.
 Being able to assume the single run case allows typescript-eslint to faster immutable Programs instead.
 
 This setting's default value can be specified by setting a `TSESTREE_SINGLE_RUN` environment variable to `"false"` or `"true"`.
-For example, `TSESTREE_SINGLE_RUN=true npx eslint .` will enable it.
+For example, `TSESTREE_SINGLE_RUN=false npx eslint .` will disable it.
 
-:::tip
-We've seen `allowAutomaticSingleRunInference` improve linting speed in CI by up to 10-20%.
-Our plan is to [enable `allowAutomaticSingleRunInference` by default in an upcoming major version](https://github.com/typescript-eslint/typescript-eslint/issues/8121).
+:::note
+We recommend leaving this option off if possible.
+We've seen allowing automatic single run inference improve linting speed in CI by up to 10-20%.
 :::
 
 ### `cacheLifetime`
@@ -84,7 +85,7 @@ This option allows you to granularly control our internal cache expiry lengths.
 
 You can specify the number of seconds as an integer number, or the string 'Infinity' if you never want the cache to expire.
 
-By default cache entries will be evicted after 30 seconds, or will persist indefinitely if the parser infers that it is a single run (see [`allowAutomaticSingleRunInference`](#allowAutomaticSingleRunInference)).
+By default cache entries will be evicted after 30 seconds, or will persist indefinitely if the parser infers that it is a single run (see [`disallowAutomaticSingleRunInference`](#disallowAutomaticSingleRunInference)).
 
 ### `ecmaFeatures`
 
@@ -209,9 +210,13 @@ All linted files must be part of the provided program(s).
 
 ### `project`
 
+:::note
+We now recommend using [`projectService`](#projectservice) instead of `project` for easier configuration and faster linting.
+:::
+
 > Default `undefined`.
 
-A path to your project's TSConfig. **This setting is required to use [rules which require type information](../getting-started/Typed_Linting.mdx)**.
+A path to your project's TSConfig. **This setting or [`projectService`](#projectservice) are required to use [rules which require type information](../getting-started/Typed_Linting.mdx)**.
 
 Accepted value types:
 
@@ -265,54 +270,15 @@ If this setting is specified, you must only lint files that are included in the
 }
 ```
 
-For an option that allows linting files outside of your TSConfig file(s), see [`EXPERIMENTAL_useProjectService`](#experimental_useprojectservice).
-
-### `projectFolderIgnoreList`
-
-> Default `["**/node_modules/**"]`.
-
-This option allows you to ignore folders from being included in your provided list of `project`s.
-This is useful if you have configured glob patterns, but want to make sure you ignore certain folders.
-
-It accepts an array of globs to exclude from the `project` globs.
-
-For example, by default it will ensure that a glob like `./**/tsconfig.json` will not match any `tsconfig`s within your `node_modules` folder (some npm packages do not exclude their source files from their published packages).
-
-### `tsconfigRootDir`
-
-> Default `undefined`.
-
-This option allows you to provide the root directory for relative TSConfig paths specified in the `project` option above.
-Doing so ensures running ESLint from a directory other than the root will still be able to find your TSConfig.
-
-### `warnOnUnsupportedTypeScriptVersion`
-
-> Default `true`.
-
-This option allows you to toggle the warning that the parser will give you if you use a version of TypeScript which is not explicitly supported. The warning message would look like this:
-
-```plaintext
-=============
-
-WARNING: You are currently running a version of TypeScript which is not officially supported by @typescript-eslint/typescript-estree.
-
-You may find that it works just fine, or you may not.
-
-SUPPORTED TYPESCRIPT VERSIONS: >=3.3.1 <5.1.0
-
-YOUR TYPESCRIPT VERSION: 5.1.3
+For an option that allows linting files outside of your TSConfig file(s), see [`projectService`](#projectService).
 
-Please only submit bug reports when using the officially supported version.
+<HiddenHeading id="experimental_useprojectservice" />
 
-=============
-```
-
-### `EXPERIMENTAL_useProjectService`
+### `projectService`
 
 > Default `false`.
 
-An experimental alternative to `parserOptions.project`.
-This directs the parser to use a more seamless TypeScript API to generate type information for rules.
+Specifies using TypeScript APIs to generate type information for rules.
 It will automatically detect the TSConfig for each file (like `project: true`), and will also allow type information to be computed for JavaScript files without the `allowJs` compiler option (unlike `project: true`).
 
 <Tabs groupId="eslint-config">
@@ -323,7 +289,7 @@ export default [
   {
     languageOptions: {
       parserOptions: {
-        EXPERIMENTAL_useProjectService: true,
+        projectService: true,
       },
     },
   },
@@ -337,25 +303,96 @@ export default [
 module.exports = {
   parser: '@typescript-eslint/parser',
   parserOptions: {
-    EXPERIMENTAL_useProjectService: true,
+    projectService: true,
   },
 };
 ```
 
 </TabItem>
 </Tabs>
 
-This option should bring two main benefits:
+**This setting or [`project`](#project) are required to use [rules which require type information](../getting-started/Typed_Linting.mdx)**.
+
+This option brings two main benefits over the older `project`:
 
 - Simpler configurations: most projects shouldn't need to explicitly configure `project` paths or create `tsconfig.eslint.json`s
 - Improved performance: this API is optimized on the TypeScript side for speed
   - Initial versions of this option demonstrated performance changes in subsets of the typescript-eslint monorepo ranging from 11% slower to 70% faster
 
-We're hopeful this option will eventually become the standard way to enable typed linting.
-It switches the parser from manually creating TypeScript programs to instead calling the same "project services" API used by editors such as VS Code.
-However, because it's so new and untested, we're keeping it under the `EXPERIMENTAL_` prefix for at least all of the `6.X` versions.
+For more information, see:
+
+- [feat(typescript-estree): add EXPERIMENTAL_useProjectService option to use TypeScript project service](https://github.com/typescript-eslint/typescript-eslint/pull/6754)
+- [docs: blog post on parserOptions.projectService](docs: blog post on parserOptions.projectService )
 
-See [feat(typescript-estree): add EXPERIMENTAL_useProjectService option to use TypeScript project service](https://github.com/typescript-eslint/typescript-eslint/pull/6754) for more information.
+#### `ProjectServiceOptions`
+
+The behavior of `parserOptions.projectService` can be customized by setting it to an object.
+
+```js
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    projectService: {
+      allowDefaultProject: ['./*.js'],
+    },
+  },
+};
+```
+
+##### `allowDefaultProject`
+
+Globs of files to allow running with the default project compiler options despite not being matched by the project service.
+
+##### `defaultProject`
+
+Path to a TSConfig to use instead of TypeScript's default project configuration.
+
+##### `maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING`
+
+> Default: `8`.
+
+The maximum number of files [`allowDefaultProject`](#allowdefaultproject) may match.
+Each file match slows down linting, so if you do need to use this, please file an informative issue on typescript-eslint explaining why - so we can help you avoid using it!
+
+### `projectFolderIgnoreList`
+
+> Default `["**/node_modules/**"]`.
+
+This option allows you to ignore folders from being included in your provided list of `project`s.
+This is useful if you have configured glob patterns, but want to make sure you ignore certain folders.
+
+It accepts an array of globs to exclude from the `project` globs.
+
+For example, by default it will ensure that a glob like `./**/tsconfig.json` will not match any `tsconfig`s within your `node_modules` folder (some npm packages do not exclude their source files from their published packages).
+
+### `tsconfigRootDir`
+
+> Default `undefined`.
+
+This option allows you to provide the root directory for relative TSConfig paths specified in the `project` option above.
+Doing so ensures running ESLint from a directory other than the root will still be able to find your TSConfig.
+
+### `warnOnUnsupportedTypeScriptVersion`
+
+> Default `true`.
+
+This option allows you to toggle the warning that the parser will give you if you use a version of TypeScript which is not explicitly supported. The warning message would look like this:
+
+```plaintext
+=============
+
+WARNING: You are currently running a version of TypeScript which is not officially supported by @typescript-eslint/typescript-estree.
+
+You may find that it works just fine, or you may not.
+
+SUPPORTED TYPESCRIPT VERSIONS: >=3.3.1 <5.1.0
+
+YOUR TYPESCRIPT VERSION: 5.1.3
+
+Please only submit bug reports when using the officially supported version.
+
+=============
+```
 
 ## Utilities
 

diff --git a/docs/packages/Rule_Tester.mdx b/docs/packages/Rule_Tester.mdx
@@ -77,6 +77,15 @@ ruleTester.run('my-rule', rule, {
         /* ... */
       ],
     },
+    // Multi-pass fixes can be tested using the array form of output.
+    // Note: this is unique to typescript-eslint, and doesn't exist in ESLint core.
+    {
+      code: 'const d = 1;',
+      output: ['const e = 1;', 'const f = 1;'],
+      errors: [
+        /* ... */
+      ],
+    },
 
     // suggestions can be tested via errors
     {