typescript-eslint · JoshuaKGoldberg · Apr 25, 2024 · Apr 15, 2024 · Apr 15, 2024 · Apr 15, 2024
diff --git a/.cspell.json b/.cspell.json
@@ -50,6 +50,7 @@
     "Airbnb",
     "Airbnb's",
     "ambiently",
+    "allowdefaultprojectforfiles",
     "Armano",
     "astexplorer",
     "Astro",
@@ -150,6 +151,7 @@
     "unoptimized",
     "unprefixed",
     "upsert",
+    "useprojectservice",
     "Waiblinger",
     "warnonunsupportedtypescriptversion",
     "Zacher"

diff --git a/docs/packages/TypeScript_ESTree.mdx b/docs/packages/TypeScript_ESTree.mdx
@@ -288,6 +288,15 @@ interface ProjectServiceOptions {
    * Path to a TSConfig to use instead of TypeScript's default project configuration.
    */
   defaultProject?: string;
+
+  /**
+   * The maximum number of files {@link allowDefaultProjectForFiles} 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!
+   * @default 8
+   */
+  maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING?: number;
 }
 
 interface ParserServices {

diff --git a/docs/troubleshooting/FAQ.mdx b/docs/troubleshooting/FAQ.mdx
@@ -32,6 +32,40 @@ If you don't find an existing extension rule, or the extension rule doesn't work
 > We release a new version our tooling every week.
 > _Please_ ensure that you [check our the latest list of "extension" rules](/rules/#extension-rules) **_before_** filing an issue.
 
+<HiddenHeading id="allowdefaultprojectforfiles-glob-too-wide" />
+
+## I get errors telling me "Having many files run with the default project is known to cause performance issues and slow down linting."
+
+These errors are caused by using the [`EXPERIMENTAL_useProjectService`](../packages/Parser.mdx#experimental_useprojectservice) `allowDefaultProjectForFiles` with an excessively wide glob.
+`allowDefaultProjectForFiles` causes a new TypeScript "program" to be built for each "out of project" file it includes, which incurs a performance overhead for each file.
+
+To resolve this error, narrow the glob(s) used for `allowDefaultProjectForFiles` to include fewer files.
+For example:
+
+```diff title="eslint.config.js"
+parserOptions: {
+  EXPERIMENTAL_useProjectService: {
+    allowDefaultProjectForFiles: [
+-      "**/*.js",
++      "./*.js"
+    ]
+  }
+}
+```
+
+You may also need to include more files in your `tsconfig.json`.
+For example:
+
+```diff title="tsconfig.json"
+"include": [
+  "src",
++ "*.js"
+]
+```
+
+If you cannot do this, please [file an issue on typescript-eslint's typescript-estree package](https://github.com/typescript-eslint/typescript-eslint/issues/new?assignees=&labels=enhancement%2Ctriage&projects=&template=07-enhancement-other.yaml&title=Enhancement%3A+%3Ca+short+description+of+my+proposal%3E) telling us your use case and why you need more out-of-project files linted.
+Be sure to include a minimal reproduction we can work with to understand your use case!
+
 ## I get errors telling me "ESLint was configured to run ... However, that TSConfig does not / none of those TSConfigs include this file"
 
 These errors are caused by an ESLint config requesting type information be generated for a file that isn't included in the TypeScript configuration.
@@ -499,6 +533,6 @@ If you think you're having issues with performance, see our [Performance Trouble
 
 ## Are TypeScript project references supported?
 
-No, TypeScript project references are not yet supported.
+Yes, but only with [`EXPERIMENTAL_useProjectService`](../packages/Parser.mdx#experimental_useprojectservice).
 
 See [issue #2094 discussing project references](https://github.com/typescript-eslint/typescript-eslint/issues/2094) for more details.
diff --git a/packages/typescript-estree/src/clear-caches.ts b/packages/typescript-estree/src/clear-caches.ts
@@ -1,5 +1,8 @@
 import { clearWatchCaches } from './create-program/getWatchProgramsForProjects';
-import { clearProgramCache as clearProgramCacheOriginal } from './parser';
+import {
+  clearDefaultProjectMatchedFiles,
+  clearProgramCache as clearProgramCacheOriginal,
+} from './parser';
 import {
   clearTSConfigMatchCache,
   clearTSServerProjectService,
@@ -14,6 +17,7 @@ import { clearGlobCache } from './parseSettings/resolveProjectList';
  * - In custom lint tooling that iteratively lints one project at a time to prevent OOMs.
  */
 export function clearCaches(): void {
+  clearDefaultProjectMatchedFiles();
   clearProgramCacheOriginal();
   clearWatchCaches();
   clearTSConfigMatchCache();

diff --git a/packages/typescript-estree/src/create-program/createProjectService.ts b/packages/typescript-estree/src/create-program/createProjectService.ts
@@ -4,6 +4,9 @@ import os from 'node:os';
 import type * as ts from 'typescript/lib/tsserverlibrary';
 
 import type { ProjectServiceOptions } from '../parser-options';
+import { validateDefaultProjectForFilesGlob } from './validateDefaultProjectForFilesGlob';
+
+const DEFAULT_PROJECT_MATCHED_FILES_THRESHOLD = 8;
 
 const doNothing = (): void => {};
 
@@ -15,13 +18,17 @@ export type TypeScriptProjectService = ts.server.ProjectService;
 
 export interface ProjectServiceSettings {
   allowDefaultProjectForFiles: string[] | undefined;
+  maximumDefaultProjectFileMatchCount: number;
   service: TypeScriptProjectService;
 }
 
 export function createProjectService(
-  options: boolean | ProjectServiceOptions | undefined,
+  optionsRaw: boolean | ProjectServiceOptions | undefined,
   jsDocParsingMode: ts.JSDocParsingMode | undefined,
 ): ProjectServiceSettings {
+  const options = typeof optionsRaw === 'object' ? optionsRaw : {};
+  validateDefaultProjectForFilesGlob(options);
+
   // We import this lazily to avoid its cost for users who don't use the service
   // TODO: Once we drop support for TS<5.3 we can import from "typescript" directly
   const tsserver = require('typescript/lib/tsserverlibrary') as typeof ts;
@@ -60,7 +67,7 @@ export function createProjectService(
     jsDocParsingMode,
   });
 
-  if (typeof options === 'object' && options.defaultProject) {
+  if (options.defaultProject) {
     let configRead;
 
     try {
@@ -97,10 +104,10 @@ export function createProjectService(
   }
 
   return {
-    allowDefaultProjectForFiles:
-      typeof options === 'object'
-        ? options.allowDefaultProjectForFiles
-        : undefined,
+    allowDefaultProjectForFiles: options.allowDefaultProjectForFiles,
+    maximumDefaultProjectFileMatchCount:
+      options.maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING ??
+      DEFAULT_PROJECT_MATCHED_FILES_THRESHOLD,
     service,
   };
 }
diff --git a/packages/typescript-estree/src/create-program/validateDefaultProjectForFilesGlob.ts b/packages/typescript-estree/src/create-program/validateDefaultProjectForFilesGlob.ts
@@ -0,0 +1,29 @@
+import type { ProjectServiceOptions } from '../parser-options';
+
+export const DEFAULT_PROJECT_FILES_ERROR_EXPLANATION = `
+
+Having many files run with the default project is known to cause performance issues and slow down linting.
+
+See https://typescript-eslint.io/troubleshooting/#allowdefaultprojectforfiles-glob-too-wide
+`;
+
+export function validateDefaultProjectForFilesGlob(
+  options: ProjectServiceOptions,
+): void {
+  if (!options.allowDefaultProjectForFiles?.length) {
+    return;
+  }
+
+  for (const glob of options.allowDefaultProjectForFiles) {
+    if (glob === '*') {
+      throw new Error(
+        `allowDefaultProjectForFiles contains the overly wide '*'.${DEFAULT_PROJECT_FILES_ERROR_EXPLANATION}`,
+      );
+    }
+    if (glob.includes('**')) {
+      throw new Error(
+        `allowDefaultProjectForFiles glob '${glob}' contains a disallowed '**'.${DEFAULT_PROJECT_FILES_ERROR_EXPLANATION}`,
+      );
+    }
+  }
+}
diff --git a/packages/typescript-estree/src/parser-options.ts b/packages/typescript-estree/src/parser-options.ts
@@ -114,6 +114,15 @@ export interface ProjectServiceOptions {
    * Path to a TSConfig to use instead of TypeScript's default project configuration.
    */
   defaultProject?: string;
+
+  /**
+   * The maximum number of files {@link allowDefaultProjectForFiles} 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!
+   * @default 8
+   */
+  maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING?: number;
 }
 
 interface ParseAndGenerateServicesOptions extends ParseOptions {

diff --git a/packages/typescript-estree/src/parser.ts b/packages/typescript-estree/src/parser.ts
@@ -40,6 +40,11 @@ function clearProgramCache(): void {
   existingPrograms.clear();
 }
 
+const defaultProjectMatchedFiles = new Set<string>();
+function clearDefaultProjectMatchedFiles(): void {
+  defaultProjectMatchedFiles.clear();
+}
+
 /**
  * @param parseSettings Internal settings for parsing the file
  * @param hasFullTypeInformation True if the program should be attempted to be calculated from provided tsconfig files
@@ -54,6 +59,7 @@ function getProgramAndAST(
       parseSettings.EXPERIMENTAL_projectService,
       parseSettings,
       hasFullTypeInformation,
+      defaultProjectMatchedFiles,
     );
     if (fromProjectService) {
       return fromProjectService;
@@ -286,6 +292,7 @@ export {
   parse,
   parseAndGenerateServices,
   ParseAndGenerateServicesResult,
+  clearDefaultProjectMatchedFiles,
   clearProgramCache,
   clearParseAndGenerateServicesCalls,
 };
diff --git a/packages/typescript-estree/src/useProgramFromProjectService.ts b/packages/typescript-estree/src/useProgramFromProjectService.ts
@@ -5,16 +5,22 @@ import path from 'path';
 import { createProjectProgram } from './create-program/createProjectProgram';
 import type { ProjectServiceSettings } from './create-program/createProjectService';
 import type { ASTAndDefiniteProgram } from './create-program/shared';
+import { DEFAULT_PROJECT_FILES_ERROR_EXPLANATION } from './create-program/validateDefaultProjectForFilesGlob';
 import type { MutableParseSettings } from './parseSettings';
 
 const log = debug(
   'typescript-eslint:typescript-estree:useProgramFromProjectService',
 );
 
 export function useProgramFromProjectService(
-  { allowDefaultProjectForFiles, service }: ProjectServiceSettings,
+  {
+    allowDefaultProjectForFiles,
+    maximumDefaultProjectFileMatchCount,
+    service,
+  }: ProjectServiceSettings,
   parseSettings: Readonly<MutableParseSettings>,
   hasFullTypeInformation: boolean,
+  defaultProjectMatchedFiles: Set<string>,
 ): ASTAndDefiniteProgram | undefined {
   // We don't canonicalize the filename because it caused a performance regression.
   // See https://github.com/typescript-eslint/typescript-eslint/issues/8519
@@ -77,6 +83,20 @@ export function useProgramFromProjectService(
     return undefined;
   }
 
+  defaultProjectMatchedFiles.add(filePathAbsolute);
+  if (defaultProjectMatchedFiles.size > maximumDefaultProjectFileMatchCount) {
+    throw new Error(
+      `Too many files (>${maximumDefaultProjectFileMatchCount}) have matched the default project.${DEFAULT_PROJECT_FILES_ERROR_EXPLANATION}
+Matching files:
+${Array.from(defaultProjectMatchedFiles)
+  .map(file => `- ${file}`)
+  .join('\n')}
+
+If you absolutely need more files included, set parserOptions.EXPERIMENTAL_useProjectService.maximumDefaultProjectFileMatchCount_THIS_WILL_SLOW_DOWN_LINTING to a larger value.
+`,
+    );
+  }
+
   log('Found project service program for: %s', filePathAbsolute);
 
   return createProjectProgram(parseSettings, [program]);

diff --git a/packages/typescript-estree/tests/lib/persistentParse.test.ts b/packages/typescript-estree/tests/lib/persistentParse.test.ts
@@ -4,7 +4,10 @@ import tmp from 'tmp';
 
 import { clearCaches } from '../../src/clear-caches';
 import { clearWatchCaches } from '../../src/create-program/getWatchProgramsForProjects';
-import { parseAndGenerateServices } from '../../src/parser';
+import {
+  clearDefaultProjectMatchedFiles,
+  parseAndGenerateServices,
+} from '../../src/parser';
 
 const CONTENTS = {
   foo: 'console.log("foo")',
@@ -19,6 +22,9 @@ const CONTENTS = {
 const cwdCopy = process.cwd();
 const tmpDirs = new Set<tmp.DirResult>();
 afterEach(() => {
+  // reset project tracking
+  clearDefaultProjectMatchedFiles();
+
   // stop watching the files and folders
   clearWatchCaches();