The Flow Codebase: Parsing

During the parsing phase, Flow finds every "interesting" file in the repository. Then it uses the Flow parser to parse the JavaScript code with the @flow docblock directive.

Finding files

The code to find all the "interesting" files lives in /src/common/files.ml. An "interesting" file is basically a file that is included, not ignored, and has the right extension. This code streams results as they come in, which lets us grab the first 100 and start parsing, even before we've found every file.

The flow ls command basically just calls this code, so it's a great way to understand what is going on, especially with the --explain flag.

Parsing

The code for the Flow parser lives in /src/parser.

The parser is written in OCaml, but can be compiled to JavaScript using js_of_ocaml. It has it's own Makefile, it's own npm package and it's own opam package

The Flow parser needs to work on half written files (for example, flow autocomplete is rarely given well-formed JavaScript), so it always tries to recover from errors (though it will still report the errors).

The parser produces an AST that matches the one declared in /src/parser/flow_ast.ml. We then have /src/parser/estree_translator.ml which translates it to match the estree spec (still working on 100% compatiblity). Flow's OCaml code just uses the OCaml AST, so this translation is more for external consumption of the AST.

The lexer is generated with ocamllex. The source lives in /src/parser/lexer_flow.mll.

The parser is broken up into pieces, one for each piece of the grammar.

• /src/parser/expression_parser.ml - Parses expressions
• /src/parser/declaration_parser.ml - Parses declarations
• etc. etc.

These are combined together in /src/parser/flow_parser.ml