hermes-transform 0.5.0

package/dist/traverse/SimpleTraverser.js.flow

@@ -0,0 +1,109 @@
+/**
+ * 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
+ */
+
+'use strict';
+
+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,
+}>;
+
+/**
+ * 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 {
+  /**
+   * 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;
+      }
+      throw ex;
+    }
+
+    const keys = getVisitorKeys(node);
+    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;
+      }
+      throw ex;
+    }
+  }
+
+  /**
+   * 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/esquery.js

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ *
+ * 
+ * @format
+ */
+'use strict';
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.query = exports.parse = exports.matches = exports.match = void 0;
+
+var _esquery = _interopRequireDefault(require("esquery"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
+
+// $FlowExpectedError[cannot-resolve-module]
+
+/** Parse a selector and return its AST. */
+var parse = _esquery["default"].parse;
+/** From a JS AST and a selector AST, collect all JS AST nodes that match the selector. */
+
+exports.parse = parse;
+var match = _esquery["default"].match;
+/** Given a `node` and its ancestors, determine if `node` is matched by `selector`. */
+
+exports.match = match;
+var matches = _esquery["default"].matches;
+/** Query the code AST using the selector string. */
+
+exports.matches = matches;
+var query = _esquery["default"].query;
+exports.query = query;

package/dist/traverse/esquery.js.flow

@@ -0,0 +1,173 @@
+/**
+ * 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
+ * @format
+ */
+
+'use strict';
+
+import type {ESNode} from 'hermes-estree';
+// $FlowExpectedError[cannot-resolve-module]
+import esquery from 'esquery';
+
+//
+// Base Atoms
+//
+interface Atom {
+  // type: string;
+}
+interface SubjectSelectorAtom extends Atom {
+  subject?: ?boolean;
+}
+interface NthSelectorAtom extends SubjectSelectorAtom {
+  index: NumericLiteralAtom;
+}
+interface BinarySelectorAtom extends SubjectSelectorAtom {
+  // type: 'child' | 'sibling' | 'adjacent' | 'descendant';
+  left: SubjectSelector;
+  right: SubjectSelector;
+}
+interface MultiSelectorAtom extends SubjectSelectorAtom {
+  selectors: Array<SubjectSelector>;
+}
+interface LiteralAtom extends Atom {
+  type: 'literal';
+  // value: string | number;
+}
+
+//
+// Literals
+//
+interface StringLiteralAtom extends LiteralAtom {
+  value: string;
+}
+interface NumericLiteralAtom extends LiteralAtom {
+  value: number;
+}
+interface RegExpLiteralAtom extends Atom {
+  type: 'regexp';
+  value: RegExp;
+}
+
+//
+// Atoms
+//
+interface FieldAtom extends Atom {
+  type: 'field';
+  name: string;
+}
+interface TypeAtom extends Atom {
+  type: 'type';
+  value: string;
+}
+interface SequenceAtom extends MultiSelectorAtom {
+  type: 'compound';
+}
+interface IdentifierAtom extends SubjectSelectorAtom {
+  type: 'identifier';
+  value: string;
+}
+interface WildcardAtom extends SubjectSelectorAtom {
+  type: 'wildcard';
+  value: '*';
+}
+interface AttributeAtom extends SubjectSelectorAtom {
+  type: 'attribute';
+  name: string;
+  operator?: ?('=' | '!=' | '>' | '<' | '>=' | '<=');
+  value?: ?(Literal | RegExpLiteralAtom | TypeAtom);
+}
+interface NthChildAtom extends NthSelectorAtom {
+  type: 'nth-child';
+}
+interface NthLastChildAtom extends NthSelectorAtom {
+  type: 'nth-last-child';
+}
+interface DescendantAtom extends BinarySelectorAtom {
+  type: 'descendant';
+}
+interface ChildAtom extends BinarySelectorAtom {
+  type: 'child';
+}
+interface SiblingAtom extends BinarySelectorAtom {
+  type: 'sibling';
+}
+interface AdjacentAtom extends BinarySelectorAtom {
+  type: 'adjacent';
+}
+interface NegationAtom extends MultiSelectorAtom {
+  type: 'not';
+}
+interface MatchesAtom extends MultiSelectorAtom {
+  type: 'matches';
+}
+interface HasAtom extends MultiSelectorAtom {
+  type: 'has';
+}
+interface ClassAtom extends Atom {
+  type: 'class';
+  name: 'declaration' | 'expression' | 'function' | 'pattern' | 'statement';
+}
+
+//
+// Unions
+//
+export type Selector =
+  | FieldAtom
+  | TypeAtom
+  | SequenceAtom
+  | IdentifierAtom
+  | WildcardAtom
+  | AttributeAtom
+  | NthChildAtom
+  | NthLastChildAtom
+  | DescendantAtom
+  | ChildAtom
+  | SiblingAtom
+  | AdjacentAtom
+  | NegationAtom
+  | MatchesAtom
+  | HasAtom
+  | ClassAtom;
+type MultiSelector = SequenceAtom | NegationAtom | MatchesAtom | HasAtom;
+type BinarySelector = DescendantAtom | ChildAtom | SiblingAtom | AdjacentAtom;
+type NthSelector = NthChildAtom | NthLastChildAtom;
+type SubjectSelector =
+  | NthSelector
+  | BinarySelector
+  | MultiSelector
+  | IdentifierAtom
+  | WildcardAtom
+  | AttributeAtom;
+type Literal = StringLiteralAtom | NumericLiteralAtom;
+
+export type ESQueryOptions = $ReadOnly<{
+  visitorKeys?: $ReadOnly<{[string]: $ReadOnlyArray<string>}>,
+  fallback?: (node: ESNode) => $ReadOnlyArray<string>,
+}>;
+
+/** Parse a selector and return its AST. */
+export const parse = (esquery.parse: (selector: string) => Selector);
+/** From a JS AST and a selector AST, collect all JS AST nodes that match the selector. */
+export const match = (esquery.match: (
+  ast: ESNode,
+  selector: ?Selector,
+  options?: ESQueryOptions,
+) => Array<ESNode>);
+/** Given a `node` and its ancestors, determine if `node` is matched by `selector`. */
+export const matches = (esquery.matches: (
+  node: ?ESNode,
+  selector: ?Selector,
+  ancestry?: Array<ESNode>,
+  options?: ESQueryOptions,
+) => boolean);
+/** Query the code AST using the selector string. */
+export const query = (esquery.query: (
+  ast: ESNode,
+  selector: string,
+  options?: ESQueryOptions,
+) => Array<ESNode>);

package/dist/traverse/traverse.js

@@ -0,0 +1,139 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.traverse = traverse;
+exports.traverseWithContext = traverseWithContext;
+
+var _NodeEventGenerator = require("./NodeEventGenerator");
+
+var _SafeEmitter = require("./SafeEmitter");
+
+var _SimpleTraverser = require("./SimpleTraverser");
+
+function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); if (enumerableOnly) { symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; }); } keys.push.apply(keys, symbols); } return keys; }
+
+function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i] != null ? arguments[i] : {}; if (i % 2) { ownKeys(Object(source), true).forEach(function (key) { _defineProperty(target, key, source[key]); }); } else if (Object.getOwnPropertyDescriptors) { Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)); } else { ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } } return target; }
+
+function _defineProperty(obj, key, value) { if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+
+function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it["return"] != null) it["return"](); } finally { if (didErr) throw err; } } }; }
+
+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 _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; }
+
+/**
+ * Traverse the AST with additional context members provided by `additionalContext`.
+ * @param ast the ESTree AST to traverse
+ * @param scopeManager the eslint-scope compatible scope manager instance calculated using the ast
+ * @param additionalContext a callback function which returns additional context members to add to the context provided to the visitor
+ */
+function traverseWithContext(ast, scopeManager, additionalContext, visitor) {
+  var emitter = new _SafeEmitter.SafeEmitter();
+  var nodeQueue = [];
+  var currentNode = ast; // set parent pointers and build up the traversal queue
+
+  _SimpleTraverser.SimpleTraverser.traverse(ast, {
+    enter: function enter(node, parent) {
+      // $FlowExpectedError[cannot-write] - hermes doesn't set this
+      node.parent = parent;
+      nodeQueue.push({
+        isEntering: true,
+        node: node
+      });
+    },
+    leave: function leave(node) {
+      nodeQueue.push({
+        isEntering: false,
+        node: node
+      });
+    }
+  });
+
+  var getScope = function getScope() {
+    var givenNode = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : currentNode;
+    // On Program node, get the outermost scope to avoid return Node.js special function scope or ES modules scope.
+    var inner = givenNode.type !== 'Program';
+
+    for (var _node = givenNode; _node; _node = _node.parent) {
+      var scope = scopeManager.acquire(_node, inner);
+
+      if (scope) {
+        if (scope.type === 'function-expression-name') {
+          return scope.childScopes[0];
+        }
+
+        return scope;
+      }
+    }
+
+    return scopeManager.scopes[0];
+  };
+
+  var traversalContextBase = Object.freeze({
+    getDeclaredVariables: function getDeclaredVariables(node) {
+      return scopeManager.getDeclaredVariables(node);
+    },
+    getBinding: function getBinding(name) {
+      var currentScope = getScope();
+
+      while (currentScope != null) {
+        var _iterator = _createForOfIteratorHelper(currentScope.variables),
+            _step;
+
+        try {
+          for (_iterator.s(); !(_step = _iterator.n()).done;) {
+            var variable = _step.value;
+
+            if (variable.defs.length && variable.name === name) {
+              return variable;
+            }
+          }
+        } catch (err) {
+          _iterator.e(err);
+        } finally {
+          _iterator.f();
+        }
+
+        currentScope = currentScope.upper;
+      }
+
+      return null;
+    },
+    getScope: getScope
+  });
+  var traversalContext = Object.freeze(_objectSpread(_objectSpread({}, traversalContextBase), additionalContext(traversalContextBase)));
+  var selectors = visitor(traversalContext); // add all the selectors from the visitor as listeners
+
+  Object.keys(selectors).forEach(function (selector) {
+    // flow doesn't want us to be general here - but it's safe
+    // $FlowExpectedError[incompatible-type]
+    // $FlowExpectedError[prop-missing]
+    var listener = selectors[selector];
+
+    if (listener) {
+      emitter.on(selector, listener);
+    }
+  });
+  var eventGenerator = new _NodeEventGenerator.NodeEventGenerator(emitter);
+  nodeQueue.forEach(function (traversalInfo) {
+    currentNode = traversalInfo.node;
+
+    try {
+      if (traversalInfo.isEntering) {
+        eventGenerator.enterNode(currentNode);
+      } else {
+        eventGenerator.leaveNode(currentNode);
+      }
+    } catch (err) {
+      err.currentNode = currentNode;
+      throw err;
+    }
+  });
+}
+
+function traverse(ast, scopeManager, visitor) {
+  traverseWithContext(ast, scopeManager, function () {}, visitor);
+}

