@ohos-ports/hermes-parser 0.37.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# hermes-parser
+A JavaScript parser built from the Hermes engine's parser compiled to WebAssembly. Can parse ES6, Flow, and JSX syntax.
+
+## API
+The Hermes parser exposes a single `parse(code, [options])` function, where `code` is the source code to parse as a string, and `options` is an optional object that may contain the following properties:
+- **babel**: `boolean`, defaults to `false`. If `true`, output an AST conforming to Babel's AST format. If `false`, output an AST conforming to the ESTree AST format.
+- **allowReturnOutsideFunction**: `boolean`, defaults to `false`. If `true`, do not error on return statements found outside functions.
+- **flow**: `"all"` or `"detect"`, defaults to `"detect"`. If `"detect"`, only parse syntax as Flow syntax where it is ambiguous whether it is a Flow feature or regular JavaScript when the `@flow` pragma is present in the file. Otherwise if `"all"`, always parse ambiguous syntax as Flow syntax regardless of the presence of an `@flow` pragma. For example `foo<T>(x)` in a file without an `@flow` pragma will be parsed as two comparisons if set to `"detect"`, otherwise if set to `"all"` or the `@flow` pragma is included it will be parsed as a call expression with a type argument.
+- **sourceFilename**: `string`, defaults to `null`. The filename corresponding to the code that is to be parsed. If non-null, the filename will be added to all source locations in the output AST.
+- **sourceType**: `"module"`, `"script"`, or `"unambiguous"` (default). If `"unambiguous"`, source type will be automatically detected and set to `"module"` if any ES6 imports or exports are present in the code, otherwise source type will be set to `"script"`.
+- **tokens**: `boolean`, defaults to `false`. If `true`, add all tokens to a `tokens` property on the root node.
+- **transformOptions**: `object`. Options to be supplied to relevant transforms.
+  - `TransformEnumSyntax`
+    - `enable`: `boolean` - Whether to enable the transform. By default, `false`.
+    - `getRuntime` (optional): `() => Expression` - The expression which should be a reference to the Flow Enums runtime. By default, is `require('flow-enums-runtime')`.

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 type HermesPosition = {
+  /** >= 1 */
+  readonly line: number,
+  /** >= 0 */
+  readonly 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,192 @@
+"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.
+ *
+ *  strict
+ * @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]);
+      }
+    }
+
+    const resultNode = this.mapNode(program);
+
+    if (resultNode.type !== 'Program') {
+      throw new Error(`HermesToESTreeAdapter: Must return a Program node, instead of "${resultNode.type}". `);
+    } // $FlowExpectedError[incompatible-type] We know this is a program at this point.
+
+
+    return resultNode;
+  }
+  /**
+   * 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[incompatible-type]
+    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) {
+    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
+    .replaceAll('_', '');
+    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,189 @@
+/**
+ * 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 {Program} from 'hermes-estree';
+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): 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]);
+      }
+    }
+
+    const resultNode = this.mapNode(program);
+    if (resultNode.type !== 'Program') {
+      throw new Error(
+        `HermesToESTreeAdapter: Must return a Program node, instead of "${resultNode.type}". `,
+      );
+    }
+
+    // $FlowExpectedError[incompatible-type] We know this is a program at this point.
+    return resultNode;
+  }
+
+  /**
+   * 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[incompatible-type]
+    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: bigint | null,
+  } {
+    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
+      .replaceAll('_', '');
+    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,108 @@
+/**
+ * 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.
+ *
+ *  strict
+ * @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 }; }
+
+let HermesParserWASM;
+let hermesParse;
+let hermesParseResult_free;
+let hermesParseResult_getError;
+let hermesParseResult_getErrorLine;
+let hermesParseResult_getErrorColumn;
+let hermesParseResult_getProgramBuffer;
+let hermesParseResult_getPositionBuffer;
+let hermesParseResult_getPositionBufferSize;
+/**
+ * Init the WASM wrapper code generated by `emscripten` to preparse the
+ * HermesParser WASM code.
+ */
+
+function initHermesParserWASM() {
+  if (HermesParserWASM != null) {
+    return;
+  }
+
+  HermesParserWASM = (0, _HermesParserWASM.default)({
+    /**
+     * The emscripten version of `quit` unconditionally assigns the `status` to
+     * `process.exitCode` which overrides any pre-existing code that has been
+     * set, even if it is non zero. For our use case we never want an
+     * `exitCode` to be set so this override removes that functionality.
+     */
+    quit(_status, toThrow) {
+      throw toThrow;
+    }
+
+  });
+  hermesParse = HermesParserWASM.cwrap('hermesParse', 'number', ['number', 'number', 'number', 'number', 'number', 'number', 'number', 'number']);
+  hermesParseResult_free = HermesParserWASM.cwrap('hermesParseResult_free', 'void', ['number']);
+  hermesParseResult_getError = HermesParserWASM.cwrap('hermesParseResult_getError', 'string', ['number']);
+  hermesParseResult_getErrorLine = HermesParserWASM.cwrap('hermesParseResult_getErrorLine', 'number', ['number']);
+  hermesParseResult_getErrorColumn = HermesParserWASM.cwrap('hermesParseResult_getErrorColumn', 'number', ['number']);
+  hermesParseResult_getProgramBuffer = HermesParserWASM.cwrap('hermesParseResult_getProgramBuffer', 'number', ['number']);
+  hermesParseResult_getPositionBuffer = HermesParserWASM.cwrap('hermesParseResult_getPositionBuffer', 'number', ['number']);
+  hermesParseResult_getPositionBufferSize = HermesParserWASM.cwrap('hermesParseResult_getPositionBufferSize', 'number', ['number']);
+} // Copy a string into the WASM heap and null-terminate
+
+
+function copyToHeap(buffer, addr) {
+  HermesParserWASM.HEAP8.set(buffer, addr);
+  HermesParserWASM.HEAP8[addr + buffer.length] = 0;
+}
+
+function parse(source, options) {
+  initHermesParserWASM(); // 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.enableExperimentalComponentSyntax, options.enableExperimentalFlowMatchSyntax, options.enableExperimentalFlowRecordSyntax, 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, options);
+      return deserializer.deserialize();
+    } finally {
+      hermesParseResult_free(parseResult);
+    }
+  } finally {
+    HermesParserWASM._free(sourceAddr);
+  }
+}