feat(typescript-estree): deprecate createDefaultProgram (#5890)

* chore(typescript-estree): deprecate createDefaultProgram * Apply suggestions from code review Co-authored-by: Brad Zacher <brad.zacher@gmail.com> * More updates to comments and name * One more comment line removal * Fix lint complaints Co-authored-by: Brad Zacher <brad.zacher@gmail.com>
typescript-eslint · Oct 27, 2022 · 9b5fa0b · 9b5fa0b
1 parent 5b9c379
commit 9b5fa0b
Show file tree

Hide file tree

Showing 11 changed files with 31 additions and 36 deletions.
diff --git a/packages/parser/README.md b/packages/parser/README.md
@@ -168,7 +168,7 @@ This option allows you to provide a path to your project's `tsconfig.json`. **Th
 
 - TypeScript will ignore files with duplicate filenames in the same folder (for example, `src/file.ts` and `src/file.js`). TypeScript purposely ignore all but one of the files, only keeping the one file with the highest priority extension (the extension priority order (from highest to lowest) is `.ts`, `.tsx`, `.d.ts`, `.js`, `.jsx`). For more info see #955.
 
-- Note that if this setting is specified and `createDefaultProgram` is not, you must only lint files that are included in the projects as defined by the provided `tsconfig.json` files. If your existing configuration does not include all of the files you would like to lint, you can create a separate `tsconfig.eslint.json` as follows:
+- Note that if this setting is specified, you must only lint files that are included in the projects as defined by the provided `tsconfig.json` files. If your existing configuration does not include all of the files you would like to lint, you can create a separate `tsconfig.eslint.json` as follows:
 
   ```jsonc
   {
@@ -217,18 +217,12 @@ 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
 
-### `parserOptions.createDefaultProgram`
-
-Default `false`.
-
-This option allows you to request that when the `project` setting is specified, files will be allowed when not included in the projects defined by the provided `tsconfig.json` files. **Using this option will incur significant performance costs. This option is primarily included for backwards-compatibility.** See the **`project`** section above for more information.
-
 ### `parserOptions.programs`
 
 Default `undefined`.
 
 This option allows you to programmatically provide an array of one or more instances of a TypeScript Program object that will provide type information to rules.
-This will override any programs that would have been computed from `parserOptions.project` or `parserOptions.createDefaultProgram`.
+This will override any programs that would have been computed from `parserOptions.project`.
 All linted files must be part of the provided program(s).
 
 ### `parserOptions.moduleResolver`

diff --git a/packages/typescript-estree/README.md b/packages/typescript-estree/README.md
@@ -207,15 +207,10 @@ interface ParseAndGenerateServicesOptions extends ParseOptions {
   programs?: Program[];
 
   /**
-   ***************************************************************************************
-   * IT IS RECOMMENDED THAT YOU DO NOT USE THIS OPTION, AS IT CAUSES PERFORMANCE ISSUES. *
-   ***************************************************************************************
-   *
-   * When passed with `project`, this allows the parser to create a catch-all, default program.
-   * This means that if the parser encounters a file not included in any of the provided `project`s,
-   * it will not error, but will instead parse the file and its dependencies in a new program.
+   * @deprecated - this flag will be removed in the next major.
+   * Do not rely on the behavior provided by this flag.
    */
-  createDefaultProgram?: boolean;
+  DEPRECATED__createDefaultProgram?: boolean;
 
   /**
    * ESLint (and therefore typescript-eslint) is used in both "single run"/one-time contexts,

diff --git a/packages/typescript-estree/src/create-program/createDefaultProgram.ts b/packages/typescript-estree/src/create-program/createDefaultProgram.ts
@@ -14,6 +14,9 @@ const log = debug('typescript-eslint:typescript-estree:createDefaultProgram');
 /**
  * @param parseSettings Internal settings for parsing the file
  * @returns If found, returns the source file corresponding to the code and the containing program
+ * @deprecated
+ * This is a legacy option that comes with severe performance penalties.
+ * Please do not use it.
  */
 function createDefaultProgram(
   parseSettings: ParseSettings,
@@ -66,4 +69,5 @@ function createDefaultProgram(
   return ast && { ast, program };
 }
 
+// eslint-disable-next-line deprecation/deprecation -- will be cleaned up with the next major
 export { createDefaultProgram };
diff --git a/packages/typescript-estree/src/create-program/createProjectProgram.ts b/packages/typescript-estree/src/create-program/createProjectProgram.ts
@@ -36,7 +36,8 @@ function createProjectProgram(
   );
 
   // The file was either matched within the tsconfig, or we allow creating a default program
-  if (astAndProgram || parseSettings.createDefaultProgram) {
+  // eslint-disable-next-line deprecation/deprecation -- will be cleaned up with the next major
+  if (astAndProgram || parseSettings.DEPRECATED__createDefaultProgram) {
     return astAndProgram;
   }
 

diff --git a/packages/typescript-estree/src/parseSettings/createParseSettings.ts b/packages/typescript-estree/src/parseSettings/createParseSettings.ts
@@ -28,7 +28,9 @@ export function createParseSettings(
     code: enforceString(code),
     comment: options.comment === true,
     comments: [],
-    createDefaultProgram: options.createDefaultProgram === true,
+    DEPRECATED__createDefaultProgram:
+      // eslint-disable-next-line deprecation/deprecation -- will be cleaned up with the next major
+      options.DEPRECATED__createDefaultProgram === true,
     debugLevel:
       options.debugLevel === true
         ? new Set(['typescript-eslint'])

diff --git a/packages/typescript-estree/src/parseSettings/index.ts b/packages/typescript-estree/src/parseSettings/index.ts
@@ -25,9 +25,11 @@ export interface MutableParseSettings {
   comments: TSESTree.Comment[];
 
   /**
-   * Whether to create a TypeScript program if one is not provided.
+   * @deprecated
+   * This is a legacy option that comes with severe performance penalties.
+   * Please do not use it.
    */
-  createDefaultProgram: boolean;
+  DEPRECATED__createDefaultProgram: boolean;
 
   /**
    * Which debug areas should be logged.

diff --git a/packages/typescript-estree/src/parser-options.ts b/packages/typescript-estree/src/parser-options.ts
@@ -144,15 +144,10 @@ interface ParseAndGenerateServicesOptions extends ParseOptions {
   programs?: ts.Program[];
 
   /**
-   ***************************************************************************************
-   * IT IS RECOMMENDED THAT YOU DO NOT USE THIS OPTION, AS IT CAUSES PERFORMANCE ISSUES. *
-   ***************************************************************************************
-   *
-   * When passed with `project`, this allows the parser to create a catch-all, default program.
-   * This means that if the parser encounters a file not included in any of the provided `project`s,
-   * it will not error, but will instead parse the file and its dependencies in a new program.
+   * @deprecated - this flag will be removed in the next major.
+   * Do not rely on the behavior provided by this flag.
    */
-  createDefaultProgram?: boolean;
+  DEPRECATED__createDefaultProgram?: boolean;
 
   /**
    * ESLint (and therefore typescript-eslint) is used in both "single run"/one-time contexts,

diff --git a/packages/typescript-estree/src/parser.ts b/packages/typescript-estree/src/parser.ts
@@ -44,7 +44,9 @@ function getProgramAndAST(
       useProvidedPrograms(parseSettings.programs, parseSettings)) ||
     (shouldProvideParserServices && createProjectProgram(parseSettings)) ||
     (shouldProvideParserServices &&
-      parseSettings.createDefaultProgram &&
+      // eslint-disable-next-line deprecation/deprecation -- will be cleaned up with the next major
+      parseSettings.DEPRECATED__createDefaultProgram &&
+      // eslint-disable-next-line deprecation/deprecation -- will be cleaned up with the next major
       createDefaultProgram(parseSettings)) ||
     createIsolatedProgram(parseSettings)
   );

diff --git a/packages/typescript-estree/tests/lib/parse.test.ts b/packages/typescript-estree/tests/lib/parse.test.ts
@@ -773,10 +773,10 @@ describe('parseAndGenerateServices', () => {
       tsconfigRootDir: PROJECT_DIR,
       filePath: resolve(PROJECT_DIR, 'file.ts'),
     };
-    const withDefaultProgramConfig: TSESTreeOptions = {
+    const withDeprecatedDefaultProgramConfig: TSESTreeOptions = {
       ...config,
       project: './tsconfig.defaultProgram.json',
-      createDefaultProgram: true,
+      DEPRECATED__createDefaultProgram: true,
     };
 
     describe('when file is in the project', () => {
@@ -818,11 +818,11 @@ describe('parseAndGenerateServices', () => {
       });
     });
 
-    describe('when file is not in the project and createDefaultProgram=true', () => {
+    describe('when file is not in the project and DEPRECATED__createDefaultProgram=true', () => {
       it('returns error because __PLACEHOLDER__ can not be resolved', () => {
         expect(
           parser
-            .parseAndGenerateServices(code, withDefaultProgramConfig)
+            .parseAndGenerateServices(code, withDeprecatedDefaultProgramConfig)
             .services.program.getSemanticDiagnostics(),
         ).toHaveProperty(
           [0, 'messageText'],
@@ -834,7 +834,7 @@ describe('parseAndGenerateServices', () => {
         expect(
           parser
             .parseAndGenerateServices(code, {
-              ...withDefaultProgramConfig,
+              ...withDeprecatedDefaultProgramConfig,
               moduleResolver: resolve(PROJECT_DIR, './moduleResolver.js'),
             })
             .services.program.getSemanticDiagnostics(),

diff --git a/packages/typescript-estree/tests/lib/semanticInfo.test.ts b/packages/typescript-estree/tests/lib/semanticInfo.test.ts
@@ -287,7 +287,7 @@ describe('semanticInfo', () => {
   it('default program produced with option', () => {
     const parseResult = parseCodeAndGenerateServices('var foo = 5;', {
       ...createOptions('<input>'),
-      createDefaultProgram: true,
+      DEPRECATED__createDefaultProgram: true,
     });
 
     expect(parseResult.services.program).toBeDefined();

diff --git a/packages/website/src/components/linter/config.ts b/packages/website/src/components/linter/config.ts
@@ -4,7 +4,7 @@ export const parseSettings: ParseSettings = {
   code: '',
   comment: true,
   comments: [],
-  createDefaultProgram: false,
+  DEPRECATED__createDefaultProgram: false,
   debugLevel: new Set(),
   errorOnUnknownASTType: false,
   extraFileExtensions: [],