|
| 1 | +# Contributing |
| 2 | + |
| 3 | +## Crates Overview |
| 4 | + |
| 5 | +Our project is organized into several crates: |
| 6 | + |
| 7 | +| Crate | Badge | Description | |
| 8 | +|----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| ----------- | |
| 9 | +| [🔍 **emmylua_parser**](./crates/emmylua_parser) | [](https://crates.io/crates/emmylua_parser) | The foundational Rust-based Lua parser engineered for maximum efficiency and accuracy. Powers all downstream analysis tools. | |
| 10 | +| [📑 **emmylua_parser_desc**](./crates/emmylua_parser_desc) | [](https://crates.io/crates/emmylua_parser_desc) | Extension for EmmyLua-Parser that handles Markdown/RST highlighting in comments. | |
| 11 | +| [🧠 **emmylua_code_analysis**](./crates/emmylua_code_analysis) | [](https://crates.io/crates/emmylua_code_analysis) | Advanced semantic analysis engine providing deep code understanding, type inference, and cross-reference resolution. | |
| 12 | +| [🖥️ **emmylua_ls**](./crates/emmylua_ls) | [](https://crates.io/crates/emmylua_ls) | The complete Language Server Protocol implementation offering rich IDE features across all major editors. | |
| 13 | +| [📚 **emmylua_doc_cli**](./crates/emmylua_doc_cli/) | [](https://crates.io/crates/emmylua_doc_cli) | Professional documentation generator creating beautiful, searchable API docs from your Lua code and annotations. | |
| 14 | +| [✅ **emmylua_check**](./crates/emmylua_check) | [](https://crates.io/crates/emmylua_check) | Comprehensive static analysis tool for code quality assurance, catching bugs before they reach production. | |
| 15 | + |
| 16 | + |
| 17 | +## Testing |
| 18 | + |
| 19 | +We use the standard Rust testing harness, along with assert macros from [`googletest-rust`]: |
| 20 | + |
| 21 | +```shell |
| 22 | +# Run all tests |
| 23 | +cargo test |
| 24 | + |
| 25 | +# Run tests for specific crate |
| 26 | +cargo test -p emmylua_parser |
| 27 | +``` |
| 28 | + |
| 29 | +If you're unfamiliar with `googletest-rust`, here's a quick overview: |
| 30 | + |
| 31 | +- Use `googletest::prelude::*` in your test modules, and annotate test functions with `#[gtest]`. |
| 32 | + |
| 33 | +- `assert_that!` checks a condition and panics on error: |
| 34 | + |
| 35 | + ```rust |
| 36 | + assert_that!(2 * 2, eq(4)); |
| 37 | + ``` |
| 38 | + |
| 39 | + Prefer `assert_that!(x, eq(y))` to `assert_eq` because the former generates a nice diff for you. |
| 40 | + |
| 41 | +- `expect_that!` checks a condition, marks test as failed on error, and continues execution. |
| 42 | + |
| 43 | + This is useful when adding multiple test cases to a single `#[gtest]` function: |
| 44 | + |
| 45 | + ```rust |
| 46 | + // Both expectations will be evaluated and reported when test fails: |
| 47 | + expect_that!(2 * 2, ne(4)); |
| 48 | + expect_that!(3 * 3, ne(9)); |
| 49 | + ``` |
| 50 | + |
| 51 | +- `verify_that!` checks a condition and returns a `googletest::Result`. |
| 52 | + |
| 53 | +- `OrFail::or_fail` converts any `Optional` and `Result` to a `googletest::Result`. It also adds current location |
| 54 | + to an error message. We have a wrapper around it called [`check!`]. |
| 55 | + |
| 56 | + |
| 57 | +## Code style and formatting |
| 58 | + |
| 59 | +We use [`rustfmt`] and [`pre-commit`] to manage project's code style. |
| 60 | + |
| 61 | +- `rustfmt` formats Rust code. Simply run `cargo fmt --all` to reformat all files. |
| 62 | + |
| 63 | +- `pre-commit` fixes common issues like trailing whitespaces or broken symlinks in all text files. |
| 64 | + |
| 65 | + To run it, |
| 66 | + |
| 67 | + 1. install [`pre-commit`][pre-commit-install], |
| 68 | + 2. invoke `pre-commit run --all`. |
| 69 | + |
| 70 | + If it suits your workflow, you can configure PreCommit to run before every commit. To do so, run `pre-commit install`. |
| 71 | + Note that this is not required because our CI will detect any issues. |
| 72 | + |
| 73 | +[`googletest-rust`]: https://github.com/google/googletest-rust/ |
| 74 | +[`rustfmt`]: https://rust-lang.github.io/rustfmt/ |
| 75 | +[`pre-commit`]: https://pre-commit.com/#install |
| 76 | +[pre-commit-install]: https://pre-commit.com/#install |
| 77 | +[`check!`]: https://github.com/search?q=repo%3AEmmyLuaLs%2Femmylua-analyzer-rust%20macro_rules!%20check&type=code |
0 commit comments