agents: add Rust coding rules and review-code auditor (#4405) Rust tooling and crate dependencies lacked dedicated coding conventions and code review checks, allowing hand-rolled subsystems, unvetted or outdated crates, and non-idiomatic CLI or error handling to slip through. Add `.agents/rules/rust.md` covering ecosystem crate usage over custom subsystems, `crates.io` dependency vetting and versioning, feature pruning for hermetic cross-compilation, and idiomatic Rust CLI and crate layout. Add a `Rust Code Auditor` sub-agent prompt to `review-code` and include `*.rs` in cross-language code style checks.
diff --git a/.agents/rules/code-style.md b/.agents/rules/code-style.md index 494ef36..2028a4d 100644 --- a/.agents/rules/code-style.md +++ b/.agents/rules/code-style.md
@@ -1,7 +1,7 @@ --- trigger: glob description: Cross-language code style, control flow, and CLI conventions -globs: "*.py,*.sh,*.cc,*.h,*.go,*.bzl,*.bazel,*.yaml,*.yml" +globs: "*.py,*.rs,*.sh,*.cc,*.h,*.go,*.bzl,*.bazel,*.yaml,*.yml" --- # Code Style Rules
diff --git a/.agents/rules/rust.md b/.agents/rules/rust.md new file mode 100644 index 0000000..e105a6c --- /dev/null +++ b/.agents/rules/rust.md
@@ -0,0 +1,64 @@ +--- +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. +* **`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`.
diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index d5eec4f..0d19668 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md
@@ -84,11 +84,11 @@ - Prompt file: `.agents/skills/review-code/review-code-style-prompt.md` - Focus: Audits cross-language code style across all code files (`*.py`, - `*.sh`, `*.cc`, `*.h`, `*.go`, `*.bzl`, `*.bazel`): file definition order, - guard clauses, fail-closed `else`, single input form, no unrequested - knobs/aliases, no speculative validation or defensive `None` checks, no - nested comprehensions, naming precision, simplification, `keep-sorted` - markers, and CLI safety annotations. + `*.rs`, `*.sh`, `*.cc`, `*.h`, `*.go`, `*.bzl`, `*.bazel`): file + definition order, guard clauses, fail-closed `else`, single input form, + no unrequested knobs/aliases, no speculative validation or defensive + `None` checks, no nested comprehensions, naming precision, + simplification, `keep-sorted` markers, and CLI safety annotations. 11. Shell Script Sub-Agent (`Role: "Shell Script Auditor"`): - Prompt file: @@ -110,6 +110,15 @@ `SHOULD-FIX` and flagging plausible technical constraints as `HUMAN-SIGN-OFF`. +13. Rust Sub-Agent (`Role: "Rust Code Auditor"`): + - Prompt file: + `.agents/skills/review-code/review-rust-prompt.md` + - Focus: Audits Rust code (`*.rs`, `crates/**`) and crate dependencies in + `MODULE.bazel` / `Cargo.*` against `.agents/rules/rust.md` (standard + ecosystem crates over custom subsystems such as regex or ZIP handling, + crate legitimacy and latest `crates.io` versions, feature pruning for + cross-compilation, library crate structure, and `rustfmt`). + ### Action Instructions - Immediately create a user-facing review artifact named `code-review-results.md` in the conversation artifact directory so progress @@ -211,8 +220,8 @@ `*requirements*.txt`, `gazelle_python_manifest.yaml`, or patches). Only flag build breakages or license issues. 3. Formatter-Handled Output: Never ask to revert a formatter's output (such as - `buildifier` or `ruff` quote/comma/order changes, trailing newlines, or - markdown hard-break backslashes). + `buildifier`, `ruff`, or `rustfmt` quote/comma/order changes, trailing + newlines, or markdown hard-break backslashes). 4. `TODO` Syntax: Do not complain about `TODO(...)` formatting or demand a username or issue number. Drop `TODO` syntax nits entirely. 5. Rule Over-Application:
diff --git a/.agents/skills/review-code/review-code-style-prompt.md b/.agents/skills/review-code/review-code-style-prompt.md index 656a87b..cf52a95 100644 --- a/.agents/skills/review-code/review-code-style-prompt.md +++ b/.agents/skills/review-code/review-code-style-prompt.md
@@ -1,7 +1,7 @@ You are a specialized Code Style & Architecture Auditor sub-agent. Your sole task is to audit all code and configuration files in `git diff` -(`*.py`, `*.sh`, `*.cc`, `*.h`, `*.go`, `*.bzl`, `*.bazel`) for cross-language -code style, control flow, refactoring, and CLI conventions: +(`*.py`, `*.rs`, `*.sh`, `*.cc`, `*.h`, `*.go`, `*.bzl`, `*.bazel`) for +cross-language code style, control flow, refactoring, and CLI conventions: 1. Read and strictly enforce `.agents/rules/code-style.md`, `AGENTS.md`, and `CONTRIBUTING.md`.
diff --git a/.agents/skills/review-code/review-rust-prompt.md b/.agents/skills/review-code/review-rust-prompt.md new file mode 100644 index 0000000..07da9e3 --- /dev/null +++ b/.agents/skills/review-code/review-rust-prompt.md
@@ -0,0 +1,47 @@ +You are a specialized Rust Code & Dependency Auditor sub-agent. +Your sole task is to audit all Rust source, build, and crate dependency changes +(`*.rs`, `crates/**`, `Cargo.*`, and `rust_crates` entries in `MODULE.bazel`) +in `git diff`: + +1. Read and strictly enforce `.agents/rules/rust.md`, + `.agents/rules/code-style.md`, `AGENTS.md`, and `CONTRIBUTING.md`. +2. No Re-Implemented Subsystems: Flag custom implementations of non-trivial + subsystems—including CLI argument loops (`split_once('=')`, + `strip_prefix("--...")`), `@flagfile` response-file readers, CSV/INI/JSON/ + TOML parsers, base64/hex codecs, Python AST or PEP 440/508 parsers, regex + engines, archive/compression codecs, or cryptographic hashes—and require + established ecosystem crates (`https://blessed.rs/crates`) instead. +3. Dependency Legitimacy & Latest Version: When crates are added or updated in + `MODULE.bazel` or `Cargo.toml`, verify each crate against `index.crates.io` + / `crates.io`: + - Confirm the crate is legitimate (reputable maintainers/org, no unaddressed + RustSec advisories, and audited where applicable in `cargo-vet` logs). + - Confirm the specified and locked versions match the latest non-yanked + stable release on `crates.io`. If an older major/minor version is pinned, + require an inline comment explaining the technical constraint (e.g., MSRV + or cross-compilation target support) and have the + `Justification & Exception Auditor` evaluate it. + - Check feature selection: default features should remain enabled unless + defaults pull in C `-sys` libraries, target-incompatible OS crates, or + heavy unused subsystems (with a comment explaining why + `default_features = False` is set). +4. Idiomatic Rust, CLI & Crate Design: + - Verify workspace crates use `edition = "2024"`, flatten nested conditionals + with early guards and `let`-chains, and use `str` pattern methods + (`split_once`, `rsplit_once`, `strip_prefix`/`strip_suffix`) over manual + index slicing. + - Verify "parse, don't validate": flag stringly-typed `String` options where + `bool`, enums, validated `PathBuf`, or pre-compiled `Regex` belong in + `parse_args`. + - Verify CLI parsers (`lexopt`/`clap` + `argfile`) operate on `OsString` / + `PathBuf` without `to_string_lossy()` round-trips, and `main`/`run_cli` + return `std::process::ExitCode` instead of raw `i32`. + - Verify `Vec` and `HashMap`/`HashSet` are preferred over `BTreeMap`/ + `BTreeSet` unless sorted traversal is an invariant, CLI types/`parse_args`/ + `run_cli` are grouped cohesively (no top/bottom CLI sandwich), tests use + real temporary directories instead of mocked filesystem IO, and `rustfmt` + + `bazel test --config=fast-tests` pass. +5. Guardrails: Never nitpick generated `Cargo.lock` or `Cargo.Bazel.lock` + formatting; only flag stale lockfiles or unvetted/outdated crate versions. + +@.agents/skills/review-code/review-report-format.md