123 lines
3.4 KiB
Markdown
123 lines
3.4 KiB
Markdown
# Agent Guidelines for opencode-testing
|
|
|
|
This is a Rust project using Edition 2024.
|
|
|
|
## Build/Test Commands
|
|
|
|
```bash
|
|
# Build the project
|
|
cargo build
|
|
|
|
# Build for release
|
|
cargo build --release
|
|
|
|
# Run the application
|
|
cargo run
|
|
|
|
# Run all tests
|
|
cargo test
|
|
|
|
# Run a specific test (e.g., test named `test_calculate_area`)
|
|
cargo test test_calculate_area
|
|
|
|
# Run tests in a specific module
|
|
cargo test module_name::
|
|
|
|
# Run with output visible
|
|
cargo test -- --nocapture
|
|
|
|
# Check for compilation errors without building
|
|
cargo check
|
|
|
|
# Watch mode for development (requires cargo-watch)
|
|
cargo watch -x "run"
|
|
```
|
|
|
|
## Code Quality Commands
|
|
|
|
```bash
|
|
# Format code (rustfmt)
|
|
cargo fmt
|
|
|
|
# Check formatting without making changes
|
|
cargo fmt -- --check
|
|
|
|
# Run clippy lints
|
|
cargo clippy
|
|
|
|
# Run clippy with all features and warnings as errors
|
|
cargo clippy --all-features -- -D warnings
|
|
```
|
|
|
|
## Code Style Guidelines
|
|
|
|
### Formatting
|
|
- Use `cargo fmt` with default settings
|
|
- Max line width: 100 characters (default)
|
|
- Use 4 spaces for indentation (default)
|
|
- Trailing commas in multi-line lists
|
|
|
|
### Naming Conventions
|
|
- Variables, functions, modules: `snake_case`
|
|
- Types (structs, enums, traits): `CamelCase`
|
|
- Constants, statics: `SCREAMING_SNAKE_CASE`
|
|
- Lifetimes: `'lowercase`
|
|
- Generic type parameters: `CamelCase` (single uppercase letter preferred: `T`, `K`, `V`)
|
|
- Macros: `snake_case!`
|
|
|
|
### Import Organization
|
|
Group imports in this order, separated by blank lines:
|
|
1. Standard library imports (`std::`, `core::`, `alloc::`)
|
|
2. External crate imports
|
|
3. Internal crate imports (`crate::`)
|
|
4. Super module imports (`super::`)
|
|
5. Current module imports (`self::`)
|
|
|
|
Use `use` statements not `extern crate`.
|
|
|
|
### Types and Type Safety
|
|
- Prefer explicit types over `impl Trait` in public APIs
|
|
- Use `Option<T>` and `Result<T, E>` for fallible operations
|
|
- Avoid `unwrap()` and `expect()` in production code; handle errors properly
|
|
- Use `?` operator for error propagation
|
|
- Prefer `&str` over `&String`, `&[T]` over `&Vec<T>` for function parameters
|
|
|
|
### Error Handling
|
|
- Define custom error types using `thiserror` or `enum` for complex error cases
|
|
- Use `anyhow` for application code error handling
|
|
- Propagate errors with `?` operator
|
|
- Provide context with `map_err()` when needed
|
|
|
|
### Functions
|
|
- Keep functions small and focused on a single task
|
|
- Max 5-7 parameters; use structs for more complex parameter sets
|
|
- Document public functions with `///` doc comments
|
|
- Use early returns to reduce nesting
|
|
|
|
### Comments and Documentation
|
|
- Use `//` for inline comments
|
|
- Use `///` for public API documentation
|
|
- Use `//!` for module-level documentation
|
|
- Document panics, unsafe code, and complex algorithms
|
|
|
|
### Unsafe Code
|
|
- Avoid unsafe code unless absolutely necessary
|
|
- Document all safety invariants with `// SAFETY:` comments
|
|
- Keep unsafe blocks as small as possible
|
|
|
|
### Testing
|
|
- Write unit tests in the same file as the code: `#[cfg(test)]` module
|
|
- Use descriptive test names: `test_<scenario>_<expected_behavior>`
|
|
- Use `assert!`, `assert_eq!`, `assert_ne!` for assertions
|
|
- Organize tests with submodules for different scenarios
|
|
|
|
### Memory Management
|
|
- Prefer ownership and borrowing over cloning when possible
|
|
- Use `.clone()` explicitly when needed
|
|
- Consider `Cow<'_, T>` for data that may be borrowed or owned
|
|
|
|
### Performance
|
|
- Avoid premature optimization; write clear code first
|
|
- Use iterators instead of loops when appropriate
|
|
- Profile before optimizing
|