Rust Dev

Rust Development Standards

Architecture: Bounded Contexts

Parser

Parses raw git diff output into DiffFile / DiffHunk structures. No side effects, pure transformation. Handles unified diff format, binary files, rename detection.

State

SQLite persistence via rusqlite. Stores review status per hunk (keyed by SHA-256 content hash). Detects stale hunks when diff content changes. Provides ReviewDb as the single entry point.

TUI

ratatui-based interactive interface. File list on left, hunk view on right. Keyboard-driven: navigate hunks, mark reviewed, view progress. Reads from Parser output, writes to State.

Gate

Pre-commit hook integration. check_gate returns whether all hunks are reviewed. enable_gate / disable_gate install/remove the git hook. Wrapper command for CI integration.

CLI

clap derive-based argument parsing. Subcommands: review (default TUI), status (print progress), gate (check/enable/disable), reset (clear review state).

TDD Enforcement

Follow red-green-refactor:

1. Write a failing test first
2. Write minimal code to make it pass
3. Refactor while keeping tests green

Use London School (mock-first) for integration boundaries. Use real implementations for pure logic.

Error Handling

• thiserror for library errors in src/lib.rs and modules
• anyhow for the binary in src/main.rs
• No empty catch blocks or silent error swallowing
• Propagate errors with ? operator; add context with .context()

Anti-Patterns

• Do NOT shell out to git diff without sanitizing arguments
• Do NOT store absolute paths in the SQLite database (use repo-relative)
• Do NOT assume UTF-8 for all diff content (handle binary gracefully)
• Do NOT block the TUI event loop with synchronous I/O
• Do NOT use unwrap() in library code; reserve for tests only

Shell/Regex Patterns

• When writing regex in shell hooks, always test edge cases: dashes as grep options (use --), underscores in character classes, special chars in branch names
• Run cargo build and cargo test after any Rust changes before reporting completion
• Prefer grep -E over egrep (deprecated) and always use -- before patterns that might start with -

Build & Test Commands

cargo build                # Build
cargo test                 # Run all tests
cargo clippy               # Lint
cargo fmt --check          # Format check
cargo check                # Type check only

• ALWAYS run cargo test after code changes
• ALWAYS run cargo check before committing
• ALWAYS run cargo clippy -- -D warnings before opening PRs

Definition of Done

• All tests pass (cargo test)
• No clippy warnings (cargo clippy -- -D warnings)
• Code formatted (cargo fmt --check)
• No hardcoded paths or credentials
• Public APIs have doc comments
• Error cases handled, not ignored

Security Rules

• Sanitize all file paths to prevent directory traversal
• Validate git refs before passing to shell commands
• Never pass unsanitized user input to std::process::Command
• Never hardcode API keys or credentials