flow-api-translator 0.28.0 → 0.29.0

package/dist/src/flowToJS.js

@@ -0,0 +1,39 @@
+/**
+ * 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 _hermesParser = require("hermes-parser");
+
+var _DocblockUtils = require("./utils/DocblockUtils");
+
+const {
+  nodeWith
+} = _hermesParser.astNodeMutationHelpers;
+
+function stripAtFlow(ast, _options) {
+  const docblock = ast.docblock;
+
+  if (docblock == null) {
+    return ast;
+  }
+
+  return nodeWith(ast, {
+    docblock: (0, _DocblockUtils.removeAtFlowFromDocblock)(docblock)
+  });
+}
+
+function flowToJS(sourceAST, _code, _scopeManager) {
+  return [_hermesParser.Transforms.stripComponentSyntax, _hermesParser.Transforms.stripFlowTypes, stripAtFlow].reduce((ast, transform) => transform(ast, {}), sourceAST);
+}

package/dist/src/index.js

@@ -0,0 +1,114 @@
+/**
+ * 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;
+exports.unstable_translateTSDefToFlowDef = unstable_translateTSDefToFlowDef;
+
+var _hermesTransform = require("hermes-transform");
+
+var _parser = require("@typescript-eslint/parser");
+
+var _visitorKeys = require("@typescript-eslint/visitor-keys");
+
+var _flowToFlowDef = _interopRequireDefault(require("./flowToFlowDef"));
+
+var _flowDefToTSDef = require("./flowDefToTSDef");
+
+var _flowToJS = require("./flowToJS");
+
+var _flowImportTo = require("./flowImportTo");
+
+var _TSDefToFlowDef = require("./TSDefToFlowDef");
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+async function translateFlowToFlowDef(code, prettierOptions = {}) {
+  const {
+    ast,
+    scopeManager
+  } = await (0, _hermesTransform.parse)(code);
+  const [flowDefAst, mutatedCode] = (0, _flowToFlowDef.default)(ast, code, scopeManager, {
+    recoverFromErrors: true
+  });
+  return (0, _hermesTransform.print)(flowDefAst, mutatedCode, prettierOptions);
+}
+
+async function translateFlowToTSDef(code, prettierOptions = {}) {
+  const flowDefCode = await translateFlowToFlowDef(code, prettierOptions);
+  return translateFlowDefToTSDef(flowDefCode, prettierOptions);
+}
+
+async function translateFlowDefToTSDef(code, prettierOptions = {}) {
+  const {
+    ast,
+    scopeManager
+  } = await (0, _hermesTransform.parse)(code);
+  const [tsAST, mutatedCode] = (0, _flowDefToTSDef.flowDefToTSDef)(code, ast, scopeManager, {
+    recoverFromErrors: true
+  });
+  return (0, _hermesTransform.print)( // $FlowExpectedError[incompatible-call] - this is fine as we're providing the visitor keys
+  tsAST, mutatedCode, { ...prettierOptions
+  }, _visitorKeys.visitorKeys);
+}
+
+async function translateFlowToJS(code, prettierOptions = {}) {
+  const {
+    ast,
+    scopeManager
+  } = await (0, _hermesTransform.parse)(code);
+  const jsAST = (0, _flowToJS.flowToJS)(ast, code, scopeManager);
+  return (0, _hermesTransform.print)(jsAST, code, prettierOptions);
+}
+/**
+ * This translator is very experimental and unstable.
+ *
+ * It is not written with productionizing it in mind, but instead used to evaluate how close Flow
+ * is to TypeScript.
+ *
+ * If you are going to use it anyways, you agree that you are calling a potentially broken function
+ * without any guarantee.
+ *
+ * @deprecated
+ */
+
+
+async function unstable_translateTSDefToFlowDef(code, prettierOptions = {}) {
+  const ast = (0, _parser.parse)(code, {
+    loc: true,
+    range: true,
+    sourceType: 'module'
+  });
+
+  if (ast == null) {
+    throw `Failed to parse ${code} with @typescript-eslint/parser`;
+  }
+
+  const [flowAST, mutatedCode] = (0, _TSDefToFlowDef.TSDefToFlowDef)(code, ast, {
+    recoverFromErrors: false
+  });
+  return (0, _hermesTransform.print)(flowAST, mutatedCode, prettierOptions);
+}
+
+async function translateFlowImportsTo(code, prettierOptions = {}, opts) {
+  const {
+    ast,
+    scopeManager
+  } = await (0, _hermesTransform.parse)(code);
+  const jsAST = (0, _flowImportTo.flowImportTo)(ast, code, scopeManager, opts);
+  return (0, _hermesTransform.print)(jsAST, code, prettierOptions);
+}

package/dist/src/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/src/utils/ErrorUtils.js

