flow-api-translator 0.10.0

package/dist/flowToJS.js

@@ -0,0 +1,188 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * 
+ * @format
+ */
+'use strict';
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.flowToJS = flowToJS;
+
+var _DocblockUtils = require("./utils/DocblockUtils");
+
+var _hermesParser = require("hermes-parser");
+
+const {
+  nodeWith
+} = _hermesParser.astNodeMutationHelpers;
+
+function transform(node) {
+  switch (node.type) {
+    case 'Program':
+      {
+        const docblock = node.docblock;
+
+        if (docblock == null) {
+          return node;
+        }
+
+        return nodeWith(node, {
+          docblock: (0, _DocblockUtils.removeAtFlowFromDocblock)(docblock)
+        });
+      }
+
+    case 'TypeCastExpression':
+      {
+        return node.expression;
+      }
+
+    case 'CallExpression':
+    case 'NewExpression':
+      {
+        if (node.typeArguments != null) {
+          return nodeWith(node, {
+            typeArguments: null
+          });
+        }
+
+        return node;
+      }
+
+    case 'ObjectPattern':
+    case 'ArrayPattern':
+    case 'Identifier':
+      {
+        if (node.typeAnnotation != null) {
+          return nodeWith(node, {
+            typeAnnotation: null
+          });
+        }
+
+        return node;
+      }
+
+    case 'DeclareClass':
+    case 'DeclareFunction':
+    case 'DeclareInterface':
+    case 'DeclareModule':
+    case 'DeclareModuleExports':
+    case 'DeclareOpaqueType':
+    case 'DeclareTypeAlias':
+    case 'DeclareVariable':
+    case 'InterfaceDeclaration':
+    case 'OpaqueType':
+    case 'TypeAlias':
+      {
+        return null;
+      }
+
+    case 'FunctionDeclaration':
+    case 'ArrowFunctionExpression':
+    case 'FunctionExpression':
+      {
+        const newParams = [];
+
+        for (let i = 0; i < node.params.length; i++) {
+          if (i === 0 && node.params[0].type === 'Identifier' && node.params[0].name === 'this') {
+            continue;
+          }
+
+          let param = node.params[i];
+
+          if (param.type === 'AssignmentPattern') {
+            param = param.left;
+          }
+
+          if (param.optional === true) {
+            param = nodeWith(param, {
+              optional: false
+            });
+          }
+
+          newParams.push(param);
+        }
+
+        return nodeWith(node, {
+          params: newParams,
+          returnType: null,
+          typeParameters: null,
+          predicate: null
+        });
+      }
+
+    case 'ClassDeclaration':
+    case 'ClassExpression':
+      {
+        return nodeWith(node, {
+          typeParameters: null,
+          superTypeParameters: null,
+          implements: [],
+          decorators: []
+        });
+      }
+
+    case 'PropertyDefinition':
+      {
+        return nodeWith(node, {
+          typeAnnotation: null,
+          variance: null,
+          declare: false,
+          optional: false
+        });
+      }
+
+    case 'ImportDeclaration':
+      {
+        if (node.importKind === 'type' || node.importKind === 'typeof') {
+          return null;
+        }
+
+        const nonTypeSpecifiers = node.specifiers.filter(s => s.type !== 'ImportSpecifier' || s.importKind !== 'type' && s.importKind !== 'typeof');
+
+        if (nonTypeSpecifiers.length === 0) {
+          return null;
+        }
+
+        if (nonTypeSpecifiers.length === node.specifiers.length) {
+          return node;
+        }
+
+        return nodeWith(node, {
+          specifiers: nonTypeSpecifiers
+        });
+      }
+
+    case 'ExportAllDeclaration':
+    case 'ExportNamedDeclaration':
+      {
+        if (node.exportKind === 'type') {
+          return null;
+        }
+
+        return node;
+      }
+
+    default:
+      {
+        return node;
+      }
+  }
+}
+
+function flowToJS(sourceAST, _code, _scopeManager) {
+  const result = _hermesParser.SimpleTransform.transform(sourceAST, {
+    transform
+  });
+
+  if (result == null || result.type !== 'Program') {
+    throw new Error('flowToJS: Unexpected transform result.');
+  }
+
+  return result;
+}

package/dist/flowToJS.js.flow