package/dist/traverse/traverse.js.flow

@@ -0,0 +1,149 @@
+/**
+ * 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 {ESNode, ESQueryNodeSelectors, Program} from 'hermes-estree';
+import type {ScopeManager, Scope, Variable} from 'hermes-eslint';
+import type {EmitterListener} from './SafeEmitter';
+
+import {NodeEventGenerator} from './NodeEventGenerator';
+import {SafeEmitter} from './SafeEmitter';
+import {SimpleTraverser} from './SimpleTraverser';
+
+export type TraversalContext<T = void> = $ReadOnly<{
+  /**
+   * Gets the variables that were declared by the given node.
+   */
+  getDeclaredVariables: (node: ESNode) => $ReadOnlyArray<Variable>,
+  /**
+   * Gets the nearest variable declared for the given name declare in the
+   * current or an upper scope.
+   */
+  getBinding: (name: string) => ?Variable,
+  /**
+   * Gets the scope for the given node.
+   * Defaults to the currently traversed node.
+   */
+  getScope: (node?: ESNode) => Scope,
+
+  ...T,
+}>;
+
+export type Visitor<T = void> = (
+  context: TraversalContext<T>,
+) => ESQueryNodeSelectors;
+
+/**
+ * Traverse the AST with additional context members provided by `additionalContext`.
+ * @param ast the ESTree AST to traverse
+ * @param scopeManager the eslint-scope compatible scope manager instance calculated using the ast
+ * @param additionalContext a callback function which returns additional context members to add to the context provided to the visitor
+ */
+export function traverseWithContext<T = void>(
+  ast: Program,
+  scopeManager: ScopeManager,
+  additionalContext: (TraversalContext<void>) => T,
+  visitor: Visitor<T>,
+): void {
+  const emitter = new SafeEmitter();
+  const nodeQueue: Array<{isEntering: boolean, node: ESNode}> = [];
+
+  let currentNode: ESNode = ast;
+
+  // set parent pointers and build up the traversal queue
+  SimpleTraverser.traverse(ast, {
+    enter(node, parent) {
+      // $FlowExpectedError[cannot-write] - hermes doesn't set this
+      node.parent = parent;
+      nodeQueue.push({isEntering: true, node});
+    },
+    leave(node) {
+      nodeQueue.push({isEntering: false, node});
+    },
+  });
+
+  const getScope = (givenNode: ESNode = currentNode) => {
+    // On Program node, get the outermost scope to avoid return Node.js special function scope or ES modules scope.
+    const inner = givenNode.type !== 'Program';
+
+    for (let node = givenNode; node; node = node.parent) {
+      const scope = scopeManager.acquire(node, inner);
+
+      if (scope) {
+        if (scope.type === 'function-expression-name') {
+          return scope.childScopes[0];
+        }
+        return scope;
+      }
+    }
+
+    return scopeManager.scopes[0];
+  };
+
+  const traversalContextBase: TraversalContext<void> = Object.freeze({
+    getDeclaredVariables: (node: ESNode) =>
+      scopeManager.getDeclaredVariables(node),
+    getBinding: (name: string) => {
+      let currentScope = getScope();
+
+      while (currentScope != null) {
+        for (const variable of currentScope.variables) {
+          if (variable.defs.length && variable.name === name) {
+            return variable;
+          }
+        }
+        currentScope = currentScope.upper;
+      }
+
+      return null;
+    },
+    getScope,
+  });
+  const traversalContext: TraversalContext<T> = Object.freeze({
+    ...traversalContextBase,
+    ...additionalContext(traversalContextBase),
+  });
+
+  const selectors = visitor(traversalContext);
+
+  // add all the selectors from the visitor as listeners
+  Object.keys(selectors).forEach(selector => {
+    // flow doesn't want us to be general here - but it's safe
+    // $FlowExpectedError[incompatible-type]
+    // $FlowExpectedError[prop-missing]
+    const listener: ?EmitterListener = selectors[selector];
+    if (listener) {
+      emitter.on(selector, listener);
+    }
+  });
+
+  const eventGenerator = new NodeEventGenerator(emitter);
+  nodeQueue.forEach(traversalInfo => {
+    currentNode = traversalInfo.node;
+
+    try {
+      if (traversalInfo.isEntering) {
+        eventGenerator.enterNode(currentNode);
+      } else {
+        eventGenerator.leaveNode(currentNode);
+      }
+    } catch (err) {
+      err.currentNode = currentNode;
+      throw err;
+    }
+  });
+}
+
+export function traverse(
+  ast: Program,
+  scopeManager: ScopeManager,
+  visitor: Visitor<void>,
+): void {
+  traverseWithContext(ast, scopeManager, () => {}, visitor);
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "hermes-transform",
+  "version": "0.5.0",
+  "description": "Tools built on top of Hermes-ESTree to enable codebase transformation",
+  "main": "dist/index.js",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:facebook/hermes.git"
+  },
+  "dependencies": {
+    "esquery": "^1.4.0",
+    "hermes-eslint": "0.5.0",
+    "hermes-estree": "0.5.0"
+  },
+  "peerDependencies": {
+    "prettier": "^2.4.1"
+  },
+  "files": [
+    "dist"
+  ]
+}