diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 78756d14..ec6147da 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -11,9 +11,8 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Use descriptive variable and closure parameter names by default — single letters are only allowed in: conventional names (`n` for count, `f` for formatter), comparison closures (`|a, b|`), trivial single-expression closures, fold accumulators, index variables (`i`/`j`/`k` in short closures or index-based loops only), and test fixtures (identical roles only). Never use single letters in multi-line functions or closures - Prefer `where` clauses for multiple trait bounds - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated -- Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` +- Custom errors: `#[derive(Debug, Display, Error)]` - Minimize `unwrap()` in non-test code — use proper error handling -- `#![deny(warnings)]` is active — code must be warning-free - Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add --toolchain "$(< rust-toolchain)" rustfmt clippy` - If the AI agent is Claude Code, `gh` (GitHub CLI) is not installed — do not attempt to use it - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes diff --git a/AGENTS.md b/AGENTS.md index 78756d14..ec6147da 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,9 +11,8 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Use descriptive variable and closure parameter names by default — single letters are only allowed in: conventional names (`n` for count, `f` for formatter), comparison closures (`|a, b|`), trivial single-expression closures, fold accumulators, index variables (`i`/`j`/`k` in short closures or index-based loops only), and test fixtures (identical roles only). Never use single letters in multi-line functions or closures - Prefer `where` clauses for multiple trait bounds - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated -- Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` +- Custom errors: `#[derive(Debug, Display, Error)]` - Minimize `unwrap()` in non-test code — use proper error handling -- `#![deny(warnings)]` is active — code must be warning-free - Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add --toolchain "$(< rust-toolchain)" rustfmt clippy` - If the AI agent is Claude Code, `gh` (GitHub CLI) is not installed — do not attempt to use it - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes diff --git a/CLAUDE.md b/CLAUDE.md index 78756d14..ec6147da 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,9 +11,8 @@ Read and follow the CONTRIBUTING.md file in this repository for all code style c - Use descriptive variable and closure parameter names by default — single letters are only allowed in: conventional names (`n` for count, `f` for formatter), comparison closures (`|a, b|`), trivial single-expression closures, fold accumulators, index variables (`i`/`j`/`k` in short closures or index-based loops only), and test fixtures (identical roles only). Never use single letters in multi-line functions or closures - Prefer `where` clauses for multiple trait bounds - Derive order: std traits → comparison traits → `Hash` → derive_more → feature-gated -- Custom errors: `#[derive(Debug, Display, Error)]` + `#[non_exhaustive]` +- Custom errors: `#[derive(Debug, Display, Error)]` - Minimize `unwrap()` in non-test code — use proper error handling -- `#![deny(warnings)]` is active — code must be warning-free - Install toolchain before running tests: `rustup toolchain install "$(< rust-toolchain)" && rustup component add --toolchain "$(< rust-toolchain)" rustfmt clippy` - If the AI agent is Claude Code, `gh` (GitHub CLI) is not installed — do not attempt to use it - Run `FMT=true LINT=true BUILD=true TEST=true DOC=true ./test.sh` to validate changes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 74033a2e..aa517273 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,12 +64,6 @@ pub use error_report::ErrorReport; pub use event::Event; ``` -- Type aliases using `pub use ... as ...` are used to provide semantic alternative names: - -```rust -pub use Reflection as DataTreeReflection; -``` - ### Derive Macro Ordering When deriving multiple traits, use this order and split across multiple `#[derive(...)]` lines for readability: @@ -202,16 +196,9 @@ where HardlinksRecorder: RecordHardlinks + Sync + ?Sized, ``` -### Visibility - -- Use `pub` for the public API surface. -- Use `pub(crate)` for items shared within the crate but not exposed externally. -- Default to private for everything else. - ### Error Handling - Define custom error enums with `#[derive(Debug, Display, Error)]` from `derive_more`. -- Mark error enums as `#[non_exhaustive]`. - Minimize `unwrap()` in non-test code — use proper error propagation. `unwrap()` is acceptable in tests and for provably infallible operations (with a comment explaining why). When deliberately ignoring an error, use `.ok()` with a comment explaining why. ```rust @@ -223,22 +210,9 @@ pub enum RuntimeError { } ``` -### Documentation Comments - -- Use `///` doc comments for all public types, traits, functions, and fields. -- Use `//!` module-level doc comments at the top of `lib.rs` and significant modules. -- Include usage examples with `/// ```no_run` blocks for key public APIs. -- Reference related types with `[`backtick links`](crate::path)` syntax. - -### Feature Gating - -- Use `#[cfg(feature = "...")]` for optional functionality (e.g., `json`, `cli`). -- Use `#[cfg(unix)]` for POSIX-specific code. -- Use `#[cfg_attr(feature = "json", derive(Deserialize, Serialize))]` for conditional derives. - ### Pattern Matching -Use exhaustive matching. When mapping enum variants to values, prefer the concise wrapping style: +When mapping enum variants to values, prefer the concise wrapping style: ```rust ExitCode::from(match self { @@ -247,18 +221,6 @@ ExitCode::from(match self { }) ``` -### Struct Field Ordering - -Order fields logically by purpose, not alphabetically. Group related fields together. Document every public field with `///` comments. - -### Macros - -Use macros to reduce boilerplate for repetitive patterns (e.g. newtype wrappers, trait impls for multiple numeric types). Keep macros well-scoped and documented. - -### Warnings Policy - -The crate uses `#![deny(warnings)]` — all warnings are treated as errors. Code must compile warning-free. - ## Setup Install the required Rust toolchain and components before running any checks: