# Developer Guide **Status**: ✅ Complete **Last Updated**: December 5, 2025 --- ## Overview This guide is for developers who want to contribute to RiceCoder or extend it with custom functionality. It covers development setup, architecture, coding standards, testing, and contribution workflow. ## Table of Contents - [Getting Started](#getting-started) - [Development Setup](#development-setup) - [Project Structure](#project-structure) - [Architecture Overview](#architecture-overview) - [Coding Standards](#coding-standards) - [Testing](#testing) - [Building and Releasing](#building-and-releasing) - [Contributing](#contributing) - [Debugging](#debugging) - [Performance Profiling](#performance-profiling) --- ## Getting Started ### Prerequisites - Rust 1.75+ ([Install Rust](https://rustup.rs/)) - Git - Cargo (comes with Rust) - A code editor (VS Code recommended) ### Quick Start ```bash # Clone the repository git clone https://github.com/moabualruz/ricecoder.git cd ricecoder # Build the project cargo build # Run tests cargo test --all # Run RiceCoder cargo run -- --help ``` --- ## Development Setup ### 1. Clone Repository ```bash git clone https://github.com/moabualruz/ricecoder.git cd ricecoder ``` ### 2. Install Dependencies ```bash # Install Rust (if not already installed) curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Update Rust rustup update # Install additional tools cargo install cargo-clippy cargo install cargo-fmt cargo install cargo-tarpaulin # For code coverage ``` ### 3. Configure IDE **VS Code**: 1. Install Rust Analyzer extension 2. Install CodeLLDB extension (for debugging) 3. Create `.vscode/settings.json`: ```json { "[rust]": { "editor.formatOnSave": true, "editor.defaultFormatter": "rust-lang.rust-analyzer" }, "rust-analyzer.checkOnSave.command": "clippy" } ``` ### 4. Set Up Git Hooks ```bash # Create pre-commit hook cat > .git/hooks/pre-commit << 'EOF' #!/bin/bash cargo fmt --all cargo clippy --all -- -D warnings EOF chmod +x .git/hooks/pre-commit ``` ### 5. Configure Environment ```bash # Create .env file for development cat > .env << 'EOF' RUST_LOG=debug RICECODER_HOME=~/.ricecoder-dev EOF ``` --- ## Project Structure ``` ricecoder/ ├── projects/ricecoder/ # Main RiceCoder project │ ├── src/ # Source code │ │ ├── main.rs # Entry point │ │ ├── cli/ # CLI interface │ │ ├── tui/ # Terminal UI │ │ ├── lsp/ # LSP integration │ │ ├── completion/ # Code completion │ │ ├── hooks/ # Hooks system │ │ ├── infrastructure/ # Infrastructure layer │ │ ├── domain/ # Domain layer │ │ ├── application/ # Application layer │ │ └── interface/ # Interface layer │ ├── tests/ # Integration tests │ ├── benches/ # Benchmarks │ ├── Cargo.toml # Project manifest │ └── README.md # Project README ├── projects/ricecoder.wiki/ # Wiki documentation ├── .ai/specs/ricecoder/ # Feature specifications │ ├── requirements.md # Requirements │ ├── design.md # Design document │ ├── tasks.md # Implementation tasks │ └── done-specs/ # Archived specs └── Cargo.toml # Workspace manifest ``` --- ## Architecture Overview ### Layered Architecture RiceCoder follows a layered architecture: ``` ┌─────────────────────────────────────┐ │ Interface Layer (CLI/TUI) │ ├─────────────────────────────────────┤ │ Application Layer (Use Cases) │ ├─────────────────────────────────────┤ │ Domain Layer (Business Logic) │ ├─────────────────────────────────────┤ │ Infrastructure Layer (Services) │ └─────────────────────────────────────┘ ``` ### Key Components **CLI Layer** (`src/cli/`): - Command parsing and routing - User input handling - Output formatting **TUI Layer** (`src/tui/`): - Terminal UI rendering - Event handling - Theme management **LSP Layer** (`src/lsp/`): - Language Server Protocol implementation - Semantic analysis - Diagnostics **Completion Layer** (`src/completion/`): - Code completion engine - Context analysis - Ranking and filtering **Hooks Layer** (`src/hooks/`): - Event-driven automation - Hook registration and execution - Configuration management **Infrastructure Layer** (`src/infrastructure/`): - Storage and configuration - AI provider abstraction - File management - Session management **Domain Layer** (`src/domain/`): - Core business logic - Data models - Validation rules **Application Layer** (`src/application/`): - Use case orchestration - Workflow execution - Error handling --- ## Coding Standards ### Rust Style Guide Follow the [Rust Style Guide](https://doc.rust-lang.org/1.0.0/style/): ```rust // Use snake_case for functions and variables fn process_input(input: &str) -> Result { // Implementation } // Use PascalCase for types and traits pub struct MyStruct { field: String, } pub trait MyTrait { fn my_method(&self); } // Use UPPER_CASE for constants const MAX_RETRIES: u32 = 3; ``` ### Code Organization **Module Structure**: ```rust // src/my_module/mod.rs pub mod submodule; pub use submodule::PublicType; pub fn public_function() { // Implementation } fn private_function() { // Implementation } ``` **Error Handling**: ```rust use thiserror::Error; #[derive(Debug, Error)] pub enum MyError { #[error("IO error: {0}")] IoError(#[from] std::io::Error), #[error("Invalid input: {0}")] InvalidInput(String), } pub fn my_function() -> Result { // Implementation } ``` **Documentation**: ```rust /// Processes the input and returns the result. /// /// # Arguments /// /// * `input` - The input string to process /// /// # Returns /// /// Returns a `Result` containing the processed string or an error. /// /// # Examples /// /// ``` /// let result = process_input("hello")?; /// assert_eq!(result, "HELLO"); /// ``` pub fn process_input(input: &str) -> Result { // Implementation } ``` ### Naming Conventions | Item | Convention | Example | |------|-----------|---------| | Functions | snake_case | `process_input()` | | Variables | snake_case | `my_variable` | | Constants | UPPER_CASE | `MAX_RETRIES` | | Types | PascalCase | `MyStruct` | | Traits | PascalCase | `MyTrait` | | Modules | snake_case | `my_module` | | Files | snake_case | `my_module.rs` | ### Code Quality **Clippy Warnings**: All code must pass clippy without warnings: ```bash cargo clippy --all -- -D warnings ``` **Formatting**: Use rustfmt to format code: ```bash cargo fmt --all ``` **Documentation**: All public APIs must be documented: ```bash cargo doc --open ``` --- ## Testing ### Unit Tests Place unit tests in the same file as the code: ```rust #[cfg(test)] mod tests { use super::*; #[test] fn test_process_input() { let result = process_input("hello").unwrap(); assert_eq!(result, "HELLO"); } #[test] fn test_process_input_error() { let result = process_input(""); assert!(result.is_err()); } } ``` ### Integration Tests Place integration tests in `tests/` directory: ```rust // tests/integration_test.rs use ricecoder::cli::run; #[test] fn test_cli_help() { let output = run(&["--help"]).unwrap(); assert!(output.contains("RiceCoder")); } ``` ### Property-Based Tests Use `proptest` for property-based testing: ```rust use proptest::prelude::*; proptest! { #[test] fn test_process_input_never_panics(s in ".*") { let _ = process_input(&s); } } ``` ### Running Tests ```bash # Run all tests cargo test --all # Run tests with output cargo test --all -- --nocapture # Run specific test cargo test test_process_input # Run tests with coverage cargo tarpaulin --all --out Html ``` ### Test Coverage Minimum coverage requirements: - Public APIs: 80%+ - Core logic: 90%+ - Error handling: 100% --- ## Building and Releasing ### Development Build ```bash # Debug build (faster compilation, slower runtime) cargo build # Run with debug build cargo run -- chat ``` ### Release Build ```bash # Release build (slower compilation, faster runtime) cargo build --release # Run with release build cargo run --release -- chat ``` ### Benchmarking ```bash # Run benchmarks cargo bench --all # Run specific benchmark cargo bench my_benchmark ``` ### Creating a Release ```bash # Update version in Cargo.toml # Update CHANGELOG.md # Commit changes git add Cargo.toml CHANGELOG.md git commit -m "Release v0.1.4" # Create git tag git tag v0.1.4 # Push to GitHub git push origin main git push origin v0.1.4 # Publish to crates.io cargo publish ``` --- ## Contributing ### Contribution Workflow 1. **Fork the repository** on GitHub 2. **Create a feature branch**: `git checkout -b feature/my-feature` 3. **Make your changes** and commit: `git commit -am "Add my feature"` 4. **Push to your fork**: `git push origin feature/my-feature` 5. **Create a Pull Request** on GitHub 6. **Address review feedback** and update your PR 7. **Merge** when approved ### Pull Request Guidelines - **Title**: Clear, descriptive title - **Description**: Explain what and why - **Tests**: Include tests for new functionality - **Documentation**: Update docs if needed - **Commits**: Logical, atomic commits - **Code Quality**: Pass clippy and tests ### Commit Message Format ``` :