Update babel-types docs generator

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

@@ -7,7 +7,7 @@ import * as t from "../../lib/index.js";
 const readme = [
   `---
 id: babel-types
-title: @babel/types
+title: "@babel/types"
 ---
 <!-- Do not modify! This file is automatically generated by
   github.com/babel/babel/babel-types/scripts/generators/docs.js !-->
@@ -16,7 +16,7 @@ title: @babel/types
 
 ## Install
 
-\`\`\`sh
+\`\`\`shell npm2yarn
 npm install --save-dev @babel/types
 \`\`\`
 
@@ -48,14 +48,103 @@ const customTypes = {
 };
 const APIHistory = {
   ClassProperty: [["v7.6.0", "Supports `static`"]],
+  ImportDeclaration: [["v7.20.0", "Supports `module`"]],
+  ModuleDeclaration: [["v7.21.0", "Deprecated"]],
+  TSSatisfiesExpression: [["v7.20.0", "Introduced"]],
+  TSTypeParameter: [["v7.21.0", "Supports `const`"]],
+  VariableDeclaration: [["v7.20.0", '`kind` can be "using".']],
 };
+const aliasDescriptions = {
+  Accessor: "Deprecated. Will be removed in Babel 8.",
+  Binary:
+    "A cover of BinaryExpression and LogicalExpression, which share the same AST shape.",
+  Block: "Deprecated. Will be removed in Babel 8.",
+  BlockParent:
+    "A cover of AST nodes that start an execution context with new [LexicalEnvironment](https://tc39.es/ecma262/#table-additional-state-components-for-ecmascript-code-execution-contexts). In other words, they define the scope of `let` and `const` declarations.",
+  Class:
+    "A cover of ClassExpression and ClassDeclaration, which share the same AST shape.",
+  CompletionStatement:
+    "A statement that indicates the [completion records](https://tc39.es/ecma262/#sec-completion-record-specification-type). In other words, they define the control flow of the program, such as when should a loop break or an action throws critical errors.",
+  Conditional:
+    "A cover of ConditionalExpression and IfStatement, which share the same AST shape.",
+  Declaration:
+    "A cover of any [Declaration](https://tc39.es/ecma262/#prod-Declaration)s.",
+  EnumBody: "A cover of Flow enum bodies.",
+  EnumMember: "A cover of Flow enum members.",
+  ExportDeclaration:
+    "A cover of any [ExportDeclaration](https://tc39.es/ecma262/#prod-ExportDeclaration)s.",
+  Expression:
+    "A cover of any [Expression](https://tc39.es/ecma262/#sec-ecmascript-language-expressions)s.",
+  ExpressionWrapper:
+    "A wrapper of expression that does not have runtime semantics.",
+  Flow: "A cover of AST nodes defined for Flow.",
+  FlowBaseAnnotation: "A cover of primary Flow type annotations.",
+  FlowDeclaration: "A cover of Flow declarations.",
+  FlowPredicate: "A cover of Flow predicates.",
+  FlowType: "A cover of Flow type annotations.",
+  For: "A cover of [ForStatement](https://tc39.es/ecma262/#sec-for-statement)s and [ForXStatement](#forxstatement)s.",
+  ForXStatement:
+    "A cover of [ForInStatements and ForOfStatements](https://tc39.es/ecma262/#sec-for-in-and-for-of-statements).",
+  Function:
+    "A cover of functions and [method](#method)s, the must have `body` and `params`. Note: `Function` is different to `FunctionParent`. For example, a `StaticBlock` is a `FunctionParent` but not `Function`.",
+  FunctionParent:
+    "A cover of AST nodes that start an execution context with new [VariableEnvironment](https://tc39.es/ecma262/#table-additional-state-components-for-ecmascript-code-execution-contexts). In other words, they define the scope of `var` declarations. FunctionParent did not include `Program` since Babel 7.",
+  Immutable:
+    "A cover of immutable objects and JSX elements. An object is [immutable](https://tc39.es/ecma262/#immutable-prototype-exotic-object) if no other properties can be defined once created.",
+  ImportOrExportDeclaration:
+    "A cover of ImportDeclaration and [ExportDeclaration](#exportdeclaration)",
+  JSX: "A cover of AST nodes defined for [JSX](https://facebook.github.io/jsx/).",
+  LVal: "A cover of left hand side expressions used in the `left` of assignment expressions and [ForXStatement](#forxstatement)s.",
+  Literal:
+    "A cover of [Literal](https://tc39.es/ecma262/#sec-primary-expression-literals)s, [Regular Expression Literal](https://tc39.es/ecma262/#sec-primary-expression-regular-expression-literals)s and [Template Literal](https://tc39.es/ecma262/#sec-template-literals)s.",
+  Loop: "A cover of loop statements.",
+  Method: "A cover of object methods and class methods.",
+  Miscellaneous:
+    "A cover of non-standard AST types that are sometimes useful for development.",
+  ModuleSpecifier:
+    "A cover of import and export specifiers. Note: It is _not_ the [ModuleSpecifier](https://tc39.es/ecma262/#prod-ModuleSpecifier) defined in the spec.",
+  ObjectMember:
+    "A cover of [members](https://tc39.es/ecma262/#prod-PropertyDefinitionList) in an object literal.",
+  Pattern:
+    "A cover of [BindingPattern](https://tc39.es/ecma262/#prod-BindingPattern) except Identifiers.",
+  PatternLike:
+    "A cover of [BindingPattern](https://tc39.es/ecma262/#prod-BindingPattern)s.",
+  Private: "A cover of private class elements and private identifiers.",
+  Property: "A cover of object properties and class properties.",
+  Pureish:
+    "A cover of AST nodes which do not have side-effects. In other words, there is no observable behaviour changes if they are evaluated more than once.",
+  Scopable:
+    "A cover of [FunctionParent](#functionparent) and [BlockParent](#blockparent).",
+  Standardized:
+    "A cover of AST nodes which are part of an official ECMAScript specification.",
+  Statement:
+    "A cover of any [Statement](https://tc39.es/ecma262/#prod-Statement)s.",
+  TSBaseType: "A cover of primary TypeScript type annotations.",
+  TSEntityName: "A cover of ts entities.",
+  TSType: "A cover of TypeScript type annotations.",
+  TSTypeElement: "A cover of TypeScript type declarations.",
+  TypeScript: "A cover of AST nodes defined for TypeScript.",
+  Terminatorless:
+    "A cover of AST nodes whose semantic will change when a line terminator is inserted between the operator and the operand.",
+  UnaryLike: "A cover of UnaryExpression and SpreadElement.",
+  UserWhitespacable: "Deprecated. Will be removed in Babel 8.",
+  While:
+    "A cover of DoWhileStatement and WhileStatement, which share the same AST shape.",
+};
+
+const aliasDeprecationNotes = {
+  ModuleDeclaration:
+    "Check out [PR #15266](https://github.com/babel/babel/pull/15266#issue-1492649843) for migration notes.",
+};
+
 function formatHistory(historyItems) {
   const lines = historyItems.map(
     item => "| `" + item[0] + "` | " + item[1] + " |"
   );
   return [
     "<details>",
     "  <summary>History</summary>",
+    "",
     "| Version | Changes |",
     "| --- | --- |",
     ...lines,
@@ -137,7 +226,7 @@ Object.keys(t.BUILDER_KEYS)
   .forEach(function (key) {
     readme.push("#### " + toFunctionName(key));
     readme.push("");
-    readme.push("```javascript");
+    readme.push('```js title="JavaScript"');
     readme.push(
       "t." + toFunctionName(key) + "(" + t.BUILDER_KEYS[key].join(", ") + ");"
     );
@@ -173,107 +262,47 @@ function generateMapAliasToNodeTypes() {
       nodeTypes.push(nodeType);
     }
   }
