hermes-estree 0.9.0 → 0.10.1

package/dist/HermesAST.js.flow

@@ -0,0 +1,57 @@
+/**
+ * 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
+ */
+
+// flowlint unclear-type:off
+
+export interface HermesPosition {
+  /** >= 1 */
+  +line: number;
+  /** >= 0 */
+  +column: number;
+}
+export type HermesSourceLocation = {
+  start?: HermesPosition,
+  end?: HermesPosition,
+  rangeStart?: number,
+  rangeEnd?: number,
+};
+export type HermesNode = {
+  type: string,
+  [string]: any,
+};
+export type HermesToken = {
+  type:
+    | 'Boolean'
+    | 'Identifier'
+    | 'Keyword'
+    | 'Null'
+    | 'Numeric'
+    | 'BigInt'
+    | 'Punctuator'
+    | 'String'
+    | 'RegularExpression'
+    | 'Template'
+    | 'JSXText',
+  loc: HermesSourceLocation,
+  value: ?string,
+};
+export type HermesComment = {
+  type: 'CommentLine' | 'CommentBlock' | 'InterpreterDirective',
+  loc: HermesSourceLocation,
+  value: ?string,
+};
+export type HermesProgram = {
+  type: 'Program',
+  loc: HermesSourceLocation,
+  body: Array<?HermesNode>,
+  comments: Array<HermesComment>,
+  tokens?: Array<HermesToken>,
+  interpreter?: ?HermesComment,
+};

package/dist/HermesASTAdapter.js

@@ -0,0 +1,186 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _ParserVisitorKeys = require("./generated/ParserVisitorKeys");
+
+/**
+ * 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
+ */
+
+/**
+ * The base class for transforming the Hermes AST to the desired output format.
+ * Extended by concrete adapters which output an ESTree or Babel AST.
+ */
+class HermesASTAdapter {
+  constructor(options) {
+    this.sourceFilename = void 0;
+    this.sourceType = void 0;
+    this.sourceFilename = options.sourceFilename;
+    this.sourceType = options.sourceType;
+  }
+  /**
+   * Transform the input Hermes AST to the desired output format.
+   * This modifies the input AST in place instead of constructing a new AST.
+   */
+
+
+  transform(program) {
+    // Comments are not traversed via visitor keys
+    const comments = program.comments;
+
+    for (let i = 0; i < comments.length; i++) {
+      const comment = comments[i];
+      this.fixSourceLocation(comment);
+      comments[i] = this.mapComment(comment);
+    } // The first comment may be an interpreter directive and is stored directly on the program node
+
+
+    program.interpreter = comments.length > 0 && comments[0].type === 'InterpreterDirective' ? comments.shift() : null; // Tokens are not traversed via visitor keys
+
+    const tokens = program.tokens;
+
+    if (tokens) {
+      for (let i = 0; i < tokens.length; i++) {
+        this.fixSourceLocation(tokens[i]);
+      }
+    }
+
+    return this.mapNode(program);
+  }
+  /**
+   * Transform a Hermes AST node to the output AST format.
+   *
+   * This may modify the input node in-place and return that same node, or a completely
+   * new node may be constructed and returned. Overriden in child classes.
+   */
+
+
+  mapNode(_node) {
+    throw new Error('Implemented in subclasses');
+  }
+
+  mapNodeDefault(node) {
+    const visitorKeys = _ParserVisitorKeys.HERMES_AST_VISITOR_KEYS[node.type];
+
+    for (const key in visitorKeys) {
+      const childType = visitorKeys[key];
+
+      if (childType === _ParserVisitorKeys.NODE_CHILD) {
+        const child = node[key];
+
+        if (child != null) {
+          node[key] = this.mapNode(child);
+        }
+      } else if (childType === _ParserVisitorKeys.NODE_LIST_CHILD) {
+        const children = node[key];
+
+        for (let i = 0; i < children.length; i++) {
+          const child = children[i];
+
+          if (child != null) {
+            children[i] = this.mapNode(child);
+          }
+        }
+      }
+    }
+
+    return node;
+  }
+  /**
+   * Update the source location for this node depending on the output AST format.
+   * This can modify the input node in-place. Overriden in child classes.
+   */
+
+
+  fixSourceLocation(_node) {
+    throw new Error('Implemented in subclasses');
+  }
+
+  getSourceType() {
+    var _this$sourceType;
+
+    return (_this$sourceType = this.sourceType) != null ? _this$sourceType : 'script';
+  }
+
+  setModuleSourceType() {
+    if (this.sourceType == null) {
+      this.sourceType = 'module';
+    }
+  }
+
+  mapComment(node) {
+    return node;
+  }
+
+  mapEmpty(_node) {
+    // $FlowExpectedError
+    return null;
+  }
+
+  mapImportDeclaration(node) {
+    if (node.importKind === 'value') {
+      this.setModuleSourceType();
+    }
+
+    return this.mapNodeDefault(node);
+  }
+
+  mapImportSpecifier(node) {
+    if (node.importKind === 'value') {
+      node.importKind = null;
+    }
+
+    return this.mapNodeDefault(node);
+  }
+
+  mapExportDefaultDeclaration(node) {
+    this.setModuleSourceType();
+    return this.mapNodeDefault(node);
+  }
+
+  mapExportNamedDeclaration(node) {
+    if (node.exportKind === 'value') {
+      this.setModuleSourceType();
+    }
+
+    return this.mapNodeDefault(node);
+  }
+
+  mapExportAllDeclaration(node) {
+    if (node.exportKind === 'value') {
+      this.setModuleSourceType();
+    }
+
+    return this.mapNodeDefault(node);
+  }
+
+  formatError(node, message) {
+    return `${message} (${node.loc.start.line}:${node.loc.start.column})`;
+  }
+
+  getBigIntLiteralValue(bigintString) {
+    // TODO - once we update flow we can remove this
+    const bigint = bigintString // estree spec is to not have a trailing `n` on this property
+    // https://github.com/estree/estree/blob/db962bb417a97effcfe9892f87fbb93c81a68584/es2020.md#bigintliteral
+    .replace(/n$/, '') // `BigInt` doesn't accept numeric separator and `bigint` property should not include numeric separator
+    .replace(/_/, '');
+    return {
+      bigint,
+      // coerce the string to a bigint value if supported by the environment
+      value: typeof BigInt === 'function' ? BigInt(bigint) : null
+    };
+  }
+
+}
+
+exports.default = HermesASTAdapter;

