| --- | |
| 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`, | |
| `configparser`, 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. | |
| * **Compression backends**: For `zip`/`flate2` DEFLATE workloads, prefer | |
| pure-Rust `zlib-rs` (`flate2` features `["zlib-rs", "runtime_detection"]`, | |
| plus `zip` feature `deflate-flate2-zlib-rs` when using `zip`, both with | |
| `default-features = false`) over `miniz_oxide` so throughput matches or | |
| exceeds C `zlib` while preserving pure-Rust `musl` cross-compilation and | |
| deterministic bitstreams. | |
| * **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(ext) = path.extension() && ext == "whl"`). | |
| * **String & line processing**: Prefer raw string literals (`r#"..."#`) when a | |
| string contains embedded quotes or backslashes instead of backslash-escaping | |
| them. Prefer `str` pattern methods (`split_once`, `rsplit_once`, | |
| `strip_prefix`, `strip_suffix`) over manual index slicing. Iterate lines | |
| directly with `str::lines()` (`.map(str::trim).filter(...)`) instead of | |
| pre-allocating `.replace("\r\n", "\n")` (`str::lines()` strips both `\n` and | |
| `\r\n`). | |
| * **Filesystem parent directories**: Pass `parent` directly to | |
| `fs::create_dir_all(parent)` without `!parent.as_os_str().is_empty()` (`""` is | |
| already a no-op). | |
| * **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`. | |
| * **Symbolic constants in `match` arms**: When string tokens (subcommand names, | |
| CLI flags, or wire-format tags) appear across multiple sites (`match` arms, | |
| registries, or error messages), group them as constants in a module (`mod | |
| flags`, `mod subcommands`) and match via qualified paths (`flags::TEMPLATE`, | |
| `subcommands::ZIPPER`). A misspelled bare identifier in a Rust `match` arm | |
| parses as a catch-all variable binding, whereas a module-qualified path fails | |
| compilation (`E0531`). Keep raw string literals in tests so tests catch typos | |
| in constant values, and pass `case=no` to `keep-sorted` when `_` vs. | |
| uppercase ASCII would invert runtime lowercase sort order (`"zip_main_maker"` | |
| < `"zipper"`, whereas `ZIPPER` < `ZIP_MAIN_MAKER`). | |
| * **Collections**: Default to `Vec` and `HashMap`/`HashSet` over | |
| `BTreeMap`/`BTreeSet` (and over `Vec<(K, V)>` linear scans when insertion | |
| order is not required) unless sorted-key traversal is a data-structure | |
| invariant. Sort a `Vec` at formatting or output boundaries when deterministic | |
| order is required; omit defensive key sorting when template placeholders are | |
| disjoint delimited tokens (e.g., `%KEY%`). | |
| * **Cohesive file organization**: Place core logic in library crates | |
| (`src/lib.rs`) so unit tests call library functions directly, and extract | |
| shared wire/manifest parsers into a small workspace library crate rather than | |
| duplicating line parsing across sibling `shrubbery` crates. 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. | |
| * **Document `# Errors`**: Add `# Errors` rustdoc sections on fallible `pub fn` | |
| library items stating when they return `Err`. | |
| * **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: initialize base | |
| collections as fixed-size arrays (`[...]`) or strings rather than `vec![...]` | |
| before rebinding under `#[cfg(unix)]` (spot-check the non-Unix branch locally | |
| on Linux by temporarily flipping `#[cfg(unix)]` to `#[cfg(windows)]` before | |
| pushing). | |
| * **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. |