Raw view: Rust Cargo Workspace CLAUDE.md
No invisible, zero-width, or bidi-control characters detected.
# {{PROJECT_NAME}}
Cargo workspace. Rust stable, MSRV {{MSRV}} (see `rust-toolchain.toml` and `rust-version` in `Cargo.toml`). Crates live in `crates/`: `{{CORE_CRATE}}` (library, no IO), `{{BIN_CRATE}}` (binary), plus internal helpers.
## Commands
| Task | Command |
|------|---------|
| Build everything | `cargo build --workspace --all-targets` |
| Test | `cargo test --workspace` (one test: `cargo test -p {{CORE_CRATE}} parse_header`) |
| Format | `cargo fmt --all` (check only: `cargo fmt --all -- --check`) |
| Lint | `cargo clippy --workspace --all-targets --all-features -- -D warnings` |
| Docs | `cargo doc --workspace --no-deps` |
| Run | `cargo run -p {{BIN_CRATE}} -- <args>` |
| Dependency audit | `cargo audit` (needs `cargo install cargo-audit`) |
Definition of done: fmt check, clippy with `-D warnings`, and `cargo test --workspace` all exit 0. Paste the final `test result:` lines. Run `cargo doc` too if you touched public items.
## Workspace rules
- Shared dependency versions live in `[workspace.dependencies]` in the root `Cargo.toml`. Crates reference them with `foo = { workspace = true }`. Never pin a version in a member crate.
- Shared lints live in `[workspace.lints]`; each crate has `[lints] workspace = true`. Do not add `#![allow(...)]` at crate level.
- New crate: `cargo new --lib crates/<name>`, add it to `[workspace.members]`, set `publish = false` unless it is meant for crates.io.
- Commit `Cargo.lock`. Update one dependency with `cargo update -p <name>`, not a blanket `cargo update`.
## Error handling
- Library crates: one `Error` enum per crate with `thiserror`. Every variant carries context (`#[error("reading {path}: {source}")]`). Expose `pub type Result<T> = std::result::Result<T, Error>;`.
- Binary crates and tests: `anyhow::Result`, adding context with `.with_context(|| format!("..."))` at each IO boundary.
- Never `unwrap()` or `expect()` in library code outside tests. In binaries, `expect("reason")` is allowed only for invariants that cannot fail by construction, with the reason saying why.
- Do not use `Box<dyn Error>` in public signatures. Do not `panic!` to signal a recoverable condition.
## Unsafe policy
- `{{CORE_CRATE}}` and all library crates carry `#![forbid(unsafe_code)]`. Do not remove it.
- `unsafe` is permitted only in crates whose name ends in `-sys` or `-ffi`. Each `unsafe` block needs a `// SAFETY:` comment on the line above stating the invariant that makes it sound and who upholds it.
- Any new or changed `unsafe` block must be called out in your report and needs a test that exercises it. Run it under `cargo +nightly miri test` if Miri is installed.
## Code conventions
- Public items get `///` docs with at least one sentence and, for fallible functions, an `# Errors` section. Fix every `rustdoc::broken_intra_doc_links` warning.
- Borrow in parameters (`&str`, `&[T]`, `impl AsRef<Path>`); return owned types.
- Derive in this order: `Debug, Clone, Copy, PartialEq, Eq, Hash, Default`, then serde derives. Derive only what the type needs.
- Feature flags are additive and documented in the crate's `README.md`. Default features must compile on all tier-1 targets.
- No `use super::*` outside `mod tests`.
## Tests
- Unit tests in `#[cfg(test)] mod tests` at the bottom of the file they test.
- Integration tests in `crates/<name>/tests/*.rs`, one file per feature area. Shared helpers in `tests/common/mod.rs`.
- Property tests with `proptest` for parsers and serializers; keep `proptest-regressions/` committed.
- Doctests are tests: every rust code block in docs must compile. Use `no_run` for examples that need a network; never use `ignore`.
- Use `insta` snapshots for large structured output; review with `cargo insta review` and commit the `.snap` files.
## Do not
- Do not add a dependency for something `std` already does. Any new dependency goes in the report with a one-line reason.
- Do not change `rust-toolchain.toml`, `rust-version`, or edition.
- Do not silence clippy with `#[allow(clippy::...)]` on a function; fix the lint or justify it in a comment and the report.
- Do not run `cargo publish`.