hermes-transform 0.5.0 → 0.8.0

package/dist/transform/TransformContext.js.flow

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) Facebook, Inc. and its affiliates.
+ * 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.
@@ -9,9 +9,11 @@
  */
 
 import type {
+  ClassMember,
   Comment,
   ESNode,
   Expression,
+  FunctionParameter,
   ModuleDeclaration,
   Statement,
   TypeAnnotationType,
@@ -19,36 +21,38 @@ import type {
 import type {DetachedNode} from '../detachedNode';
 import type {TransformCloneSignatures} from '../generated/TransformCloneSignatures';
 import type {TransformReplaceSignatures} from '../generated/TransformReplaceSignatures';
-import type {AddLeadingCommentsMutation} from './mutations/AddLeadingComments';
-import type {AddTrailingCommentsMutation} from './mutations/AddTrailingComments';
+import type {TraversalContext} from '../traverse/traverse';
+import type {AddCommentsMutation} from './mutations/AddComments';
 import type {CloneCommentsToMutation} from './mutations/CloneCommentsTo';
 import type {InsertStatementMutation} from './mutations/InsertStatement';
 import type {RemoveCommentMutation} from './mutations/RemoveComment';
+import type {RemoveNodeMutation} from './mutations/RemoveNode';
 import type {RemoveStatementMutation} from './mutations/RemoveStatement';
 import type {ReplaceNodeMutation} from './mutations/ReplaceNode';
 import type {ReplaceStatementWithManyMutation} from './mutations/ReplaceStatementWithMany';
 
 import {deepCloneNode, shallowCloneNode} from '../detachedNode';
 import {
+  CommentPlacement,
   getCommentsForNode,
   isLeadingComment,
   isTrailingComment,
 } from './comments/comments';
-import {createAddLeadingCommentsMutation} from './mutations/AddLeadingComments';
-import {createAddTrailingCommentsMutation} from './mutations/AddTrailingComments';
+import {createAddCommentsMutation} from './mutations/AddComments';
 import {createCloneCommentsToMutation} from './mutations/CloneCommentsTo';
 import {createInsertStatementMutation} from './mutations/InsertStatement';
 import {createRemoveCommentMutation} from './mutations/RemoveComment';
+import {createRemoveNodeMutation} from './mutations/RemoveNode';
 import {createRemoveStatementMutation} from './mutations/RemoveStatement';
 import {createReplaceNodeMutation} from './mutations/ReplaceNode';
 import {createReplaceStatementWithManyMutation} from './mutations/ReplaceStatementWithMany';
 
 type Mutation = $ReadOnly<
-  | AddLeadingCommentsMutation
-  | AddTrailingCommentsMutation
+  | AddCommentsMutation
   | CloneCommentsToMutation
   | InsertStatementMutation
   | RemoveCommentMutation
+  | RemoveNodeMutation
   | RemoveStatementMutation
   | ReplaceNodeMutation
   | ReplaceStatementWithManyMutation,
@@ -65,12 +69,10 @@ type ReplaceNodeOptions = $ReadOnly<{
   keepComments?: boolean,
 }>;
 
-export type TransformContext = $ReadOnly<{
-  mutations: $ReadOnlyArray<Mutation>,
-  astWasMutated: boolean,
-
+type TransformCloneAPIs = $ReadOnly<{
   /**
-   * Shallowly clones the given node and applies the given overrides.
+   * Shallowly clones the given node.
+   *
    * !!! Be careful about using this !!!
    * This does not clone children nodes. This means that if you keep
    * the original node in the AST then you will have two trees in the
@@ -84,12 +86,17 @@ export type TransformContext = $ReadOnly<{
    * If you want to literally duplicate a node to place somewhere else
    * in the AST, then use `deepCloneNode` instead.
    */
-  shallowCloneNode: TransformCloneSignatures & {
-    // generic passthrough cases with no options
+  shallowCloneNode: {
     <T: ESNode>(node: T): DetachedNode<T>,
     <T: ESNode>(node: ?T): DetachedNode<T> | null,
   },
 
+  /**
+   * Shallowly clones the given node and applies the given overrides.
+   * {@see shallowCloneNode}
+   */
+  shallowCloneNodeWithOverrides: TransformCloneSignatures,
+
   /**
    * {@see shallowCloneNode}
    */
@@ -99,25 +106,99 @@ export type TransformContext = $ReadOnly<{
   },
 
   /**
-   * Deeply clones the node and all its children, then applies the
-   * given overrides.
+   * Deeply clones the node and all its children.
+   *
    * !!! Be careful about using this !!!
    * Because this is a deep clone, using it high up in the AST can
    * result in a lot of work being done.
    */
-  deepCloneNode: TransformCloneSignatures & {
-    // generic passthrough cases with no options
+  deepCloneNode: {
     <T: ESNode>(node: T): DetachedNode<T>,
     <T: ESNode>(node: ?T): DetachedNode<T> | null,
   },
 
+  /**
+   * Deeply clones the node and all its children, then applies the
+   * given overrides.
+   * {@see deepCloneNode}
+   */
+  deepCloneNodeWithOverrides: TransformCloneSignatures,
+}>;
+
+type TransformCommentAPIs = $ReadOnly<{
+  /**
+   * Gets all of the comments attached to the given node.
+   */
+  getComments: (node: ESNode) => Array<Comment>,
+
+  /**
+   * Gets the leading comments attached to the given node.
+   */
+  getLeadingComments: (node: ESNode) => Array<Comment>,
+
+  /**
+   * Gets the trailing comments attached to the given node.
+   */
+  getTrailingComments: (node: ESNode) => Array<Comment>,
+
+  /**
+   * Clones all of the comments from the target node to the destination node.
+   * As its name suggest - this will clone the comments, duplicating them
+   * entirely. It will not remove the comments from the target node afterward.
+   */
+  cloneCommentsTo: (
+    target: ESNode,
+    destination: ESNode | DetachedNode<ESNode>,
+  ) => void,
+
+  /**
+   * Add comments on the line before a specified node.
+   */
+  addLeadingComments: (
+    node: ESNode | DetachedNode<ESNode>,
+    comments: SingleOrArray<Comment>,
+  ) => void,
+
+  /**
+   * Add comments inline before a specified node.
+   */
+  addLeadingInlineComments: (
+    node: ESNode | DetachedNode<ESNode>,
+    comments: SingleOrArray<Comment>,
+  ) => void,
+
+  /**
+   * Add comments on the line after a specified node.
+   */
+  addTrailingComments: (
+    node: ESNode | DetachedNode<ESNode>,
+    comments: SingleOrArray<Comment>,
+  ) => void,
+
+  /**
+   * Add comments inline after a specified node.
+   */
+  addTrailingInlineComments: (
+    node: ESNode | DetachedNode<ESNode>,
+    comments: SingleOrArray<Comment>,
+  ) => void,
+
+  /**
+   * Removes the specified comments
+   */
+  removeComments: (comments: SingleOrArray<Comment>) => void,
+}>;
+
+type TransformInsertAPIs = $ReadOnly<{
   /**
    * Insert `nodeToInsert` after the `target` statement.
    * The inserted nodes will be kept in the order given.
    */
   insertAfterStatement: (
-    target: ModuleDeclaration | Statement,
-    nodeToInsert: SingleOrArray<DetachedNode<ModuleDeclaration | Statement>>,
+    target: InsertStatementMutation['target'],
+    nodeToInsert: SingleOrArray<
+      DetachedNode<InsertStatementMutation['target']>,
+    >,
   ) => void,
 
   /**
@@ -125,39 +206,69 @@ export type TransformContext = $ReadOnly<{
    * The inserted nodes will be kept in the order given.
    */
   insertBeforeStatement: (
-    target: ModuleDeclaration | Statement,
-    nodeToInsert: SingleOrArray<DetachedNode<ModuleDeclaration | Statement>>,
+    target: InsertStatementMutation['target'],
+    nodeToInsert: SingleOrArray<
+      DetachedNode<InsertStatementMutation['target']>,
+    >,
   ) => void,
+}>;
+
+type TransformRemoveAPIs = $ReadOnly<{
+  /**
+   * Removes a given node from the AST.
+   * The set of thigns that can be removed is intentionally restricted by types.
+   * This represents the set of "misc nodes" that are known to be safe to remove without outright breaking the AST.
+   */
+  removeNode: (node: RemoveNodeMutation['node']) => void,
 
+  /**
+   * Removes a given statement from the AST.
+   */
+  removeStatement: (node: RemoveStatementMutation['node']) => void,
+}>;
+
+type TransformReplaceAPIs = $ReadOnly<{
   /**
    * Replace the `target` node with the `nodeToReplaceWith` node.
    * This simply does an in-place replacement in the AST.
    */
   replaceNode: {
-    // expressions must be replaced with other expressions
+    // Expressions may be replaced with other expressions
     (
       target: Expression,
       nodeToReplaceWith: DetachedNode<Expression>,
       options?: ReplaceNodeOptions,
     ): void,
-    // module declarations must be replaced with statements or other module declarations
+    // Module declarations may be replaced with statements or other module declarations
     (
       target: ModuleDeclaration,
       nodeToReplaceWith: DetachedNode<ModuleDeclaration | Statement>,
       options?: ReplaceNodeOptions,
     ): void,
-    // Statement must be replaced with statements or module declarations
+    // Statement maybe be replaced with statements or module declarations
     (
       target: Statement,
       nodeToReplaceWith: DetachedNode<ModuleDeclaration | Statement>,
       options?: ReplaceNodeOptions,
     ): void,
-    // Types must be replaced with types
+    // Types maybe be replaced with other types
     (
       target: TypeAnnotationType,
       nodeToReplaceWith: DetachedNode<TypeAnnotationType>,
       options?: ReplaceNodeOptions,
     ): void,
+    // Class members may be replaced with other class members
+    (
+      target: ClassMember,
+      nodeToReplaceWith: DetachedNode<ClassMember>,
+      options?: ReplaceNodeOptions,
+    ): void,
+    // Function params amy be replace with other function params
+    (
+      target: FunctionParameter,
+      nodeToReplaceWith: DetachedNode<FunctionParameter>,
+      options?: ReplaceNodeOptions,
+    ): void,
   } & TransformReplaceSignatures, // allow like-for-like replacements as well
 
   /**
@@ -165,10 +276,8 @@ export type TransformContext = $ReadOnly<{
    * The nodes will be kept in the order given.
    */
   replaceStatementWithMany: (
-    target: ModuleDeclaration | Statement,
-    nodesToReplaceWith: $ReadOnlyArray<
-      DetachedNode<ModuleDeclaration | Statement>,
-    >,
+    target: ReplaceStatementWithManyMutation['target'],
+    nodesToReplaceWith: ReplaceStatementWithManyMutation['nodesToReplaceWith'],
     options?: {
       /**
        * Moves the comments from the target node to the first node in the array.
@@ -178,64 +287,21 @@ export type TransformContext = $ReadOnly<{
       keepComments?: boolean,
     },
   ) => void,
+}>;
 
-  /**
-   * Removes a given node from the AST.
-   */
-  removeStatement: (node: ModuleDeclaration | Statement) => void,
-
-  //
-  // Comment APIs
-  //
-
-  /**
-   * Gets all of the comments attached to the given node.
-   */
-  getComments: (node: ESNode) => Array<Comment>,
-
-  /**
-   * Gets the leading comments attached to the given node.
-   */
-  getLeadingComments: (node: ESNode) => Array<Comment>,
-
-  /**
-   * Gets the trailing comments attached to the given node.
-   */
-  getTrailingComments: (node: ESNode) => Array<Comment>,
-
-  /**
-   * Clones all of the comments from the target node to the destination node.
-   * As its name suggest - this will clone the comments, duplicating them
-   * entirely. It will not remove the comments from the target node afterward.
-   */
-  cloneCommentsTo: (
-    target: ESNode,
-    destination: ESNode | DetachedNode<ESNode>,
-  ) => void,
-
-  /**
-   * Add leading comments to the specified node.
-   */
-  addLeadingComments: (
-    node: ESNode | DetachedNode<ESNode>,
-    comments: SingleOrArray<Comment>,
-  ) => void,
-
-  /**
-   * Add trailing comments to the specified node.
-   */
-  addTrailingComments: (
-    node: ESNode | DetachedNode<ESNode>,
-    comments: SingleOrArray<Comment>,
-  ) => void,
+export type TransformContextAdditions = $ReadOnly<{
+  mutations: $ReadOnlyArray<Mutation>,
+  astWasMutated: boolean,
 
-  /**
-   * Removes the specified comments
-   */
-  removeComments: (comments: SingleOrArray<Comment>) => void,
+  ...TransformCommentAPIs,
+  ...TransformCloneAPIs,
+  ...TransformInsertAPIs,
+  ...TransformRemoveAPIs,
+  ...TransformReplaceAPIs,
 }>;
+export type TransformContext = TraversalContext<TransformContextAdditions>;
 
-export function getTransformContext(): TransformContext {
+export function getTransformContext(): TransformContextAdditions {
   /**
    * The mutations in order of collection.
    */
@@ -246,27 +312,29 @@ export function getTransformContext(): TransformContext {
     }
   }
 
-  return {
-    mutations,
+  const cloneAPIs: TransformCloneAPIs = {
+    shallowCloneNode: ((
+      node: ?ESNode,
+    ): // $FlowExpectedError[incompatible-cast]
+    ?DetachedNode<ESNode> => {
+      if (node == null) {
+        return null;
+      }
 
-    // $FlowExpectedError[unsafe-getters-setters]
-    get astWasMutated(): boolean {
-      return mutations.length > 0;
-    },
+      return shallowCloneNode(node);
+    }: TransformCloneAPIs['shallowCloneNode']),
 
     // $FlowExpectedError[incompatible-exact]
-    shallowCloneNode: ((
+    shallowCloneNodeWithOverrides: ((
       node: ?ESNode,
       newProps?: $ReadOnly<{...}>,
-    ): // $FlowExpectedError[incompatible-cast]
-    // $FlowExpectedError[prop-missing]
-    ?DetachedNode<ESNode> => {
+    ): ?DetachedNode<ESNode> => {
       if (node == null) {
         return null;
       }
 
       return shallowCloneNode(node, newProps);
-    }: TransformContext['shallowCloneNode']),
+    }: TransformCloneAPIs['shallowCloneNodeWithOverrides']),
 
     shallowCloneArray: (<T: ESNode>(
       nodes: ?$ReadOnlyArray<T>,
@@ -277,48 +345,139 @@ export function getTransformContext(): TransformContext {
       }
 
       return nodes.map(node => shallowCloneNode<T>(node));
-    }: TransformContext['shallowCloneArray']),
+    }: TransformCloneAPIs['shallowCloneArray']),
 
-    // $FlowExpectedError[incompatible-exact]
     deepCloneNode: ((
       node: ?ESNode,
-      newProps?: $ReadOnly<{...}>,
     ): // $FlowExpectedError[incompatible-cast]
-    // $FlowExpectedError[prop-missing]
     ?DetachedNode<ESNode> => {
       if (node == null) {
         return null;
       }
 
+      return deepCloneNode(node);
+    }: TransformCloneAPIs['deepCloneNode']),
+
+    // $FlowExpectedError[incompatible-exact]
+    deepCloneNodeWithOverrides: ((
+      node: ?ESNode,
+      newProps?: $ReadOnly<{...}>,
+    ): ?DetachedNode<ESNode> => {
+      if (node == null) {
+        return null;
+      }
+
       return deepCloneNode(node, newProps);
-    }: TransformContext['deepCloneNode']),
+    }: TransformCloneAPIs['deepCloneNodeWithOverrides']),
+  };
+  const commentAPIs: TransformCommentAPIs = {
+    getComments: ((node): Array<Comment> => {
+      return [...getCommentsForNode(node)];
+    }: TransformCommentAPIs['getComments']),
+
+    getLeadingComments: ((node): Array<Comment> => {
+      return getCommentsForNode(node).filter(isLeadingComment);
+    }: TransformCommentAPIs['getLeadingComments']),
+
+    getTrailingComments: ((node): Array<Comment> => {
+      return getCommentsForNode(node).filter(isTrailingComment);
+    }: TransformCommentAPIs['getTrailingComments']),
+
+    cloneCommentsTo: ((target, destination): void => {
+      pushMutation(createCloneCommentsToMutation(target, destination));
+    }: TransformCommentAPIs['cloneCommentsTo']),
+
+    addLeadingComments: ((node, comments): void => {
+      pushMutation(
+        createAddCommentsMutation(
+          node,
+          toArray(comments).map(comment => ({
+            comment,
+            placement: CommentPlacement.LEADING_OWN_LINE,
+          })),
+        ),
+      );
+    }: TransformCommentAPIs['addLeadingComments']),
+
+    addLeadingInlineComments: ((node, comments): void => {
+      pushMutation(
+        createAddCommentsMutation(
+          node,
+          toArray(comments).map(comment => ({
+            comment,
+            placement: CommentPlacement.LEADING_INLINE,
+          })),
+        ),
+      );
+    }: TransformCommentAPIs['addLeadingInlineComments']),
+
+    addTrailingComments: ((node, comments): void => {
+      pushMutation(
+        createAddCommentsMutation(
+          node,
+          toArray(comments).map(comment => ({
+            comment,
+            placement: CommentPlacement.TRAILING_OWN_LINE,
+          })),
+        ),
+      );
+    }: TransformCommentAPIs['addTrailingComments']),
+
+    addTrailingInlineComments: ((node, comments): void => {
+      pushMutation(
+        createAddCommentsMutation(
+          node,
+          toArray(comments).map(comment => ({
+            comment,
+            placement: CommentPlacement.TRAILING_INLINE,
+          })),
+        ),
+      );
+    }: TransformCommentAPIs['addTrailingInlineComments']),
 
+    removeComments: ((comments): void => {
+      toArray(comments).forEach(comment => {
+        pushMutation(createRemoveCommentMutation(comment));
+      });
+    }: TransformCommentAPIs['removeComments']),
+  };
+  const insertAPIs: TransformInsertAPIs = {
     insertAfterStatement: ((target, nodesToInsert): void => {
       pushMutation(
         createInsertStatementMutation('after', target, toArray(nodesToInsert)),
       );
-    }: TransformContext['insertBeforeStatement']),
+    }: TransformInsertAPIs['insertBeforeStatement']),
 
     insertBeforeStatement: ((target, nodesToInsert): void => {
       pushMutation(
         createInsertStatementMutation('before', target, toArray(nodesToInsert)),
       );
-    }: TransformContext['insertBeforeStatement']),
+    }: TransformInsertAPIs['insertBeforeStatement']),
+  };
+  const removeAPIs: TransformRemoveAPIs = {
+    removeNode: ((node): void => {
+      pushMutation(createRemoveNodeMutation(node));
+    }: TransformRemoveAPIs['removeNode']),
 
+    removeStatement: ((node): void => {
+      pushMutation(createRemoveStatementMutation(node));
+    }: TransformRemoveAPIs['removeStatement']),
+  };
+  const replaceAPIs: TransformReplaceAPIs = {
     replaceNode: ((
       target: ESNode,
       nodeToReplaceWith: DetachedNode<ESNode>,
-      options?: $ReadOnly<{keepComments?: boolean}>,
+      options?: ReplaceNodeOptions,
     ): void => {
       pushMutation(
         createReplaceNodeMutation(target, nodeToReplaceWith, options),
       );
-    }: TransformContext['replaceNode']),
+    }: TransformReplaceAPIs['replaceNode']),
 
     replaceStatementWithMany: ((
       target,
       nodesToReplaceWith,
-      options?: $ReadOnly<{keepComments?: boolean}>,
+      options?: ReplaceNodeOptions,
     ): void => {
       pushMutation(
         createReplaceStatementWithManyMutation(
@@ -327,45 +486,22 @@ export function getTransformContext(): TransformContext {
           options,
         ),
       );
-    }: TransformContext['replaceStatementWithMany']),
-
-    removeStatement: ((node): void => {
-      pushMutation(createRemoveStatementMutation(node));
-    }: TransformContext['removeStatement']),
-
-    //
-    // Comment APIs
-    //
-
-    getComments: ((node): Array<Comment> => {
-      return [...getCommentsForNode(node)];
-    }: TransformContext['getComments']),
-
-    getLeadingComments: ((node): Array<Comment> => {
-      return getCommentsForNode(node).filter(isLeadingComment);
-    }: TransformContext['getLeadingComments']),
-
-    getTrailingComments: ((node): Array<Comment> => {
-      return getCommentsForNode(node).filter(isTrailingComment);
-    }: TransformContext['getTrailingComments']),
-
-    cloneCommentsTo: ((target, destination): void => {
-      pushMutation(createCloneCommentsToMutation(target, destination));
-    }: TransformContext['cloneCommentsTo']),
+    }: TransformReplaceAPIs['replaceStatementWithMany']),
+  };
 
-    addLeadingComments: ((node, comments): void => {
-      pushMutation(createAddLeadingCommentsMutation(node, toArray(comments)));
-    }: TransformContext['addLeadingComments']),
+  return {
+    mutations,
 
-    addTrailingComments: ((node, comments): void => {
-      pushMutation(createAddTrailingCommentsMutation(node, toArray(comments)));
-    }: TransformContext['addTrailingComments']),
+    // $FlowExpectedError[unsafe-getters-setters]
+    get astWasMutated(): boolean {
+      return mutations.length > 0;
+    },
 
-    removeComments: ((comments): void => {
-      toArray(comments).forEach(comment => {
-        pushMutation(createRemoveCommentMutation(comment));
-      });
-    }: TransformContext['removeComments']),
+    ...cloneAPIs,
+    ...commentAPIs,
+    ...insertAPIs,
+    ...removeAPIs,
+    ...replaceAPIs,
   };
 }