@@ -0,0 +1,166 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+'use strict';
+
+import type {ScopeManager} from 'hermes-eslint';
+import type {ESNode, Program} from 'hermes-estree';
+
+import {removeAtFlowFromDocblock} from './utils/DocblockUtils';
+
+import {SimpleTransform, astNodeMutationHelpers} from 'hermes-parser';
+const {nodeWith} = astNodeMutationHelpers;
+
+function transform(node: ESNode): ESNode | null {
+  switch (node.type) {
+    case 'Program': {
+      const docblock = node.docblock;
+      if (docblock == null) {
+        return node;
+      }
+
+      return nodeWith(node, {
+        docblock: removeAtFlowFromDocblock(docblock),
+      });
+    }
+
+    case 'TypeCastExpression': {
+      return node.expression;
+    }
+
+    case 'CallExpression':
+    case 'NewExpression': {
+      if (node.typeArguments != null) {
+        return nodeWith(node, {typeArguments: null});
+      }
+      return node;
+    }
+
+    case 'ObjectPattern':
+    case 'ArrayPattern':
+    case 'Identifier': {
+      if (node.typeAnnotation != null) {
+        return nodeWith(node, {typeAnnotation: null});
+      }
+      return node;
+    }
+
+    case 'DeclareClass':
+    case 'DeclareFunction':
+    case 'DeclareInterface':
+    case 'DeclareModule':
+    case 'DeclareModuleExports':
+    case 'DeclareOpaqueType':
+    case 'DeclareTypeAlias':
+    case 'DeclareVariable':
+    case 'InterfaceDeclaration':
+    case 'OpaqueType':
+    case 'TypeAlias': {
+      return null;
+    }
+
+    case 'FunctionDeclaration':
+    case 'ArrowFunctionExpression':
+    case 'FunctionExpression': {
+      const newParams = [];
+      for (let i = 0; i < node.params.length; i++) {
+        if (
+          i === 0 &&
+          node.params[0].type === 'Identifier' &&
+          node.params[0].name === 'this'
+        ) {
+          continue;
+        }
+
+        let param = node.params[i];
+        if (param.type === 'AssignmentPattern') {
+          param = param.left;
+        }
+        if (param.optional === true) {
+          param = nodeWith(param, {optional: false});
+        }
+        newParams.push(param);
+      }
+
+      return nodeWith(node, {
+        params: newParams,
+        returnType: null,
+        typeParameters: null,
+        predicate: null,
+      });
+    }
+
+    case 'ClassDeclaration':
+    case 'ClassExpression': {
+      return nodeWith(node, {
+        typeParameters: null,
+        superTypeParameters: null,
+        implements: [],
+        decorators: [],
+      });
+    }
+
+    case 'PropertyDefinition': {
+      return nodeWith(node, {
+        typeAnnotation: null,
+        variance: null,
+        declare: false,
+        optional: false,
+      });
+    }
+
+    case 'ImportDeclaration': {
+      if (node.importKind === 'type' || node.importKind === 'typeof') {
+        return null;
+      }
+      const nonTypeSpecifiers = node.specifiers.filter(
+        s =>
+          s.type !== 'ImportSpecifier' ||
+          (s.importKind !== 'type' && s.importKind !== 'typeof'),
+      );
+      if (nonTypeSpecifiers.length === 0) {
+        return null;
+      }
+      if (nonTypeSpecifiers.length === node.specifiers.length) {
+        return node;
+      }
+
+      return nodeWith(node, {
+        specifiers: nonTypeSpecifiers,
+      });
+    }
+
+    case 'ExportAllDeclaration':
+    case 'ExportNamedDeclaration': {
+      if (node.exportKind === 'type') {
+        return null;
+      }
+      return node;
+    }
+
+    default: {
+      return node;
+    }
+  }
+}
+
+export function flowToJS(
+  sourceAST: Program,
+  _code: string,
+  _scopeManager: ScopeManager,
+): Program {
+  const result = SimpleTransform.transform(sourceAST, {
+    transform,
+  });
+  if (result == null || result.type !== 'Program') {
+    throw new Error('flowToJS: Unexpected transform result.');
+  }
+  return result;
+}

package/dist/index.js

