# Contributing to jiq
## Prerequisites
- Rust (latest stable, 2024 edition)
- jq ([jqlang.org/download](https://jqlang.org/download/))
- cargo-insta (`cargo install cargo-insta`)
## Architecture
### Module Structure
Features are self-contained modules:
```
src/feature_name/
├── mod.rs # Exports
├── state.rs # State struct
├── events.rs # Event handlers (optional)
```
### Key Rules
1. **Self-contained modules** - Features define their state and event logic in their own module
2. **Integration pattern** - `App` holds feature state, main dispatcher calls feature event handlers
3. **Small files** - Easy to reason about, single responsibility
Example:
```rust
// Feature owns its state and events
// src/clipboard/state.rs
pub struct ClipboardState { ... }
// src/clipboard/events.rs
pub fn handle_clipboard_key(app: &mut App, key: KeyEvent) -> bool { ... }
// Main app integrates the feature
// src/app/state.rs
pub struct App {
pub clipboard: ClipboardState,
...
}
// src/app/events.rs - Dispatcher calls feature handler
if clipboard::events::handle_clipboard_key(self, key) {
return;
}
```
### Why This Pattern
1. **Separation of Concerns** - Each module owns its domain logic, main app is just a coordinator
2. **Testability** - Feature modules tested independently without full app context
3. **Maintainability** - Changes to clipboard don't touch history or search
4. **Rust Ownership** - App owns state, feature functions borrow mutably, clear ownership
5. **Scalability** - Adding features doesn't bloat existing files
## Standards
### Code Quality
```bash
cargo build # Zero warnings required
cargo clippy -D warnings # Must pass
```
### Rust 2024 Edition
- Use `#[derive(Default)]` with `#[default]` for enums
- Prefer derive macros over manual implementations
- Document public APIs with `///`
## Testing
### Required
- **Unit tests** for all business logic
- **Snapshot tests** for visual components (`cargo-insta`)
- **Debug logging** for TUI interactions (`log::debug!`)
```bash
cargo test # All tests
cargo insta test # Snapshots
cargo insta review # Accept snapshots
```
## Pull Request Checklist
- [ ] Feature in self-contained module
- [ ] Unit tests for logic
- [ ] Snapshot tests for visuals
- [ ] Zero warnings (`cargo build` + `cargo clippy`)
- [ ] Manual TUI testing done
## Commits
```
type(scope): description
feat(clipboard): add OSC 52 support
fix(autocomplete): handle empty suggestions
refactor(help): move to dedicated module
```
Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`