Deprecate ModuleDeclaration alias (#15266)

packages/babel-traverse/src/path/generated/asserts.d.ts

@@ -258,6 +258,9 @@ export interface NodePathAssertions {
   assertImportNamespaceSpecifier(
     opts?: object,
   ): asserts this is NodePath<t.ImportNamespaceSpecifier>;
+  assertImportOrExportDeclaration(
+    opts?: object,
+  ): asserts this is NodePath<t.ImportOrExportDeclaration>;
   assertImportSpecifier(
     opts?: object,
   ): asserts this is NodePath<t.ImportSpecifier>;

packages/babel-traverse/src/path/generated/validators.d.ts

@@ -431,6 +431,10 @@ interface BaseNodePathValidators {
     this: NodePath<T>,
     opts?: object,
   ): this is NodePath<T & t.ImportNamespaceSpecifier>;
+  isImportOrExportDeclaration<T extends t.Node>(
+    this: NodePath<T>,
+    opts?: object,
+  ): this is NodePath<T & t.ImportOrExportDeclaration>;
   isImportSpecifier<T extends t.Node>(
     this: NodePath<T>,
     opts?: object,

packages/babel-traverse/src/visitors.ts

@@ -1,5 +1,10 @@
 import * as virtualTypes from "./path/lib/virtual-types";
-import { DEPRECATED_KEYS, FLIPPED_ALIAS_KEYS, TYPES } from "@babel/types";
+import {
+  DEPRECATED_KEYS,
+  DEPRECATED_ALIASES,
+  FLIPPED_ALIAS_KEYS,
+  TYPES,
+} from "@babel/types";
 import type { NodePath, Visitor } from "./index";
 
 type VIRTUAL_TYPES = keyof typeof virtualTypes;
@@ -93,20 +98,26 @@ export function explode(visitor: Visitor) {
   for (const nodeType of Object.keys(visitor) as (keyof Visitor)[]) {
     if (shouldIgnoreKey(nodeType)) continue;
 
-    const fns = visitor[nodeType];
-
     let aliases = FLIPPED_ALIAS_KEYS[nodeType];
 
-    const deprecatedKey = DEPRECATED_KEYS[nodeType];
-    if (deprecatedKey) {
+    if (nodeType in DEPRECATED_KEYS) {
+      const deprecatedKey = DEPRECATED_KEYS[nodeType];
       console.trace(
         `Visitor defined for ${nodeType} but it has been renamed to ${deprecatedKey}`,
       );
       aliases = [deprecatedKey];
+    } else if (nodeType in DEPRECATED_ALIASES) {
+      const deprecatedAlias =
+        DEPRECATED_ALIASES[nodeType as keyof typeof DEPRECATED_ALIASES];
+      console.trace(
+        `Visitor defined for ${nodeType} but it has been renamed to ${deprecatedAlias}`,
+      );
+      aliases = FLIPPED_ALIAS_KEYS[deprecatedAlias];
     }
 
     if (!aliases) continue;
 
+    const fns = visitor[nodeType];
     // clear it from the visitor
     delete visitor[nodeType];
 

packages/babel-traverse/test/traverse.js

@@ -337,4 +337,40 @@ describe("traverse", function () {
       expect(programShouldStop).toBe(false);
     });
   });
+  describe("traverse.explode", () => {
+    describe("deprecated types and aliases", () => {
+      beforeAll(() => {
+        jest.spyOn(console, "trace").mockImplementation(() => {});
+      });
+      afterAll(() => {
+        console.trace.mockClear();
+      });
+      it("should warn for deprecated node types", () => {
+        const visitNumericLiteral = () => {};
+        const visitor = {
+          NumberLiteral: visitNumericLiteral,
+        };
+        traverse.explode(visitor);
+        expect(console.trace).toHaveBeenCalledWith(
+          "Visitor defined for NumberLiteral but it has been renamed to NumericLiteral",
+        );
+        expect(visitor).toHaveProperty("NumericLiteral.enter", [
+          visitNumericLiteral,
+        ]);
+      });
+      it("should warn for deprecated aliases", () => {
+        const visitImportOrExportDeclaration = () => {};
+        const visitor = {
+          ModuleDeclaration: visitImportOrExportDeclaration,
+        };
+        traverse.explode(visitor);
+        expect(console.trace).toHaveBeenCalledWith(
+          "Visitor defined for ModuleDeclaration but it has been renamed to ImportOrExportDeclaration",
+        );
+        expect(visitor).toHaveProperty("ImportDeclaration.enter", [
+          visitImportOrExportDeclaration,
+        ]);
+      });
+    });
+  });
 });

packages/babel-types/scripts/generators/asserts.js

@@ -1,5 +1,6 @@
 import {
   DEPRECATED_KEYS,
+  DEPRECATED_ALIASES,
   FLIPPED_ALIAS_KEYS,
   NODE_FIELDS,
   VISITOR_KEYS,
@@ -39,14 +40,23 @@ function assert(type: string, node: any, opts?: any): void {
     output += addAssertHelper(type);
   });
 
-  Object.keys(FLIPPED_ALIAS_KEYS).forEach(type => {
-    output += addAssertHelper(type);
-  });
+  Object.keys(FLIPPED_ALIAS_KEYS)
+    .filter(
+      type => !Object.prototype.hasOwnProperty.call(DEPRECATED_ALIASES, type)
+    )
+    .forEach(type => {
+      output += addAssertHelper(type);
+    });
+
+  const deprecatedNodeTypesAndAliases = {
+    ...DEPRECATED_KEYS,
+    ...DEPRECATED_ALIASES,
+  };
 
-  Object.keys(DEPRECATED_KEYS).forEach(type => {
-    const newType = DEPRECATED_KEYS[type];
+  Object.keys(deprecatedNodeTypesAndAliases).forEach(type => {
+    const newType = deprecatedNodeTypesAndAliases[type];
     output += `export function assert${type}(node: any, opts: any): void {
-  console.trace("The node type ${type} has been renamed to ${newType}");
+  console.trace("\`assert${type}\` has been deprecated, please migrate to \`assert${newType}\`.");
   assert("${type}", node, opts);
 }\n`;
   });

packages/babel-types/scripts/generators/constants.js

@@ -1,4 +1,4 @@
-import { FLIPPED_ALIAS_KEYS } from "../../lib/index.js";
+import { DEPRECATED_ALIASES, FLIPPED_ALIAS_KEYS } from "../../lib/index.js";
 
 export default function generateConstants() {
   let output = `/*
@@ -7,8 +7,20 @@ export default function generateConstants() {
  */
 import { FLIPPED_ALIAS_KEYS } from "../../definitions";\n\n`;
 
-  Object.keys(FLIPPED_ALIAS_KEYS).forEach(type => {
-    output += `export const ${type.toUpperCase()}_TYPES = FLIPPED_ALIAS_KEYS["${type}"];\n`;
+  Object.keys(FLIPPED_ALIAS_KEYS)
+    .filter(
+      type => !Object.prototype.hasOwnProperty.call(DEPRECATED_ALIASES, type)
+    )
+    .forEach(type => {
+      output += `export const ${type.toUpperCase()}_TYPES = FLIPPED_ALIAS_KEYS["${type}"];\n`;
+    });
+
+  Object.keys(DEPRECATED_ALIASES).forEach(type => {
+    const newType = `${DEPRECATED_ALIASES[type].toUpperCase()}_TYPES`;
+    output += `/**
+* @deprecated migrate to ${newType}.
+*/
+export const ${type.toUpperCase()}_TYPES = ${newType}`;
   });
 
   return output;

packages/babel-types/scripts/generators/validators.js

@@ -1,4 +1,5 @@
 import {
+  DEPRECATED_ALIASES,
   DEPRECATED_KEYS,
   FLIPPED_ALIAS_KEYS,
   NODE_FIELDS,
@@ -77,15 +78,29 @@ import type * as t from "../..";\n\n`;
     output += addIsHelper(type);
   });
 
-  Object.keys(FLIPPED_ALIAS_KEYS).forEach(type => {
-    output += addIsHelper(type, FLIPPED_ALIAS_KEYS[type]);
-  });
+  Object.keys(FLIPPED_ALIAS_KEYS)
+    .filter(
+      type => !Object.prototype.hasOwnProperty.call(DEPRECATED_ALIASES, type)
+    )
+    .forEach(type => {
+      output += addIsHelper(type, FLIPPED_ALIAS_KEYS[type]);
+    });
 
   Object.keys(DEPRECATED_KEYS).forEach(type => {
     const newType = DEPRECATED_KEYS[type];
-    const deprecated = `console.trace("The node type ${type} has been renamed to ${newType}");`;
+    const deprecated = `console.trace("\`is${type}\` has been deprecated, please migrate to \`is${newType}\`.");`;
     output += addIsHelper(type, null, deprecated);
   });
 
+  Object.keys(DEPRECATED_ALIASES).forEach(type => {
+    const newType = DEPRECATED_ALIASES[type];
+    const deprecated = `console.trace("\`is${type}\` has been deprecated, please migrate to \`is${newType}\`.");`;
+    output += `export function is${type}(node: object | null | undefined, opts?: object | null): node is t.${newType} {
+  ${deprecated}
+  return is${newType}(node, opts);
+}
+`;
+  });
+
   return output;
 }

packages/babel-types/src/asserts/generated/index.ts

@@ -1694,11 +1694,11 @@ export function assertClass(
 ): asserts node is t.Class {
   assert("Class", node, opts);
 }
-export function assertModuleDeclaration(
+export function assertImportOrExportDeclaration(
   node: object | null | undefined,
   opts?: object | null,
-): asserts node is t.ModuleDeclaration {
-  assert("ModuleDeclaration", node, opts);
+): asserts node is t.ImportOrExportDeclaration {
+  assert("ImportOrExportDeclaration", node, opts);
 }
 export function assertExportDeclaration(
   node: object | null | undefined,
@@ -1804,21 +1804,31 @@ export function assertTSBaseType(
 }
 export function assertNumberLiteral(node: any, opts: any): void {
   console.trace(
-    "The node type NumberLiteral has been renamed to NumericLiteral",
+    "`assertNumberLiteral` has been deprecated, please migrate to `assertNumericLiteral`.",
   );
   assert("NumberLiteral", node, opts);
 }
 export function assertRegexLiteral(node: any, opts: any): void {
-  console.trace("The node type RegexLiteral has been renamed to RegExpLiteral");
+  console.trace(
+    "`assertRegexLiteral` has been deprecated, please migrate to `assertRegExpLiteral`.",
+  );
   assert("RegexLiteral", node, opts);
 }
 export function assertRestProperty(node: any, opts: any): void {
-  console.trace("The node type RestProperty has been renamed to RestElement");
+  console.trace(
+    "`assertRestProperty` has been deprecated, please migrate to `assertRestElement`.",
+  );
   assert("RestProperty", node, opts);
 }
 export function assertSpreadProperty(node: any, opts: any): void {
   console.trace(
-    "The node type SpreadProperty has been renamed to SpreadElement",
+    "`assertSpreadProperty` has been deprecated, please migrate to `assertSpreadElement`.",
   );
   assert("SpreadProperty", node, opts);
 }
+export function assertModuleDeclaration(node: any, opts: any): void {
+  console.trace(
+    "`assertModuleDeclaration` has been deprecated, please migrate to `assertImportOrExportDeclaration`.",
+  );
+  assert("ModuleDeclaration", node, opts);
+}

packages/babel-types/src/ast-types/generated/index.ts

@@ -2455,7 +2455,7 @@ export type Property =
 export type UnaryLike = UnaryExpression | SpreadElement;
 export type Pattern = AssignmentPattern | ArrayPattern | ObjectPattern;
 export type Class = ClassExpression | ClassDeclaration;
-export type ModuleDeclaration =
+export type ImportOrExportDeclaration =
   | ExportAllDeclaration
   | ExportDefaultDeclaration
   | ExportNamedDeclaration
@@ -2743,6 +2743,11 @@ export type TSBaseType =
   | TSVoidKeyword
   | TSThisType
   | TSLiteralType;
+export type ModuleDeclaration =
+  | ExportAllDeclaration
+  | ExportDefaultDeclaration
+  | ExportNamedDeclaration
+  | ImportDeclaration;
 
 export interface Aliases {
   Standardized: Standardized;
@@ -2776,7 +2781,7 @@ export interface Aliases {
   UnaryLike: UnaryLike;
   Pattern: Pattern;
   Class: Class;
-  ModuleDeclaration: ModuleDeclaration;
+  ImportOrExportDeclaration: ImportOrExportDeclaration;
   ExportDeclaration: ExportDeclaration;
   ModuleSpecifier: ModuleSpecifier;
   Accessor: Accessor;
@@ -2794,6 +2799,7 @@ export interface Aliases {
   TSTypeElement: TSTypeElement;
   TSType: TSType;
   TSBaseType: TSBaseType;
+  ModuleDeclaration: ModuleDeclaration;
 }
 
 export type DeprecatedAliases =

packages/babel-types/src/constants/generated/index.ts

@@ -36,7 +36,8 @@ export const PROPERTY_TYPES = FLIPPED_ALIAS_KEYS["Property"];
 export const UNARYLIKE_TYPES = FLIPPED_ALIAS_KEYS["UnaryLike"];
 export const PATTERN_TYPES = FLIPPED_ALIAS_KEYS["Pattern"];
 export const CLASS_TYPES = FLIPPED_ALIAS_KEYS["Class"];
-export const MODULEDECLARATION_TYPES = FLIPPED_ALIAS_KEYS["ModuleDeclaration"];
+export const IMPORTOREXPORTDECLARATION_TYPES =
+  FLIPPED_ALIAS_KEYS["ImportOrExportDeclaration"];
 export const EXPORTDECLARATION_TYPES = FLIPPED_ALIAS_KEYS["ExportDeclaration"];
 export const MODULESPECIFIER_TYPES = FLIPPED_ALIAS_KEYS["ModuleSpecifier"];
 export const ACCESSOR_TYPES = FLIPPED_ALIAS_KEYS["Accessor"];
@@ -55,3 +56,7 @@ export const TYPESCRIPT_TYPES = FLIPPED_ALIAS_KEYS["TypeScript"];
 export const TSTYPEELEMENT_TYPES = FLIPPED_ALIAS_KEYS["TSTypeElement"];
 export const TSTYPE_TYPES = FLIPPED_ALIAS_KEYS["TSType"];
 export const TSBASETYPE_TYPES = FLIPPED_ALIAS_KEYS["TSBaseType"];
+/**
+ * @deprecated migrate to IMPORTOREXPORTDECLARATION_TYPES.
+ */
+export const MODULEDECLARATION_TYPES = IMPORTOREXPORTDECLARATION_TYPES;

packages/babel-types/src/definitions/core.ts

@@ -1487,7 +1487,7 @@ defineType("ExportAllDeclaration", {
   aliases: [
     "Statement",
     "Declaration",
-    "ModuleDeclaration",
+    "ImportOrExportDeclaration",
     "ExportDeclaration",
   ],
   fields: {
@@ -1510,7 +1510,7 @@ defineType("ExportDefaultDeclaration", {
   aliases: [
     "Statement",
     "Declaration",
-    "ModuleDeclaration",
+    "ImportOrExportDeclaration",
     "ExportDeclaration",
   ],
   fields: {
@@ -1531,7 +1531,7 @@ defineType("ExportNamedDeclaration", {
   aliases: [
     "Statement",
     "Declaration",
-    "ModuleDeclaration",
+    "ImportOrExportDeclaration",
     "ExportDeclaration",
   ],
   fields: {
@@ -1675,7 +1675,7 @@ defineType("ForOfStatement", {
 
 defineType("ImportDeclaration", {
   visitor: ["specifiers", "source"],
-  aliases: ["Statement", "Declaration", "ModuleDeclaration"],
+  aliases: ["Statement", "Declaration", "ImportOrExportDeclaration"],
   fields: {
     assertions: {
       optional: true,

packages/babel-types/src/definitions/deprecated-aliases.ts

@@ -0,0 +1,3 @@
+export const DEPRECATED_ALIASES = {
+  ModuleDeclaration: "ImportOrExportDeclaration",
+};

packages/babel-types/src/definitions/index.ts

@@ -19,6 +19,14 @@ import {
   PLACEHOLDERS_ALIAS,
   PLACEHOLDERS_FLIPPED_ALIAS,
 } from "./placeholders";
+import { DEPRECATED_ALIASES } from "./deprecated-aliases";
+
+(
+  Object.keys(DEPRECATED_ALIASES) as (keyof typeof DEPRECATED_ALIASES)[]
+).forEach(deprecatedAlias => {
+  FLIPPED_ALIAS_KEYS[deprecatedAlias] =
+    FLIPPED_ALIAS_KEYS[DEPRECATED_ALIASES[deprecatedAlias]];
+});
 
 // We do this here, because at this point the visitor keys should be ready and setup
 toFastProperties(VISITOR_KEYS);
@@ -43,6 +51,7 @@ export {
   FLIPPED_ALIAS_KEYS,
   NODE_FIELDS,
   BUILDER_KEYS,
+  DEPRECATED_ALIASES,
   DEPRECATED_KEYS,
   NODE_PARENT_VALIDATIONS,
   PLACEHOLDERS,