hermes-parser 0.7.0 → 0.8.0

package/dist/HermesToESTreeAdapter.js.flow

@@ -21,6 +21,7 @@ import type {HermesNode} from './HermesAST';
 import type {ParserOptions} from './ParserOptions';
 
 import HermesASTAdapter from './HermesASTAdapter';
+import {getModuleDocblock} from './getModuleDocblock';
 
 declare var BigInt: ?(value: $FlowFixMe) => mixed;
 
@@ -45,6 +46,9 @@ export default class HermesToESTreeAdapter extends HermesASTAdapter {
     };
 
     node.range = [loc.rangeStart, loc.rangeEnd];
+
+    delete node.start;
+    delete node.end;
   }
 
   mapNode(node: HermesNode): HermesNode {
@@ -81,11 +85,22 @@ export default class HermesToESTreeAdapter extends HermesASTAdapter {
         return this.mapExportNamedDeclaration(node);
       case 'ExportAllDeclaration':
         return this.mapExportAllDeclaration(node);
-      case 'PrivateName':
-      case 'ClassPrivateProperty':
-        return this.mapPrivateProperty(node);
       case 'Property':
         return this.mapProperty(node);
+      case 'FunctionDeclaration':
+      case 'FunctionExpression':
+      case 'ArrowFunctionExpression':
+        return this.mapFunction(node);
+      case 'PrivateName':
+        return this.mapPrivateName(node);
+      case 'ClassProperty':
+      case 'ClassPrivateProperty':
+        return this.mapClassProperty(node);
+      case 'MemberExpression':
+      case 'OptionalMemberExpression':
+      case 'CallExpression':
+      case 'OptionalCallExpression':
+        return this.mapChainExpression(node);
       default:
         return this.mapNodeDefault(node);
     }
@@ -95,6 +110,8 @@ export default class HermesToESTreeAdapter extends HermesASTAdapter {
     node = this.mapNodeDefault(node);
     node.sourceType = this.getSourceType();
 
+    node.docblock = getModuleDocblock(node);
+
     return node;
   }
 
@@ -230,4 +247,191 @@ export default class HermesToESTreeAdapter extends HermesASTAdapter {
 
     return node;
   }
+
+  mapFunction(nodeUnprocessed: HermesNode): HermesNode {
+    const node = this.mapNodeDefault(nodeUnprocessed);
+
+    switch (node.type) {
+      case 'FunctionDeclaration':
+      case 'FunctionExpression':
+        node.expression = false;
+        return node;
+
+      case 'ArrowFunctionExpression':
+        node.expression = node.body.type !== 'BlockStatement';
+        return node;
+    }
+
+    return node;
+  }
+
+  mapChainExpression(nodeUnprocessed: HermesNode): HermesNode {
+    /*
+    NOTE - In the below comments `MemberExpression` and `CallExpression`
+           are completely interchangable. For terseness we just reference
+           one each time.
+    */
+
+    /*
+    Hermes uses the old babel-style AST:
+    ```
+    (one?.two).three?.four;
+    ^^^^^^^^^^^^^^^^^^^^^^ OptionalMemberExpression
+    ^^^^^^^^^^^^^^^^ MemberExpression
+     ^^^^^^^^ OptionalMemberExpression
+    ```
+
+    We need to convert it to the ESTree representation:
+    ```
+    (one?.two).three?.four;
+    ^^^^^^^^^^^^^^^^^^^^^^ ChainExpression
+    ^^^^^^^^^^^^^^^^^^^^^^ MemberExpression[optional = true]
+    ^^^^^^^^^^^^^^^^ MemberExpression[optional = false]
+     ^^^^^^^^ ChainExpression
+     ^^^^^^^^ MemberExpression[optional = true]
+    ```
+
+    We do this by converting the AST and its children (depth first), and then unwrapping
+    the resulting AST as appropriate.
+
+    Put another way:
+    1) traverse to the leaf
+    2) if the current node is an `OptionalMemberExpression`:
+      a) if the `.object` is a `ChainExpression`:
+        i)   unwrap the child (`node.object = child.expression`)
+      b) convert this node to a `MemberExpression[optional = true]`
+      c) wrap this node (`node = ChainExpression[expression = node]`)
+    3) if the current node is a `MembedExpression`:
+      a) convert this node to a `MemberExpression[optional = true]`
+    */
+
+    const node = this.mapNodeDefault(nodeUnprocessed);
+
+    const {child, childKey, isOptional} = ((): {
+      child: HermesNode,
+      childKey: string,
+      isOptional: boolean,
+    } => {
+      const isOptional: boolean = node.optional === true;
+      if (node.type.endsWith('MemberExpression')) {
+        return {
+          child: node.object,
+          childKey: 'object',
+          isOptional,
+        };
+      } else if (node.type.endsWith('CallExpression')) {
+        return {
+          child: node.callee,
+          childKey: 'callee',
+          isOptional,
+        };
+      } else {
+        return {
+          child: node.expression,
+          childKey: 'expression',
+          isOptional: false,
+        };
+      }
+    })();
+
+    const isChildUnwrappable =
+      child.type === 'ChainExpression' &&
+      // (x?.y).z is semantically different to `x?.y.z`.
+      // In the un-parenthesised case `.z` is only executed if and only if `x?.y` returns a non-nullish value.
+      // In the parenthesised case, `.z` is **always** executed, regardless of the return of `x?.y`.
+      // As such the AST is different between the two cases.
+      //
+      // In the hermes AST - any member part of a non-short-circuited optional chain is represented with `OptionalMemberExpression`
+      // so if we see a `MemberExpression`, then we know we've hit a parenthesis boundary.
+      node.type !== 'MemberExpression' &&
+      node.type !== 'CallExpression';
+
+    if (node.type.startsWith('Optional')) {
+      node.type = node.type.replace('Optional', '');
+      node.optional = isOptional;
+    } else {
+      node.optional = false;
+    }
+
+    if (!isChildUnwrappable && !isOptional) {
+      return node;
+    }
+
+    if (isChildUnwrappable) {
+      const newChild = child.expression;
+      node[childKey] = newChild;
+    }
+
+    return {
+      type: 'ChainExpression',
+      expression: node,
+      loc: node.loc,
+      range: node.range,
+    };
+  }
+
+  mapClassProperty(nodeUnprocessed: HermesNode): HermesNode {
+    const node = this.mapNodeDefault(nodeUnprocessed);
+
+    const key = (() => {
+      if (node.type === 'ClassPrivateProperty') {
+        const key = this.mapNodeDefault(node.key);
+        return {
+          type: 'PrivateIdentifier',
+          name: key.name,
+          range: key.range,
+          loc: key.loc,
+        };
+      }
+
+      return node.key;
+    })();
+
+    return {
+      ...node,
+      computed: node.type === 'ClassPrivateProperty' ? false : node.computed,
+      key,
+      type: 'PropertyDefinition',
+    };
+  }
+
+  mapPrivateName(node: HermesNode): HermesNode {
+    return {
+      type: 'PrivateIdentifier',
+      name: node.id.name,
+      // estree the location refers to the entire string including the hash token
+      range: node.range,
+      loc: node.loc,
+    };
+  }
+
+  mapExportNamedDeclaration(nodeUnprocessed: HermesNode): HermesNode {
+    const node = super.mapExportNamedDeclaration(nodeUnprocessed);
+
+    const namespaceSpecifier = node.specifiers.find(
+      spec => spec.type === 'ExportNamespaceSpecifier',
+    );
+    if (namespaceSpecifier != null) {
+      if (node.specifiers.length !== 1) {
+        // this should already a hermes parser error - but let's be absolutely sure we're aligned with the spec
+        throw new Error('Cannot use an export all with any other specifiers');
+      }
+      return {
+        type: 'ExportAllDeclaration',
+        source: node.source,
+        exportKind: node.exportKind ?? 'value',
+        exported: namespaceSpecifier.exported,
+        range: node.range,
+        loc: node.loc,
+      };
+    }
+
+    return node;
+  }
+
+  mapExportAllDeclaration(nodeUnprocessed: HermesNode): HermesNode {
+    const node = super.mapExportAllDeclaration(nodeUnprocessed);
+    node.exported = node.exported ?? null;
+    return node;
+  }
 }