package/dist/HermesASTAdapter.js.flow

@@ -0,0 +1,183 @@
+/**
+ * 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
+ */
+
+import type {HermesNode} from './HermesAST';
+import type {ParserOptions} from './ParserOptions';
+
+import {
+  HERMES_AST_VISITOR_KEYS,
+  NODE_CHILD,
+  NODE_LIST_CHILD,
+} from './generated/ParserVisitorKeys';
+
+/**
+ * The base class for transforming the Hermes AST to the desired output format.
+ * Extended by concrete adapters which output an ESTree or Babel AST.
+ */
+export default class HermesASTAdapter {
+  sourceFilename: ParserOptions['sourceFilename'];
+  sourceType: ParserOptions['sourceType'];
+
+  constructor(options: ParserOptions) {
+    this.sourceFilename = options.sourceFilename;
+    this.sourceType = options.sourceType;
+  }
+
+  /**
+   * Transform the input Hermes AST to the desired output format.
+   * This modifies the input AST in place instead of constructing a new AST.
+   */
+  transform(program: HermesNode): ?HermesNode {
+    // Comments are not traversed via visitor keys
+    const comments = program.comments;
+    for (let i = 0; i < comments.length; i++) {
+      const comment = comments[i];
+      this.fixSourceLocation(comment);
+      comments[i] = this.mapComment(comment);
+    }
+
+    // The first comment may be an interpreter directive and is stored directly on the program node
+    program.interpreter =
+      comments.length > 0 && comments[0].type === 'InterpreterDirective'
+        ? comments.shift()
+        : null;
+
+    // Tokens are not traversed via visitor keys
+    const tokens = program.tokens;
+    if (tokens) {
+      for (let i = 0; i < tokens.length; i++) {
+        this.fixSourceLocation(tokens[i]);
+      }
+    }
+
+    return this.mapNode(program);
+  }
+
+  /**
+   * Transform a Hermes AST node to the output AST format.
+   *
+   * This may modify the input node in-place and return that same node, or a completely
+   * new node may be constructed and returned. Overriden in child classes.
+   */
+  mapNode(_node: HermesNode): HermesNode {
+    throw new Error('Implemented in subclasses');
+  }
+
+  mapNodeDefault(node: HermesNode): HermesNode {
+    const visitorKeys = HERMES_AST_VISITOR_KEYS[node.type];
+    for (const key in visitorKeys) {
+      const childType = visitorKeys[key];
+      if (childType === NODE_CHILD) {
+        const child = node[key];
+        if (child != null) {
+          node[key] = this.mapNode(child);
+        }
+      } else if (childType === NODE_LIST_CHILD) {
+        const children = node[key];
+        for (let i = 0; i < children.length; i++) {
+          const child = children[i];
+          if (child != null) {
+            children[i] = this.mapNode(child);
+          }
+        }
+      }
+    }
+
+    return node;
+  }
+
+  /**
+   * Update the source location for this node depending on the output AST format.
+   * This can modify the input node in-place. Overriden in child classes.
+   */
+  fixSourceLocation(_node: HermesNode): void {
+    throw new Error('Implemented in subclasses');
+  }
+
+  getSourceType(): ParserOptions['sourceType'] {
+    return this.sourceType ?? 'script';
+  }
+
+  setModuleSourceType(): void {
+    if (this.sourceType == null) {
+      this.sourceType = 'module';
+    }
+  }
+
+  mapComment(node: HermesNode): HermesNode {
+    return node;
+  }
+
+  mapEmpty(_node: HermesNode): HermesNode {
+    // $FlowExpectedError
+    return null;
+  }
+
+  mapImportDeclaration(node: HermesNode): HermesNode {
+    if (node.importKind === 'value') {
+      this.setModuleSourceType();
+    }
+
+    return this.mapNodeDefault(node);
+  }
+
+  mapImportSpecifier(node: HermesNode): HermesNode {
+    if (node.importKind === 'value') {
+      node.importKind = null;
+    }
+
+    return this.mapNodeDefault(node);
+  }
+
+  mapExportDefaultDeclaration(node: HermesNode): HermesNode {
+    this.setModuleSourceType();
+    return this.mapNodeDefault(node);
+  }
+
+  mapExportNamedDeclaration(node: HermesNode): HermesNode {
+    if (node.exportKind === 'value') {
+      this.setModuleSourceType();
+    }
+
+    return this.mapNodeDefault(node);
+  }
+
+  mapExportAllDeclaration(node: HermesNode): HermesNode {
+    if (node.exportKind === 'value') {
+      this.setModuleSourceType();
+    }
+
+    return this.mapNodeDefault(node);
+  }
+
+  formatError(node: HermesNode, message: string): string {
+    return `${message} (${node.loc.start.line}:${node.loc.start.column})`;
+  }
+
+  getBigIntLiteralValue(bigintString: string): {
+    bigint: string,
+    value: $FlowFixMe /* bigint */,
+  } {
+    // TODO - once we update flow we can remove this
+    declare var BigInt: ?(value: $FlowFixMe) => mixed;
+
+    const bigint = bigintString
+      // estree spec is to not have a trailing `n` on this property
+      // https://github.com/estree/estree/blob/db962bb417a97effcfe9892f87fbb93c81a68584/es2020.md#bigintliteral
+      .replace(/n$/, '')
+      // `BigInt` doesn't accept numeric separator and `bigint` property should not include numeric separator
+      .replace(/_/, '');
+    return {
+      bigint,
+      // coerce the string to a bigint value if supported by the environment
+      value: typeof BigInt === 'function' ? BigInt(bigint) : null,
+    };
+  }
+}

