Developer Guide

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
• Development Setup
• Project Structure
• Architecture Overview
• Coding Standards
• Testing
• Building and Releasing
• Contributing
• Debugging
• Performance Profiling

---

Getting Started

Prerequisites

• Rust 1.75+ (Install Rust)
• Git
• Cargo (comes with Rust)
• A code editor (VS Code recommended)

Quick Start

# 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

git clone https://github.com/moabualruz/ricecoder.git
cd ricecoder

2. Install Dependencies

# 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:

{
  "[rust]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "rust-lang.rust-analyzer"
  },
  "rust-analyzer.checkOnSave.command": "clippy"
}

4. Set Up Git Hooks

# 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

# 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:

// Use snake_case for functions and variables
fn process_input(input: &str) -> Result<String, Error> {
    // 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:

// src/my_module/mod.rs
pub mod submodule;

pub use submodule::PublicType;

pub fn public_function() {
    // Implementation
}

fn private_function() {
    // Implementation
}

Error Handling:

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<String, MyError> {
    // Implementation
}

Documentation:

/// 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<String, MyError> {
    // 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:

cargo clippy --all -- -D warnings

Formatting: Use rustfmt to format code:

cargo fmt --all

Documentation: All public APIs must be documented:

cargo doc --open

---

Testing

Unit Tests

Place unit tests in the same file as the code:

#[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:

// 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:

use proptest::prelude::*;

proptest! {
    #[test]
    fn test_process_input_never_panics(s in ".*") {
        let _ = process_input(&s);
    }
}

Running Tests

# 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

# Debug build (faster compilation, slower runtime)
cargo build

# Run with debug build
cargo run -- chat

Release Build

# Release build (slower compilation, faster runtime)
cargo build --release

# Run with release build
cargo run --release -- chat

Benchmarking

# Run benchmarks
cargo bench --all

# Run specific benchmark
cargo bench my_benchmark

Creating a Release

# 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

<type>: <subject>

<body>

<footer>

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation
• style: Code style
• refactor: Code refactoring
• test: Test changes
• chore: Build, dependencies, etc.

Example:

feat: Add code completion for Rust

Implement context-aware code completion for Rust files using
rust-analyzer LSP server. Includes ranking and filtering of
suggestions based on context.

Fixes #123

---

Debugging

Debug Logging

Enable debug logging:

RUST_LOG=debug cargo run -- chat

Log Levels:

• error: Errors only
• warn: Warnings and errors
• info: Info, warnings, and errors
• debug: Debug, info, warnings, and errors
• trace: All messages

Debug Breakpoints

Using VS Code with CodeLLDB:

1. Set breakpoint by clicking line number
2. Run with debugger: Ctrl+Shift+D
3. Select "Rust" configuration
4. Step through code with F10/F11

Debugging Tips

// Print debug information
dbg!(variable);

// Print with context
eprintln!("Debug: {:?}", variable);

// Use log macros
log::debug!("Debug message");
log::info!("Info message");
log::warn!("Warning message");
log::error!("Error message");

---

Performance Profiling

CPU Profiling

Using cargo-flamegraph:

# Install flamegraph
cargo install flamegraph

# Run with profiling
cargo flamegraph -- chat

# View result
open flamegraph.svg

Memory Profiling

Using valgrind (Linux):

# Install valgrind
sudo apt-get install valgrind

# Run with profiling
valgrind --leak-check=full cargo run -- chat

Benchmarking

# Run benchmarks
cargo bench --all

# Compare benchmarks
cargo bench --all -- --baseline main

---

Common Development Tasks

Adding a New Command

1. Create command handler in src/cli/commands/
2. Register command in src/cli/mod.rs
3. Add tests in tests/
4. Update documentation

Adding a New Feature

1. Create feature module in src/
2. Implement feature logic
3. Add tests
4. Update documentation
5. Create spec in .ai/specs/ricecoder/

Updating Dependencies

# Check for updates
cargo outdated

# Update dependencies
cargo update

# Update specific dependency
cargo update -p dependency-name

Fixing Clippy Warnings

# See all warnings
cargo clippy --all

# Fix automatically (if possible)
cargo clippy --fix --all

---

Resources

Documentation

• Rust Book
• Rust API Guidelines
• Cargo Book
• RiceCoder Architecture

Tools

• Rust Analyzer
• Clippy
• Rustfmt
• Cargo

Community

• Rust Forum
• Rust Discord
• RiceCoder GitHub
• RiceCoder Discussions

---

See Also

• Contributing Guide - Contribution guidelines
• Architecture Overview - System architecture
• API Reference - API documentation
• Troubleshooting Guide - Troubleshooting help

---

Last updated: December 5, 2025