flow-api-translator 0.331.0 → 0.333.0

package/dist/flowToFlowDef.js

@@ -10,6 +10,120 @@ var _TranslationUtils = require("./utils/TranslationUtils");
 var _ErrorUtils = require("./utils/ErrorUtils");
 var _flowEstree = require("flow-estree");
 const EMPTY_TRANSLATION_RESULT = [null, []];
+function isDocComment(comment) {
+  return comment.type === 'Block' && comment.value.startsWith('*') && !/@(flow|noflow|format)\b/.test(comment.value) && !comment.value.includes('Copyright');
+}
+function findDefaultExport(body) {
+  for (const statement of body) {
+    if (statement.type === 'ExportDefaultDeclaration' || statement.type === 'DeclareExportDeclaration' && statement.default === true) {
+      return statement;
+    }
+  }
+  return null;
+}
+function getExportedIdentifierName(defaultExport) {
+  const declaration = defaultExport.declaration;
+  if (declaration == null) {
+    return null;
+  }
+  let node = declaration;
+  while (node.type === 'AsExpression' || node.type === 'TypeCastExpression') {
+    node = node.expression;
+  }
+  if (node.type === 'TypeofTypeAnnotation') {
+    return node.argument.type === 'Identifier' ? node.argument.name : null;
+  }
+  return node.type === 'Identifier' ? node.name : null;
+}
+function findDeclarationByName(body, name) {
+  for (const statement of body) {
+    const declaration = statement.type === 'ExportNamedDeclaration' && statement.declaration != null ? statement.declaration : statement;
+    if ((declaration.type === 'ClassDeclaration' || declaration.type === 'FunctionDeclaration' || declaration.type === 'ComponentDeclaration') && declaration.id != null && declaration.id.name === name) {
+      return {
+        kind: declaration.type,
+        statement
+      };
+    }
+    if (declaration.type === 'VariableDeclaration' || declaration.type === 'DeclareVariable') {
+      for (const declarator of declaration.declarations) {
+        if (declarator.id.type === 'Identifier' && declarator.id.name === name) {
+          return {
+            kind: declaration.type,
+            statement
+          };
+        }
+      }
+    }
+  }
+  return null;
+}
+function findDisplayName(body, name) {
+  for (const statement of body) {
+    if (statement.type === 'ExpressionStatement' && statement.expression.type === 'AssignmentExpression') {
+      const {
+        left,
+        right
+      } = statement.expression;
+      if (left.type === 'MemberExpression' && left.object.type === 'Identifier' && left.object.name === name && left.property.type === 'Identifier' && left.property.name === 'displayName' && right.type === 'Literal' && typeof right.value === 'string') {
+        return right.value;
+      }
+    }
+  }
+  return null;
+}
+function applyDefaultExportDocPlacement(body, translatedStatements, placement, code) {
+  if (placement === 'declaration') {
+    return code;
+  }
+  const defaultExport = findDefaultExport(body);
+  if (defaultExport == null || (0, _flowTransform.getLeadingCommentsForNode)(defaultExport).some(isDocComment)) {
+    return code;
+  }
+  const exportedName = getExportedIdentifierName(defaultExport);
+  if (exportedName == null) {
+    return code;
+  }
+  const exportedDeclaration = findDeclarationByName(body, exportedName);
+  if ((exportedDeclaration == null ? void 0 : exportedDeclaration.kind) === 'ClassDeclaration') {
+    return code;
+  }
+  const sources = [];
+  if (exportedDeclaration != null) {
+    sources.push(exportedDeclaration);
+  }
+  const displayName = findDisplayName(body, exportedName);
+  if (displayName != null && displayName !== exportedName) {
+    const displayNameDeclaration = findDeclarationByName(body, displayName);
+    if (displayNameDeclaration != null) {
+      sources.push(displayNameDeclaration);
+    }
+  }
+  const translatedDefaultExport = translatedStatements.get(defaultExport);
+  if (translatedDefaultExport == null) {
+    return code;
+  }
+  for (const source of sources) {
+    const docComments = (0, _flowTransform.getLeadingCommentsForNode)(source.statement).filter(isDocComment);
+    if (docComments.length === 0) {
+      continue;
+    }
+    let mutatedCode = code;
+    const clonedComments = docComments.map(comment => {
+      const clonedComment = (0, _flowTransform.cloneCommentWithMarkers)(comment);
+      mutatedCode = (0, _flowTransform.makeCommentOwnLine)(mutatedCode, clonedComment);
+      return clonedComment;
+    });
+    (0, _flowTransform.setCommentsOnNode)(translatedDefaultExport, [...(0, _flowTransform.getCommentsForNode)(translatedDefaultExport), ...clonedComments]);
+    if (placement === 'export') {
+      const translatedSource = translatedStatements.get(source.statement);
+      if (translatedSource != null) {
+        (0, _flowTransform.setCommentsOnNode)(translatedSource, (0, _flowTransform.getCommentsForNode)(translatedSource).filter(comment => !docComments.includes(comment)));
+      }
+    }
+    return mutatedCode;
+  }
+  return code;
+}
 function convertArray(items, convert) {
   const resultItems = [];
   const deps = [];
@@ -39,7 +153,7 @@ function transferProgramStatementProperties(stmt, orgStmt) {
   stmt.loc = orgStmt.loc;
 }
 function flowToFlowDef(ast, code, scopeManager, opts) {
-  var _ast$interpreter$valu, _ast$interpreter;
+  var _opts$defaultExportDo, _ast$interpreter$valu, _ast$interpreter;
   const context = (0, _TranslationUtils.createTranslationContext)(code, scopeManager, opts);
   const translatedStatements = new Map();
   function storeTranslatedStatement(stmt, orgStmt) {
@@ -100,9 +214,11 @@ function flowToFlowDef(ast, code, scopeManager, opts) {
     if (translatedStatement != null) {
       const optimizedStatement = stripUnusedDefs(translatedStatement, seenDeps, context);
       transferProgramStatementProperties(optimizedStatement, stmt);
+      storeTranslatedStatement(optimizedStatement, stmt);
       translatedBody.push(optimizedStatement);
     }
   }
+  const outputCode = applyDefaultExportDocPlacement(ast.body, translatedStatements, (_opts$defaultExportDo = opts.defaultExportDocPlacement) != null ? _opts$defaultExportDo : 'declaration', code);
   return [_flowTransform.t.Program({
     body: translatedBody,
     sourceType: ast.sourceType,
@@ -110,7 +226,7 @@ function flowToFlowDef(ast, code, scopeManager, opts) {
     comments: ast.comments,
     tokens: ast.tokens,
     docblock: ast.docblock
-  }), code];
+  }), outputCode];
 }
 function convertExport(stmt, context) {
   switch (stmt.type) {
@@ -740,6 +856,9 @@ function convertSuperClass(superClass, superTypeArguments, context) {
       {
         const typeAnnotation = superClass.type === 'TypeCastExpression' ? superClass.typeAnnotation.typeAnnotation : superClass.typeAnnotation;
         if (typeAnnotation.type === 'GenericTypeAnnotation') {
+          if (typeAnnotation.id.type === 'ImportType') {
+            throw (0, _ErrorUtils.translationError)(superClass, 'SuperClass: Import type not supported', context);
+          }
           return convertSuperClassHelper((0, _flowTransform.asDetachedNode)(typeAnnotation.id), typeAnnotation, superTypeArguments, context);
         }
         if (typeAnnotation.type === 'TypeofTypeAnnotation') {

package/dist/flowToFlowDef.js.flow

@@ -22,8 +22,10 @@ import type {
   ComponentDeclaration,
   ComponentParameter,
   ComponentTypeParameter,
+  Comment,
   DeclareClass,
   DeclareComponent,
+  DeclareExportDeclaration,
   DeclareHook,
   DeclareFunction,
   DeclareOpaqueType,
@@ -68,6 +70,7 @@ import type {
 import type {ScopeManager} from 'flow-eslint';
 import type {DetachedNode} from 'flow-transform';
 import type {
+  DefaultExportDocPlacement,
   Dep,
   TranslationContext,
   TranslationOptions,
@@ -79,7 +82,14 @@ import {
   analyzeTypeDependencies,
 } from './utils/FlowAnalyze';
 import {createTranslationContext} from './utils/TranslationUtils';
-import {asDetachedNode} from 'flow-transform';
+import {
+  asDetachedNode,
+  cloneCommentWithMarkers,
+  getCommentsForNode,
+  getLeadingCommentsForNode,
+  makeCommentOwnLine,
+  setCommentsOnNode,
+} from 'flow-transform';
 import {translationError, flowFixMeOrError} from './utils/ErrorUtils';
 import {
   isExpression,
@@ -103,6 +113,223 @@ type TranslatedResult<T> = [DetachedNode<T>, TranslatedDeps];
 
 type ProgramStatement = Statement | ModuleDeclaration;
 
+type DefaultExport = ExportDefaultDeclaration | DeclareExportDeclaration;
+
+type DeclarationMatch = {
+  kind: string,
+  statement: ProgramStatement,
+};
+
+/**
+ * A JSDoc-style block comment (`/** ... *\/`), excluding the license/pragma
+ * docblock, which describes the module rather than the exported value.
+ */
+function isDocComment(comment: Comment): boolean {
+  return (
+    comment.type === 'Block' &&
+    comment.value.startsWith('*') &&
+    !/@(flow|noflow|format)\b/.test(comment.value) &&
+    !comment.value.includes('Copyright')
+  );
+}
+
+function findDefaultExport(
+  body: ReadonlyArray<ProgramStatement>,
+): ?DefaultExport {
+  for (const statement of body) {
+    if (
+      statement.type === 'ExportDefaultDeclaration' ||
+      (statement.type === 'DeclareExportDeclaration' &&
+        statement.default === true)
+    ) {
+      return statement;
+    }
+  }
+  return null;
+}
+
+/**
+ * Name of the exported identifier, unwrapping `as` casts and the `typeof X`
+ * form. Returns `null` for inline/anonymous declarations.
+ */
+function getExportedIdentifierName(defaultExport: DefaultExport): ?string {
+  const declaration = defaultExport.declaration;
+  if (declaration == null) {
+    return null;
+  }
+
+  let node: ESNode = declaration;
+  while (node.type === 'AsExpression' || node.type === 'TypeCastExpression') {
+    node = node.expression;
+  }
+  if (node.type === 'TypeofTypeAnnotation') {
+    return node.argument.type === 'Identifier' ? node.argument.name : null;
+  }
+  return node.type === 'Identifier' ? node.name : null;
+}
+
+function findDeclarationByName(
+  body: ReadonlyArray<ProgramStatement>,
+  name: string,
+): ?DeclarationMatch {
+  for (const statement of body) {
+    const declaration =
+      statement.type === 'ExportNamedDeclaration' &&
+      statement.declaration != null
+        ? statement.declaration
+        : statement;
+
+    if (
+      (declaration.type === 'ClassDeclaration' ||
+        declaration.type === 'FunctionDeclaration' ||
+        declaration.type === 'ComponentDeclaration') &&
+      declaration.id != null &&
+      declaration.id.name === name
+    ) {
+      return {kind: declaration.type, statement};
+    }
+
+    // `DeclareVariable` is `declare const X` in an already-declaration input
+    if (
+      declaration.type === 'VariableDeclaration' ||
+      declaration.type === 'DeclareVariable'
+    ) {
+      for (const declarator of declaration.declarations) {
+        if (
+          declarator.id.type === 'Identifier' &&
+          declarator.id.name === name
+        ) {
+          return {kind: declaration.type, statement};
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function findDisplayName(
+  body: ReadonlyArray<ProgramStatement>,
+  name: string,
+): ?string {
+  for (const statement of body) {
+    if (
+      statement.type === 'ExpressionStatement' &&
+      statement.expression.type === 'AssignmentExpression'
+    ) {
+      const {left, right} = statement.expression;
+      if (
+        left.type === 'MemberExpression' &&
+        left.object.type === 'Identifier' &&
+        left.object.name === name &&
+        left.property.type === 'Identifier' &&
+        left.property.name === 'displayName' &&
+        right.type === 'Literal' &&
+        typeof right.value === 'string'
+      ) {
+        return right.value;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Associate a declaration's documentation with the module's default export.
+ *
+ * Stripping the runtime implementation leaves the documentation on the
+ * declaration the `export default` aliases via `typeof`, which is not the
+ * symbol TypeScript resolves a default re-export to. Returns the (possibly
+ * mutated) source text, since cloned comments need a range that makes prettier
+ * print them on their own line.
+ */
+function applyDefaultExportDocPlacement(
+  body: ReadonlyArray<ProgramStatement>,
+  translatedStatements: Map<ProgramStatement, DetachedNode<ProgramStatement>>,
+  placement: DefaultExportDocPlacement,
+  code: string,
+): string {
+  if (placement === 'declaration') {
+    return code;
+  }
+
+  const defaultExport = findDefaultExport(body);
+  if (
+    defaultExport == null ||
+    // Leave already-documented (and inline) default exports untouched.
+    getLeadingCommentsForNode(defaultExport).some(isDocComment)
+  ) {
+    return code;
+  }
+
+  const exportedName = getExportedIdentifierName(defaultExport);
+  if (exportedName == null) {
+    return code;
+  }
+
+  const exportedDeclaration = findDeclarationByName(body, exportedName);
+  // A directly-exported class keeps its declaration, where TypeScript already
+  // resolves the documentation; moving it would hide it.
+  if (exportedDeclaration?.kind === 'ClassDeclaration') {
+    return code;
+  }
+
+  // Statements whose leading comment may document the default export, in
+  // priority order.
+  const sources: Array<DeclarationMatch> = [];
+  if (exportedDeclaration != null) {
+    sources.push(exportedDeclaration);
+  }
+  // Renamed wrappers (e.g. `memo`-wrapped) carry the documentation on the
+  // declaration matching the display name.
+  const displayName = findDisplayName(body, exportedName);
+  if (displayName != null && displayName !== exportedName) {
+    const displayNameDeclaration = findDeclarationByName(body, displayName);
+    if (displayNameDeclaration != null) {
+      sources.push(displayNameDeclaration);
+    }
+  }
+
+  const translatedDefaultExport = translatedStatements.get(defaultExport);
+  if (translatedDefaultExport == null) {
+    return code;
+  }
+
+  for (const source of sources) {
+    const docComments = getLeadingCommentsForNode(source.statement).filter(
+      isDocComment,
+    );
+    if (docComments.length === 0) {
+      continue;
+    }
+
+    let mutatedCode = code;
+    const clonedComments = docComments.map(comment => {
+      const clonedComment = cloneCommentWithMarkers(comment);
+      mutatedCode = makeCommentOwnLine(mutatedCode, clonedComment);
+      return clonedComment;
+    });
+    setCommentsOnNode(translatedDefaultExport, [
+      ...getCommentsForNode(translatedDefaultExport),
+      ...clonedComments,
+    ]);
+
+    if (placement === 'export') {
+      const translatedSource = translatedStatements.get(source.statement);
+      if (translatedSource != null) {
+        setCommentsOnNode(
+          translatedSource,
+          getCommentsForNode(translatedSource).filter(
+            comment => !docComments.includes(comment),
+          ),
+        );
+      }
+    }
+    return mutatedCode;
+  }
+
+  return code;
+}
+
 function convertArray<TIn, TOut>(
   items: ReadonlyArray<TIn>,
   convert: TIn => TranslatedResultOrNull<TOut>,
@@ -246,10 +473,18 @@ export default function flowToFlowDef(
         context,
       );
       transferProgramStatementProperties(optimizedStatement, stmt);
+      storeTranslatedStatement(optimizedStatement, stmt);
       translatedBody.push(optimizedStatement);
     }
   }
 
+  const outputCode = applyDefaultExportDocPlacement(
+    ast.body,
+    translatedStatements,
+    opts.defaultExportDocPlacement ?? 'declaration',
+    code,
+  );
+
   return [
     t.Program({
       body: translatedBody,
@@ -259,7 +494,7 @@ export default function flowToFlowDef(
       tokens: ast.tokens,
       docblock: ast.docblock,
     }),
-    code,
+    outputCode,
   ];
 }
 
@@ -1193,6 +1428,13 @@ function convertSuperClass(
           : superClass.typeAnnotation;
 
       if (typeAnnotation.type === 'GenericTypeAnnotation') {
+        if (typeAnnotation.id.type === 'ImportType') {
+          throw translationError(
+            superClass,
+            'SuperClass: Import type not supported',
+            context,
+          );
+        }
         return convertSuperClassHelper(
           asDetachedNode(typeAnnotation.id),
           typeAnnotation,

package/dist/index.js

@@ -24,21 +24,22 @@ async function translateFlowToFlowDef(code, prettierOptions = {}, opts) {
     scopeManager
   } = await (0, _flowTransform.parse)(code);
   const [flowDefAst, mutatedCode] = (0, _flowToFlowDef.default)(ast, code, scopeManager, {
-    recoverFromErrors: true,
-    mungeUnderscores: opts == null ? void 0 : opts.mungeUnderscores
+    ...opts,
+    recoverFromErrors: true
   });
   return (0, _flowTransform.print)(flowDefAst, mutatedCode, prettierOptions);
 }
-async function translateFlowToTSDef(code, prettierOptions = {}) {
-  const flowDefCode = await translateFlowToFlowDef(code, prettierOptions);
-  return translateFlowDefToTSDef(flowDefCode, prettierOptions);
+async function translateFlowToTSDef(code, prettierOptions = {}, opts) {
+  const flowDefCode = await translateFlowToFlowDef(code, prettierOptions, opts);
+  return translateFlowDefToTSDef(flowDefCode, prettierOptions, opts);
 }
-async function translateFlowDefToTSDef(code, prettierOptions = {}) {
+async function translateFlowDefToTSDef(code, prettierOptions = {}, opts) {
   const {
     ast,
     scopeManager
   } = await (0, _flowTransform.parse)(code);
   const [tsAST, mutatedCode] = (0, _flowDefToTSDef.flowDefToTSDef)(code, ast, scopeManager, {
+    ...opts,
     recoverFromErrors: true
   });
   return (0, _flowTransform.print)(tsAST, mutatedCode, {

package/dist/index.js.flow

@@ -11,6 +11,10 @@
 'use strict';
 
 import type {MapperOptions} from './flowImportTo';
+import type {
+  DefaultExportDocPlacement,
+  TranslationOptions,
+} from './utils/TranslationUtils';
 
 import {parse, print} from 'flow-transform';
 import {parse as parseTS} from '@typescript-eslint/parser';
@@ -21,16 +25,21 @@ import {flowToJS} from './flowToJS';
 import {flowImportTo} from './flowImportTo';
 import {TSDefToFlowDef} from './TSDefToFlowDef';
 
+// `recoverFromErrors` is deliberately not exposed: the entry points always recover.
+export type TranslateOptions = Omit<TranslationOptions, 'recoverFromErrors'>;
+
+export type {DefaultExportDocPlacement};
+
 export async function translateFlowToFlowDef(
   code: string,
   prettierOptions: {...} = {},
-  opts?: {mungeUnderscores?: boolean},
+  opts?: TranslateOptions,
 ): Promise<string> {
   const {ast, scopeManager} = await parse(code);
 
   const [flowDefAst, mutatedCode] = flowToFlowDef(ast, code, scopeManager, {
+    ...opts,
     recoverFromErrors: true,
-    mungeUnderscores: opts?.mungeUnderscores,
   });
 
   return print(flowDefAst, mutatedCode, prettierOptions);
@@ -39,18 +48,21 @@ export async function translateFlowToFlowDef(
 export async function translateFlowToTSDef(
   code: string,
   prettierOptions: {...} = {},
+  opts?: TranslateOptions,
 ): Promise<string> {
-  const flowDefCode = await translateFlowToFlowDef(code, prettierOptions);
+  const flowDefCode = await translateFlowToFlowDef(code, prettierOptions, opts);
 
-  return translateFlowDefToTSDef(flowDefCode, prettierOptions);
+  return translateFlowDefToTSDef(flowDefCode, prettierOptions, opts);
 }
 
 export async function translateFlowDefToTSDef(
   code: string,
   prettierOptions: {...} = {},
+  opts?: TranslateOptions,
 ): Promise<string> {
   const {ast, scopeManager} = await parse(code);
   const [tsAST, mutatedCode] = flowDefToTSDef(code, ast, scopeManager, {
+    ...opts,
     recoverFromErrors: true,
   });
 

package/dist/src/TSDefToFlowDef.js

@@ -264,11 +264,15 @@ const getTransforms = (originalCode, opts) => {
           value: node.source.value,
           raw: node.source.raw
         });
-        const specifiers = node.specifiers.map(specifier => constructFlowNode({
-          type: 'ExportSpecifier',
-          local: Transform.Identifier(specifier.local),
-          exported: Transform.Identifier(specifier.exported)
-        }));
+        const specifiers = node.specifiers.map(specifier => {
+          var _specifier$exportKind;
+          return constructFlowNode({
+            type: 'ExportSpecifier',
+            local: Transform.Identifier(specifier.local),
+            exported: Transform.Identifier(specifier.exported),
+            exportKind: (_specifier$exportKind = specifier.exportKind) != null ? _specifier$exportKind : 'value'
+          });
+        });
         return constructFlowNode({
           type: 'DeclareExportDeclaration',
           declaration: null,
@@ -318,7 +322,8 @@ const getTransforms = (originalCode, opts) => {
               specifiers: [constructFlowNode({
                 type: 'ExportSpecifier',
                 local: decl.id,
-                exported: decl.id
+                exported: decl.id,
+                exportKind: 'value'
               })]
             })];
           }
@@ -814,6 +819,9 @@ const getTransforms = (originalCode, opts) => {
       const namesRev = [];
       while (qualifier.type !== 'Identifier') {
         namesRev.push(qualifier.id.name);
+        if (qualifier.qualification.type === 'ImportType') {
+          return unsupportedAnnotation(node, 'nested import types in import type qualifiers');
+        }
         qualifier = qualifier.qualification;
       }
       namesRev.push(qualifier.name);
@@ -949,10 +957,12 @@ const getTransforms = (originalCode, opts) => {
         keyTparam,
         propType: Transform.TSTypeAnnotationOpt(node.typeAnnotation),
         sourceType,
-        variance: node.readonly === '+' || Boolean(node.readonly) ? constructFlowNode({
+        nameType: node.nameType == null ? null : Transform.TSTypeAnnotation(node.nameType),
+        variance: node.readonly != null && node.readonly !== false ? constructFlowNode({
           type: 'Variance',
           kind: 'plus'
         }) : null,
+        varianceOp: node.readonly === '+' ? '+' : node.readonly === '-' ? '-' : null,
         optional: node.optional === '+' ? 'PlusOptional' : node.optional === '-' ? 'MinusOptional' : Boolean(node.optional) ? 'Optional' : null
       });
       return constructFlowNode({