@@ -0,0 +1,103 @@
+/**
+ * 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.buildCodeFrame = buildCodeFrame;
+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, highlightCode = process.env.NODE_ENV !== 'test') {
+  // 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,
+    message: message
+  });
+}

package/dist/src/utils/FlowAnalyze.js

@@ -0,0 +1,55 @@
+/**
+ * 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.analyzeFunctionReturn = analyzeFunctionReturn;
+exports.analyzeTypeDependencies = analyzeTypeDependencies;
+
+var _hermesTransform = require("hermes-transform");
+
+var _hermesParser = require("hermes-parser");
+
+function analyzeFunctionReturn(func) {
+  const returnType = func.returnType;
+
+  if (returnType != null) {
+    return returnType;
+  } // We trust Flow has validated this function to only return void
+  // $FlowFixMe[incompatible-return]
+
+
+  return _hermesTransform.t.TypeAnnotation({
+    typeAnnotation: _hermesTransform.t.VoidTypeAnnotation()
+  });
+}
+
+function analyzeTypeDependencies(rootNode, context) {
+  const deps = [];
+
+  _hermesParser.SimpleTraverser.traverse(rootNode, {
+    enter(node) {
+      if (node.type === 'Identifier' || node.type === 'JSXIdentifier') {
+        const variable = context.referenceMap.get(node);
+
+        if (variable != null) {
+          deps.push(variable.name);
+        }
+      }
+    },
+
+    leave() {}
+
+  });
+
+  return deps;
+}

package/dist/src/utils/TranslationUtils.js

@@ -0,0 +1,42 @@
+/**
+ * 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.createTranslationContext = createTranslationContext;
+
+function createTranslationContext(code, scopeManager, {
+  recoverFromErrors
+}) {
+  const referenceMap = new Map();
+  const variableMap = new Map();
+  const moduleScope = scopeManager.globalScope.childScopes[0];
+
+  if (moduleScope == null || moduleScope.type !== 'module') {
+    throw new Error('createTranslationContext: Module scope not found');
+  }
+
+  for (const variable of moduleScope.variables) {
+    for (const reference of variable.references) {
+      referenceMap.set(reference.identifier, variable);
+      variableMap.set(variable.name, variable);
+    }
+  }
+
+  return {
+    scopeManager,
+    referenceMap,
+    variableMap,
+    recoverFromErrors,
+    code
+  };
+}

package/dist/src/utils/ts-estree-ast-types.js

@@ -0,0 +1,30 @@
+/**
+ * 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
+ */
+
+/**
+ * The following types have been adapted by hand from
+ * https://unpkg.com/browse/@typescript-eslint/types@5.41.0/dist/generated/ast-spec.d.ts
+ *
+ * Changes:
+ * - remove and inline `ValueOf` type
+ * - `undefined` -> `void`
+ * - remove all `declare` keywords
+ * - comment out `bigint` type
+ *     -> flow doesn't support it yet
+ * - remove `range` and `loc` from `NodeOrTokenData`
+ *     -> during conversion our locations will be all off, so we'll rely on prettier to print later
+ * - make all properties readonly and all arrays $ReadOnlyArray
+ *     -> unlike TS - flow enforces subtype constraints strictly!
+ * - add `type` to interfaces that previously relied upon inheriting the `type`
+ *     -> this is because flow sentinel refinement does not check inherited members
+ * - create "Ambiguous" versions for some nodes that have unions (like PropertyDefinition, MemberDefinition)
+ *     -> makes it easier to construct them from other nodes that have unions
+ */
+'use strict';

package/dist/utils/ts-estree-ast-types.js.flow

@@ -350,7 +350,7 @@ export interface ExportDefaultDeclaration extends BaseNode {
    */
   +exportKind: ExportKind;
 }
-type ExportKind = ExportAndImportKind;
+export type ExportKind = ExportAndImportKind;
 export type ExportNamedDeclaration =
   | ExportNamedDeclarationWithoutSourceWithMultiple
   | ExportNamedDeclarationWithoutSourceWithSingle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flow-api-translator",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Toolkit for creating Flow and TypeScript compatible libraries from Flow source code.",
   "main": "dist/index.js",
   "license": "MIT",
@@ -13,10 +13,10 @@
     "@typescript-eslint/parser": "7.2.0",
     "@typescript-eslint/visitor-keys": "7.2.0",
     "flow-enums-runtime": "^0.0.6",
-    "hermes-eslint": "0.28.0",
-    "hermes-estree": "0.28.0",
-    "hermes-parser": "0.28.0",
-    "hermes-transform": "0.28.0",
+    "hermes-eslint": "0.29.0",
+    "hermes-estree": "0.29.0",
+    "hermes-parser": "0.29.0",
+    "hermes-transform": "0.29.0",
     "typescript": "5.3.2"
   },
   "peerDependencies": {