package/dist/generated/visitor-keys.js

@@ -77,6 +77,9 @@ const HERMES_AST_VISITOR_KEYS = {
     param: 'Node',
     body: 'Node'
   },
+  ChainExpression: {
+    expression: 'Node'
+  },
   ClassBody: {
     body: 'NodeList'
   },
@@ -102,18 +105,6 @@ const HERMES_AST_VISITOR_KEYS = {
     id: 'Node',
     typeParameters: 'Node'
   },
-  ClassPrivateProperty: {
-    key: 'Node',
-    value: 'Node',
-    variance: 'Node',
-    typeAnnotation: 'Node'
-  },
-  ClassProperty: {
-    key: 'Node',
-    value: 'Node',
-    variance: 'Node',
-    typeAnnotation: 'Node'
-  },
   ConditionalExpression: {
     test: 'Node',
     alternate: 'Node',
@@ -212,6 +203,7 @@ const HERMES_AST_VISITOR_KEYS = {
   },
   ExistsTypeAnnotation: {},
   ExportAllDeclaration: {
+    exported: 'Node',
     source: 'Node'
   },
   ExportDefaultDeclaration: {
@@ -222,9 +214,6 @@ const HERMES_AST_VISITOR_KEYS = {
     specifiers: 'NodeList',
     source: 'Node'
   },
-  ExportNamespaceSpecifier: {
-    exported: 'Node'
-  },
   ExportSpecifier: {
     exported: 'Node',
     local: 'Node'
@@ -449,22 +438,11 @@ const HERMES_AST_VISITOR_KEYS = {
     impltype: 'Node',
     supertype: 'Node'
   },
-  OptionalCallExpression: {
-    callee: 'Node',
-    typeArguments: 'Node',
-    arguments: 'NodeList'
-  },
   OptionalIndexedAccessType: {
     objectType: 'Node',
     indexType: 'Node'
   },
-  OptionalMemberExpression: {
-    object: 'Node',
-    property: 'Node'
-  },
-  PrivateName: {
-    id: 'Node'
-  },
+  PrivateIdentifier: {},
   Program: {
     body: 'NodeList'
   },
@@ -472,6 +450,12 @@ const HERMES_AST_VISITOR_KEYS = {
     key: 'Node',
     value: 'Node'
   },
+  PropertyDefinition: {
+    key: 'Node',
+    value: 'Node',
+    variance: 'Node',
+    typeAnnotation: 'Node'
+  },
   QualifiedTypeIdentifier: {
     qualification: 'Node',
     id: 'Node'
@@ -600,6 +584,30 @@ const HERMES_AST_VISITOR_KEYS = {
     returnType: 'Node',
     typeParameters: 'NodeList'
   },
-  Import: {}
+  Import: {},
+  ClassProperty: {
+    key: 'Node',
+    value: 'Node',
+    variance: 'Node',
+    typeAnnotation: 'Node'
+  },
+  ClassPrivateProperty: {
+    key: 'Node',
+    value: 'Node',
+    variance: 'Node',
+    typeAnnotation: 'Node'
+  },
+  PrivateName: {
+    id: 'Node'
+  },
+  OptionalCallExpression: {
+    callee: 'Node',
+    typeArguments: 'Node',
+    arguments: 'NodeList'
+  },
+  OptionalMemberExpression: {
+    object: 'Node',
+    property: 'Node'
+  }
 };
 exports.HERMES_AST_VISITOR_KEYS = HERMES_AST_VISITOR_KEYS;

package/dist/getModuleDocblock.js

@@ -0,0 +1,111 @@
+/**
+ * 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.getModuleDocblock = getModuleDocblock;
+exports.parseDocblockString = parseDocblockString;
+const DIRECTIVE_REGEX = /^\s*@([a-zA-Z0-9_-]+)( +.+)?$/;
+
+function parseDocblockString(docblock) {
+  const directiveLines = docblock.split('\n') // remove the leading " *" from each line
+  .map(line => line.trimStart().replace(/^\* ?/, '').trim()).filter(line => line.startsWith('@'));
+  const directives = {};
+
+  for (const line of directiveLines) {
+    var _match$;
+
+    const match = DIRECTIVE_REGEX.exec(line);
+
+    if (match == null) {
+      continue;
+    }
+
+    const name = match[1]; // explicitly use an empty string if there's no value
+    // this way the array length tracks how many instances of the directive there was
+
+    const value = ((_match$ = match[2]) != null ? _match$ : '').trim();
+
+    if (directives[name]) {
+      directives[name].push(value);
+    } else {
+      directives[name] = [value];
+    }
+  }
+
+  return directives;
+}
+
+function getModuleDocblock(hermesProgram) {
+  const docblockNode = (() => {
+    if (hermesProgram.type !== 'Program') {
+      return null;
+    } // $FlowExpectedError[incompatible-type] - escape out of the unsafe hermes types
+
+
+    const program = hermesProgram;
+
+    if (program.comments.length === 0) {
+      return null;
+    }
+
+    const firstComment = (() => {
+      const first = program.comments[0];
+
+      if (first.type === 'Block') {
+        return first;
+      }
+
+      if (program.comments.length === 1) {
+        return null;
+      } // ESLint will always strip out the shebang comment from the code before passing it to the parser
+      // https://github.com/eslint/eslint/blob/21d647904dc30f9484b22acdd9243a6d0ecfba38/lib/linter/linter.js#L779
+      // this means that we're forced to parse it as a line comment :(
+      // this hacks around it by selecting the second comment in this case
+
+
+      const second = program.comments[1];
+
+      if (first.type === 'Line' && first.range[0] === 0 && second.type === 'Block') {
+        return second;
+      }
+
+      return null;
+    })();
+
+    if (firstComment == null) {
+      return null;
+    }
+    /*
+    Handle cases like this where the comment isn't actually the first thing in the code:
+    ```
+    const x = 1; /* docblock *./
+    ```
+    */
+
+
+    if (program.body.length > 0 && program.body[0].range[0] < firstComment.range[0]) {
+      return null;
+    }
+
+    return firstComment;
+  })();
+
+  if (docblockNode == null) {
+    return null;
+  }
+
+  return {
+    directives: parseDocblockString(docblockNode.value),
+    comment: docblockNode
+  };
+}

