Replace the unmaintained OCaml Flow parser dependency

[cknitt]

Problem

ReScript depends on the unmaintained OCaml implementation of flow_parser to validate and classify JavaScript in %raw expressions.

Our fork supports ppxlib 0.36, which requires OCaml < 5.4. This blocks upgrades to OCaml 5.4 and 5.5. Updating the fork for each ppxlib release would only postpone the problem.

ReScript currently depends directly on Flow AST and parser types, although it only needs syntax validation, error locations, regexp validation, and classification of literals, functions and comment-only statements.

Possible solutions

1. Vendor the Flow parser

ReScript previously vendored these sources under compiler/js_parser.

We could restore the currently used parser sources and maintain them inside the repository. Ideally, we would commit the PPX-generated OCaml code so the parser no longer depends on ppxlib.

This is the lowest-risk solution and can preserve the existing direct Flow AST integration. However, it leaves ReScript responsible for roughly 33,000 lines of parser code whose JavaScript syntax support will no longer receive upstream updates.

2. Move to js_of_ocaml’s JavaScript parser

js_of_ocaml-compiler's Parse_js API provides maintained OCaml functions for parsing JavaScript expressions and programs.

For a safe migration, we should first introduce a small ReScript-owned parser interface backed by the existing Flow parser. This interface would expose only the operations ReScript needs and remove direct uses of Flow_ast, Parser_flow, Loc, and Parse_error from the rest of the compiler.

We should add focused tests for parsing, error locations, regexp validation, function arity, literal classification, leading comments and comment-only programs. The js_of_ocaml implementation could then be tested against the same corpus before switching.

js_of_ocaml maintains its parser to read JavaScript runtimes and user-provided stubs before linking and optimizing them with generated JavaScript. Its primary goal is therefore not to be a universal parser supporting every new TC39 feature immediately. Its syntax coverage, diagnostics, comment handling and classifications must be compared with the current Flow implementation.

A migration could be split into two independent changes:

1. Introduce the internal parser abstraction backed by Flow Parser and strengthen test coverage.
2. Implement the abstraction using js_of_ocaml, compare both implementations, and remove flow_parser if compatibility is sufficient.

Decision

• Vendoring is the quickest and least disruptive solution, but makes ReScript the permanent owner of an unmaintained parser.
• Moving to js_of_ocaml requires more migration work, but offers a maintained long-term dependency with much less parser-specific coupling.

[cknitt]

I prototyped the js_of_ocaml parser integration. The required AST adapter is small and can determine everything ReScript currently needs: function arity, arrow functions, literal expressions, regular expressions, syntax validity, and comment-only programs.

The remaining integration issues are:

• js_of_ocaml-compiler depends on upstream OCaml compiler-libs.
• ReScript’s compiler libraries are currently unwrapped and contain modules with the same names, such as Ident, Warnings, and Parsetree.
• Therefore, both implementations cannot currently be linked into the same executable. Putting the adapter in another ordinary Dune library does not help because its dependencies are still linked transitively.

One possible solution is to wrap and namespace ReScript’s compiler libraries, for example as Rescript_compiler.Parsetree. This would remove the conflict and would also prepare the compiler libraries for potential publication on opam. It is a broader migration, but has benefits beyond replacing Flow.

Alternatively, we could extract or vendor the relevant js_of_ocaml parser modules without their compiler-libs dependency.

Two smaller compatibility issues remain:

• The public JSOO lexer API signals errors but does not expose sufficiently detailed messages and source ranges. We would need a small upstream API addition or a vendored diagnostics adapter.
• Leading comments are not attached to expression AST nodes. Preserving ReScript’s current leading-comment behavior would require inspecting lexer/token information in the adapter.