chore: document and refactor 'extra' to 'parserSettings'

packages/typescript-estree/src/ast-converter.ts

@@ -4,13 +4,13 @@ import type { ASTMaps } from './convert';
 import { Converter, convertError } from './convert';
 import { convertComments } from './convert-comments';
 import { convertTokens } from './node-utils';
-import type { Extra } from './parser-options';
+import type { ParseSettings } from './parseSettings';
 import { simpleTraverse } from './simple-traverse';
 import type { TSESTree } from './ts-estree';
 
 export function astConverter(
   ast: SourceFile,
-  extra: Extra,
+  parseSettings: ParseSettings,
   shouldPreserveNodeMaps: boolean,
 ): { estree: TSESTree.Program; astMaps: ASTMaps } {
   /**
@@ -26,7 +26,7 @@ export function astConverter(
    * Recursively convert the TypeScript AST into an ESTree-compatible AST
    */
   const instance = new Converter(ast, {
-    errorOnUnknownASTType: extra.errorOnUnknownASTType || false,
+    errorOnUnknownASTType: parseSettings.errorOnUnknownASTType || false,
     shouldPreserveNodeMaps,
   });
 
@@ -35,15 +35,15 @@ export function astConverter(
   /**
    * Optionally remove range and loc if specified
    */
-  if (!extra.range || !extra.loc) {
+  if (!parseSettings.range || !parseSettings.loc) {
     simpleTraverse(estree, {
       enter: node => {
-        if (!extra.range) {
+        if (!parseSettings.range) {
           // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- TS 4.0 made this an error because the types aren't optional
           // @ts-expect-error
           delete node.range;
         }
-        if (!extra.loc) {
+        if (!parseSettings.loc) {
           // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- TS 4.0 made this an error because the types aren't optional
           // @ts-expect-error
           delete node.loc;
@@ -55,15 +55,15 @@ export function astConverter(
   /**
    * Optionally convert and include all tokens in the AST
    */
-  if (extra.tokens) {
+  if (parseSettings.tokens) {
     estree.tokens = convertTokens(ast);
   }
 
   /**
    * Optionally convert and include all comments in the AST
    */
-  if (extra.comment) {
-    estree.comments = convertComments(ast, extra.code);
+  if (parseSettings.comment) {
+    estree.comments = convertComments(ast, parseSettings.code);
   }
 
   const astMaps = instance.getASTMaps();

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

@@ -2,8 +2,8 @@ import debug from 'debug';
 import path from 'path';
 import * as ts from 'typescript';
 
-import type { Extra } from '../parser-options';
-import type { ASTAndProgram, CanonicalPath } from './shared';
+import type { ParseSettings } from '../parseSettings';
+import type { ASTAndProgram } from './shared';
 import {
   createDefaultCompilerOptionsFromExtra,
   getModuleResolver,
@@ -12,27 +12,26 @@ import {
 const log = debug('typescript-eslint:typescript-estree:createDefaultProgram');
 
 /**
- * @param code The code of the file being linted
- * @param extra The config object
- * @param extra.tsconfigRootDir The root directory for relative tsconfig paths
- * @param extra.projects Provided tsconfig paths
+ * @param parseSettings Internal settings for parsing the file
  * @returns If found, returns the source file corresponding to the code and the containing program
  */
 function createDefaultProgram(
-  code: string,
-  extra: Extra,
+  parseSettings: ParseSettings,
 ): ASTAndProgram | undefined {
-  log('Getting default program for: %s', extra.filePath || 'unnamed file');
+  log(
+    'Getting default program for: %s',
+    parseSettings.filePath || 'unnamed file',
+  );
 
-  if (!extra.projects || extra.projects.length !== 1) {
+  if (parseSettings.projects?.length !== 1) {
     return undefined;
   }
 
-  const tsconfigPath: CanonicalPath = extra.projects[0];
+  const tsconfigPath = parseSettings.projects[0];
 
   const commandLine = ts.getParsedCommandLineOfConfigFile(
     tsconfigPath,
-    createDefaultCompilerOptionsFromExtra(extra),
+    createDefaultCompilerOptionsFromExtra(parseSettings),
     { ...ts.sys, onUnRecoverableConfigFileDiagnostic: () => {} },
   );
 
@@ -45,24 +44,24 @@ function createDefaultProgram(
     /* setParentNodes */ true,
   );
 
-  if (extra.moduleResolver) {
+  if (parseSettings.moduleResolver) {
     compilerHost.resolveModuleNames = getModuleResolver(
-      extra.moduleResolver,
+      parseSettings.moduleResolver,
     ).resolveModuleNames;
   }
 
   const oldReadFile = compilerHost.readFile;
   compilerHost.readFile = (fileName: string): string | undefined =>
-    path.normalize(fileName) === path.normalize(extra.filePath)
-      ? code
+    path.normalize(fileName) === path.normalize(parseSettings.filePath)
+      ? parseSettings.code
       : oldReadFile(fileName);
 
   const program = ts.createProgram(
-    [extra.filePath],
+    [parseSettings.filePath],
     commandLine.options,
     compilerHost,
   );
-  const ast = program.getSourceFile(extra.filePath);
+  const ast = program.getSourceFile(parseSettings.filePath);
 
   return ast && { ast, program };
 }

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

@@ -1,7 +1,7 @@
 import debug from 'debug';
 import * as ts from 'typescript';
 
-import type { Extra } from '../parser-options';
+import type { ParseSettings } from '../parseSettings';
 import { getScriptKind } from './getScriptKind';
 import type { ASTAndProgram } from './shared';
 import { createDefaultCompilerOptionsFromExtra } from './shared';
@@ -12,19 +12,19 @@ const log = debug('typescript-eslint:typescript-estree:createIsolatedProgram');
  * @param code The code of the file being linted
  * @returns Returns a new source file and program corresponding to the linted code
  */
-function createIsolatedProgram(code: string, extra: Extra): ASTAndProgram {
+function createIsolatedProgram(parseSettings: ParseSettings): ASTAndProgram {
   log(
     'Getting isolated program in %s mode for: %s',
-    extra.jsx ? 'TSX' : 'TS',
-    extra.filePath,
+    parseSettings.jsx ? 'TSX' : 'TS',
+    parseSettings.filePath,
   );
 
   const compilerHost: ts.CompilerHost = {
     fileExists() {
       return true;
     },
     getCanonicalFileName() {
-      return extra.filePath;
+      return parseSettings.filePath;
     },
     getCurrentDirectory() {
       return '';
@@ -43,10 +43,10 @@ function createIsolatedProgram(code: string, extra: Extra): ASTAndProgram {
     getSourceFile(filename: string) {
       return ts.createSourceFile(
         filename,
-        code,
+        parseSettings.code,
         ts.ScriptTarget.Latest,
         /* setParentNodes */ true,
-        getScriptKind(extra.filePath, extra.jsx),
+        getScriptKind(parseSettings.filePath, parseSettings.jsx),
       );
     },
     readFile() {
@@ -61,17 +61,17 @@ function createIsolatedProgram(code: string, extra: Extra): ASTAndProgram {
   };
 
   const program = ts.createProgram(
-    [extra.filePath],
+    [parseSettings.filePath],
     {
       noResolve: true,
       target: ts.ScriptTarget.Latest,
-      jsx: extra.jsx ? ts.JsxEmit.Preserve : undefined,
-      ...createDefaultCompilerOptionsFromExtra(extra),
+      jsx: parseSettings.jsx ? ts.JsxEmit.Preserve : undefined,
+      ...createDefaultCompilerOptionsFromExtra(parseSettings),
     },
     compilerHost,
   );
 
-  const ast = program.getSourceFile(extra.filePath);
+  const ast = program.getSourceFile(parseSettings.filePath);
   if (!ast) {
     throw new Error(
       'Expected an ast to be returned for the single-file isolated program.',

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

@@ -3,7 +3,7 @@ import path from 'path';
 import * as ts from 'typescript';
 
 import { firstDefined } from '../node-utils';
-import type { Extra } from '../parser-options';
+import type { ParseSettings } from '../parseSettings';
 import { getProgramsForProjects } from './createWatchProgram';
 import type { ASTAndProgram } from './shared';
 import { getAstFromProgram } from './shared';
@@ -22,35 +22,33 @@ const DEFAULT_EXTRA_FILE_EXTENSIONS = [
 ] as readonly string[];
 
 /**
- * @param code The code of the file being linted
- * @param createDefaultProgram True if the default program should be created
- * @param extra The config object
- * @returns If found, returns the source file corresponding to the code and the containing program
+ * @param parseSettings.code Code of the file being parsed
+ * @param parseSettings.createDefaultProgram Whether the default program should be created
+ * @param parseSettings Internal settings for parsing the file
+ * @returns If found, the source file corresponding to the code and the containing program
  */
 function createProjectProgram(
-  code: string,
-  createDefaultProgram: boolean,
-  extra: Extra,
+  parseSettings: ParseSettings,
 ): ASTAndProgram | undefined {
-  log('Creating project program for: %s', extra.filePath);
+  log('Creating project program for: %s', parseSettings.filePath);
 
   const astAndProgram = firstDefined(
-    getProgramsForProjects(code, extra.filePath, extra),
-    currentProgram => getAstFromProgram(currentProgram, extra),
+    getProgramsForProjects(parseSettings),
+    currentProgram => getAstFromProgram(currentProgram, parseSettings),
   );
 
-  if (!astAndProgram && !createDefaultProgram) {
+  if (!astAndProgram && !parseSettings.createDefaultProgram) {
     // the file was either not matched within the tsconfig, or the extension wasn't expected
     const errorLines = [
       '"parserOptions.project" has been set for @typescript-eslint/parser.',
       `The file does not match your project config: ${path.relative(
-        extra.tsconfigRootDir || process.cwd(),
-        extra.filePath,
+        parseSettings.tsconfigRootDir || process.cwd(),
+        parseSettings.filePath,
       )}.`,
     ];
     let hasMatchedAnError = false;
 
-    const extraFileExtensions = extra.extraFileExtensions || [];
+    const extraFileExtensions = parseSettings.extraFileExtensions || [];
 
     extraFileExtensions.forEach(extraExtension => {
       if (!extraExtension.startsWith('.')) {
@@ -65,7 +63,7 @@ function createProjectProgram(
       }
     });
 
-    const fileExtension = path.extname(extra.filePath);
+    const fileExtension = path.extname(parseSettings.filePath);
     if (!DEFAULT_EXTRA_FILE_EXTENSIONS.includes(fileExtension)) {
       const nonStandardExt = `The extension for the file (${fileExtension}) is non-standard`;
       if (extraFileExtensions.length > 0) {

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

@@ -1,24 +1,27 @@
 import debug from 'debug';
 import * as ts from 'typescript';
 
-import type { Extra } from '../parser-options';
+import type { ParseSettings } from '../parseSettings';
 import { getScriptKind } from './getScriptKind';
 
 const log = debug('typescript-eslint:typescript-estree:createSourceFile');
 
-function createSourceFile(code: string, extra: Extra): ts.SourceFile {
+function createSourceFile(
+  code: string,
+  parseSettings: ParseSettings,
+): ts.SourceFile {
   log(
     'Getting AST without type information in %s mode for: %s',
-    extra.jsx ? 'TSX' : 'TS',
-    extra.filePath,
+    parseSettings.jsx ? 'TSX' : 'TS',
+    parseSettings.filePath,
   );
 
   return ts.createSourceFile(
-    extra.filePath,
+    parseSettings.filePath,
     code,
     ts.ScriptTarget.Latest,
     /* setParentNodes */ true,
-    getScriptKind(extra.filePath, extra.jsx),
+    getScriptKind(parseSettings.filePath, parseSettings.jsx),
   );
 }