hermes-transform 0.5.0

package/dist/transform/TransformContext.js.flow

@@ -0,0 +1,378 @@
+/**
+ * Copyright (c) Facebook, Inc. and its 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
+ */
+
+import type {
+  Comment,
+  ESNode,
+  Expression,
+  ModuleDeclaration,
+  Statement,
+  TypeAnnotationType,
+} from 'hermes-estree';
+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 {CloneCommentsToMutation} from './mutations/CloneCommentsTo';
+import type {InsertStatementMutation} from './mutations/InsertStatement';
+import type {RemoveCommentMutation} from './mutations/RemoveComment';
+import type {RemoveStatementMutation} from './mutations/RemoveStatement';
+import type {ReplaceNodeMutation} from './mutations/ReplaceNode';
+import type {ReplaceStatementWithManyMutation} from './mutations/ReplaceStatementWithMany';
+
+import {deepCloneNode, shallowCloneNode} from '../detachedNode';
+import {
+  getCommentsForNode,
+  isLeadingComment,
+  isTrailingComment,
+} from './comments/comments';
+import {createAddLeadingCommentsMutation} from './mutations/AddLeadingComments';
+import {createAddTrailingCommentsMutation} from './mutations/AddTrailingComments';
+import {createCloneCommentsToMutation} from './mutations/CloneCommentsTo';
+import {createInsertStatementMutation} from './mutations/InsertStatement';
+import {createRemoveCommentMutation} from './mutations/RemoveComment';
+import {createRemoveStatementMutation} from './mutations/RemoveStatement';
+import {createReplaceNodeMutation} from './mutations/ReplaceNode';
+import {createReplaceStatementWithManyMutation} from './mutations/ReplaceStatementWithMany';
+
+type Mutation = $ReadOnly<
+  | AddLeadingCommentsMutation
+  | AddTrailingCommentsMutation
+  | CloneCommentsToMutation
+  | InsertStatementMutation
+  | RemoveCommentMutation
+  | RemoveStatementMutation
+  | ReplaceNodeMutation
+  | ReplaceStatementWithManyMutation,
+>;
+
+type SingleOrArray<+T> = T | $ReadOnlyArray<T>;
+
+type ReplaceNodeOptions = $ReadOnly<{
+  /**
+   * Moves the comments from the target node to the nodetoReplaceWith.
+   * Note that this does not *clone* comments, it moves them and clears out
+   * the target node's comments afterward.
+   */
+  keepComments?: boolean,
+}>;
+
+export type TransformContext = $ReadOnly<{
+  mutations: $ReadOnlyArray<Mutation>,
+  astWasMutated: boolean,
+
+  /**
+   * Shallowly clones the given node and applies the given overrides.
+   * !!! 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
+   * AST which refer to the exact same node objects; which will lead
+   * to ***undefined*** behaviour.
+   *
+   * You should only use this if:
+   * 1) the node is a simple leaf (eg literals, identifiers, etc)
+   * 2) you are 100% removing the original node from the AST
+   *
+   * 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
+    <T: ESNode>(node: T): DetachedNode<T>,
+    <T: ESNode>(node: ?T): DetachedNode<T> | null,
+  },
+
+  /**
+   * {@see shallowCloneNode}
+   */
+  shallowCloneArray: {
+    <T: ESNode>(node: $ReadOnlyArray<T>): $ReadOnlyArray<DetachedNode<T>>,
+    <T: ESNode>(node: ?$ReadOnlyArray<T>): ?$ReadOnlyArray<DetachedNode<T>>,
+  },
+
+  /**
+   * Deeply clones the node and all its children, then applies the
+   * given overrides.
+   * !!! 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
+    <T: ESNode>(node: T): DetachedNode<T>,
+    <T: ESNode>(node: ?T): DetachedNode<T> | null,
+  },
+
+  /**
+   * 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>>,
+  ) => void,
+
+  /**
+   * Insert `nodeToInsert` before the `target` statement.
+   * The inserted nodes will be kept in the order given.
+   */
+  insertBeforeStatement: (
+    target: ModuleDeclaration | Statement,
+    nodeToInsert: SingleOrArray<DetachedNode<ModuleDeclaration | Statement>>,
+  ) => void,
+
+  /**
+   * 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
+    (
+      target: Expression,
+      nodeToReplaceWith: DetachedNode<Expression>,
+      options?: ReplaceNodeOptions,
+    ): void,
+    // module declarations must 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
+    (
+      target: Statement,
+      nodeToReplaceWith: DetachedNode<ModuleDeclaration | Statement>,
+      options?: ReplaceNodeOptions,
+    ): void,
+    // Types must be replaced with types
+    (
+      target: TypeAnnotationType,
+      nodeToReplaceWith: DetachedNode<TypeAnnotationType>,
+      options?: ReplaceNodeOptions,
+    ): void,
+  } & TransformReplaceSignatures, // allow like-for-like replacements as well
+
+  /**
+   * Replaces the `target` node with all of the `nodesToReplaceWith` nodes.
+   * The nodes will be kept in the order given.
+   */
+  replaceStatementWithMany: (
+    target: ModuleDeclaration | Statement,
+    nodesToReplaceWith: $ReadOnlyArray<
+      DetachedNode<ModuleDeclaration | Statement>,
+    >,
+    options?: {
+      /**
+       * Moves the comments from the target node to the first node in the array.
+       * Note that this does not *clone* comments, it moves them and clears out
+       * the target node's comments afterward.
+       */
+      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,
+
+  /**
+   * Removes the specified comments
+   */
+  removeComments: (comments: SingleOrArray<Comment>) => void,
+}>;
+
+export function getTransformContext(): TransformContext {
+  /**
+   * The mutations in order of collection.
+   */
+  const mutations: Array<Mutation> = [];
+  function pushMutation(mutation: ?Mutation): void {
+    if (mutation != null) {
+      mutations.push(mutation);
+    }
+  }
+
+  return {
+    mutations,
+
+    // $FlowExpectedError[unsafe-getters-setters]
+    get astWasMutated(): boolean {
+      return mutations.length > 0;
+    },
+
+    // $FlowExpectedError[incompatible-exact]
+    shallowCloneNode: ((
+      node: ?ESNode,
+      newProps?: $ReadOnly<{...}>,
+    ): // $FlowExpectedError[incompatible-cast]
+    // $FlowExpectedError[prop-missing]
+    ?DetachedNode<ESNode> => {
+      if (node == null) {
+        return null;
+      }
+
+      return shallowCloneNode(node, newProps);
+    }: TransformContext['shallowCloneNode']),
+
+    shallowCloneArray: (<T: ESNode>(
+      nodes: ?$ReadOnlyArray<T>,
+    ): // $FlowExpectedError[incompatible-cast]
+    ?$ReadOnlyArray<DetachedNode<ESNode>> => {
+      if (nodes == null) {
+        return null;
+      }
+
+      return nodes.map(node => shallowCloneNode<T>(node));
+    }: TransformContext['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, newProps);
+    }: TransformContext['deepCloneNode']),
+
+    insertAfterStatement: ((target, nodesToInsert): void => {
+      pushMutation(
+        createInsertStatementMutation('after', target, toArray(nodesToInsert)),
+      );
+    }: TransformContext['insertBeforeStatement']),
+
+    insertBeforeStatement: ((target, nodesToInsert): void => {
+      pushMutation(
+        createInsertStatementMutation('before', target, toArray(nodesToInsert)),
+      );
+    }: TransformContext['insertBeforeStatement']),
+
+    replaceNode: ((
+      target: ESNode,
+      nodeToReplaceWith: DetachedNode<ESNode>,
+      options?: $ReadOnly<{keepComments?: boolean}>,
+    ): void => {
+      pushMutation(
+        createReplaceNodeMutation(target, nodeToReplaceWith, options),
+      );
+    }: TransformContext['replaceNode']),
+
+    replaceStatementWithMany: ((
+      target,
+      nodesToReplaceWith,
+      options?: $ReadOnly<{keepComments?: boolean}>,
+    ): void => {
+      pushMutation(
+        createReplaceStatementWithManyMutation(
+          target,
+          nodesToReplaceWith,
+          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']),
+
+    addLeadingComments: ((node, comments): void => {
+      pushMutation(createAddLeadingCommentsMutation(node, toArray(comments)));
+    }: TransformContext['addLeadingComments']),
+
+    addTrailingComments: ((node, comments): void => {
+      pushMutation(createAddTrailingCommentsMutation(node, toArray(comments)));
+    }: TransformContext['addTrailingComments']),
+
+    removeComments: ((comments): void => {
+      toArray(comments).forEach(comment => {
+        pushMutation(createRemoveCommentMutation(comment));
+      });
+    }: TransformContext['removeComments']),
+  };
+}
+
+function toArray<T>(thing: SingleOrArray<T>): $ReadOnlyArray<T> {
+  if (Array.isArray(thing)) {
+    // $FlowExpectedError[incompatible-return]
+    return thing;
+  }
+  return [thing];
+}

package/dist/transform/comments/comments.js

@@ -0,0 +1,140 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.addCommentsToNode = addCommentsToNode;
+exports.addLeadingComment = addLeadingComment;
+exports.addTrailingComment = addTrailingComment;
+exports.appendCommentToSource = appendCommentToSource;
+exports.attachComments = attachComments;
+exports.cloneComment = cloneComment;
+exports.cloneCommentWithMarkers = cloneCommentWithMarkers;
+exports.getCommentsForNode = getCommentsForNode;
+exports.isLeadingComment = isLeadingComment;
+exports.isTrailingComment = isTrailingComment;
+exports.moveCommentsToNewNode = moveCommentsToNewNode;
+exports.setCommentsOnNode = setCommentsOnNode;
+
+var _comments = require("./prettier/main/comments");
+
+var _loc = require("./prettier/language-js/loc");
+
+var _printerEstree = _interopRequireDefault(require("./prettier/language-js/printer-estree"));
+
+var _util = require("./prettier/common/util");
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
+
+function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread(); }
+
+function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+
+function _iterableToArray(iter) { if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter); }
+
+function _arrayWithoutHoles(arr) { if (Array.isArray(arr)) return _arrayLikeToArray(arr); }
+
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) { arr2[i] = arr[i]; } return arr2; }
+
+function attachComments(comments, ast, text) {
+  (0, _comments.attach)(comments, ast, text, {
+    locStart: _loc.locStart,
+    locEnd: _loc.locEnd,
+    printer: _printerEstree["default"]
+  });
+}
+
+function moveCommentsToNewNode(oldNode, newNode) {
+  setCommentsOnNode(newNode, getCommentsForNode(oldNode));
+  setCommentsOnNode(oldNode, []);
+}
+
+function setCommentsOnNode(node, comments) {
+  // $FlowExpectedError - this property is secretly added by prettier.
+  node.comments = comments;
+}
+
+function addCommentsToNode(node, comments) {
+  var _node$comments, _ref;
+
+  // $FlowExpectedError - this property is secretly added by prettier.
+  node.comments = (_node$comments = node.comments) !== null && _node$comments !== void 0 ? _node$comments : []; // $FlowExpectedError
+
+  (_ref = node.comments).push.apply(_ref, _toConsumableArray(comments));
+}
+
+function getCommentsForNode(node) {
+  var _node$comments2;
+
+  // $FlowExpectedError - this property is secretly added by prettier.
+  return (_node$comments2 = node.comments) !== null && _node$comments2 !== void 0 ? _node$comments2 : [];
+}
+
+function isLeadingComment(comment) {
+  // $FlowExpectedError - this property is secretly added by prettier.
+  return comment.leading === true;
+}
+
+function isTrailingComment(comment) {
+  // $FlowExpectedError - this property is secretly added by prettier.
+  return comment.trailing === true;
+}
+
+function addLeadingComment(node, comment) {
+  (0, _util.addLeadingComment)(node, comment);
+}
+
+function addTrailingComment(node, comment) {
+  (0, _util.addTrailingComment)(node, comment);
+}
+
+function cloneComment(comment) {
+  // $FlowExpectedError[incompatible-return]
+  return {
+    type: comment.type,
+    value: comment.value,
+    loc: comment.loc,
+    range: comment.range
+  };
+}
+
+function cloneCommentWithMarkers(comment) {
+  // $FlowExpectedError[incompatible-return]
+  return {
+    type: comment.type,
+    value: comment.value,
+    loc: comment.loc,
+    range: comment.range,
+    leading: isLeadingComment(comment),
+    trailing: isTrailingComment(comment)
+  };
+}
+
+function appendCommentToSource(code, comment) {
+  // prettier slices comments directly from the source code when printing
+  // https://github.com/prettier/prettier/blob/5f0ee39fa03532c85bd1c35291450fe7ac3667b3/src/language-js/print/comment.js#L15-L20
+  // this means that we need to have any appended comments directly in the
+  // source code or else prettier will slice nothing and bork up the transform
+  var commentText = comment.value;
+
+  switch (comment.type) {
+    case 'Block':
+      commentText = "/*".concat(commentText, "*/");
+      break;
+
+    case 'Line':
+      commentText = "//".concat(commentText);
+      break;
+  }
+
+  var newCode = code;
+  newCode += '\n';
+  var start = newCode.length;
+  newCode += commentText;
+  var end = newCode.length; // $FlowExpectedError[cannot-write]
+
+  comment.range = [start, end];
+  return newCode;
+}

package/dist/transform/comments/comments.js.flow

@@ -0,0 +1,145 @@
+/**
+ * Copyright (c) Facebook, Inc. and its 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
+ */
+
+import type {Comment, ESNode, Program} from 'hermes-estree';
+import type {DetachedNode} from '../../detachedNode';
+
+// $FlowExpectedError[untyped-import]
+import {attach as untypedAttach} from './prettier/main/comments';
+// $FlowExpectedError[untyped-import]
+import {locEnd, locStart} from './prettier/language-js/loc';
+// $FlowExpectedError[untyped-import]
+import printer from './prettier/language-js/printer-estree';
+import {
+  // $FlowExpectedError[untyped-import]
+  addLeadingComment as untypedAddLeadingComment,
+  // $FlowExpectedError[untyped-import]
+  addTrailingComment as untypedAddTrailingComment,
+} from './prettier/common/util';
+
+export type Options = $ReadOnly<{}>;
+
+export function attachComments(
+  comments: $ReadOnlyArray<Comment>,
+  ast: Program,
+  text: string,
+): void {
+  untypedAttach(comments, ast, text, {
+    locStart,
+    locEnd,
+    printer,
+  });
+}
+
+export function moveCommentsToNewNode(
+  oldNode: ESNode,
+  newNode: DetachedNode<ESNode>,
+): void {
+  setCommentsOnNode(newNode, getCommentsForNode(oldNode));
+  setCommentsOnNode(oldNode, []);
+}
+
+export function setCommentsOnNode(
+  node: ESNode | DetachedNode<ESNode>,
+  comments: $ReadOnlyArray<Comment>,
+): void {
+  // $FlowExpectedError - this property is secretly added by prettier.
+  node.comments = comments;
+}
+
+export function addCommentsToNode(
+  node: ESNode | DetachedNode<ESNode>,
+  comments: $ReadOnlyArray<Comment>,
+): void {
+  // $FlowExpectedError - this property is secretly added by prettier.
+  node.comments = node.comments ?? [];
+  // $FlowExpectedError
+  (node.comments: Array<Comment>).push(...comments);
+}
+
+export function getCommentsForNode(
+  node: ESNode | DetachedNode<ESNode>,
+): $ReadOnlyArray<Comment> {
+  // $FlowExpectedError - this property is secretly added by prettier.
+  return node.comments ?? [];
+}
+
+export function isLeadingComment(comment: Comment): boolean {
+  // $FlowExpectedError - this property is secretly added by prettier.
+  return comment.leading === true;
+}
+export function isTrailingComment(comment: Comment): boolean {
+  // $FlowExpectedError - this property is secretly added by prettier.
+  return comment.trailing === true;
+}
+
+export function addLeadingComment(
+  node: ESNode | DetachedNode<ESNode>,
+  comment: Comment,
+): void {
+  untypedAddLeadingComment(node, comment);
+}
+
+export function addTrailingComment(
+  node: ESNode | DetachedNode<ESNode>,
+  comment: Comment,
+): void {
+  untypedAddTrailingComment(node, comment);
+}
+
+export function cloneComment<T: Comment>(comment: T): T {
+  // $FlowExpectedError[incompatible-return]
+  return {
+    type: comment.type,
+    value: comment.value,
+    loc: comment.loc,
+    range: comment.range,
+  };
+}
+
+export function cloneCommentWithMarkers<T: Comment>(comment: T): T {
+  // $FlowExpectedError[incompatible-return]
+  return {
+    type: comment.type,
+    value: comment.value,
+    loc: comment.loc,
+    range: comment.range,
+    leading: isLeadingComment(comment),
+    trailing: isTrailingComment(comment),
+  };
+}
+
+export function appendCommentToSource(code: string, comment: Comment): string {
+  // prettier slices comments directly from the source code when printing
+  // https://github.com/prettier/prettier/blob/5f0ee39fa03532c85bd1c35291450fe7ac3667b3/src/language-js/print/comment.js#L15-L20
+  // this means that we need to have any appended comments directly in the
+  // source code or else prettier will slice nothing and bork up the transform
+
+  let commentText = comment.value;
+  switch (comment.type) {
+    case 'Block':
+      commentText = `/*${commentText}*/`;
+      break;
+    case 'Line':
+      commentText = `//${commentText}`;
+      break;
+  }
+
+  let newCode = code;
+  newCode += '\n';
+  const start = newCode.length;
+  newCode += commentText;
+  const end = newCode.length;
+
+  // $FlowExpectedError[cannot-write]
+  comment.range = [start, end];
+
+  return newCode;
+}

package/dist/transform/comments/prettier/README.md

@@ -0,0 +1,6 @@
+# Comment Attachment
+
+This is a fork of prettier's comment attachment algorithm. The original license for `prettier` can be found in the `PRETTIER_LICENCE` file in the root of this package.
+Specifically this fork contains the `attach` method from [`src/main/comments.js`](https://github.com/prettier/prettier/blob/894f841fbd948875fc2a47bd63f3db3dcadc5f43/src/main/comments.js#L357) and the minimum set of code required for it.
+
+The folder structure has been maintained to make merging future updates easier.