feat(typescript-estree): added allowInvalidAST option to not throw on invalid tokens

docs/architecture/TypeScript-ESTree.mdx

@@ -48,6 +48,16 @@ interface ParseOptions {
    */
   debugLevel?: boolean | ('typescript-eslint' | 'eslint' | 'typescript')[];
 
+  /**
+   * Causes the parser to an error if it receives an invalid AST from TypeScript.
+   * This case only usually occurs when attempting to lint invalid code.
+   *
+   * @remarks
+   * This is because TypeScript reports some syntax issues as semantic diagnostics.
+   * See https://github.com/typescript-eslint/typescript-eslint/issues/1852.
+   */
+  errorOnInvalidAST?: boolean;
+
   /**
    * Cause the parser to error if it encounters an unknown AST node type (useful for testing).
    * This case only usually occurs when TypeScript releases new features.
@@ -99,7 +109,7 @@ interface ParseOptions {
 
 const PARSE_DEFAULT_OPTIONS: ParseOptions = {
   comment: false,
-  errorOnUnknownASTType: false,
+
   filePath: 'estree.ts', // or 'estree.tsx', if you pass jsx: true
   jsx: false,
   loc: false,

packages/parser/tests/lib/parser.ts

@@ -35,7 +35,7 @@ describe('parser', () => {
       // ts-estree specific
       filePath: 'isolated-file.src.ts',
       project: 'tsconfig.json',
-      errorOnUnknownASTType: false,
+
       errorOnTypeScriptSyntacticAndSemanticIssues: false,
       tsconfigRootDir: 'tests/fixtures/services',
       extraFileExtensions: ['.foo'],
@@ -89,7 +89,7 @@ describe('parser', () => {
       // ts-estree specific
       filePath: 'isolated-file.src.ts',
       project: 'tsconfig.json',
-      errorOnUnknownASTType: false,
+
       errorOnTypeScriptSyntacticAndSemanticIssues: false,
       tsconfigRootDir: 'tests/fixtures/services',
       extraFileExtensions: ['.foo'],

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

@@ -26,6 +26,7 @@ export function astConverter(
    * Recursively convert the TypeScript AST into an ESTree-compatible AST
    */
   const instance = new Converter(ast, {
+    errorOnInvalidAST: parseSettings.errorOnInvalidAST || false,
     errorOnUnknownASTType: parseSettings.errorOnUnknownASTType || false,
     shouldPreserveNodeMaps,
   });

packages/typescript-estree/src/convert.ts

@@ -24,6 +24,7 @@ import {
   isESTreeClassMember,
   isOptional,
   isThisInTypeQuery,
+  nodeHasIllegalDecorators,
   unescapeStringLiteralText,
 } from './node-utils';
 import type {
@@ -37,8 +38,9 @@ import { AST_NODE_TYPES } from './ts-estree';
 const SyntaxKind = ts.SyntaxKind;
 
 interface ConverterOptions {
-  errorOnUnknownASTType: boolean;
-  shouldPreserveNodeMaps: boolean;
+  errorOnInvalidAST?: boolean;
+  errorOnUnknownASTType?: boolean;
+  shouldPreserveNodeMaps?: boolean;
 }
 
 /**
@@ -76,7 +78,7 @@ export class Converter {
    * @param options additional options for the conversion
    * @returns the converted ESTreeNode
    */
-  constructor(ast: ts.SourceFile, options: ConverterOptions) {
+  constructor(ast: ts.SourceFile, options: ConverterOptions = {}) {
     this.ast = ast;
     this.options = { ...options };
   }
@@ -238,6 +240,22 @@ export class Converter {
     return this.converter(child, parent, this.inTypeMode, false);
   }
 
+  /**
+   * Converts a TypeScript child node into an ESTree node, throwing an error
+   * if the child is not defined and options.errorOnInvalidAST is true.
+   * @returns The converted ESTree node.
+   */
+  private convertChildStrict(
+    child: ts.Node | undefined,
+    parent: ts.Node,
+    message: string,
+  ): any | null {
+    if (!child && this.options.errorOnInvalidAST) {
+      throw createError(this.ast, parent.pos, message);
+    }
+    return this.converter(child, parent, this.inTypeMode, false);
+  }
+
   /**
    * Converts a TypeScript node into an ESTree node.
    * @param child the child ts.Node
@@ -983,6 +1001,8 @@ export class Converter {
       }
 
       case SyntaxKind.VariableStatement: {
+        this.#checkIllegalDecorators(node);
+
         const result = this.createNode<TSESTree.VariableDeclaration>(node, {
           type: AST_NODE_TYPES.VariableDeclaration,
           declarations: node.declarationList.declarations.map(el =>
@@ -991,6 +1011,14 @@ export class Converter {
           kind: getDeclarationKind(node.declarationList),
         });
 
+        if (this.options.errorOnInvalidAST && !result.declarations.length) {
+          throw createError(
+            this.ast,
+            node.pos,
+            'A variable declaration list must have at least one variable declarator.',
+          );
+        }
+
         /**
          * Semantically, decorators are not allowed on variable declarations,
          * Pre 4.8 TS would include them in the AST, so we did as well.
@@ -2449,6 +2477,8 @@ export class Converter {
         return this.convertChild(node.expression, parent);
 
       case SyntaxKind.TypeAliasDeclaration: {
+        this.#checkIllegalDecorators(node);
+
         const result = this.createNode<TSESTree.TSTypeAliasDeclaration>(node, {
           type: AST_NODE_TYPES.TSTypeAliasDeclaration,
           id: this.convertChild(node.name),
@@ -2605,6 +2635,8 @@ export class Converter {
       }
 
       case SyntaxKind.InterfaceDeclaration: {
+        this.#checkIllegalDecorators(node);
+
         const interfaceHeritageClauses = node.heritageClauses ?? [];
         const result = this.createNode<TSESTree.TSInterfaceDeclaration>(node, {
           type: AST_NODE_TYPES.TSInterfaceDeclaration,
@@ -2695,6 +2727,8 @@ export class Converter {
       }
 
       case SyntaxKind.EnumDeclaration: {
+        this.#checkIllegalDecorators(node);
+
         const result = this.createNode<TSESTree.TSEnumDeclaration>(node, {
           type: AST_NODE_TYPES.TSEnumDeclaration,
           id: this.convertChild(node.name),
@@ -2922,4 +2956,10 @@ export class Converter {
         return this.deeplyCopy(node);
     }
   }
+
+  #checkIllegalDecorators(node: ts.Node): void {
+    if (this.options.errorOnInvalidAST && nodeHasIllegalDecorators(node)) {
+      throw createError(this.ast, node.pos, 'Decorators are not valid here.');
+    }
+  }
 }

packages/typescript-estree/src/node-utils.ts

@@ -628,6 +628,13 @@ export function createError(
   return new TSError(message, ast.fileName, start, loc.line + 1, loc.character);
 }
 
+export function nodeHasIllegalDecorators(node: ts.Node): boolean {
+  return !!(
+    'illegalDecorators' in node &&
+    (node.illegalDecorators as unknown[] | undefined)?.length
+  );
+}
+
 /**
  * @param n the TSNode
  * @param ast the TS AST

packages/typescript-estree/src/parseSettings/createParseSettings.ts

@@ -41,6 +41,7 @@ export function createParseSettings(
         : Array.isArray(options.debugLevel)
         ? new Set(options.debugLevel)
         : new Set(),
+    errorOnInvalidAST: options.errorOnInvalidAST === true,
     errorOnTypeScriptSyntacticAndSemanticIssues: false,
     errorOnUnknownASTType: options.errorOnUnknownASTType === true,
     EXPERIMENTAL_useSourceOfProjectReferenceRedirect:

packages/typescript-estree/src/parseSettings/index.ts

@@ -41,6 +41,11 @@ export interface MutableParseSettings {
    */
   debugLevel: Set<DebugModule>;
 
+  /**
+   * Whether to throw an error when a required node child does not exist.
+   */
+  errorOnInvalidAST: boolean;
+
   /**
    * Whether to error if TypeScript reports a semantic or syntactic error diagnostic.
    */

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

@@ -25,6 +25,16 @@ interface ParseOptions {
    */
   debugLevel?: DebugLevel;
 
+  /**
+   * Causes the parser to an error if it sees that a required node child does not exist.
+   * This case only usually occurs when attempting to lint invalid code.
+   *
+   * @remarks
+   * This is because TypeScript reports some syntax issues as semantic diagnostics.
+   * See https://github.com/typescript-eslint/typescript-eslint/issues/1852.
+   */
+  errorOnInvalidAST?: boolean;
+
   /**
    * Cause the parser to error if it encounters an unknown AST node type (useful for testing).
    * This case only usually occurs when TypeScript releases new features.

packages/typescript-estree/tests/lib/convert.test.ts

@@ -26,20 +26,14 @@ describe('convert', () => {
 
     ts.forEachChild(ast, fakeUnknownKind);
 
-    const instance = new Converter(ast, {
-      errorOnUnknownASTType: false,
-      shouldPreserveNodeMaps: false,
-    });
+    const instance = new Converter(ast);
     expect(instance.convertProgram()).toMatchSnapshot();
   });
 
   it('deeplyCopy should convert node with decorators correctly', () => {
     const ast = convertCode('@test class foo {}');
 
-    const instance = new Converter(ast, {
-      errorOnUnknownASTType: false,
-      shouldPreserveNodeMaps: false,
-    });
+    const instance = new Converter(ast);
 
     expect(
       instance['deeplyCopy'](ast.statements[0] as ts.ClassDeclaration),
@@ -49,10 +43,7 @@ describe('convert', () => {
   it('deeplyCopy should convert node with type parameters correctly', () => {
     const ast = convertCode('class foo<T> {}');
 
-    const instance = new Converter(ast, {
-      errorOnUnknownASTType: false,
-      shouldPreserveNodeMaps: false,
-    });
+    const instance = new Converter(ast);
 
     expect(
       instance['deeplyCopy'](ast.statements[0] as ts.ClassDeclaration),
@@ -62,10 +53,7 @@ describe('convert', () => {
   it('deeplyCopy should convert node with type arguments correctly', () => {
     const ast = convertCode('new foo<T>()');
 
-    const instance = new Converter(ast, {
-      errorOnUnknownASTType: false,
-      shouldPreserveNodeMaps: false,
-    });
+    const instance = new Converter(ast);
 
     expect(
       instance['deeplyCopy'](
@@ -78,10 +66,7 @@ describe('convert', () => {
   it('deeplyCopy should convert array of nodes', () => {
     const ast = convertCode('new foo<T>()');
 
-    const instance = new Converter(ast, {
-      errorOnUnknownASTType: false,
-      shouldPreserveNodeMaps: false,
-    });
+    const instance = new Converter(ast);
     expect(instance['deeplyCopy'](ast)).toMatchSnapshot();
   });
 
@@ -90,7 +75,6 @@ describe('convert', () => {
 
     const instance = new Converter(ast, {
       errorOnUnknownASTType: true,
-      shouldPreserveNodeMaps: false,
     });
 
     expect(() => instance['deeplyCopy'](ast)).toThrow(
@@ -107,7 +91,6 @@ describe('convert', () => {
     `);
 
     const instance = new Converter(ast, {
-      errorOnUnknownASTType: false,
       shouldPreserveNodeMaps: true,
     });
     instance.convertProgram();
@@ -140,7 +123,6 @@ describe('convert', () => {
     const ast = convertCode(`<a.b.c.d.e></a.b.c.d.e>`);
 
     const instance = new Converter(ast, {
-      errorOnUnknownASTType: false,
       shouldPreserveNodeMaps: true,
     });
     instance.convertProgram();
@@ -172,7 +154,6 @@ describe('convert', () => {
     const ast = convertCode(`export function foo () {}`);
 
     const instance = new Converter(ast, {
-      errorOnUnknownASTType: false,
       shouldPreserveNodeMaps: true,
     });
     const program = instance.convertProgram();
@@ -203,7 +184,6 @@ describe('convert', () => {
   it('should correctly create node with range and loc set', () => {
     const ast = convertCode('');
     const instance = new Converter(ast, {
-      errorOnUnknownASTType: false,
       shouldPreserveNodeMaps: true,
     });
 
@@ -252,13 +232,62 @@ describe('convert', () => {
     for (const code of jsDocCode) {
       const ast = convertCode(code);
 
-      const instance = new Converter(ast, {
-        errorOnUnknownASTType: false,
-        shouldPreserveNodeMaps: false,
-      });
+      const instance = new Converter(ast);
       expect(() => instance.convertProgram()).toThrow(
         'JSDoc types can only be used inside documentation comments.',
       );
     }
   });
+
+  describe('errorOnInvalidAST', () => {
+    function generateTest(title: string, code: string, error: string): void {
+      it(`does not throw an error for ${title} when errorOnInvalidAST is false`, () => {
+        const ast = convertCode(code);
+
+        const instance = new Converter(ast);
+
+        expect(() => instance.convertProgram()).not.toThrow();
+      });
+
+      it(`throws an error for ${title} when errorOnInvalidAST is true`, () => {
+        const ast = convertCode(code);
+
+        const instance = new Converter(ast, {
+          errorOnInvalidAST: true,
+        });
+
+        expect(() => instance.convertProgram()).toThrow(error);
+      });
+    }
+
+    generateTest(
+      'a decorator on an enum declaration',
+      '@decl let value;',
+      'Decorators are not valid here.',
+    );
+
+    generateTest(
+      'a decorator on an interface declaration',
+      '@decl interface _ {};',
+      'Decorators are not valid here.',
+    );
+
+    generateTest(
+      'a decorator on a type alias declaration',
+      '@decl type _ = {};',
+      'Decorators are not valid here.',
+    );
+
+    generateTest(
+      'a decorator on a variable statement',
+      '@decl let value;',
+      'Decorators are not valid here.',
+    );
+
+    generateTest(
+      'a variable declaration with no variables',
+      'const;',
+      'A variable declaration list must have at least one variable declarator.',
+    );
+  });
 });

packages/website/src/components/linter/config.ts

@@ -7,7 +7,7 @@ export const parseSettings: ParseSettings = {
   comments: [],
   DEPRECATED__createDefaultProgram: false,
   debugLevel: new Set(),
-  errorOnUnknownASTType: false,
+
   extraFileExtensions: [],
   filePath: '',
   jsx: false,