flow-parser 0.317.0 → 0.319.0

package/oxidized/index.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
+ */
+
+'use strict';
+
+import type {Program as ESTreeProgram} from 'flow-estree';
+import type {ParserOptions} from './ParserOptions';
+import type {BabelFile} from './babel/TransformESTreeToBabel';
+
+import * as FlowParser from './FlowParser';
+import FlowVisitorKeys from './generated/ESTreeVisitorKeys';
+import * as TransformComponentSyntax from './estree/TransformComponentSyntax';
+import * as TransformEnumSyntax from './estree/TransformEnumSyntax';
+import * as TransformMatchSyntax from './estree/TransformMatchSyntax';
+import * as TransformRecordSyntax from './estree/TransformRecordSyntax';
+import * as StripFlowTypesForBabel from './estree/StripFlowTypesForBabel';
+import * as TransformESTreeToBabel from './babel/TransformESTreeToBabel';
+import * as StripFlowTypes from './estree/StripFlowTypes';
+
+const DEFAULTS: {flow: 'detect'} = {
+  flow: 'detect',
+};
+
+function getOptions(opts?: ParserOptions): ParserOptions {
+  // Always build a fresh object so we never mutate the caller's input.
+  // Repeated calls with the same `opts` reference must produce identical
+  // results — earlier versions wrote normalized fields back onto `opts`,
+  // poisoning subsequent calls.
+  const options: ParserOptions = {...DEFAULTS, ...(opts ?? {})};
+
+  // Default to detecting whether to parse Flow syntax by the presence
+  // of an @flow pragma.
+  if (options.flow !== 'all' && options.flow !== 'detect') {
+    throw new Error('flow option must be "all" or "detect"');
+  }
+
+  if (options.sourceType === 'unambiguous') {
+    // Clear source type so that it will be detected from the contents of the file
+    delete options.sourceType;
+  } else if (
+    options.sourceType != null &&
+    options.sourceType !== 'script' &&
+    options.sourceType !== 'module'
+  ) {
+    throw new Error(
+      'sourceType option must be "script", "module", or "unambiguous" if set',
+    );
+  }
+
+  if (options.enableExperimentalComponentSyntax == null) {
+    options.enableExperimentalComponentSyntax = true; // Enable by default
+  }
+
+  if (options.enableExperimentalFlowMatchSyntax == null) {
+    options.enableExperimentalFlowMatchSyntax = true; // Enable by default
+  }
+
+  // Record syntax: upstream defaults `enableExperimentalFlowRecordSyntax` to
+  // `true`. The fork's WASM cwrap (FlowParser.js) reads `options.enableRecords`
+  // — a separate, OCaml-aligned key intentionally mirroring
+  // `default_parse_options`. To preserve the upstream-compatible API surface
+  // on the outside while keeping the OCaml-aligned key on the WASM boundary,
+  // bridge: default the upstream key, then mirror it onto the cwrap key. The
+  // mirroring belongs here (the public-API layer) and not at the wasm
+  // boundary, because the wasm fixture runner under
+  // `__tests__/runWasmFixtures.js` calls `FlowParser.parse` directly and
+  // expects OCaml's strict defaults to apply.
+  if (options.enableExperimentalFlowRecordSyntax == null) {
+    options.enableExperimentalFlowRecordSyntax = true; // Enable by default
+  }
+  options.enableRecords = options.enableExperimentalFlowRecordSyntax;
+
+  // Enum syntax: upstream hermes-parser always parses Flow `enum` syntax. The
+  // fork's WASM cwrap reads `options.enableEnums` — an OCaml-aligned key that
+  // defaults to false in `default_parse_options`. Default `enableEnums` to
+  // true so unflagged hermes-parser-style callers can parse `enum X { A }`
+  // without opt-in. Same wasm-fixture-runner consideration as `enableRecords`.
+  if (options.enableEnums == null) {
+    options.enableEnums = true;
+  }
+
+  // Decorators: upstream hermes-parser supports stage-1 decorators by default.
+  // The fork's WASM cwrap reads `enableExperimentalDecorators`, which
+  // defaults to false in OCaml's `default_parse_options`. Default true on the
+  // JS surface to match upstream. Same wasm-fixture-runner consideration as
+  // `enableRecords`.
+  if (options.enableExperimentalDecorators == null) {
+    options.enableExperimentalDecorators = true;
+  }
+
+  options.tokens = options.tokens === true;
+  options.allowReturnOutsideFunction =
+    options.allowReturnOutsideFunction === true;
+
+  return options;
+}
+
+declare function parse(
+  code: string,
+  opts: Readonly<{...ParserOptions, babel: true}>,
+): BabelFile;
+// eslint-disable-next-line no-redeclare
+declare function parse(
+  code: string,
+  opts?:
+    | Readonly<{...ParserOptions, babel?: false | void}>
+    | Readonly<{...ParserOptions, babel: false}>,
+): ESTreeProgram;
+
+// eslint-disable-next-line no-redeclare
+export function parse(
+  code: string,
+  opts?: ParserOptions,
+): BabelFile | ESTreeProgram {
+  const options = getOptions(opts);
+
+  // Resolve `flow: 'all' | 'detect'` to the Rust parser's option set.
+  // `flow: 'all'` always parses Flow type syntax (`enableTypes: true`).
+  // `flow: 'detect'` opts the Rust parser into docblock-pragma scanning
+  // (`enableTypesPragmaDetection: true`); the Rust side mirrors C++
+  // hermes-parser by parsing all Flow syntax with `@flow`, and only
+  // unambiguous Flow syntax without it.
+  if (options.flow === 'all') {
+    options.enableTypes = true;
+  } else {
+    options.enableTypesPragmaDetection = true;
+  }
+  // Flow Rust parser outputs ESTree-compatible AST directly. The wire→ESTree
+  // loc/range normalization (source-filename assignment, `node.range` synthesis
+  // from `loc.rangeStart`/`rangeEnd`, then cleanup of those wire-only loc
+  // fields) is done at the parser level inside `FlowParser.parse` so callers
+  // that bypass this hermes-parser-compatibility wrapper still get canonical
+  // ESTree loc/range. Optional-chain ESTree wrapping is emitted by the WASM
+  // serializer, mirroring upstream `HermesToESTreeAdapter.mapChainExpression`.
+  // See FlowParser.js.
+  const estreeAST = FlowParser.parse(code, options);
+
+  if (options.babel !== true) {
+    return estreeAST;
+  }
+
+  // `babel: true` overload — reduce the ESTree AST through the same syntax
+  // lowering pipeline upstream uses (Enum/Match/Component/Record syntax,
+  // strip Flow types), then convert ESTree → Babel AST shape.
+  const loweredESTreeAST = [
+    options.transformOptions?.TransformEnumSyntax?.enable
+      ? TransformEnumSyntax.transformProgram
+      : null,
+    TransformMatchSyntax.transformProgram,
+    TransformComponentSyntax.transformProgram,
+    TransformRecordSyntax.transformProgram,
+    StripFlowTypesForBabel.transformProgram,
+  ].reduce((ast, transform) => transform?.(ast, options) ?? ast, estreeAST);
+
+  return TransformESTreeToBabel.transformProgram(loweredESTreeAST, options);
+}
+
+export type {ParserOptions} from './ParserOptions';
+export * from './ParserOptions';
+export * from './traverse/SimpleTraverser';
+export * from './transform/SimpleTransform';
+export * from './traverse/getVisitorKeys';
+export {FlowVisitorKeys};
+export * as astArrayMutationHelpers from './transform/astArrayMutationHelpers';
+export * as astNodeMutationHelpers from './transform/astNodeMutationHelpers';
+export {default as mutateESTreeASTForPrettier} from './utils/mutateESTreeASTForPrettier';
+
+const Transforms = {
+  transformEnumSyntax: TransformEnumSyntax.transformProgram,
+  transformMatchSyntax: TransformMatchSyntax.transformProgram,
+  transformComponentSyntax: TransformComponentSyntax.transformProgram,
+  transformRecordSyntax: TransformRecordSyntax.transformProgram,
+  stripFlowTypesForBabel: StripFlowTypesForBabel.transformProgram,
+  stripFlowTypes: StripFlowTypes.transformProgram,
+};
+export {Transforms};

