typescript-eslint · bradzacher · Jun 23, 2024 · Jun 2, 2024 · Jun 2, 2024 · Jun 2, 2024
diff --git a/packages/ast-spec/src/base/FunctionBase.ts b/packages/ast-spec/src/base/FunctionBase.ts
@@ -19,7 +19,7 @@ export interface FunctionBase extends BaseNode {
   /**
    * The body of the function.
    * - For an `ArrowFunctionExpression` this may be an `Expression` or `BlockStatement`.
-   * - For a `FunctionDeclaration` or `FunctionExpression` this is always a `BlockStatement.
+   * - For a `FunctionDeclaration` or `FunctionExpression` this is always a `BlockStatement`.
    * - For a `TSDeclareFunction` this is always `undefined`.
    * - For a `TSEmptyBodyFunctionExpression` this is always `null`.
    */

diff --git a/packages/ast-spec/src/declaration/ClassDeclaration/spec.ts b/packages/ast-spec/src/declaration/ClassDeclaration/spec.ts
@@ -6,10 +6,22 @@ interface ClassDeclarationBase extends ClassBase {
   type: AST_NODE_TYPES.ClassDeclaration;
 }
 
+/**
+ * A normal class declaration:
+ * ```
+ * class A {}
+ * ```
+ */
 export interface ClassDeclarationWithName extends ClassDeclarationBase {
   id: Identifier;
 }
 
+/**
+ * Default-exported class declarations have optional names:
+ * ```
+ * export default class {}
+ * ```
+ */
 export interface ClassDeclarationWithOptionalName extends ClassDeclarationBase {
   id: Identifier | null;
 }

diff --git a/packages/ast-spec/src/declaration/ExportAllDeclaration/spec.ts b/packages/ast-spec/src/declaration/ExportAllDeclaration/spec.ts
@@ -12,24 +12,23 @@ export interface ExportAllDeclaration extends BaseNode {
    * ```
    * export * from 'mod' assert { type: 'json' };
    * ```
-   * @deprecated -- Replaced with {@link `attributes`}.
+   * @deprecated Replaced with {@link `attributes`}.
    */
   assertions: ImportAttribute[];
   /**
    * The attributes declared for the export.
    * ```
-   * export * from 'mod' assert { type: 'json' };
+   * export * from 'mod' with { type: 'json' };
    * ```
    */
   attributes: ImportAttribute[];
   /**
-   * The name for the exported items. `null` if no name is assigned.
+   * The name for the exported items (`as X`). `null` if no name is assigned.
    */
   exported: Identifier | null;
   /**
    * The kind of the export.
    */
-  // TODO(#1852) - breaking change remove this because it is a semantic error to have it
   exportKind: ExportKind;
   /**
    * The source module being exported from.

diff --git a/packages/ast-spec/src/declaration/ExportDefaultDeclaration/spec.ts b/packages/ast-spec/src/declaration/ExportDefaultDeclaration/spec.ts
@@ -1,7 +1,6 @@
 import type { AST_NODE_TYPES } from '../../ast-node-types';
 import type { BaseNode } from '../../base/BaseNode';
 import type { DefaultExportDeclarations } from '../../unions/ExportDeclaration';
-import type { ExportKind } from '../ExportAndImportKind';
 
 export interface ExportDefaultDeclaration extends BaseNode {
   type: AST_NODE_TYPES.ExportDefaultDeclaration;
@@ -10,7 +9,7 @@ export interface ExportDefaultDeclaration extends BaseNode {
    */
   declaration: DefaultExportDeclarations;
   /**
-   * The kind of the export.
+   * The kind of the export. Always `value` for default exports.
    */
-  exportKind: ExportKind;
+  exportKind: 'value';
 }
diff --git a/packages/ast-spec/src/declaration/ExportNamedDeclaration/spec.ts b/packages/ast-spec/src/declaration/ExportNamedDeclaration/spec.ts
@@ -20,7 +20,7 @@ interface ExportNamedDeclarationBase extends BaseNode {
   /**
    * The attributes declared for the export.
    * ```
-   * export { foo } from 'mod' assert { type: 'json' };
+   * export { foo } from 'mod' with { type: 'json' };
    * ```
    * This will be an empty array if `source` is `null`
    */
@@ -51,6 +51,13 @@ interface ExportNamedDeclarationBase extends BaseNode {
   specifiers: ExportSpecifier[];
 }
 
+/**
+ * Exporting names from the current module.
+ * ```
+ * export {};
+ * export { a, b };
+ * ```
+ */
 export interface ExportNamedDeclarationWithoutSourceWithMultiple
   extends ExportNamedDeclarationBase {
   /**
@@ -64,9 +71,14 @@ export interface ExportNamedDeclarationWithoutSourceWithMultiple
   attributes: ImportAttribute[];
   declaration: null;
   source: null;
-  specifiers: ExportSpecifier[];
 }
 
+/**
+ * Exporting a single named declaration.
+ * ```
+ * export const x = 1;
+ * ```
+ */
 export interface ExportNamedDeclarationWithoutSourceWithSingle
   extends ExportNamedDeclarationBase {
   /**
@@ -80,24 +92,22 @@ export interface ExportNamedDeclarationWithoutSourceWithSingle
   attributes: ImportAttribute[];
   declaration: NamedExportDeclarations;
   source: null;
-  // This will always be an empty array.
+  /**
+   * This will always be an empty array.
+   */
   specifiers: ExportSpecifier[];
 }
 
+/**
+ * Export names from another module.
+ * ```
+ * export { a, b } from 'mod';
+ * ```
+ */
 export interface ExportNamedDeclarationWithSource
   extends ExportNamedDeclarationBase {
-  /**
-   * This will always be an empty array.
-   * @deprecated Replaced with {@link `attributes`}.
-   */
-  assertions: ImportAttribute[];
-  /**
-   * This will always be an empty array.
-   */
-  attributes: ImportAttribute[];
   declaration: null;
   source: StringLiteral;
-  specifiers: ExportSpecifier[];
 }
 
 export type ExportNamedDeclaration =

diff --git a/packages/ast-spec/src/declaration/FunctionDeclaration/spec.ts b/packages/ast-spec/src/declaration/FunctionDeclaration/spec.ts
@@ -10,10 +10,22 @@ interface FunctionDeclarationBase extends FunctionBase {
   expression: false;
 }
 
+/**
+ * A normal function declaration:
+ * ```
+ * function f() {}
+ * ```
+ */
 export interface FunctionDeclarationWithName extends FunctionDeclarationBase {
   id: Identifier;
 }
 
+/**
+ * Default-exported function declarations have optional names:
+ * ```
+ * export default function () {}
+ * ```
+ */
 export interface FunctionDeclarationWithOptionalName
   extends FunctionDeclarationBase {
   id: Identifier | null;

diff --git a/packages/ast-spec/src/declaration/ImportDeclaration/spec.ts b/packages/ast-spec/src/declaration/ImportDeclaration/spec.ts
@@ -12,7 +12,7 @@ export interface ImportDeclaration extends BaseNode {
    * ```
    * import * from 'mod' assert { type: 'json' };
    * ```
-   * @deprecated -- Replaced with {@link `attributes`}.
+   * @deprecated Replaced with {@link `attributes`}.
    */
   assertions: ImportAttribute[];
   /**

diff --git a/packages/ast-spec/src/declaration/TSImportEqualsDeclaration/spec.ts b/packages/ast-spec/src/declaration/TSImportEqualsDeclaration/spec.ts
@@ -2,13 +2,13 @@ import type { AST_NODE_TYPES } from '../../ast-node-types';
 import type { BaseNode } from '../../base/BaseNode';
 import type { Identifier } from '../../expression/Identifier/spec';
 import type { TSExternalModuleReference } from '../../special/TSExternalModuleReference/spec';
-import type { EntityName } from '../../unions/EntityName';
+import type { TSQualifiedName } from '../../type/TSQualifiedName/spec';
 import type { ImportKind } from '../ExportAndImportKind';
 
-export interface TSImportEqualsDeclaration extends BaseNode {
+interface TSImportEqualsDeclarationBase extends BaseNode {
   type: AST_NODE_TYPES.TSImportEqualsDeclaration;
   /**
-   * The locally imported name
+   * The locally imported name.
    */
   id: Identifier;
   /**
@@ -19,7 +19,45 @@ export interface TSImportEqualsDeclaration extends BaseNode {
    * import F3 = require('mod');
    * ```
    */
-  moduleReference: EntityName | TSExternalModuleReference;
-  // TODO(#1852) - breaking change remove this as it is invalid
+  moduleReference: Identifier | TSExternalModuleReference | TSQualifiedName;
+  /**
+   * The kind of the import. Always `'value'` unless `moduleReference` is a
+   * `TSExternalModuleReference`.
+   */
   importKind: ImportKind;
 }
+
+export interface TSImportEqualsNamespaceDeclaration
+  extends TSImportEqualsDeclarationBase {
+  /**
+   * The value being aliased.
+   * ```
+   * import F1 = A;
+   * import F2 = A.B.C;
+   * ```
+   */
+  moduleReference: Identifier | TSQualifiedName;
+  /**
+   * The kind of the import.
+   */
+  importKind: 'value';
+}
+
+export interface TSImportEqualsRequireDeclaration
+  extends TSImportEqualsDeclarationBase {
+  /**
+   * The value being aliased.
+   * ```
+   * import F3 = require('mod');
+   * ```
+   */
+  moduleReference: TSExternalModuleReference;
+  /**
+   * The kind of the import.
+   */
+  importKind: ImportKind;
+}
+
+export type TSImportEqualsDeclaration =
+  | TSImportEqualsNamespaceDeclaration
+  | TSImportEqualsRequireDeclaration;
diff --git a/packages/ast-spec/src/declaration/TSInterfaceDeclaration/spec.ts b/packages/ast-spec/src/declaration/TSInterfaceDeclaration/spec.ts
@@ -12,7 +12,7 @@ export interface TSInterfaceDeclaration extends BaseNode {
    */
   body: TSInterfaceBody;
   /**
-   * Whether the interface was `declare`d, `undefined` otherwise
+   * Whether the interface was `declare`d
    */
   declare: boolean;
   /**
@@ -24,7 +24,8 @@ export interface TSInterfaceDeclaration extends BaseNode {
    */
   id: Identifier;
   /**
-   * The generic type parameters declared for the interface.
+   * The generic type parameters declared for the interface. Empty declaration
+   * (`<>`) is different from no declaration.
    */
   typeParameters: TSTypeParameterDeclaration | undefined;
 }
diff --git a/packages/ast-spec/src/declaration/TSModuleDeclaration/spec.ts b/packages/ast-spec/src/declaration/TSModuleDeclaration/spec.ts
@@ -22,14 +22,12 @@ interface TSModuleDeclarationBase extends BaseNode {
   /**
    * The body of the module.
    * This can only be `undefined` for the code `declare module 'mod';`
-   * This will be a `TSModuleDeclaration` if the name is "nested" (`Foo.Bar`).
    */
   body?: TSModuleBlock;
   /**
    * Whether this is a global declaration
-   * ```
-   * declare global {}
-   * ```
+   *
+   * @deprecated Use {@link kind} instead
    */
   // TODO - remove this in the next major (we have `.kind` now)
   global: boolean;
@@ -50,64 +48,81 @@ interface TSModuleDeclarationBase extends BaseNode {
    * module 'foo' {}
    * ^^^^^^
    *
-   * declare global {}
-   *         ^^^^^^
+   * global {}
+   * ^^^^^^
    * ```
    */
   kind: TSModuleDeclarationKind;
 }
 
 export interface TSModuleDeclarationNamespace extends TSModuleDeclarationBase {
   kind: 'namespace';
-  // namespaces cannot have literal IDs
   id: Identifier | TSQualifiedName;
-  // namespaces must always have a body
   body: TSModuleBlock;
 }
 
 export interface TSModuleDeclarationGlobal extends TSModuleDeclarationBase {
   kind: 'global';
-  // cannot have a nested namespace for global module augmentation
-  // cannot have `declare global;`
-  body: TSModuleBlock;
-  // this will always be an Identifier with name `global`
+  /**
+   * This will always be an Identifier with name `global`
+   */
   id: Identifier;
+  body: TSModuleBlock;
 }
 
 interface TSModuleDeclarationModuleBase extends TSModuleDeclarationBase {
   kind: 'module';
 }
 
-export type TSModuleDeclarationModule =
-  | TSModuleDeclarationModuleWithIdentifierId
-  | TSModuleDeclarationModuleWithStringId;
-export type TSModuleDeclarationModuleWithStringId =
-  | TSModuleDeclarationModuleWithStringIdDeclared
-  | TSModuleDeclarationModuleWithStringIdNotDeclared;
+/**
+ * A string module declaration that is not declared:
+ * ```
+ * module 'foo' {}
+ * ```
+ */
 export interface TSModuleDeclarationModuleWithStringIdNotDeclared
   extends TSModuleDeclarationModuleBase {
   kind: 'module';
   id: StringLiteral;
   declare: false;
-  // cannot have nested namespaces with a string ID, must have a body
   body: TSModuleBlock;
 }
+/**
+ * A string module declaration that is declared:
+ * ```
+ * declare module 'foo' {}
+ * declare module 'foo';
+ * ```
+ */
 export interface TSModuleDeclarationModuleWithStringIdDeclared
   extends TSModuleDeclarationModuleBase {
   kind: 'module';
   id: StringLiteral;
   declare: true;
-  // cannot have nested namespaces with a string ID, might not have a body
   body?: TSModuleBlock;
 }
+/**
+ * The legacy module declaration, replaced with namespace declarations.
+ * ```
+ * module A {}
+ * ```
+ */
 export interface TSModuleDeclarationModuleWithIdentifierId
   extends TSModuleDeclarationModuleBase {
   kind: 'module';
   id: Identifier;
-  // modules with an Identifier must always have a body
+  // TODO: we emit the wrong AST for `module A.B {}`
+  // https://github.com/typescript-eslint/typescript-eslint/pull/6272 only fixed namespaces
+  // Maybe not worth fixing since it's legacy
   body: TSModuleBlock;
 }
 
+export type TSModuleDeclarationModuleWithStringId =
+  | TSModuleDeclarationModuleWithStringIdDeclared
+  | TSModuleDeclarationModuleWithStringIdNotDeclared;
+export type TSModuleDeclarationModule =
+  | TSModuleDeclarationModuleWithIdentifierId
+  | TSModuleDeclarationModuleWithStringId;
 export type TSModuleDeclaration =
   | TSModuleDeclarationGlobal
   | TSModuleDeclarationModule