| --- | |
| trigger: glob | |
| description: Rust coding, dependency vetting, and rules_rust crate conventions | |
| globs: "*.rs,Cargo.toml,Cargo.lock,Cargo.Bazel.lock,MODULE.bazel" | |
| --- | |
| # Rust Conventions | |
| ## Standard Libraries Over Custom Subsystems | |
| * Prefer `std` and established ecosystem crates (consult | |
| `https://blessed.rs/crates`) over implementing non-trivial subsystems from | |
| scratch. | |
| * Never hand-roll CLI argument parsers (`lexopt` or `clap`), `@flagfile` | |
| response-file readers (`argfile`), CSV/INI/JSON/TOML format parsers (`csv`, | |
| etc.), base64/hex codecs (`base64`), language or packaging-spec parsers | |
| (`ruff_python_parser`, `pep440_rs`, `pep508_rs`), regex engines (`regex`), | |
| archive/compression codecs (`zip`, `flate2`), or cryptographic hashes | |
| (`sha2`). | |
| ## Dependency Vetting & Versioning | |
| When adding or updating a Rust crate dependency: | |
| * **Verify legitimacy**: Confirm the crate's maintainers and source repository | |
| on `crates.io` (prefer established organizations such as `rust-lang`, | |
| `rust-cli`, `RustCrypto`, `astral-sh`, or `zip-rs`), check corporate | |
| `cargo-vet` audit logs (Google/ChromeOS or Mozilla `audits.toml`), and check | |
| `rustsec.org` for advisories. | |
| * **Use the latest version**: Query `index.crates.io` or `crates.io` and pin | |
| the latest non-yanked stable release. Document any version ceiling required | |
| by MSRV or cross-compilation platform constraints in a comment next to the | |
| dependency spec. | |
| * **Keep default features unless problematic**: Leave crate default features | |
| enabled by default. Set `default_features = False` only when defaults pull in | |
| C `-sys` libraries (breaking hermetic cross-compiled and static `musl` | |
| builds), platform-incompatible OS crates, or heavy unused subsystems, and | |
| document the reason in a comment. | |
| * **Regenerate lockfiles**: Update `Cargo.lock` and `Cargo.Bazel.lock` with | |
| `CARGO_BAZEL_REPIN=1`; never hand-edit generated lockfiles. | |
| ## Idiomatic Rust, CLI Design & Crate Layout | |
| * **Edition & control flow**: Use `edition = "2024"`. Flatten nested | |
| conditionals with early `continue`/`return` guards and `let`-chains | |
| (`if let Some(p) = out.parent() && !p.as_os_str().is_empty()`). Prefer `str` | |
| pattern methods (`split_once`, `rsplit_once`, `strip_prefix`, `strip_suffix`) | |
| over manual index slicing. | |
| * **Parse, don't validate**: Parse CLI flags and raw inputs into strong types | |
| (`bool`, enums, validated `PathBuf`, pre-compiled `Regex`) in `parse_args` | |
| rather than storing stringly-typed `String` fields or deferring validation to | |
| execution. | |
| * **Positional argument counts**: Validate fixed positional argument counts with | |
| an explicit length check (e.g., `if positional.len() != 3`) rather than | |
| collection-length match guards or fixed-size array `try_from` conversions. | |
| * **`OsString` & `ExitCode`**: Keep CLI arguments and file paths as `OsString` | |
| and `PathBuf`; never round-trip `OsString -> String -> PathBuf` via | |
| `to_string_lossy()`. Return `std::process::ExitCode` from `main()` and | |
| `run_cli`. | |
| * **Collections**: Default to `Vec` and `HashMap`/`HashSet` over | |
| `BTreeMap`/`BTreeSet` unless sorted-key traversal is a data-structure | |
| invariant. Sort a `Vec` at formatting or output boundaries when deterministic | |
| order is required. | |
| * **Cohesive file organization**: Place core logic in library crates | |
| (`src/lib.rs`) so unit tests call library functions directly. Group CLI | |
| option structs, `parse_args`, and `run_cli` together in one contiguous | |
| section rather than splitting `parse_args` at the top and `run_cli` at the | |
| bottom around domain logic. | |
| * **Formatting**: Format Rust sources with `bazel run @rules_rust//:rustfmt` | |
| and verify with `--aspects=@rules_rust//rust:defs.bzl%rustfmt_aspect` | |
| `--output_groups=+rustfmt_checks`. | |
| ## Errors, Panics & Linting | |
| * **Return errors, don't panic**: Production crates (`crates/*/src/*.rs`) | |
| carry `#![deny(clippy::expect_used, clippy::unwrap_used)]`; propagate | |
| with `?` and attach context so every failure names the path, line, or | |
| entry it concerns. Reach for `const` values (e.g. | |
| `zip::DateTime::DEFAULT`) instead of `.expect()` on infallible | |
| constructors. | |
| * **Choose the error type by audience**: For CLI tools and other code that | |
| owns the error-handling context (the `shrubbery` subcommand crates), use | |
| `anyhow` (`bail!`, `.context()`, `.with_context(|| ...)`) and print the | |
| chain with `{err:#}` in `run_cli`. For library code consumed by other | |
| crates, define a typed error (`thiserror` enum implementing | |
| `std::error::Error` with `#[from]`/`#[source]`) so callers can match on | |
| variants and errors compose across crate boundaries; such a type still | |
| converts into `anyhow::Error` for free at the CLI layer. | |
| * **Tests may panic**: `unwrap()`, `expect()`, `panic!`, and indexing are | |
| allowed in test code (`.clippy.toml` sets `allow-*-in-tests`). When using | |
| `expect()`, write the message in std's recommended style, stating why the | |
| value *should* be `Ok`/`Some` (`"manifest should be writable"`, | |
| `"output zip should be a valid archive"`), not the action that failed | |
| (`"write manifest"`). | |
| * **Lints run on every build**: `.bazelrc` applies the clippy and rustfmt | |
| aspects by default (`--config=rust-lint`, `-Dwarnings`), so a plain | |
| `bazel build` fails on lint or formatting problems. Do not add | |
| `-Dclippy::unwrap_used`/`expect_used` globally: clippy's | |
| `allow-*-in-tests` settings only recognize `#[test]` functions and | |
| `#[cfg(test)]` items, so helper functions in integration-test crates | |
| (`tests/*/*_test.rs`) would be flagged. Code under `#[cfg(unix)]` must | |
| leave no `unused_mut`/`useless_vec` behind on Windows; rebind instead of | |
| conditionally `push`ing. | |
| * **WORKSPACE-mode stub**: Any new `@rules_rust//...` flag or aspect | |
| referenced from `.bazelrc` must also exist in | |
| `tests/modules/rules_rust_stub/`, which WORKSPACE CI jobs use in place of | |
| rules_rust. |