@@ -0,0 +1,78 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * 
+ * @format
+ */
+'use strict';
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.translateFlowDefToTSDef = translateFlowDefToTSDef;
+exports.translateFlowImportsTo = translateFlowImportsTo;
+exports.translateFlowToFlowDef = translateFlowToFlowDef;
+exports.translateFlowToJS = translateFlowToJS;
+exports.translateFlowToTSDef = translateFlowToTSDef;
+
+var _hermesTransform = require("hermes-transform");
+
+var _visitorKeys = require("@typescript-eslint/visitor-keys");
+
+var _flowToFlowDef = _interopRequireDefault(require("./flowToFlowDef"));
+
+var _flowDefToTSDef = require("./flowDefToTSDef");
+
+var _flowToJS = require("./flowToJS");
+
+var _flowImportTo = require("./flowImportTo");
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+function translateFlowToFlowDef(code, prettierOptions = {}) {
+  const {
+    ast,
+    scopeManager
+  } = (0, _hermesTransform.parse)(code);
+  const [flowDefAst, mutatedCode] = (0, _flowToFlowDef.default)(ast, code, scopeManager, {
+    recoverFromErrors: true
+  });
+  return (0, _hermesTransform.print)(flowDefAst, mutatedCode, prettierOptions);
+}
+
+function translateFlowToTSDef(code, prettierOptions = {}) {
+  const flowDefCode = translateFlowToFlowDef(code, prettierOptions);
+  return translateFlowDefToTSDef(flowDefCode, prettierOptions);
+}
+
+function translateFlowDefToTSDef(code, prettierOptions = {}) {
+  const {
+    ast,
+    scopeManager
+  } = (0, _hermesTransform.parse)(code);
+  const tsAST = (0, _flowDefToTSDef.flowDefToTSDef)(code, ast, scopeManager);
+  return (0, _hermesTransform.print)( // $FlowExpectedError[incompatible-call] - this is fine as we're providing the visitor keys
+  tsAST, code, { ...prettierOptions
+  }, _visitorKeys.visitorKeys);
+}
+
+function translateFlowToJS(code, prettierOptions = {}) {
+  const {
+    ast,
+    scopeManager
+  } = (0, _hermesTransform.parse)(code);
+  const jsAST = (0, _flowToJS.flowToJS)(ast, code, scopeManager);
+  return (0, _hermesTransform.print)(jsAST, code, prettierOptions);
+}
+
+function translateFlowImportsTo(code, prettierOptions = {}, opts) {
+  const {
+    ast,
+    scopeManager
+  } = (0, _hermesTransform.parse)(code);
+  const jsAST = (0, _flowImportTo.flowImportTo)(ast, code, scopeManager, opts);
+  return (0, _hermesTransform.print)(jsAST, code, prettierOptions);
+}

package/dist/index.js.flow

@@ -0,0 +1,84 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+'use strict';
+
+import type {MapperOptions} from './flowImportTo';
+
+import {parse, print} from 'hermes-transform';
+import {visitorKeys as tsVisitorKeys} from '@typescript-eslint/visitor-keys';
+import flowToFlowDef from './flowToFlowDef';
+import {flowDefToTSDef} from './flowDefToTSDef';
+import {flowToJS} from './flowToJS';
+import {flowImportTo} from './flowImportTo';
+
+export function translateFlowToFlowDef(
+  code: string,
+  prettierOptions: {...} = {},
+): string {
+  const {ast, scopeManager} = parse(code);
+
+  const [flowDefAst, mutatedCode] = flowToFlowDef(ast, code, scopeManager, {
+    recoverFromErrors: true,
+  });
+
+  return print(flowDefAst, mutatedCode, prettierOptions);
+}
+
+export function translateFlowToTSDef(
+  code: string,
+  prettierOptions: {...} = {},
+): string {
+  const flowDefCode = translateFlowToFlowDef(code, prettierOptions);
+
+  return translateFlowDefToTSDef(flowDefCode, prettierOptions);
+}
+
+export function translateFlowDefToTSDef(
+  code: string,
+  prettierOptions: {...} = {},
+): string {
+  const {ast, scopeManager} = parse(code);
+  const tsAST = flowDefToTSDef(code, ast, scopeManager);
+
+  return print(
+    // $FlowExpectedError[incompatible-call] - this is fine as we're providing the visitor keys
+    tsAST,
+    code,
+    {
+      ...prettierOptions,
+    },
+    tsVisitorKeys,
+  );
+}
+
+export function translateFlowToJS(
+  code: string,
+  prettierOptions: {...} = {},
+): string {
+  const {ast, scopeManager} = parse(code);
+
+  const jsAST = flowToJS(ast, code, scopeManager);
+
+  return print(jsAST, code, prettierOptions);
+}
+
+export type {MapperOptions as FlowImportsMapperOptions};
+export function translateFlowImportsTo(
+  code: string,
+  prettierOptions: {...} = {},
+  opts: MapperOptions,
+): string {
+  const {ast, scopeManager} = parse(code);
+
+  const jsAST = flowImportTo(ast, code, scopeManager, opts);
+
+  return print(jsAST, code, prettierOptions);
+}

