From 4ae62968c53b1b4fdfd5698059c4fd70f71afe3d Mon Sep 17 00:00:00 2001
From: Josh Goldberg <git@joshuakgoldberg.com>
Date: Tue, 26 Dec 2023 15:09:46 -0500
Subject: [PATCH 1/2] docs: document allowAutomaticSingleRunInference

---
 .eslintrc.js             | 15 ++++++---------
 docs/packages/Parser.mdx | 21 ++++++++++++++++++++-
 2 files changed, 26 insertions(+), 10 deletions(-)

diff --git a/.eslintrc.js b/.eslintrc.js
index 400ed10c4aaa..111232e4753b 100644
--- a/.eslintrc.js
+++ b/.eslintrc.js
@@ -24,7 +24,12 @@ module.exports = {
     'plugin:@typescript-eslint/stylistic-type-checked',
   ],
   parserOptions: {
-    sourceType: 'module',
+    allowAutomaticSingleRunInference: true,
+    cacheLifetime: {
+      // we pretty well never create/change tsconfig structure - so need to ever evict the cache
+      // in the rare case that we do - just need to manually restart their IDE.
+      glob: 'Infinity',
+    },
     project: [
       './tsconfig.eslint.json',
       './packages/*/tsconfig.json',
@@ -38,15 +43,7 @@ module.exports = {
       './packages/scope-manager/tsconfig.build.json',
       './packages/scope-manager/tsconfig.spec.json',
     ],
-    allowAutomaticSingleRunInference: true,
     tsconfigRootDir: __dirname,
-    warnOnUnsupportedTypeScriptVersion: false,
-    EXPERIMENTAL_useSourceOfProjectReferenceRedirect: false,
-    cacheLifetime: {
-      // we pretty well never create/change tsconfig structure - so need to ever evict the cache
-      // in the rare case that we do - just need to manually restart their IDE.
-      glob: 'Infinity',
-    },
   },
   rules: {
     // make sure we're not leveraging any deprecated APIs
diff --git a/docs/packages/Parser.mdx b/docs/packages/Parser.mdx
index efaa66924ce5..5d5860493103 100644
--- a/docs/packages/Parser.mdx
+++ b/docs/packages/Parser.mdx
@@ -30,6 +30,7 @@ The following additional configuration options are available by specifying them
 
 ```ts
 interface ParserOptions {
+  allowAutomaticSingleRunInference?: boolean;
   cacheLifetime?: {
     glob?: number | 'Infinity';
   };
@@ -49,16 +50,32 @@ interface ParserOptions {
   projectFolderIgnoreList?: string[];
   tsconfigRootDir?: string;
   warnOnUnsupportedTypeScriptVersion?: boolean;
+  EXPERIMENTAL_useProjectService?: boolean;
 }
 ```
 
+### `allowAutomaticSingleRunInference`
+
+> Default `false`.
+
+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).
+
+When typescript-eslint handles TypeScript Program management behind the scenes for [linting with type information](../linting/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.
+
+:::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).
+:::
+
 ### `cacheLifetime`
 
 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.
+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)).
 
 ### `ecmaFeatures`
 
@@ -267,6 +284,8 @@ Please only submit bug reports when using the officially supported version.
 
 ### `EXPERIMENTAL_useProjectService`
 
+> 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.
 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`).

From d55acac5b3cce08ddbe9fed5f7c7428d9238c1a7 Mon Sep 17 00:00:00 2001
From: Josh Goldberg <git@joshuakgoldberg.com>
Date: Sun, 7 Jan 2024 11:23:06 -0500
Subject: [PATCH 2/2] so 'no' need

---
 .eslintrc.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.eslintrc.js b/.eslintrc.js
index 111232e4753b..42ac029d1feb 100644
--- a/.eslintrc.js
+++ b/.eslintrc.js
@@ -26,7 +26,7 @@ module.exports = {
   parserOptions: {
     allowAutomaticSingleRunInference: true,
     cacheLifetime: {
-      // we pretty well never create/change tsconfig structure - so need to ever evict the cache
+      // we pretty well never create/change tsconfig structure - so no need to ever evict the cache
       // in the rare case that we do - just need to manually restart their IDE.
       glob: 'Infinity',
     },