Generate TypeScript typings, and improve generated Flow typings (#7101)

* generate typescript types * improve type generator output * move generator scripts to scripts/generators * use new stringifier for generating flow types too * export summary types * add support for oneOfNodeOrValueTypes to improve type generation * export typescript types from top level, and remove module declaration * generate typescript/flow types and copy typescript types to babel-types/lib as part of make build * copy flow types to babel-types/lib as part of make build (fix #6839) * improve typing: Identifier->name should be a string, not any * avoid destructuring, to support node 4 * update doc generator to share more code, regenerate babel-types readme, pipe all generator output to stdout * regenerate babel-types readme as part of make build * improve typing: ClassProperty->key should be Identifier | StringLiteral | NumericLiteral | Expression, not any * improve typing: optional node properties are nullable, not undefinedable * improve docs: FlowClassImplements should be ClassImplements * make ts usage more friendly: when using babel-types api, make optional params | undefined, and when reading nodes keep optional params | null * rm lib/types.d.ts and lib/types.js in favor of packages/babel-types/lib * add missing variance node type, address review comments * add tests for flow variance * Comment should be a disjoint union of tagged types * update .flowconfig
2018-01-17 07:31:46 -08:00
parent 667f5815c1
commit c3654d83c8
18 changed files with 423 additions and 1980 deletions
--- a/scripts/generators/docs.js
+++ b/scripts/generators/docs.js
@@ -0,0 +1,116 @@
+"use strict";
+
+const util = require("util");
+const utils = require("./utils");
+
+const types = require("../../packages/babel-types");
+
+const readme = [
+  `# @babel/types
+
+> This module contains methods for building ASTs manually and for checking the types of AST nodes.
+
+## Install
+
+\`\`\`sh
+npm install --save-dev @babel/types
+\`\`\`
+
+## API`,
+];
+
+const customTypes = {
+  ClassMethod: {
+    key: "if computed then `Expression` else `Identifier | Literal`",
+  },
+  Identifier: {
+    name: "`string`",
+  },
+  MemberExpression: {
+    property: "if computed then `Expression` else `Identifier`",
+  },
+  ObjectMethod: {
+    key: "if computed then `Expression` else `Identifier | Literal`",
+  },
+  ObjectProperty: {
+    key: "if computed then `Expression` else `Identifier | Literal`",
+  },
+};
+Object.keys(types.BUILDER_KEYS)
+  .sort()
+  .forEach(function(key) {
+    readme.push("### " + key[0].toLowerCase() + key.substr(1));
+    readme.push("```javascript");
+    readme.push(
+      "t." +
+        utils.toFunctionName(key) +
+        "(" +
+        types.BUILDER_KEYS[key].join(", ") +
+        ")"
+    );
+    readme.push("```");
+    readme.push("");
+    readme.push(
+      "See also `t.is" +
+        key +
+        "(node, opts)` and `t.assert" +
+        key +
+        "(node, opts)`."
+    );
+    readme.push("");
+    if (types.ALIAS_KEYS[key] && types.ALIAS_KEYS[key].length) {
+      readme.push(
+        "Aliases: " +
+          types.ALIAS_KEYS[key]
+            .map(function(key) {
+              return "`" + key + "`";
+            })
+            .join(", ")
+      );
+      readme.push("");
+    }
+    Object.keys(types.NODE_FIELDS[key])
+      .sort(function(fieldA, fieldB) {
+        const indexA = types.BUILDER_KEYS[key].indexOf(fieldA);
+        const indexB = types.BUILDER_KEYS[key].indexOf(fieldB);
+        if (indexA === indexB) return fieldA < fieldB ? -1 : 1;
+        if (indexA === -1) return 1;
+        if (indexB === -1) return -1;
+        return indexA - indexB;
+      })
+      .forEach(function(field) {
+        const defaultValue = types.NODE_FIELDS[key][field].default;
+        const fieldDescription = ["`" + field + "`"];
+        const validator = types.NODE_FIELDS[key][field].validate;
+        if (customTypes[key] && customTypes[key][field]) {
+          fieldDescription.push(`: ${customTypes[key][field]}`);
+        } else if (validator) {
+          try {
+            fieldDescription.push(
+              ": `" + utils.stringifyValidator(validator, "") + "`"
+            );
+          } catch (ex) {
+            if (ex.code === "UNEXPECTED_VALIDATOR_TYPE") {
+              console.log(
+                "Unrecognised validator type for " + key + "." + field
+              );
+              console.dir(ex.validator, { depth: 10, colors: true });
+            }
+          }
+        }
+        if (defaultValue !== null || types.NODE_FIELDS[key][field].optional) {
+          fieldDescription.push(
+            " (default: `" + util.inspect(defaultValue) + "`)"
+          );
+        } else {
+          fieldDescription.push(" (required)");
+        }
+        readme.push(" - " + fieldDescription.join(""));
+      });
+
+    readme.push("");
+    readme.push("---");
+    readme.push("");
+  });
+
+process.stdout.write(readme.join("\n"));