package/dist/getModuleDocblock.js.flow

@@ -0,0 +1,116 @@
+/**
+ * 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
+ * @format
+ */
+
+'use strict';
+
+import type {HermesNode} from './HermesAST';
+import type {DocblockDirectives, Program} from 'hermes-estree';
+
+const DIRECTIVE_REGEX = /^\s*@([a-zA-Z0-9_-]+)( +.+)?$/;
+
+export function parseDocblockString(docblock: string): DocblockDirectives {
+  const directiveLines = docblock
+    .split('\n')
+    // remove the leading " *" from each line
+    .map(line => line.trimStart().replace(/^\* ?/, '').trim())
+    .filter(line => line.startsWith('@'));
+
+  const directives: {
+    [string]: Array<string>,
+  } = {};
+
+  for (const line of directiveLines) {
+    const match = DIRECTIVE_REGEX.exec(line);
+    if (match == null) {
+      continue;
+    }
+    const name = match[1];
+    // explicitly use an empty string if there's no value
+    // this way the array length tracks how many instances of the directive there was
+    const value = (match[2] ?? '').trim();
+    if (directives[name]) {
+      directives[name].push(value);
+    } else {
+      directives[name] = [value];
+    }
+  }
+
+  return directives;
+}
+
+export function getModuleDocblock(
+  hermesProgram: HermesNode,
+): Program['docblock'] {
+  const docblockNode = (() => {
+    if (hermesProgram.type !== 'Program') {
+      return null;
+    }
+
+    // $FlowExpectedError[incompatible-type] - escape out of the unsafe hermes types
+    const program: Program = hermesProgram;
+
+    if (program.comments.length === 0) {
+      return null;
+    }
+
+    const firstComment = (() => {
+      const first = program.comments[0];
+      if (first.type === 'Block') {
+        return first;
+      }
+
+      if (program.comments.length === 1) {
+        return null;
+      }
+
+      // ESLint will always strip out the shebang comment from the code before passing it to the parser
+      // https://github.com/eslint/eslint/blob/21d647904dc30f9484b22acdd9243a6d0ecfba38/lib/linter/linter.js#L779
+      // this means that we're forced to parse it as a line comment :(
+      // this hacks around it by selecting the second comment in this case
+      const second = program.comments[1];
+      if (
+        first.type === 'Line' &&
+        first.range[0] === 0 &&
+        second.type === 'Block'
+      ) {
+        return second;
+      }
+
+      return null;
+    })();
+    if (firstComment == null) {
+      return null;
+    }
+
+    /*
+    Handle cases like this where the comment isn't actually the first thing in the code:
+    ```
+    const x = 1; /* docblock *./
+    ```
+    */
+    if (
+      program.body.length > 0 &&
+      program.body[0].range[0] < firstComment.range[0]
+    ) {
+      return null;
+    }
+
+    return firstComment;
+  })();
+
+  if (docblockNode == null) {
+    return null;
+  }
+
+  return {
+    directives: parseDocblockString(docblockNode.value),
+    comment: docblockNode,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hermes-parser",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A JavaScript parser built from the Hermes engine",
   "main": "dist/index.js",
   "license": "MIT",
@@ -9,10 +9,12 @@
     "url": "git@github.com:facebook/hermes.git"
   },
   "dependencies": {
-    "hermes-estree": "0.7.0"
+    "hermes-estree": "0.8.0"
   },
   "devDependencies": {
-    "hermes-transform": "0.7.0"
+    "@babel/parser": "7.7.4",
+    "espree": "9.3.2",
+    "hermes-transform": "0.8.0"
   },
   "files": [
     "dist"