Add alias docs for @babel/types (#13151)

* add alias docs generator

* fix LVal and PatternLike

* sort alias covered node types

* add inner links between alias and node types

* review comments

* tiny tweaks

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

@@ -124,17 +124,18 @@ function printAliasKeys(key, readme) {
       "Aliases: " +
         t.ALIAS_KEYS[key]
           .map(function (key) {
-            return "`" + key + "`";
+            return "[`" + key + "`](#" + key.toLowerCase() + ")";
           })
           .join(", ")
     );
   }
 }
-
+readme.push("### Node Builders");
+readme.push("");
 Object.keys(t.BUILDER_KEYS)
   .sort()
   .forEach(function (key) {
-    readme.push("### " + toFunctionName(key));
+    readme.push("#### " + toFunctionName(key));
     readme.push("");
     readme.push("```javascript");
     readme.push(
@@ -159,4 +160,121 @@ Object.keys(t.BUILDER_KEYS)
     readme.push("");
   });
 
+function generateMapAliasToNodeTypes() {
+  const result = new Map();
+  for (const nodeType of Object.keys(t.ALIAS_KEYS)) {
+    const aliases = t.ALIAS_KEYS[nodeType];
+    if (!aliases) continue;
+    for (const alias of aliases) {
+      if (!result.has(alias)) {
+        result.set(alias, []);
+      }
+      const nodeTypes = result.get(alias);
+      nodeTypes.push(nodeType);
+    }
+  }
+  return result;
+}
+const aliasDescriptions = {
+  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 membors.",
+  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`.",
+  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.",
+  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).",
+  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.",
+  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(",")
+    );
+  }
+  readme.push("#### " + alias);
+  readme.push("");
+  readme.push(aliasDescriptions[alias]);
+  readme.push("```javascript");
+  readme.push("t.is" + alias + "(node);");
+  readme.push("```");
+  readme.push("");
+  readme.push("Covered nodes: ");
+  for (const nodeType of nodeTypes) {
+    readme.push("- [`" + nodeType + "`](#" + nodeType.toLowerCase() + ")");
+  }
+  readme.push("");
+}
+
 process.stdout.write(readme.join("\n"));