|
| 1 | +<!-- |
| 2 | + Scope: AGENTS.md guides the Copilot coding agent and Copilot Chat. |
| 3 | + For code completion and code review patterns, see .github/copilot-instructions.md |
| 4 | + For Claude Code, see CLAUDE.md |
| 5 | +--> |
| 6 | + |
| 7 | +# DigitalRain |
| 8 | + |
| 9 | +Matrix-style digital rain terminal visual effect written in Rust. |
| 10 | + |
| 11 | +## Tech Stack |
| 12 | + |
| 13 | +- **Language**: Rust (edition 2024, MSRV 1.85) |
| 14 | +- **Terminal**: crossterm 0.29 (cross-platform terminal manipulation) |
| 15 | +- **CLI**: clap 4 (command-line argument parsing with derive macros) |
| 16 | +- **Config**: toml + serde (TOML config file parsing) |
| 17 | +- **RNG**: rand 0.9 (random number generation for rain effects) |
| 18 | +- **Paths**: dirs 6 (platform-specific config directory resolution) |
| 19 | + |
| 20 | +## Build and Test Commands |
| 21 | + |
| 22 | +```bash |
| 23 | +# Build |
| 24 | +cargo build |
| 25 | + |
| 26 | +# Build release (optimized) |
| 27 | +cargo build --release |
| 28 | + |
| 29 | +# Test |
| 30 | +cargo test |
| 31 | + |
| 32 | +# Lint |
| 33 | +cargo clippy -- -D warnings |
| 34 | + |
| 35 | +# Format check |
| 36 | +cargo fmt --check |
| 37 | + |
| 38 | +# Full verification (run before any PR) |
| 39 | +cargo build && cargo test && cargo clippy -- -D warnings && cargo fmt --check |
| 40 | +``` |
| 41 | + |
| 42 | +## Project Structure |
| 43 | + |
| 44 | +```text |
| 45 | +DigitalRain/ |
| 46 | +├── src/ |
| 47 | +│ ├── main.rs - Entry point, CLI parsing, main loop |
| 48 | +│ ├── buffer.rs - Terminal buffer management |
| 49 | +│ ├── config.rs - Configuration loading and defaults |
| 50 | +│ ├── crt.rs - CRT monitor visual effect |
| 51 | +│ ├── overlay.rs - Text overlay rendering |
| 52 | +│ ├── terminal.rs - Terminal setup and teardown |
| 53 | +│ ├── timing.rs - Frame timing and tick control |
| 54 | +│ ├── transition.rs - Visual transition effects |
| 55 | +│ ├── color/ - Color schemes and gradient logic |
| 56 | +│ ├── effects/ - Visual effect implementations |
| 57 | +│ └── rain/ - Core rain drop simulation |
| 58 | +├── assets/ - Static assets (screenshots, etc.) |
| 59 | +├── docs/ - Project documentation |
| 60 | +├── scripts/ - Build and CI helper scripts |
| 61 | +├── .github/ - CI workflows and Copilot config |
| 62 | +├── Cargo.toml - Rust package manifest |
| 63 | +└── CLAUDE.md - Claude Code instructions |
| 64 | +``` |
| 65 | + |
| 66 | +## Workflow Rules |
| 67 | + |
| 68 | +### Always Do |
| 69 | + |
| 70 | +- Create a feature branch for every change (`feature/issue-NNN-description`) |
| 71 | +- Use conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:` |
| 72 | +- Run build, test, and lint before opening a PR |
| 73 | +- Use the `?` operator for error propagation with meaningful context |
| 74 | +- Fix every error you find, regardless of who introduced it |
| 75 | +- Use `cargo fmt` to format code before committing |
| 76 | + |
| 77 | +### Ask First |
| 78 | + |
| 79 | +- Adding new dependencies (check if `std` covers the need) |
| 80 | +- Architectural changes (new modules, major trait changes) |
| 81 | +- Changes to CI/CD workflows |
| 82 | +- Removing or renaming public APIs or CLI flags |
| 83 | +- Changes to the config file schema |
| 84 | + |
| 85 | +### Never Do |
| 86 | + |
| 87 | +- Commit directly to `main` -- always use feature branches |
| 88 | +- Skip tests or lint checks -- even for "small changes" |
| 89 | +- Use `--no-verify` or `--force` flags |
| 90 | +- Commit secrets, credentials, or API keys |
| 91 | +- Add TODO comments without a linked issue number |
| 92 | +- Mark work as complete when build, test, or lint failures remain |
| 93 | + |
| 94 | +## Core Principles |
| 95 | + |
| 96 | +These are unconditional -- no optimization or time pressure overrides them: |
| 97 | + |
| 98 | +1. **Quality**: Once found, always fix, never leave. There is no "pre-existing" error. |
| 99 | +2. **Verification**: Build, test, and lint must pass before any commit. |
| 100 | +3. **Safety**: Never force-push `main`. Never skip hooks. Never commit secrets. |
| 101 | +4. **Honesty**: Never mark work as complete when it is not. |
| 102 | + |
| 103 | +## Error Handling |
| 104 | + |
| 105 | +```rust |
| 106 | +// Use the ? operator to propagate errors with context |
| 107 | +fn load_config(path: &Path) -> Result<Config, Box<dyn std::error::Error>> { |
| 108 | + let content = std::fs::read_to_string(path) |
| 109 | + .map_err(|e| format!("failed to read config at {}: {}", path.display(), e))?; |
| 110 | + let config: Config = toml::from_str(&content) |
| 111 | + .map_err(|e| format!("failed to parse config: {}", e))?; |
| 112 | + Ok(config) |
| 113 | +} |
| 114 | + |
| 115 | +// Use Option for values that may be absent (not sentinel values) |
| 116 | +fn find_column(&self, x: u16) -> Option<&RainColumn> { |
| 117 | + self.columns.iter().find(|c| c.x == x) |
| 118 | +} |
| 119 | +``` |
| 120 | + |
| 121 | +## Testing Conventions |
| 122 | + |
| 123 | +```rust |
| 124 | +#[cfg(test)] |
| 125 | +mod tests { |
| 126 | + use super::*; |
| 127 | + |
| 128 | + #[test] |
| 129 | + fn test_config_default_values() { |
| 130 | + let config = Config::default(); |
| 131 | + assert!(config.speed > 0.0); |
| 132 | + assert!(!config.color_scheme.is_empty()); |
| 133 | + } |
| 134 | + |
| 135 | + #[test] |
| 136 | + fn test_buffer_dimensions() { |
| 137 | + let buffer = Buffer::new(80, 24); |
| 138 | + assert_eq!(buffer.width(), 80); |
| 139 | + assert_eq!(buffer.height(), 24); |
| 140 | + } |
| 141 | +} |
| 142 | +``` |
| 143 | + |
| 144 | +## Commit Format |
| 145 | + |
| 146 | +```text |
| 147 | +feat: add configurable rain density |
| 148 | +
|
| 149 | +Adds --density CLI flag and config option to control drop spawn rate. |
| 150 | +
|
| 151 | +Closes #42 |
| 152 | +Co-Authored-By: GitHub Copilot <copilot@github.com> |
| 153 | +``` |
| 154 | + |
| 155 | +Types: `feat` (new feature), `fix` (bug fix), `refactor` (no behavior change), |
| 156 | +`docs` (documentation only), `test` (tests only), `chore` (build/tooling). |
0 commit comments