package/dist/utils/DocblockUtils.js

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * 
+ * @format
+ */
+'use strict';
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.removeAtFlowFromDocblock = removeAtFlowFromDocblock;
+const FLOW_DIRECTIVE = /(@flow(\s+(strict(-local)?|weak))?|@noflow)/;
+
+function removeAtFlowFromDocblock(docblock) {
+  if (!FLOW_DIRECTIVE.test(docblock.comment.value)) {
+    return docblock;
+  }
+
+  return {
+    // $FlowExpectedError[cannot-spread-interface]
+    comment: { ...docblock.comment,
+      value: docblock.comment.value.replace(FLOW_DIRECTIVE, '')
+    },
+    directives: { ...docblock.directives,
+      flow: undefined,
+      noflow: undefined
+    }
+  };
+}

package/dist/utils/DocblockUtils.js.flow

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+'use strict';
+
+import type {DocblockMetadata} from 'hermes-estree';
+
+const FLOW_DIRECTIVE = /(@flow(\s+(strict(-local)?|weak))?|@noflow)/;
+
+export function removeAtFlowFromDocblock(
+  docblock: DocblockMetadata,
+): DocblockMetadata {
+  if (!FLOW_DIRECTIVE.test(docblock.comment.value)) {
+    return docblock;
+  }
+
+  return {
+    // $FlowExpectedError[cannot-spread-interface]
+    comment: {
+      ...docblock.comment,
+      value: docblock.comment.value.replace(FLOW_DIRECTIVE, ''),
+    },
+    directives: {
+      ...docblock.directives,
+      flow: undefined,
+      noflow: undefined,
+    },
+  };
+}

package/dist/utils/ErrorUtils.js

@@ -0,0 +1,102 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * 
+ * @format
+ */
+'use strict';
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.UnexpectedTranslationError = exports.ExpectedTranslationError = void 0;
+exports.flowFixMeOrError = flowFixMeOrError;
+exports.translationError = translationError;
+exports.unexpectedTranslationError = unexpectedTranslationError;
+
+var _hermesTransform = require("hermes-transform");
+
+var _codeFrame = require("@babel/code-frame");
+
+function flowFixMeOrError(container, message, context) {
+  if (context.recoverFromErrors) {
+    return _hermesTransform.t.GenericTypeAnnotation({
+      id: _hermesTransform.t.Identifier({
+        name: '$FlowFixMe'
+      })
+    });
+  }
+
+  throw translationError(container, message, context);
+}
+
+class TranslationErrorBase extends Error {
+  constructor(node, message, context) {
+    const framedMessage = buildCodeFrame(node, message, context.code);
+    super( // jest error snapshots will use a hard-coded string representation if
+    // `instanceof Error` which makes the code frame look awful and hard to verify:
+    //
+    // [TranslationError: > 12 | code
+    //       | ^^^^ error]
+    //
+    // this just adds a newline in jest tests so that it all lines up nicely
+    //
+    // [TranslationError:
+    // > 12 | code
+    //      | ^^^^ error]
+    process.env.JEST_WORKER_ID == null ? framedMessage : `\n${framedMessage}`);
+    this.name = 'TranslationError';
+  }
+
+}
+
+class ExpectedTranslationError extends TranslationErrorBase {
+  constructor(...args) {
+    super(...args);
+    this.name = 'ExpectedTranslationError';
+  }
+
+}
+
+exports.ExpectedTranslationError = ExpectedTranslationError;
+
+function translationError(node, message, context) {
+  return new ExpectedTranslationError(node, message, context);
+}
+
+class UnexpectedTranslationError extends TranslationErrorBase {
+  constructor(...args) {
+    super(...args);
+    this.name = 'UnexpectedTranslationError';
+  }
+
+}
+
+exports.UnexpectedTranslationError = UnexpectedTranslationError;
+
+function unexpectedTranslationError(node, message, context) {
+  return new UnexpectedTranslationError(node, message, context);
+}
+
+function buildCodeFrame(node, message, code) {
+  // babel uses 1-indexed columns
+  const locForBabel = {
+    start: {
+      line: node.loc.start.line,
+      column: node.loc.start.column + 1
+    },
+    end: {
+      line: node.loc.end.line,
+      column: node.loc.end.column + 1
+    }
+  };
+  return (0, _codeFrame.codeFrameColumns)(code, locForBabel, {
+    linesAbove: 0,
+    linesBelow: 0,
+    highlightCode: process.env.NODE_ENV !== 'test',
+    message: message
+  });
+}