flow-api-translator 0.10.0

package/dist/utils/ErrorUtils.js.flow

@@ -0,0 +1,100 @@
+/**
+ * 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 {ObjectWithLoc, TypeAnnotationType} from 'hermes-estree';
+import type {TranslationContext} from './TranslationUtils';
+import type {DetachedNode} from 'hermes-transform';
+
+import {t} from 'hermes-transform';
+import {codeFrameColumns} from '@babel/code-frame';
+
+export function flowFixMeOrError(
+  container: ObjectWithLoc,
+  message: string,
+  context: TranslationContext,
+): DetachedNode<TypeAnnotationType> {
+  if (context.recoverFromErrors) {
+    return t.GenericTypeAnnotation({id: t.Identifier({name: '$FlowFixMe'})});
+  }
+  throw translationError(container, message, context);
+}
+
+class TranslationErrorBase extends Error {
+  name: string = 'TranslationError';
+  constructor(
+    node: ObjectWithLoc,
+    message: string,
+    context: $ReadOnly<{code: string, ...}>,
+  ) {
+    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}`,
+    );
+  }
+}
+
+export class ExpectedTranslationError extends TranslationErrorBase {
+  name: string = 'ExpectedTranslationError';
+}
+export function translationError(
+  node: ObjectWithLoc,
+  message: string,
+  context: $ReadOnly<{code: string, ...}>,
+): Error {
+  return new ExpectedTranslationError(node, message, context);
+}
+
+export class UnexpectedTranslationError extends TranslationErrorBase {
+  name: string = 'UnexpectedTranslationError';
+}
+export function unexpectedTranslationError(
+  node: ObjectWithLoc,
+  message: string,
+  context: $ReadOnly<{code: string, ...}>,
+): Error {
+  return new UnexpectedTranslationError(node, message, context);
+}
+
+function buildCodeFrame(
+  node: ObjectWithLoc,
+  message: string,
+  code: string,
+): string {
+  // 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 codeFrameColumns(code, locForBabel, {
+    linesAbove: 0,
+    linesBelow: 0,
+    highlightCode: process.env.NODE_ENV !== 'test',
+    message: message,
+  });
+}

package/dist/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/utils/FlowAnalyze.js.flow

@@ -0,0 +1,47 @@
+/**
+ * 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 {AFunction, TypeAnnotation, ESNode} from 'hermes-estree';
+import type {TranslationContext, Dep} from './TranslationUtils';
+
+import {t} from 'hermes-transform';
+import {SimpleTraverser} from 'hermes-parser';
+
+export function analyzeFunctionReturn(func: AFunction): TypeAnnotation {
+  const returnType = func.returnType;
+  if (returnType != null) {
+    return returnType;
+  }
+
+  // We trust Flow has validated this function to only return void
+  // $FlowFixMe[incompatible-return]
+  return t.TypeAnnotation({typeAnnotation: t.VoidTypeAnnotation()});
+}
+
+export function analyzeTypeDependencies(
+  rootNode: ESNode,
+  context: TranslationContext,
+): $ReadOnlyArray<Dep> {
+  const deps = [];
+  SimpleTraverser.traverse(rootNode, {
+    enter(node: ESNode) {
+      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/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/utils/TranslationUtils.js.flow

@@ -0,0 +1,44 @@
+/**
+ * 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 {Identifier, JSXIdentifier} from 'hermes-estree';
+import type {ScopeManager, Variable} from 'hermes-eslint';
+
+export type Dep = string;
+export type TranslationOptions = {recoverFromErrors: boolean};
+export type TranslationContext = {
+  scopeManager: ScopeManager,
+  referenceMap: Map<Identifier | JSXIdentifier, Variable>,
+  variableMap: Map<Dep, Variable>,
+  recoverFromErrors: boolean,
+  code: string,
+};
+
+export function createTranslationContext(
+  code: string,
+  scopeManager: ScopeManager,
+  {recoverFromErrors}: TranslationOptions,
+): TranslationContext {
+  const referenceMap = new Map<Identifier | JSXIdentifier, Variable>();
+  const variableMap = new Map<Dep, Variable>();
+  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/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';