hermes-parser 0.9.0 → 0.10.0

package/dist/transform/astNodeMutationHelpers.js

@@ -0,0 +1,186 @@
+/**
+ * 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.deepCloneNode = deepCloneNode;
+exports.nodeWith = nodeWith;
+exports.removeNodeOnParent = removeNodeOnParent;
+exports.replaceNodeOnParent = replaceNodeOnParent;
+exports.setParentPointersInDirectChildren = setParentPointersInDirectChildren;
+exports.shallowCloneNode = shallowCloneNode;
+exports.updateAllParentPointers = updateAllParentPointers;
+
+var _astArrayMutationHelpers = require("./astArrayMutationHelpers");
+
+var _getVisitorKeys = require("../traverse/getVisitorKeys");
+
+var _SimpleTraverser = require("../traverse/SimpleTraverser");
+
+function getParentKey(target, parent) {
+  if (parent == null) {
+    throw new Error(`Expected parent node to be set on "${target.type}"`);
+  }
+
+  for (const key of (0, _getVisitorKeys.getVisitorKeys)(parent)) {
+    if ((0, _getVisitorKeys.isNode)( // $FlowExpectedError[prop-missing]
+    parent[key])) {
+      if (parent[key] === target) {
+        return {
+          type: 'single',
+          node: parent,
+          key
+        };
+      }
+    } else if (Array.isArray(parent[key])) {
+      for (let i = 0; i < parent[key].length; i += 1) {
+        const current = parent[key][i];
+
+        if (current === target) {
+          return {
+            type: 'array',
+            node: parent,
+            key,
+            targetIndex: i
+          };
+        }
+      }
+    }
+  } // this shouldn't happen ever
+
+
+  throw new Error(`Expected to find the ${target.type} as a direct child of the ${parent.type}.`);
+}
+/**
+ * Replace a node with a new node within an AST (via the parent pointer).
+ */
+
+
+function replaceNodeOnParent(originalNode, originalNodeParent, nodeToReplaceWith) {
+  const replacementParent = getParentKey(originalNode, originalNodeParent);
+  const parent = replacementParent.node;
+
+  if (replacementParent.type === 'array') {
+    // $FlowExpectedError[prop-missing]
+    parent[replacementParent.key] = (0, _astArrayMutationHelpers.replaceInArray)( // $FlowExpectedError[prop-missing]
+    parent[replacementParent.key], replacementParent.targetIndex, [nodeToReplaceWith]);
+  } else {
+    // $FlowExpectedError[prop-missing]
+    parent[replacementParent.key] = nodeToReplaceWith;
+  }
+}
+/**
+ * Remove a node from the AST its connected to (via the parent pointer).
+ */
+
+
+function removeNodeOnParent(originalNode, originalNodeParent) {
+  const replacementParent = getParentKey(originalNode, originalNodeParent);
+  const parent = replacementParent.node;
+
+  if (replacementParent.type === 'array') {
+    // $FlowExpectedError[prop-missing]
+    parent[replacementParent.key] = (0, _astArrayMutationHelpers.removeFromArray)( // $FlowExpectedError[prop-missing]
+    parent[replacementParent.key], replacementParent.targetIndex);
+  } else {
+    // $FlowExpectedError[prop-missing]
+    parent[replacementParent.key] = null;
+  }
+}
+/**
+ * Corrects the parent pointers in direct children of the given node.
+ */
+
+
+function setParentPointersInDirectChildren(node) {
+  for (const key of (0, _getVisitorKeys.getVisitorKeys)(node)) {
+    if ((0, _getVisitorKeys.isNode)( // $FlowExpectedError[prop-missing]
+    node[key])) {
+      node[key].parent = node;
+    } else if (Array.isArray(node[key])) {
+      for (const child of node[key]) {
+        child.parent = node;
+      }
+    }
+  }
+}
+/**
+ * Traverses the entire subtree to ensure the parent pointers are set correctly.
+ */
+
+
+function updateAllParentPointers(node) {
+  _SimpleTraverser.SimpleTraverser.traverse(node, {
+    enter(node, parent) {
+      // $FlowExpectedError[cannot-write]
+      node.parent = parent;
+    },
+
+    leave() {}
+
+  });
+}
+/**
+ * Clone node and add new props.
+ *
+ * This will only create a new object if the overrides actually result in a change.
+ */
+
+
+function nodeWith(node, overrideProps) {
+  // Check if this will actually result in a change, maintaining referential equality is important.
+  const willBeUnchanged = Object.entries(overrideProps).every(([key, value]) => // $FlowExpectedError[prop-missing]
+  Array.isArray(value) ? (0, _astArrayMutationHelpers.arrayIsEqual)(node[key], value) : node[key] === value);
+
+  if (willBeUnchanged) {
+    return node;
+  } // Create new node.
+  // $FlowExpectedError[cannot-spread-interface]
+
+
+  const newNode = { ...node,
+    ...overrideProps
+  }; // Ensure parent pointers are correctly set within this nodes children.
+
+  setParentPointersInDirectChildren(newNode);
+  return newNode;
+}
+/**
+ * Shallow clones node, providing a new reference for an existing node.
+ */
+
+
+function shallowCloneNode(node) {
+  // $FlowExpectedError[cannot-spread-interface]
+  const newNode = { ...node
+  }; // Ensure parent pointers are correctly set within this nodes children.
+
+  setParentPointersInDirectChildren(newNode);
+  return newNode;
+}
+/**
+ * Deeply clones node and its entire tree.
+ */
+
+
+function deepCloneNode(node) {
+  const clone = JSON.parse(JSON.stringify(node, (key, value) => {
+    // null out parent pointers
+    if (key === 'parent') {
+      return undefined;
+    }
+
+    return value;
+  }));
+  updateAllParentPointers(clone);
+  return clone;
+}

