feat: allow user to provide TS program instance in parser options

packages/parser/README.md

@@ -64,6 +64,8 @@ interface ParserOptions {
   tsconfigRootDir?: string;
   extraFileExtensions?: string[];
   warnOnUnsupportedTypeScriptVersion?: boolean;
+
+  program?: import('typescript').Program;
 }
 ```
 
@@ -211,6 +213,14 @@ 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.program`
+
+Default `undefined`.
+
+This option allows you to programmatically provide an instance of a TypeScript Program object that will provide type information to rules.
+This will override any program that would have been computed from `parserOptions.project` or `parserOptions.createDefaultProgram`.
+All linted files must be part of the provided program.
+
 ## Supported TypeScript Version
 
 Please see [`typescript-eslint`](https://github.com/typescript-eslint/typescript-eslint) for the supported TypeScript version.

packages/parser/tests/lib/services.ts

@@ -4,6 +4,7 @@ import glob from 'glob';
 import { ParserOptions } from '../../src/parser';
 import {
   createSnapshotTestBlock,
+  createTSProgram,
   formatSnapshotName,
   testServices,
 } from '../tools/test-utils';
@@ -30,15 +31,17 @@ function createConfig(filename: string): ParserOptions {
 //------------------------------------------------------------------------------
 
 describe('services', () => {
+  const program = createTSProgram(path.resolve(FIXTURES_DIR, 'tsconfig.json'));
   testFiles.forEach(filename => {
     const code = fs.readFileSync(path.join(FIXTURES_DIR, filename), 'utf8');
     const config = createConfig(filename);
-    it(
-      formatSnapshotName(filename, FIXTURES_DIR, '.ts'),
-      createSnapshotTestBlock(code, config),
-    );
-    it(`${formatSnapshotName(filename, FIXTURES_DIR, '.ts')} services`, () => {
+    const snapshotName = formatSnapshotName(filename, FIXTURES_DIR, '.ts');
+    it(snapshotName, createSnapshotTestBlock(code, config));
+    it(`${snapshotName} services`, () => {
       testServices(code, config);
     });
+    it(`${snapshotName} services with provided program`, () => {
+      testServices(code, { ...config, program });
+    });
   });
 });

packages/parser/tests/tools/test-utils.ts

@@ -1,4 +1,7 @@
 import { TSESTree } from '@typescript-eslint/typescript-estree';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as ts from 'typescript';
 import * as parser from '../../src/parser';
 import { ParserOptions } from '../../src/parser';
 
@@ -89,3 +92,26 @@ export function formatSnapshotName(
     .replace(fixturesDir + '/', '')
     .replace(fileExtension, '')}`;
 }
+
+export function createTSProgram(configFile: string): ts.Program {
+  const projectDirectory = path.dirname(configFile);
+  const config = ts.readConfigFile(configFile, ts.sys.readFile);
+  expect(config.error).toBeUndefined();
+  const parseConfigHost: ts.ParseConfigHost = {
+    fileExists: fs.existsSync,
+    readDirectory: ts.sys.readDirectory,
+    readFile: file => fs.readFileSync(file, 'utf8'),
+    useCaseSensitiveFileNames: true,
+  };
+  const parsed = ts.parseJsonConfigFileContent(
+    config.config,
+    parseConfigHost,
+    path.resolve(projectDirectory),
+    { noEmit: true },
+  );
+  expect(parsed.errors).toHaveLength(0);
+  const host = ts.createCompilerHost(parsed.options, true);
+  const program = ts.createProgram(parsed.fileNames, parsed.options, host);
+
+  return program;
+}

packages/types/package.json

@@ -48,5 +48,8 @@
         "_ts3.4/*"
       ]
     }
+  },
+  "devDependencies": {
+    "typescript": ">=2.6.0"
   }
 }

packages/types/src/parser-options.ts

@@ -1,4 +1,5 @@
 import { Lib } from './lib';
+import { Program } from 'typescript';
 
 type DebugLevel = boolean | ('typescript-eslint' | 'eslint' | 'typescript')[];
 
@@ -41,6 +42,7 @@ interface ParserOptions {
   extraFileExtensions?: string[];
   filePath?: string;
   loc?: boolean;
+  program?: Program;
   project?: string | string[];
   projectFolderIgnoreList?: (string | RegExp)[];
   range?: boolean;

packages/typescript-estree/README.md

@@ -208,6 +208,13 @@ interface ParseAndGenerateServicesOptions extends ParseOptions {
    */
   tsconfigRootDir?: string;
 
+  /**
+   * Instance of a TypeScript Program object to be used for type information.
+   * This overrides any program or programs that would have been computed from the `project` option.
+   * All linted files must be part of the provided program.
+   */
+  program?: import('typescript').Program;
+
   /**
    ***************************************************************************************
    * IT IS RECOMMENDED THAT YOU DO NOT USE THIS OPTION, AS IT CAUSES PERFORMANCE ISSUES. *

packages/typescript-estree/package.json

@@ -64,6 +64,9 @@
     "jest-specific-snapshot": "*",
     "make-dir": "*",
     "tmp": "^0.2.1",
+    "typescript": "^4.3.2"
+  },
+  "peerDependencies": {
     "typescript": "*"
   },
   "peerDependenciesMeta": {

packages/typescript-estree/src/create-program/createProjectProgram.ts

@@ -3,19 +3,12 @@ import path from 'path';
 import { getProgramsForProjects } from './createWatchProgram';
 import { firstDefined } from '../node-utils';
 import { Extra } from '../parser-options';
-import { ASTAndProgram } from './shared';
+import { ASTAndProgram, getAstFromProgram } from './shared';
 
 const log = debug('typescript-eslint:typescript-estree:createProjectProgram');
 
 const DEFAULT_EXTRA_FILE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
 
-function getExtension(fileName: string | undefined): string | null {
-  if (!fileName) {
-    return null;
-  }
-  return fileName.endsWith('.d.ts') ? '.d.ts' : path.extname(fileName);
-}
-
 /**
  * @param code The code of the file being linted
  * @param createDefaultProgram True if the default program should be created
@@ -31,18 +24,7 @@ function createProjectProgram(
 
   const astAndProgram = firstDefined(
     getProgramsForProjects(code, extra.filePath, extra),
-    currentProgram => {
-      const ast = currentProgram.getSourceFile(extra.filePath);
-
-      // working around https://github.com/typescript-eslint/typescript-eslint/issues/1573
-      const expectedExt = getExtension(extra.filePath);
-      const returnedExt = getExtension(ast?.fileName);
-      if (expectedExt !== returnedExt) {
-        return;
-      }
-
-      return ast && { ast, program: currentProgram };
-    },
+    currentProgram => getAstFromProgram(currentProgram, extra),
   );
 
   if (!astAndProgram && !createDefaultProgram) {

packages/typescript-estree/src/create-program/shared.ts

@@ -1,5 +1,6 @@
 import path from 'path';
 import * as ts from 'typescript';
+import { Program } from 'typescript';
 import { Extra } from '../parser-options';
 
 interface ASTAndProgram {
@@ -93,6 +94,29 @@ function getScriptKind(
   }
 }
 
+function getExtension(fileName: string | undefined): string | null {
+  if (!fileName) {
+    return null;
+  }
+  return fileName.endsWith('.d.ts') ? '.d.ts' : path.extname(fileName);
+}
+
+function getAstFromProgram(
+  currentProgram: Program,
+  extra: Extra,
+): ASTAndProgram | undefined {
+  const ast = currentProgram.getSourceFile(extra.filePath);
+
+  // working around https://github.com/typescript-eslint/typescript-eslint/issues/1573
+  const expectedExt = getExtension(extra.filePath);
+  const returnedExt = getExtension(ast?.fileName);
+  if (expectedExt !== returnedExt) {
+    return undefined;
+  }
+
+  return ast && { ast, program: currentProgram };
+}
+
 export {
   ASTAndProgram,
   canonicalDirname,
@@ -101,4 +125,5 @@ export {
   ensureAbsolutePath,
   getCanonicalFileName,
   getScriptKind,
+  getAstFromProgram,
 };

packages/typescript-estree/src/create-program/useProvidedProgram.ts

@@ -0,0 +1,28 @@
+import debug from 'debug';
+import { Program } from 'typescript';
+import { Extra } from '../parser-options';
+import { ASTAndProgram, getAstFromProgram } from './shared';
+
+const log = debug('typescript-eslint:typescript-estree:useProvidedProgram');
+
+function useProvidedProgram(
+  programInstance: Program,
+  extra: Extra,
+): ASTAndProgram | undefined {
+  log('Retrieving ast for %s from provided program instance', extra.filePath);
+
+  const astAndProgram = getAstFromProgram(programInstance, extra);
+
+  if (!astAndProgram) {
+    const errorLines = [
+      '"parserOptions.program" has been provided for @typescript-eslint/parser.',
+      `The file was not found in the provided program instance: ${extra.filePath}`,
+    ];
+
+    throw new Error(errorLines.join('\n'));
+  }
+
+  return astAndProgram;
+}
+
+export { useProvidedProgram };

packages/typescript-estree/src/parser-options.ts

@@ -20,6 +20,7 @@ export interface Extra {
   loc: boolean;
   log: (message: string) => void;
   preserveNodeMaps?: boolean;
+  program: null | Program;
   projects: CanonicalPath[];
   range: boolean;
   strict: boolean;
@@ -169,6 +170,13 @@ interface ParseAndGenerateServicesOptions extends ParseOptions {
    */
   tsconfigRootDir?: string;
 
+  /**
+   * Instance of a TypeScript Program object to be used for type information.
+   * This overrides any program or programs that would have been computed from the `project` option.
+   * All linted files must be part of the provided program.
+   */
+  program?: Program;
+
   /**
    ***************************************************************************************
    * IT IS RECOMMENDED THAT YOU DO NOT USE THIS OPTION, AS IT CAUSES PERFORMANCE ISSUES. *

packages/typescript-estree/src/parser.ts

@@ -18,6 +18,8 @@ import {
   ensureAbsolutePath,
   getCanonicalFileName,
 } from './create-program/shared';
+import { Program } from 'typescript';
+import { useProvidedProgram } from './create-program/useProvidedProgram';
 
 const log = debug('typescript-eslint:typescript-estree:parser');
 
@@ -61,10 +63,12 @@ function enforceString(code: unknown): string {
  */
 function getProgramAndAST(
   code: string,
+  programInstance: Program | null,
   shouldProvideParserServices: boolean,
   shouldCreateDefaultProgram: boolean,
 ): ASTAndProgram {
   return (
+    (programInstance && useProvidedProgram(programInstance, extra)) ||
     (shouldProvideParserServices &&
       createProjectProgram(code, shouldCreateDefaultProgram, extra)) ||
     (shouldProvideParserServices &&
@@ -105,6 +109,7 @@ function resetExtra(): void {
     loc: false,
     log: console.log, // eslint-disable-line no-console
     preserveNodeMaps: true,
+    program: null,
     projects: [],
     range: false,
     strict: false,
@@ -264,22 +269,32 @@ function applyParserOptionsToExtra(options: TSESTreeOptions): void {
   // NOTE - ensureAbsolutePath relies upon having the correct tsconfigRootDir in extra
   extra.filePath = ensureAbsolutePath(extra.filePath, extra);
 
-  const projectFolderIgnoreList = (
-    options.projectFolderIgnoreList ?? ['**/node_modules/**']
-  )
-    .reduce<string[]>((acc, folder) => {
-      if (typeof folder === 'string') {
-        acc.push(folder);
-      }
-      return acc;
-    }, [])
-    // prefix with a ! for not match glob
-    .map(folder => (folder.startsWith('!') ? folder : `!${folder}`));
-  // NOTE - prepareAndTransformProjects relies upon having the correct tsconfigRootDir in extra
-  extra.projects = prepareAndTransformProjects(
-    options.project,
-    projectFolderIgnoreList,
-  );
+  if (typeof options.program === 'object') {
+    extra.program = options.program;
+    log(
+      'parserOptions.program was provided, so parserOptions.project will be ignored.',
+    );
+  }
+
+  if (extra.program === null) {
+    // providing a program overrides project resolution
+    const projectFolderIgnoreList = (
+      options.projectFolderIgnoreList ?? ['**/node_modules/**']
+    )
+      .reduce<string[]>((acc, folder) => {
+        if (typeof folder === 'string') {
+          acc.push(folder);
+        }
+        return acc;
+      }, [])
+      // prefix with a ! for not match glob
+      .map(folder => (folder.startsWith('!') ? folder : `!${folder}`));
+    // NOTE - prepareAndTransformProjects relies upon having the correct tsconfigRootDir in extra
+    extra.projects = prepareAndTransformProjects(
+      options.project,
+      projectFolderIgnoreList,
+    );
+  }
 
   if (
     Array.isArray(options.extraFileExtensions) &&
@@ -453,6 +468,7 @@ function parseAndGenerateServices<T extends TSESTreeOptions = TSESTreeOptions>(
     extra.projects && extra.projects.length > 0;
   const { ast, program } = getProgramAndAST(
     code,
+    extra.program,
     shouldProvideParserServices,
     extra.createDefaultProgram,
   )!;