docs: document allowAutomaticSingleRunInference (#8138)

* docs: document allowAutomaticSingleRunInference * so 'no' need
typescript-eslint · Jan 7, 2024 · 8450dbe · 8450dbe
1 parent 1ee3087
commit 8450dbe
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 10 deletions.
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -26,7 +26,12 @@ module.exports = {
     'plugin:@typescript-eslint/stylistic-type-checked',
   ],
   parserOptions: {
-    sourceType: 'module',
+    allowAutomaticSingleRunInference: true,
+    cacheLifetime: {
+      // 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',
+    },
     project: [
       './tsconfig.eslint.json',
       './packages/*/tsconfig.json',
@@ -40,15 +45,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
@@ -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`).