package/dist/transform/astNodeMutationHelpers.js.flow

@@ -0,0 +1,205 @@
+/**
+ * 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 {ESNode} from 'hermes-estree';
+
+import {
+  arrayIsEqual,
+  removeFromArray,
+  replaceInArray,
+} from './astArrayMutationHelpers';
+import {getVisitorKeys, isNode} from '../traverse/getVisitorKeys';
+import {SimpleTraverser} from '../traverse/SimpleTraverser';
+
+function getParentKey(
+  target: ESNode,
+  parent: ESNode,
+): $ReadOnly<
+  | {
+      type: 'single',
+      node: ESNode,
+      key: string,
+    }
+  | {
+      type: 'array',
+      node: ESNode,
+      key: string,
+      targetIndex: number,
+    },
+> {
+  if (parent == null) {
+    throw new Error(`Expected parent node to be set on "${target.type}"`);
+  }
+  for (const key of getVisitorKeys(parent)) {
+    if (
+      isNode(
+        // $FlowExpectedError[prop-missing]
+        parent[key],
+      )
+    ) {
+      if (parent[key] === target) {
+        return {type: 'single', node: parent, key};
+      }
+    } else if (Array.isArray(parent[key])) {
+      for (let i = 0; i < parent[key].length; i += 1) {
+        const current = parent[key][i];
+        if (current === target) {
+          return {type: 'array', node: parent, key, targetIndex: i};
+        }
+      }
+    }
+  }
+
+  // this shouldn't happen ever
+  throw new Error(
+    `Expected to find the ${target.type} as a direct child of the ${parent.type}.`,
+  );
+}
+
+/**
+ * Replace a node with a new node within an AST (via the parent pointer).
+ */
+export function replaceNodeOnParent(
+  originalNode: ESNode,
+  originalNodeParent: ESNode,
+  nodeToReplaceWith: ESNode,
+): void {
+  const replacementParent = getParentKey(originalNode, originalNodeParent);
+  const parent = replacementParent.node;
+  if (replacementParent.type === 'array') {
+    // $FlowExpectedError[prop-missing]
+    parent[replacementParent.key] = replaceInArray(
+      // $FlowExpectedError[prop-missing]
+      parent[replacementParent.key],
+      replacementParent.targetIndex,
+      [nodeToReplaceWith],
+    );
+  } else {
+    // $FlowExpectedError[prop-missing]
+    parent[replacementParent.key] = nodeToReplaceWith;
+  }
+}
+
+/**
+ * Remove a node from the AST its connected to (via the parent pointer).
+ */
+export function removeNodeOnParent(
+  originalNode: ESNode,
+  originalNodeParent: ESNode,
+): void {
+  const replacementParent = getParentKey(originalNode, originalNodeParent);
+  const parent = replacementParent.node;
+  if (replacementParent.type === 'array') {
+    // $FlowExpectedError[prop-missing]
+    parent[replacementParent.key] = removeFromArray(
+      // $FlowExpectedError[prop-missing]
+      parent[replacementParent.key],
+      replacementParent.targetIndex,
+    );
+  } else {
+    // $FlowExpectedError[prop-missing]
+    parent[replacementParent.key] = null;
+  }
+}
+
+/**
+ * Corrects the parent pointers in direct children of the given node.
+ */
+export function setParentPointersInDirectChildren(node: ESNode): void {
+  for (const key of getVisitorKeys(node)) {
+    if (
+      isNode(
+        // $FlowExpectedError[prop-missing]
+        node[key],
+      )
+    ) {
+      node[key].parent = node;
+    } else if (Array.isArray(node[key])) {
+      for (const child of node[key]) {
+        child.parent = node;
+      }
+    }
+  }
+}
+
+/**
+ * Traverses the entire subtree to ensure the parent pointers are set correctly.
+ */
+export function updateAllParentPointers(node: ESNode) {
+  SimpleTraverser.traverse(node, {
+    enter(node, parent) {
+      // $FlowExpectedError[cannot-write]
+      node.parent = parent;
+    },
+    leave() {},
+  });
+}
+
+/**
+ * Clone node and add new props.
+ *
+ * This will only create a new object if the overrides actually result in a change.
+ */
+export function nodeWith<T: ESNode>(node: T, overrideProps: $Partial<T>): T {
+  // Check if this will actually result in a change, maintaining referential equality is important.
+  const willBeUnchanged = Object.entries(overrideProps).every(([key, value]) =>
+    // $FlowExpectedError[prop-missing]
+    Array.isArray(value) ? arrayIsEqual(node[key], value) : node[key] === value,
+  );
+  if (willBeUnchanged) {
+    return node;
+  }
+
+  // Create new node.
+  // $FlowExpectedError[cannot-spread-interface]
+  const newNode: T = {
+    ...node,
+    ...overrideProps,
+  };
+
+  // Ensure parent pointers are correctly set within this nodes children.
+  setParentPointersInDirectChildren(newNode);
+
+  return newNode;
+}
+
+/**
+ * Shallow clones node, providing a new reference for an existing node.
+ */
+export function shallowCloneNode<T: ESNode>(node: T): T {
+  // $FlowExpectedError[cannot-spread-interface]
+  const newNode: T = {...node};
+
+  // Ensure parent pointers are correctly set within this nodes children.
+  setParentPointersInDirectChildren(newNode);
+
+  return newNode;
+}
+
+/**
+ * Deeply clones node and its entire tree.
+ */
+export function deepCloneNode<T: ESNode>(node: T): T {
+  const clone: T = JSON.parse(
+    JSON.stringify(node, (key, value) => {
+      // null out parent pointers
+      if (key === 'parent') {
+        return undefined;
+      }
+      return value;
+    }),
+  );
+
+  updateAllParentPointers(clone);
+
+  return clone;
+}