+  for (const deprecated of Object.keys(t.DEPRECATED_ALIASES)) {
+    result.set(deprecated, result.get(t.DEPRECATED_ALIASES[deprecated]));
+  }
   return result;
 }
-const aliasDescriptions = {
-  Accessor: "Deprecated. Will be removed in Babel 8.",
-  Binary:
-    "A cover of BinaryExpression and LogicalExpression, which share the same AST shape.",
-  Block: "Deprecated. Will be removed in Babel 8.",
-  BlockParent:
-    "A cover of AST nodes that start an execution context with new [LexicalEnvironment](https://tc39.es/ecma262/#table-additional-state-components-for-ecmascript-code-execution-contexts). In other words, they define the scope of `let` and `const` declarations.",
-  Class:
-    "A cover of ClassExpression and ClassDeclaration, which share the same AST shape.",
-  CompletionStatement:
-    "A statement that indicates the [completion records](https://tc39.es/ecma262/#sec-completion-record-specification-type). In other words, they define the control flow of the program, such as when should a loop break or an action throws critical errors.",
-  Conditional:
-    "A cover of ConditionalExpression and IfStatement, which share the same AST shape.",
-  Declaration:
-    "A cover of any [Declaration](https://tc39.es/ecma262/#prod-Declaration)s.",
-  EnumBody: "A cover of Flow enum bodies.",
-  EnumMember: "A cover of Flow enum members.",
-  ExportDeclaration:
-    "A cover of any [ExportDeclaration](https://tc39.es/ecma262/#prod-ExportDeclaration)s.",
-  Expression:
-    "A cover of any [Expression](https://tc39.es/ecma262/#sec-ecmascript-language-expressions)s.",
-  ExpressionWrapper:
-    "A wrapper of expression that does not have runtime semantics.",
-  Flow: "A cover of AST nodes defined for Flow.",
-  FlowBaseAnnotation: "A cover of primary Flow type annotations.",
-  FlowDeclaration: "A cover of Flow declarations.",
-  FlowPredicate: "A cover of Flow predicates.",
-  FlowType: "A cover of Flow type annotations.",
-  For: "A cover of [ForStatement](https://tc39.es/ecma262/#sec-for-statement)s and [ForXStatement](#forxstatement)s.",
-  ForXStatement:
-    "A cover of [ForInStatements and ForOfStatements](https://tc39.es/ecma262/#sec-for-in-and-for-of-statements).",
-  Function:
-    "A cover of functions and [method](#method)s, the must have `body` and `params`. Note: `Function` is different to `FunctionParent`. For example, a `StaticBlock` is a `FunctionParent` but not `Function`.",
-  FunctionParent:
-    "A cover of AST nodes that start an execution context with new [VariableEnvironment](https://tc39.es/ecma262/#table-additional-state-components-for-ecmascript-code-execution-contexts). In other words, they define the scope of `var` declarations. FunctionParent did not include `Program` since Babel 7.",
-  Immutable:
-    "A cover of immutable objects and JSX elements. An object is [immutable](https://tc39.es/ecma262/#immutable-prototype-exotic-object) if no other properties can be defined once created.",
-  JSX: "A cover of AST nodes defined for [JSX](https://facebook.github.io/jsx/).",
-  LVal: "A cover of left hand side expressions used in the `left` of assignment expressions and [ForXStatement](#forxstatement)s. ",
-  Literal:
-    "A cover of [Literal](https://tc39.es/ecma262/#sec-primary-expression-literals)s, [Regular Expression Literal](https://tc39.es/ecma262/#sec-primary-expression-regular-expression-literals)s and [Template Literal](https://tc39.es/ecma262/#sec-template-literals)s.",
-  Loop: "A cover of loop statements.",
-  Method: "A cover of object methods and class methods.",
-  Miscellaneous:
-    "A cover of non-standard AST types that are sometimes useful for development.",
-  ModuleDeclaration:
-    "A cover of ImportDeclaration and [ExportDeclaration](#exportdeclaration)",
-  ModuleSpecifier:
-    "A cover of import and export specifiers. Note: It is _not_ the [ModuleSpecifier](https://tc39.es/ecma262/#prod-ModuleSpecifier) defined in the spec.",
-  ObjectMember:
-    "A cover of [members](https://tc39.es/ecma262/#prod-PropertyDefinitionList) in an object literal.",
-  Pattern:
-    "A cover of [BindingPattern](https://tc39.es/ecma262/#prod-BindingPattern) except Identifiers.",
-  PatternLike:
-    "A cover of [BindingPattern](https://tc39.es/ecma262/#prod-BindingPattern)s. ",
-  Private: "A cover of private class elements and private identifiers.",
-  Property: "A cover of object properties and class properties.",
-  Pureish:
-    "A cover of AST nodes which do not have side-effects. In other words, there is no observable behaviour changes if they are evaluated more than once.",
-  Scopable:
-    "A cover of [FunctionParent](#functionparent) and [BlockParent](#blockparent).",
-  Standardized:
-    "A cover of AST nodes which are part of an official ECMAScript specification.",
-  Statement:
-    "A cover of any [Statement](https://tc39.es/ecma262/#prod-Statement)s.",
-  TSBaseType: "A cover of primary TypeScript type annotations.",
-  TSEntityName: "A cover of ts entities.",
-  TSType: "A cover of TypeScript type annotations.",
-  TSTypeElement: "A cover of TypeScript type declarations.",
-  TypeScript: "A cover of AST nodes defined for TypeScript.",
-  Terminatorless:
-    "A cover of AST nodes whose semantic will change when a line terminator is inserted between the operator and the operand.",
-  UnaryLike: "A cover of UnaryExpression and SpreadElement.",
-  UserWhitespacable: "Deprecated. Will be removed in Babel 8.",
-  While:
-    "A cover of DoWhileStatement and WhileStatement, which share the same AST shape.",
-};
+
 const mapAliasToNodeTypes = generateMapAliasToNodeTypes();
 readme.push("### Aliases");
 readme.push("");
 for (const alias of [...mapAliasToNodeTypes.keys()].sort()) {
   const nodeTypes = mapAliasToNodeTypes.get(alias);
   nodeTypes.sort();
   if (!(alias in aliasDescriptions)) {
-    throw new Error(
-      'Missing alias descriptions of "' +
-        alias +
-        ", which covers " +
-        nodeTypes.join(",")
-    );
+    if (alias in t.DEPRECATED_ALIASES) {
+      const newAlias = t.DEPRECATED_ALIASES[alias];
+      let aliasDescription = `Deprecated, use [\`${newAlias}\`](#${newAlias.toLowerCase()}) instead.`;
+      if (alias in aliasDeprecationNotes) {
+        aliasDescription += " " + aliasDeprecationNotes[alias];
+      }
+      // wrap alias description in caution admonitions
+      // https://docusaurus.io/docs/markdown-features/admonitions
+      aliasDescription = `:::caution\n\n${aliasDescription}\n\n:::`;
+      aliasDescriptions[alias] = aliasDescription;
+    } else {
+      throw new Error(
+        'Missing alias descriptions of "' +
+          alias +
+          ", which covers " +
+          nodeTypes.join(",")
+      );
+    }
   }
   readme.push("#### " + alias);
+  printAPIHistory(alias, readme);
   readme.push("");
   readme.push(aliasDescriptions[alias]);
-  readme.push("```javascript");
+  readme.push('```js title="JavaScript"');
   readme.push("t.is" + alias + "(node);");
   readme.push("```");
   readme.push("");
-  readme.push("Covered nodes: ");
+  readme.push("Covered nodes:");
   for (const nodeType of nodeTypes) {
     readme.push("- [`" + nodeType + "`](#" + nodeType.toLowerCase() + ")");
   }