blob: adaa035d3af047f15a60f7b8c51965a55f11f017 [file] [view]
---
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.