package/dist/traverse/SimpleTraverser.js

@@ -0,0 +1,138 @@
+/**
+ * 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.SimpleTraverserSkip = exports.SimpleTraverserBreak = exports.SimpleTraverser = void 0;
+
+var _getVisitorKeys = require("./getVisitorKeys");
+
+/**
+ * Can be thrown within the traversal "enter" function to prevent the traverser
+ * from traversing the node any further, essentially culling the remainder of the
+ * AST branch
+ */
+const SimpleTraverserSkip = new Error();
+/**
+ * Can be thrown at any point during the traversal to immediately stop traversal
+ * entirely.
+ */
+
+exports.SimpleTraverserSkip = SimpleTraverserSkip;
+const SimpleTraverserBreak = new Error();
+/**
+ * A very simple traverser class to traverse AST trees.
+ */
+
+exports.SimpleTraverserBreak = SimpleTraverserBreak;
+
+class SimpleTraverser {
+  /**
+   * Traverse the given AST tree.
+   * @param node The root node to traverse.
+   * @param options The option object.
+   */
+  traverse(node, options) {
+    try {
+      this._traverse(node, null, options);
+    } catch (ex) {
+      if (ex === SimpleTraverserBreak) {
+        return;
+      }
+
+      throw ex;
+    }
+  }
+  /**
+   * Traverse the given AST tree recursively.
+   * @param node The current node.
+   * @param parent The parent node.
+   * @private
+   */
+
+
+  _traverse(node, parent, options) {
+    if (!(0, _getVisitorKeys.isNode)(node)) {
+      return;
+    }
+
+    try {
+      options.enter(node, parent);
+    } catch (ex) {
+      if (ex === SimpleTraverserSkip) {
+        return;
+      }
+
+      this._setErrorContext(ex, node);
+
+      throw ex;
+    }
+
+    const keys = (0, _getVisitorKeys.getVisitorKeys)(node, options.visitorKeys);
+
+    for (const key of keys) {
+      // $FlowExpectedError[prop-missing]
+      const child = node[key];
+
+      if (Array.isArray(child)) {
+        for (let j = 0; j < child.length; ++j) {
+          this._traverse(child[j], node, options);
+        }
+      } else {
+        this._traverse(child, node, options);
+      }
+    }
+
+    try {
+      options.leave(node, parent);
+    } catch (ex) {
+      if (ex === SimpleTraverserSkip) {
+        return;
+      }
+
+      this._setErrorContext(ex, node);
+
+      throw ex;
+    }
+  }
+  /**
+   * Set useful contextual information onto the error object.
+   * @param ex The error object.
+   * @param node The current node.
+   * @private
+   */
+
+
+  _setErrorContext(ex, node) {
+    // $FlowFixMe[prop-missing]
+    ex.currentNode = {
+      type: node.type,
+      range: node.range,
+      loc: node.loc
+    };
+  }
+  /**
+   * Traverse the given AST tree.
+   * @param node The root node to traverse.
+   * @param options The option object.
+   */
+
+
+  static traverse(node, options) {
+    new SimpleTraverser().traverse(node, options);
+  }
+
+}
+
+exports.SimpleTraverser = SimpleTraverser;
+SimpleTraverser.Break = SimpleTraverserBreak;
+SimpleTraverser.Skip = SimpleTraverserSkip;