package/oxidized/oxidized-src/FlowParser.js

@@ -0,0 +1,249 @@
+'use strict';
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.parse = parse;
+
+var _FlowParserDeserializer = _interopRequireDefault(require("./FlowParserDeserializer"));
+
+var _FlowParserWASM = _interopRequireDefault(require("./FlowParserWASM"));
+
+var _getModuleDocblock = require("./getModuleDocblock");
+
+function _interopRequireDefault(obj) {
+  return obj && obj.__esModule ? obj : {
+    default: obj
+  };
+}
+
+let FlowParserWASM;
+let flowParse;
+let flowParseResult_free;
+let flowParseResult_getError;
+let flowParseResult_getErrorLine;
+let flowParseResult_getErrorColumn;
+let flowParseResult_getProgramBuffer;
+let flowParseResult_getPositionBuffer;
+let flowParseResult_getPositionBufferSize;
+let flowParseResult_getStringBuffer;
+
+function initFlowParserWASM() {
+  if (FlowParserWASM != null) {
+    return;
+  }
+
+  FlowParserWASM = (0, _FlowParserWASM.default)({
+    quit(_status, toThrow) {
+      throw toThrow;
+    }
+
+  });
+  flowParse = FlowParserWASM.cwrap('hermesParse', 'number', ['number', 'number', 'number', 'number', 'number', 'number', 'number', 'number', 'number', 'number', 'number', 'number', 'number', 'number', 'number', 'number']);
+  flowParseResult_free = FlowParserWASM.cwrap('hermesParseResult_free', 'void', ['number']);
+  flowParseResult_getError = FlowParserWASM.cwrap('hermesParseResult_getError', 'string', ['number']);
+  flowParseResult_getErrorLine = FlowParserWASM.cwrap('hermesParseResult_getErrorLine', 'number', ['number']);
+  flowParseResult_getErrorColumn = FlowParserWASM.cwrap('hermesParseResult_getErrorColumn', 'number', ['number']);
+  flowParseResult_getProgramBuffer = FlowParserWASM.cwrap('hermesParseResult_getProgramBuffer', 'number', ['number']);
+  flowParseResult_getPositionBuffer = FlowParserWASM.cwrap('hermesParseResult_getPositionBuffer', 'number', ['number']);
+  flowParseResult_getPositionBufferSize = FlowParserWASM.cwrap('hermesParseResult_getPositionBufferSize', 'number', ['number']);
+  flowParseResult_getStringBuffer = FlowParserWASM.cwrap('hermesParseResult_getStringBuffer', 'number', ['number']);
+}
+
+function copyToHeap(buffer, addr) {
+  FlowParserWASM.HEAP8.set(buffer, addr);
+  FlowParserWASM.HEAP8[addr + buffer.length] = 0;
+}
+
+function flag(v) {
+  return v === true ? 1 : 0;
+}
+
+function parse(source, options) {
+  initFlowParserWASM();
+  const sourceBuffer = Buffer.from(source, 'utf8');
+  const filename = typeof options.sourceFilename === 'string' ? options.sourceFilename : '';
+  const filenameBuffer = filename.length > 0 ? Buffer.from(filename, 'utf8') : null;
+  let sourceAddr = 0;
+  let filenameAddr = 0;
+  let filenameLen = 0;
+  let parseResult = 0;
+
+  try {
+    sourceAddr = FlowParserWASM._malloc(sourceBuffer.length + 1);
+
+    if (!sourceAddr) {
+      throw new Error('Parser out of memory');
+    }
+
+    if (filenameBuffer != null) {
+      filenameAddr = FlowParserWASM._malloc(filenameBuffer.length + 1);
+
+      if (!filenameAddr) {
+        throw new Error('Parser out of memory');
+      }
+
+      copyToHeap(filenameBuffer, filenameAddr);
+      filenameLen = filenameBuffer.length + 1;
+    }
+
+    copyToHeap(sourceBuffer, sourceAddr);
+    const enableTypes = options.enableTypes === false ? 0 : 1;
+    const sourceTypeCode = options.sourceType === 'script' ? 1 : options.sourceType === 'module' ? 2 : 0;
+    parseResult = flowParse(sourceAddr, sourceBuffer.length + 1, filenameAddr, filenameLen, flag(options.enableExperimentalComponentSyntax), flag(options.enableExperimentalFlowMatchSyntax), flag(options.enableExperimentalDecorators), flag(options.tokens), flag(options.allowReturnOutsideFunction), flag(options.assertOperator), flag(options.enableEnums), flag(options.enableRecords), enableTypes, sourceTypeCode, flag(options.enableTypesPragmaDetection), 0);
+    const programBuffer = flowParseResult_getProgramBuffer(parseResult);
+
+    if (!programBuffer) {
+      const err = flowParseResult_getError(parseResult);
+      const syntaxError = new SyntaxError(err || 'unknown parse error');
+      syntaxError.loc = {
+        line: flowParseResult_getErrorLine(parseResult),
+        column: flowParseResult_getErrorColumn(parseResult)
+      };
+      throw syntaxError;
+    }
+
+    const deserializer = new _FlowParserDeserializer.default(programBuffer, flowParseResult_getPositionBuffer(parseResult), flowParseResult_getPositionBufferSize(parseResult), flowParseResult_getStringBuffer(parseResult), FlowParserWASM, options);
+    const ast = deserializer.deserialize();
+
+    if (ast.type !== 'Program') {
+      throw new Error(`Expected Program, got ${ast.type}`);
+    }
+
+    const sourceFilename = typeof options.sourceFilename === 'string' ? options.sourceFilename : null;
+    const visitedNodes = new WeakSet();
+    const locRanges = new WeakMap();
+
+    function fixLocs(node) {
+      if (node == null || typeof node !== 'object') {
+        return;
+      }
+
+      const wireNode = node;
+
+      if (visitedNodes.has(wireNode)) {
+        return;
+      }
+
+      visitedNodes.add(wireNode);
+
+      if (wireNode.loc != null) {
+        const loc = wireNode.loc;
+        let range = locRanges.get(loc);
+
+        if (range == null) {
+          const rangeStart = loc.rangeStart;
+          const rangeEnd = loc.rangeEnd;
+
+          if (rangeStart == null || rangeEnd == null) {
+            throw new Error('Expected serialized source range');
+          }
+
+          loc.source = sourceFilename;
+          range = [rangeStart, rangeEnd];
+          locRanges.set(loc, range);
+          delete loc.rangeStart;
+          delete loc.rangeEnd;
+        }
+
+        wireNode.range = range;
+      }
+
+      for (const key of Object.keys(wireNode)) {
+        const val = wireNode[key];
+
+        if (Array.isArray(val)) {
+          for (const child of val) {
+            fixLocs(child);
+          }
+        } else {
+          fixLocs(val);
+        }
+      }
+    }
+
+    fixLocs(ast);
+
+    if (options.throwOnParseErrors !== false) {
+      const errors = ast.errors;
+
+      if (errors != null && errors.length > 0) {
+        const first = errors[0];
+        const start = first.loc.start;
+
+        if (start == null) {
+          throw new Error('Expected serialized parser error start location');
+        }
+
+        const line = start.line;
+        const column = start.column;
+        const syntaxError = new SyntaxError(`${first.message} (${line}:${column})`);
+        syntaxError.loc = {
+          line,
+          column
+        };
+        throw syntaxError;
+      }
+    }
+
+    if (options.sourceType === 'script' || options.sourceType === 'module') {
+      ast.sourceType = options.sourceType;
+    } else {
+      ast.sourceType = detectSourceType(ast);
+    }
+
+    ast.docblock = (0, _getModuleDocblock.getModuleDocblock)(ast);
+    return asProgram(ast);
+  } finally {
+    if (parseResult !== 0) {
+      flowParseResult_free(parseResult);
+    }
+
+    if (sourceAddr !== 0) {
+      FlowParserWASM._free(sourceAddr);
+    }
+
+    if (filenameAddr !== 0) {
+      FlowParserWASM._free(filenameAddr);
+    }
+  }
+}
+
+function asProgram(ast) {
+  const program = ast;
+  return program;
+}
+
+function detectSourceType(program) {
+  if (!Array.isArray(program.body)) {
+    return 'script';
+  }
+
+  for (const stmt of program.body) {
+    if (stmt == null) {
+      continue;
+    }
+
+    switch (stmt.type) {
+      case 'ImportDeclaration':
+        if (stmt.importKind === 'value' || stmt.importKind == null) {
+          return 'module';
+        }
+
+        break;
+
+      case 'ExportDefaultDeclaration':
+        return 'module';
+
+      case 'ExportNamedDeclaration':
+      case 'ExportAllDeclaration':
+        if (stmt.exportKind === 'value' || stmt.exportKind == null) {
+          return 'module';
+        }
+
+        break;
+    }
+  }
+
+  return 'script';
+}