package/dist/HermesParser.js

@@ -0,0 +1,83 @@
+/**
+ * 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.parse = parse;
+
+var _HermesParserDeserializer = _interopRequireDefault(require("./HermesParserDeserializer"));
+
+var _HermesParserWASM = _interopRequireDefault(require("./HermesParserWASM"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+const hermesParse = _HermesParserWASM.default.cwrap('hermesParse', 'number', ['number', 'number', 'number', 'number', 'number']);
+
+const hermesParseResult_free = _HermesParserWASM.default.cwrap('hermesParseResult_free', 'void', ['number']);
+
+const hermesParseResult_getError = _HermesParserWASM.default.cwrap('hermesParseResult_getError', 'string', ['number']);
+
+const hermesParseResult_getErrorLine = _HermesParserWASM.default.cwrap('hermesParseResult_getErrorLine', 'number', ['number']);
+
+const hermesParseResult_getErrorColumn = _HermesParserWASM.default.cwrap('hermesParseResult_getErrorColumn', 'number', ['number']);
+
+const hermesParseResult_getProgramBuffer = _HermesParserWASM.default.cwrap('hermesParseResult_getProgramBuffer', 'number', ['number']);
+
+const hermesParseResult_getPositionBuffer = _HermesParserWASM.default.cwrap('hermesParseResult_getPositionBuffer', 'number', ['number']);
+
+const hermesParseResult_getPositionBufferSize = _HermesParserWASM.default.cwrap('hermesParseResult_getPositionBufferSize', 'number', ['number']); // Copy a string into the WASM heap and null-terminate
+
+
+function copyToHeap(buffer, addr) {
+  _HermesParserWASM.default.HEAP8.set(buffer, addr);
+
+  _HermesParserWASM.default.HEAP8[addr + buffer.length] = 0;
+}
+
+function parse(source, options) {
+  // Allocate space on heap for source text
+  const sourceBuffer = Buffer.from(source, 'utf8');
+
+  const sourceAddr = _HermesParserWASM.default._malloc(sourceBuffer.length + 1);
+
+  if (!sourceAddr) {
+    throw new Error('Parser out of memory');
+  }
+
+  try {
+    // Copy source text onto WASM heap
+    copyToHeap(sourceBuffer, sourceAddr);
+    const parseResult = hermesParse(sourceAddr, sourceBuffer.length + 1, options.flow === 'detect', options.tokens, options.allowReturnOutsideFunction);
+
+    try {
+      // Extract and throw error from parse result if parsing failed
+      const err = hermesParseResult_getError(parseResult);
+
+      if (err) {
+        const syntaxError = new SyntaxError(err); // $FlowExpectedError[prop-missing]
+
+        syntaxError.loc = {
+          line: hermesParseResult_getErrorLine(parseResult),
+          column: hermesParseResult_getErrorColumn(parseResult)
+        };
+        throw syntaxError;
+      }
+
+      const deserializer = new _HermesParserDeserializer.default(hermesParseResult_getProgramBuffer(parseResult), hermesParseResult_getPositionBuffer(parseResult), hermesParseResult_getPositionBufferSize(parseResult), _HermesParserWASM.default, options);
+      return deserializer.deserialize();
+    } finally {
+      hermesParseResult_free(parseResult);
+    }
+  } finally {
+    _HermesParserWASM.default._free(sourceAddr);
+  }
+}

package/dist/HermesParser.js.flow

@@ -0,0 +1,123 @@
+/**
+ * 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 {ParserOptions} from './ParserOptions';
+
+import HermesParserDeserializer from './HermesParserDeserializer';
+import HermesParserWASM from './HermesParserWASM';
+
+const hermesParse = HermesParserWASM.cwrap('hermesParse', 'number', [
+  'number',
+  'number',
+  'number',
+  'number',
+  'number',
+]);
+
+const hermesParseResult_free = HermesParserWASM.cwrap(
+  'hermesParseResult_free',
+  'void',
+  ['number'],
+);
+
+const hermesParseResult_getError = HermesParserWASM.cwrap(
+  'hermesParseResult_getError',
+  'string',
+  ['number'],
+);
+
+const hermesParseResult_getErrorLine = HermesParserWASM.cwrap(
+  'hermesParseResult_getErrorLine',
+  'number',
+  ['number'],
+);
+
+const hermesParseResult_getErrorColumn = HermesParserWASM.cwrap(
+  'hermesParseResult_getErrorColumn',
+  'number',
+  ['number'],
+);
+
+const hermesParseResult_getProgramBuffer = HermesParserWASM.cwrap(
+  'hermesParseResult_getProgramBuffer',
+  'number',
+  ['number'],
+);
+
+const hermesParseResult_getPositionBuffer = HermesParserWASM.cwrap(
+  'hermesParseResult_getPositionBuffer',
+  'number',
+  ['number'],
+);
+
+const hermesParseResult_getPositionBufferSize = HermesParserWASM.cwrap(
+  'hermesParseResult_getPositionBufferSize',
+  'number',
+  ['number'],
+);
+
+// Copy a string into the WASM heap and null-terminate
+function copyToHeap(buffer: Buffer, addr: number) {
+  HermesParserWASM.HEAP8.set(buffer, addr);
+  HermesParserWASM.HEAP8[addr + buffer.length] = 0;
+}
+
+export function parse(source: string, options: ParserOptions): HermesNode {
+  // Allocate space on heap for source text
+  const sourceBuffer = Buffer.from(source, 'utf8');
+  const sourceAddr = HermesParserWASM._malloc(sourceBuffer.length + 1);
+  if (!sourceAddr) {
+    throw new Error('Parser out of memory');
+  }
+
+  try {
+    // Copy source text onto WASM heap
+    copyToHeap(sourceBuffer, sourceAddr);
+
+    const parseResult = hermesParse(
+      sourceAddr,
+      sourceBuffer.length + 1,
+      options.flow === 'detect',
+      options.tokens,
+      options.allowReturnOutsideFunction,
+    );
+
+    try {
+      // Extract and throw error from parse result if parsing failed
+      const err = hermesParseResult_getError(parseResult);
+      if (err) {
+        const syntaxError = new SyntaxError(err);
+        // $FlowExpectedError[prop-missing]
+        syntaxError.loc = {
+          line: hermesParseResult_getErrorLine(parseResult),
+          column: hermesParseResult_getErrorColumn(parseResult),
+        };
+
+        throw syntaxError;
+      }
+
+      const deserializer = new HermesParserDeserializer(
+        hermesParseResult_getProgramBuffer(parseResult),
+        hermesParseResult_getPositionBuffer(parseResult),
+        hermesParseResult_getPositionBufferSize(parseResult),
+        HermesParserWASM,
+        options,
+      );
+      return deserializer.deserialize();
+    } finally {
+      hermesParseResult_free(parseResult);
+    }
+  } finally {
+    HermesParserWASM._free(sourceAddr);
+  }
+}

package/dist/HermesParserDecodeUTF8String.js

@@ -0,0 +1,68 @@
+/**
+ * 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';
+/**
+ * Decode a UTF-8 encoded string from Hermes with a known length.
+ * Based on Emscripten's UTF8ToString with the following differences:
+ * - Always reads all bytes up to the given length, including null bytes. This
+ *   means that we can decode strings that contain null bytes in the middle.
+ * - Allow UTF-8 encoded code points that are part of a surrogate pair, even though
+ *   this is technically invalid UTF-8 that UTF8ToString would convert to 0xfffd.
+ */
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = HermesParserDecodeUTF8String;
+
+function HermesParserDecodeUTF8String(ptrIn, length, heap) {
+  let ptr = ptrIn;
+  const endPtr = ptr + length;
+  let str = '';
+
+  while (ptr < endPtr) {
+    // ASCII characters fit in single byte code point
+    let u0 = heap[ptr++];
+
+    if (!(u0 & 0x80)) {
+      str += String.fromCharCode(u0);
+      continue;
+    } // Two byte code point
+
+
+    const u1 = heap[ptr++] & 0x3f;
+
+    if ((u0 & 0xe0) === 0xc0) {
+      str += String.fromCharCode((u0 & 0x1f) << 6 | u1);
+      continue;
+    }
+
+    const u2 = heap[ptr++] & 0x3f;
+
+    if ((u0 & 0xf0) === 0xe0) {
+      // Three byte code point
+      u0 = (u0 & 0x0f) << 12 | u1 << 6 | u2;
+    } else {
+      // Four byte code point
+      u0 = (u0 & 0x07) << 18 | u1 << 12 | u2 << 6 | heap[ptr++] & 0x3f;
+    }
+
+    if (u0 < 0x10000) {
+      // Code point fits into a single UTF-16 code unit
+      str += String.fromCharCode(u0);
+    } else {
+      // Code point does not fit into single UTF-16 code unit so convert to surrogate pair
+      u0 -= 0x10000;
+      str += String.fromCharCode(0xd800 | u0 >> 10, 0xdc00 | u0 & 0x3ff);
+    }
+  }
+
+  return str;
+}