package/dist/traverse/SimpleTraverser.js.flow

@@ -0,0 +1,132 @@
+/**
+ * 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 {VisitorKeysType} from './getVisitorKeys';
+import type {ESNode} from 'hermes-estree';
+
+import {getVisitorKeys, isNode} from './getVisitorKeys';
+
+export type TraverserCallback = (node: ESNode, parent: ?ESNode) => void;
+export type TraverserOptions = $ReadOnly<{
+  /** The callback function which is called on entering each node. */
+  enter: TraverserCallback,
+  /** The callback function which is called on leaving each node. */
+  leave: TraverserCallback,
+  /** The set of visitor keys to use for traversal. Defaults to the `hermes-eslint` visitor keys */
+  visitorKeys?: ?VisitorKeysType,
+}>;
+
+/**
+ * Can be thrown within the traversal "enter" function to prevent the traverser
+ * from traversing the node any further, essentially culling the remainder of the
+ * AST branch
+ */
+export const SimpleTraverserSkip: Error = new Error();
+/**
+ * Can be thrown at any point during the traversal to immediately stop traversal
+ * entirely.
+ */
+export const SimpleTraverserBreak: Error = new Error();
+
+/**
+ * A very simple traverser class to traverse AST trees.
+ */
+export class SimpleTraverser {
+  static Break: Error = SimpleTraverserBreak;
+  static Skip: Error = SimpleTraverserSkip;
+
+  /**
+   * Traverse the given AST tree.
+   * @param node The root node to traverse.
+   * @param options The option object.
+   */
+  traverse(node: ESNode, options: TraverserOptions): void {
+    try {
+      this._traverse(node, null, options);
+    } catch (ex) {
+      if (ex === SimpleTraverserBreak) {
+        return;
+      }
+      throw ex;
+    }
+  }
+
+  /**
+   * Traverse the given AST tree recursively.
+   * @param node The current node.
+   * @param parent The parent node.
+   * @private
+   */
+  _traverse(node: ESNode, parent: ?ESNode, options: TraverserOptions): void {
+    if (!isNode(node)) {
+      return;
+    }
+
+    try {
+      options.enter(node, parent);
+    } catch (ex) {
+      if (ex === SimpleTraverserSkip) {
+        return;
+      }
+      this._setErrorContext(ex, node);
+      throw ex;
+    }
+
+    const keys = getVisitorKeys(node, options.visitorKeys);
+    for (const key of keys) {
+      // $FlowExpectedError[prop-missing]
+      const child = node[key];
+
+      if (Array.isArray(child)) {
+        for (let j = 0; j < child.length; ++j) {
+          this._traverse(child[j], node, options);
+        }
+      } else {
+        this._traverse(child, node, options);
+      }
+    }
+
+    try {
+      options.leave(node, parent);
+    } catch (ex) {
+      if (ex === SimpleTraverserSkip) {
+        return;
+      }
+      this._setErrorContext(ex, node);
+      throw ex;
+    }
+  }
+
+  /**
+   * Set useful contextual information onto the error object.
+   * @param ex The error object.
+   * @param node The current node.
+   * @private
+   */
+  _setErrorContext(ex: Error, node: ESNode): void {
+    // $FlowFixMe[prop-missing]
+    ex.currentNode = {
+      type: node.type,
+      range: node.range,
+      loc: node.loc,
+    };
+  }
+
+  /**
+   * Traverse the given AST tree.
+   * @param node The root node to traverse.
+   * @param options The option object.
+   */
+  static traverse(node: ESNode, options: TraverserOptions) {
+    new SimpleTraverser().traverse(node, options);
+  }
+}

package/dist/traverse/getVisitorKeys.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.getVisitorKeys = getVisitorKeys;
+exports.isNode = isNode;
+
+var _hermesEslint = require("hermes-eslint");
+
+function isNode(thing) {
+  return typeof thing === 'object' && thing != null && typeof thing.type === 'string';
+}
+
+function getVisitorKeys(node, visitorKeys) {
+  const keys = (visitorKeys != null ? visitorKeys : _hermesEslint.VisitorKeys)[node.type];
+
+  if (keys == null) {
+    throw new Error(`No visitor keys found for node type "${node.type}".`);
+  } // $FlowExpectedError[prop-missing]
+
+
+  return keys;
+}