package/oxidized/oxidized-src/FlowParserDeserializer.js

@@ -0,0 +1,209 @@
+'use strict';
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _HermesParserDecodeUTF8String = _interopRequireDefault(require("./HermesParserDecodeUTF8String"));
+
+var _FlowParserNodeDeserializers = _interopRequireDefault(require("./FlowParserNodeDeserializers"));
+
+function _interopRequireDefault(obj) {
+  return obj && obj.__esModule ? obj : {
+    default: obj
+  };
+}
+
+class FlowParserDeserializer {
+  constructor(programBuffer, positionBuffer, positionBufferSize, stringBufferBase, wasmParser, options) {
+    this.programBufferIdx = void 0;
+    this.positionBufferIdx = void 0;
+    this.positionBufferSize = void 0;
+    this.stringBufferBase = void 0;
+    this.locMap = void 0;
+    this.HEAPU8 = void 0;
+    this.HEAPU32 = void 0;
+    this.HEAPF64 = void 0;
+    this.options = void 0;
+    this.commentTypes = ['Block', 'Line'];
+    this.tokenTypes = ['Boolean', 'Identifier', 'Keyword', 'Null', 'Numeric', 'BigInt', 'Punctuator', 'String', 'RegularExpression', 'Template', 'JSXText'];
+    this.programBufferIdx = programBuffer / 4;
+    this.positionBufferIdx = positionBuffer / 4;
+    this.positionBufferSize = positionBufferSize;
+    this.stringBufferBase = stringBufferBase;
+    this.locMap = {};
+    this.HEAPU8 = wasmParser.HEAPU8;
+    this.HEAPU32 = wasmParser.HEAPU32;
+    this.HEAPF64 = wasmParser.HEAPF64;
+    this.options = options;
+  }
+
+  next() {
+    const num = this.HEAPU32[this.programBufferIdx++];
+    return num;
+  }
+
+  deserialize() {
+    const program = {
+      type: 'Program',
+      loc: this.addEmptyLoc(),
+      body: this.deserializeNodeList(),
+      comments: this.deserializeComments()
+    };
+    program.interpreter = this.deserializeNode();
+
+    if (this.options.tokens === true) {
+      program.tokens = this.deserializeTokens();
+    } else {
+      this.deserializeTokens();
+    }
+
+    program.errors = this.deserializeErrors();
+    this.fillLocs();
+    return program;
+  }
+
+  deserializeErrors() {
+    const size = this.next();
+    const errors = [];
+
+    for (let i = 0; i < size; i++) {
+      const loc = this.addEmptyLoc();
+      const message = this.deserializeString();
+
+      if (message == null) {
+        throw new Error('Expected serialized parser error message');
+      }
+
+      errors.push({
+        loc,
+        message
+      });
+    }
+
+    return errors;
+  }
+
+  deserializeBoolean() {
+    return Boolean(this.next());
+  }
+
+  deserializeNumber() {
+    let floatIdx;
+
+    if (this.programBufferIdx % 2 === 0) {
+      floatIdx = this.programBufferIdx / 2;
+      this.programBufferIdx += 2;
+    } else {
+      floatIdx = (this.programBufferIdx + 1) / 2;
+      this.programBufferIdx += 3;
+    }
+
+    return this.HEAPF64[floatIdx];
+  }
+
+  deserializeString() {
+    const offsetPlusOne = this.next();
+
+    if (offsetPlusOne === 0) {
+      return null;
+    }
+
+    const size = this.next();
+    return (0, _HermesParserDecodeUTF8String.default)(this.stringBufferBase + offsetPlusOne - 1, size, this.HEAPU8);
+  }
+
+  deserializeNode() {
+    const nodeType = this.next();
+
+    if (nodeType === 0) {
+      return null;
+    }
+
+    const nodeDeserializer = _FlowParserNodeDeserializers.default[nodeType - 1].bind(this);
+
+    return nodeDeserializer();
+  }
+
+  deserializeNodeList() {
+    const size = this.next();
+    const nodeList = [];
+
+    for (let i = 0; i < size; i++) {
+      nodeList.push(this.deserializeNode());
+    }
+
+    return nodeList;
+  }
+
+  deserializeComments() {
+    const size = this.next();
+    const comments = [];
+
+    for (let i = 0; i < size; i++) {
+      const commentType = this.commentTypes[this.next()];
+      const loc = this.addEmptyLoc();
+      const value = this.deserializeString();
+      comments.push({
+        type: commentType,
+        loc,
+        value
+      });
+    }
+
+    return comments;
+  }
+
+  deserializeTokens() {
+    const size = this.next();
+    const tokens = [];
+
+    for (let i = 0; i < size; i++) {
+      const tokenType = this.tokenTypes[this.next()];
+      const loc = this.addEmptyLoc();
+      const value = this.deserializeString();
+      tokens.push({
+        type: tokenType,
+        loc,
+        value
+      });
+    }
+
+    return tokens;
+  }
+
+  addEmptyLoc() {
+    const loc = {};
+    this.locMap[this.next()] = loc;
+    return loc;
+  }
+
+  fillLocs() {
+    for (let i = 0; i < this.positionBufferSize; i++) {
+      const locId = this.HEAPU32[this.positionBufferIdx++];
+      const kind = this.HEAPU32[this.positionBufferIdx++];
+      const line = this.HEAPU32[this.positionBufferIdx++];
+      const column = this.HEAPU32[this.positionBufferIdx++];
+      const offset = this.HEAPU32[this.positionBufferIdx++];
+      const loc = this.locMap[locId];
+
+      if (kind === 0) {
+        loc.start = {
+          line,
+          column
+        };
+        loc.rangeStart = offset;
+      } else {
+        loc.end = {
+          line,
+          column
+        };
+        loc.rangeEnd = offset;
+      }
+    }
+  }
+
+}
+
+exports.default = FlowParserDeserializer;