|
2 | 2 | id: biome |
3 | 3 | title: Biome |
4 | 4 | --- |
| 5 | + |
| 6 | +[Rome](https://github.com/rome/tools) uses a different set of techniques for parsing JavaScript and TypeScript. |
| 7 | +This tutorial summarizes them in learning order for better understanding. |
| 8 | + |
| 9 | +<!--truncate--> |
| 10 | + |
| 11 | +## History |
| 12 | + |
| 13 | +- The Rome codebase was rewritten from TypeScript to Rust, see [Rome will be rewritten in Rust](https://rome.tools/blog/2021/09/21/rome-will-be-rewritten-in-rust) |
| 14 | +- The decision was made after talking to the author of [rslint](https://github.com/rslint/rslint) and [rust-analyzer](https://github.com/rust-lang/rust-analyzer) |
| 15 | +- rust-analyzer proved that IDE-centric tools built around concrete syntax tree are possible |
| 16 | +- rslint proved that it is possible to write a JavaScript parser in Rust, with the same base libraries as rust-analyzer |
| 17 | +- Rome ported the rslint codebase to their own repo with permission from rslint's author |
| 18 | + |
| 19 | +## Concrete Syntax Tree |
| 20 | + |
| 21 | +- The base library is called [rowan](https://github.com/rust-analyzer/rowan), see [overview of rowan](https://github.com/rust-lang/rust-analyzer/blob/master/docs/dev/syntax.md) |
| 22 | +- Rowan, also known as red-green trees, is named after the real green [rowan tree](https://en.wikipedia.org/wiki/Rowan) that makes red berries |
| 23 | +- The origin of red-green trees is described in this [blog post](https://ericlippert.com/2012/06/08/red-green-trees/), by the authors of the C# programming language |
| 24 | +- The whole point of rowan is to define a lossless concrete syntax tree (CST) that describes all the details of the source code and provides a set of traversal APIs (parent, children, siblings, etc) |
| 25 | +- Read the advantage of having a CST over an AST: [Pure AST based linting sucks](https://rdambrosio016.github.io/rust/2020/09/18/pure-ast-based-linting-sucks.html) |
| 26 | +- CST provides the ability to build a fully recoverable parser |
| 27 | + |
| 28 | +## Grammar |
| 29 | + |
| 30 | +- Just like an AST, we need to define the grammar. The grammar is auto-generated by using [xtask/codegen](https://github.com/rome/tools/tree/main/xtask/codegen) |
| 31 | +- The grammar is generated from the [ungrammar](https://github.com/rust-analyzer/ungrammar) DSL |
| 32 | +- The input `ungrammar` source file is in [xtask/codegen/js.ungram](https://github.com/rome/tools/blob/main/xtask/codegen/js.ungram) |
| 33 | +- The output of the codegen is in [rome_js_syntax/src/generated](https://github.com/rome/tools/tree/main/crates/rome_js_syntax/src/generated) |
| 34 | + |
| 35 | +## Entry Point |
| 36 | + |
| 37 | +The Rome codebase is getting large and slightly difficult to find the parser entry point. |
| 38 | + |
| 39 | +For first-time contributors, the `rome_cli` crate is the binary entry point for running the code: |
| 40 | + |
| 41 | +```bash |
| 42 | +cargo run -p rome_cli |
| 43 | + |
| 44 | +touch test.js |
| 45 | +cargo run -p rome_cli -- check ./test.js |
| 46 | +``` |
| 47 | + |
| 48 | +`rome_cli` will eventually call `rome_js_parser::parse` |
| 49 | + |
| 50 | +```rust reference |
| 51 | +https://github.com/rome/tools/blob/9815467c66688773bc1bb6ef9a5b2d86ca7b3682/crates/rome_js_parser/src/parse.rs#L178-L187 |
| 52 | +``` |
| 53 | + |
| 54 | +and finally the actual parsing code |
| 55 | + |
| 56 | +```rust reference |
| 57 | +https://github.com/rome/tools/blob/9815467c66688773bc1bb6ef9a5b2d86ca7b3682/crates/rome_js_parser/src/syntax/program.rs#L14-L17 |
| 58 | +``` |
| 59 | + |
| 60 | +## Contributing |
| 61 | + |
| 62 | +- [CONTRIBUTING.md](https://github.com/rome/tools/blob/main/CONTRIBUTING.md) has instructions on how to contribute |
| 63 | +- [rome_js_parser crate doc](https://rome.github.io/tools/rome_js_parser/index.html) has some more details on the parser |
| 64 | +- See [`cargo codegen test`](https://github.com/rome/tools/tree/main/xtask/codegen#cargo-codegen-test) for working with parser tests |
| 65 | +- See [`cargo coverage`](https://github.com/rome/tools/tree/main/xtask/coverage) for working with conformance tests |
| 66 | +- Join the [Discord Server](https://discord.com/invite/rome) for inquiries |
| 67 | + |
| 68 | +:::info |
| 69 | +The JavaScript / TypeScript parser is 99% complete, the best way to help is to test Rome in your own codebases |
| 70 | +or take a look at the [issues on Github](https://github.com/rome/tools/issues). |
| 71 | +::: |
0 commit comments