|
| 1 | +# AGENT.md — AI-Assisted Development Onboarding |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +**cora-cli** is a Rust CLI tool for AI-powered code review. Bring Your Own Keys (BYOK) — |
| 6 | +no managed API, no cloud service. Runs locally against diffs, scans, or branches. |
| 7 | + |
| 8 | +- **License:** MIT |
| 9 | +- **Edition:** Rust 2024 (MSRV 1.85) |
| 10 | +- **Repo:** `ajianaz/cora-cli` |
| 11 | +- **Default branch:** `develop` |
| 12 | + |
| 13 | +## Build & Development Commands |
| 14 | + |
| 15 | +```bash |
| 16 | +cargo build # Build (debug) |
| 17 | +cargo build --release # Build (release) |
| 18 | +cargo test # Run all 151 tests |
| 19 | +cargo clippy # Lint |
| 20 | +cargo fmt # Format check (use -- --check for CI) |
| 21 | +``` |
| 22 | + |
| 23 | +## Code Structure (`src/`) |
| 24 | + |
| 25 | +``` |
| 26 | +src/ |
| 27 | +├── main.rs # Entry point, CLI argument parsing |
| 28 | +├── commands/ # Subcommand handlers |
| 29 | +│ ├── mod.rs |
| 30 | +│ ├── review.rs # cora review (diff-based review) |
| 31 | +│ ├── scan.rs # cora scan (full-file scan) |
| 32 | +│ ├── config_cmd.rs # cora config (show/validate) |
| 33 | +│ ├── auth.rs # cora auth (API key management) |
| 34 | +│ ├── hook_cmd.rs # cora hook (pre-commit hook install/uninstall) |
| 35 | +│ ├── init.rs # cora init (project scaffolding) |
| 36 | +│ ├── upload.rs # cora upload (review upload) |
| 37 | +│ ├── completion.rs # Shell completion generation |
| 38 | +│ └── providers.rs # cora providers (list providers) |
| 39 | +├── config/ |
| 40 | +│ ├── mod.rs |
| 41 | +│ ├── schema.rs # Config structs & defaults |
| 42 | +│ ├── loader.rs # Config loading & priority chain |
| 43 | +│ └── providers.rs # LLM provider definitions |
| 44 | +├── engine/ |
| 45 | +│ ├── mod.rs |
| 46 | +│ ├── review.rs # Review orchestration logic |
| 47 | +│ ├── scanner.rs # File scanning engine |
| 48 | +│ ├── llm.rs # LLM API interaction |
| 49 | +│ └── types.rs # Severity, finding, and result types |
| 50 | +├── formatters/ # Output format implementations |
| 51 | +│ ├── mod.rs |
| 52 | +│ ├── pretty.rs # Human-readable terminal output |
| 53 | +│ ├── compact.rs # Compact single-line output |
| 54 | +│ ├── json_fmt.rs # JSON output |
| 55 | +│ └── sarif.rs # SARIF format (CI integration) |
| 56 | +├── git/ |
| 57 | +│ ├── mod.rs |
| 58 | +│ ├── diff.rs # Git diff parsing |
| 59 | +│ └── files.rs # File listing & filtering |
| 60 | +└── hook/ |
| 61 | + ├── mod.rs |
| 62 | + ├── install.rs # Hook install/uninstall logic |
| 63 | + └── template.rs # Hook script templates |
| 64 | +``` |
| 65 | + |
| 66 | +## Key Files |
| 67 | + |
| 68 | +| File | Purpose | |
| 69 | +|---|---| |
| 70 | +| `commands/config_cmd.rs` | Config subcommand — display, validate, path resolution | |
| 71 | +| `config/loader.rs` | Config loading with full priority chain resolution | |
| 72 | +| `config/schema.rs` | All config structs, defaults, serde annotations | |
| 73 | +| `commands/init.rs` | Project scaffolding, `.cora.yaml` generation | |
| 74 | + |
| 75 | +## Testing |
| 76 | + |
| 77 | +```bash |
| 78 | +cargo test # 151 tests total |
| 79 | + # 129 unit tests |
| 80 | + # 16 CLI integration tests |
| 81 | + # 6 config tests |
| 82 | +cargo test --no-verify # Skip pre-commit hooks (avoids timeout in hooks) |
| 83 | +``` |
| 84 | + |
| 85 | +Use `--no-verify` when running tests through pre-commit hooks to prevent nested |
| 86 | +hook execution and timeouts. |
| 87 | + |
| 88 | +## CI/CD |
| 89 | + |
| 90 | +Three GitHub Actions workflows in `.github/workflows/`: |
| 91 | + |
| 92 | +1. **ci.yml** — PR checks: build, test, clippy, fmt on push to `develop` and PRs |
| 93 | +2. **release.yml** — Triggered by `v*` tags; builds for 4 platforms (Linux x86_64, |
| 94 | + macOS x86_64, macOS ARM64, Windows x86_64), publishes to crates.io |
| 95 | +3. **deploy-website.yml** — Deploys project website/docs |
| 96 | + |
| 97 | +## Config System |
| 98 | + |
| 99 | +### Priority Chain (highest to lowest) |
| 100 | + |
| 101 | +1. **CLI flags** (`--provider`, `--model`, etc.) |
| 102 | +2. **Environment variables** (`CORA_PROVIDER`, `CORA_MODEL`, etc.) |
| 103 | +3. **Project config** (`.cora.yaml` in repo root) |
| 104 | +4. **Global config** (`~/.cora/config.yaml`) |
| 105 | +5. **Built-in defaults** (defined in `config/schema.rs`) |
| 106 | + |
| 107 | +### Auth Separation |
| 108 | + |
| 109 | +API keys live in a separate `auth.toml` file (`~/.cora/auth.toml`), not in |
| 110 | +`.cora.yaml`. This prevents accidental key leakage via committed config files. |
| 111 | + |
| 112 | +## Design Decisions |
| 113 | + |
| 114 | +- **Severity comparison uses `<=` not `>=`**: Severity filtering uses `<=` because |
| 115 | + the ordinal maps info=1, warning=2, error=3 — so `--severity warning` means |
| 116 | + "include warning and below (info)", not "warning and above (error)". This is |
| 117 | + intentional; the mapping is defined in `engine/types.rs`. |
| 118 | +- **TOML → YAML migration**: Config format migrated from TOML to YAML for better |
| 119 | + readability and broader tooling support. The loader only reads YAML now. |
| 120 | +- **Auth/config separation**: API keys are deliberately stored in `auth.toml` |
| 121 | + rather than the main config to allow `.cora.yaml` to be safely committed to |
| 122 | + repositories without exposing secrets. |
0 commit comments