Development Setup

• Prerequisites
• Quick Start
• Toolchain Management
  • Without mise
• Development Commands
• IDE Setup
  • rust-analyzer
• Project Structure
• Code Quality
  • Lint Policy
• Commit Standards

This chapter covers setting up a development environment for contributing to ruley.

Prerequisites

• Rust 1.91+ (see rust-version in Cargo.toml for minimum supported version)
• Git for version control
• mise (recommended) for development toolchain management

Quick Start

# Clone the repository
git clone https://github.com/EvilBit-Labs/ruley.git
cd ruley

# Install development tools (mise handles everything via mise.toml)
just setup

# Build the project
just build

# Run tests
just test

# Run the CLI
just run --help

Toolchain Management

ruley uses mise to manage the development toolchain. The mise.toml file at the project root defines all required tools and versions:

• Rust 1.93.1 with rustfmt and clippy components
• cargo-nextest for faster test execution
• cargo-llvm-cov for code coverage
• cargo-audit and cargo-deny for security auditing
• mdbook and plugins for documentation
• git-cliff for changelog generation
• pre-commit for pre-commit hooks
• actionlint for GitHub Actions linting

Run mise install to install all tools, or let just setup handle it.

Without mise

If you prefer not to use mise, install Rust via rustup and install individual tools with cargo install:

rustup toolchain install 1.93.1 --profile default -c rustfmt,clippy
cargo install cargo-nextest cargo-llvm-cov cargo-audit cargo-deny

Development Commands

ruley uses just as its task runner. Run just to see all available recipes:

IDE Setup

rust-analyzer

ruley works well with rust-analyzer. Recommended VS Code settings:

{
  "rust-analyzer.cargo.features": "all",
  "rust-analyzer.check.command": "clippy",
  "rust-analyzer.check.extraArgs": [
    "--all-features"
  ]
}

Project Structure

ruley/
  src/
    cli/          # CLI argument parsing and config management
    packer/       # File discovery, gitignore, compression
    llm/          # LLM providers, tokenization, chunking
    generator/    # Prompt templates and rule parsing
    output/       # Format writers and conflict resolution
    utils/        # Errors, progress, caching, validation
    lib.rs        # Pipeline orchestration (10-stage pipeline)
    main.rs       # Entry point
  tests/          # Integration tests
  benches/        # Criterion benchmarks
  prompts/        # LLM prompt templates (markdown)
  docs/           # mdbook documentation (this book)
  examples/       # Example configuration files

Code Quality

Before submitting changes, ensure:

1. All tests pass: just test
2. No clippy warnings: just lint (includes all features) and just clippy-min (no default features)
3. Code is formatted: just fmt
4. Full CI suite passes: just ci-check

Lint Policy

ruley enforces a zero-warnings policy. Key lint rules:

• unsafe_code = "deny" – No unsafe code in production (tests may use #[allow(unsafe_code)])
• unwrap_used = "deny" – No unwrap() in production code
• panic = "deny" – No panic!() in production code
• pedantic, nursery, cargo – Clippy lint groups at warn level

See [workspace.lints.clippy] in Cargo.toml for the full lint configuration.

Commit Standards

Follow Conventional Commits:

<type>[(<scope>)]: <description>

• Types: feat, fix, docs, refactor, test, perf, build, ci, chore
• Scope (optional): cli, packer, llm, generator, output, utils, config, deps
• DCO: Always sign off with git commit -s

See CONTRIBUTING.md for full contribution guidelines.