# RepoPilot
[](https://crates.io/crates/repopilot)
[](https://docs.rs/repopilot)
[](https://github.com/MykytaStel/repopilot/actions)
[](LICENSE)
Local-first CLI for repository audit, architecture risk detection, baseline tracking, and CI-friendly code review.
RepoPilot does not upload your repository. It helps developers understand what changed, what became riskier, and where to review first.
## Why RepoPilot?
Modern developers ship more code than they can carefully review, especially with AI-assisted workflows.
RepoPilot helps you understand:
- what changed;
- what became riskier;
- which findings are new;
- which findings already existed;
- where to review first.
RepoPilot runs locally and does not upload your repository.
## Features
- Repository scanning for projects, folders, and individual files
- Gitignore-aware walking with built-in ignores for common build and service directories
- Architecture, testing, code-quality, and security-oriented findings
- Evidence-backed findings with stable rule IDs, severity, file paths, line numbers, and snippets
- `repopilot.toml` configuration generated by `repopilot init`
- Baseline workflow for accepting existing findings in legacy repositories
- CI-friendly failure thresholds with `--fail-on`
- Git diff-aware review mode for prioritizing findings introduced by changed lines
- Console, JSON, Markdown, and HTML scan output
- Compare mode for diffing two JSON scan reports
See [docs/rulesets.md](docs/rulesets.md) for the implemented rules and severity levels.
## Installation
```bash
cargo install repopilot
```
Upgrade:
```bash
cargo install repopilot --force
```
Build from source:
```bash
git clone https://github.com/MykytaStel/repopilot.git
cd repopilot
cargo build --release
```
## Quick Start
```bash
repopilot init
repopilot scan .
```
Useful help commands:
```bash
repopilot --help
repopilot scan --help
repopilot review --help
repopilot baseline create --help
```
## Configuration
RepoPilot automatically reads `repopilot.toml` from the current working directory when running `scan`.
Configuration precedence:
```text
CLI args > repopilot.toml > built-in defaults
```
Generate a default config:
```bash
repopilot init
repopilot init --force
repopilot init --path ./repopilot.toml
```
Use an explicit config path:
```bash
repopilot scan . --config repopilot.toml
```
Example `repopilot.toml`:
```toml
[scan]
ignore = [
".git",
".github",
".repopilot",
"target",
"node_modules",
"dist",
"build",
".next",
"coverage"
]
[architecture]
max_file_lines = 300
huge_file_lines = 1000
max_directory_modules = 20
max_directory_depth = 5
detect_empty_directories = true
detect_suspicious_names = true
detect_large_files = true
[testing]
detect_missing_tests = true
[security]
detect_secret_like_names = true
[output]
default_format = "console"
```
CLI threshold overrides:
```bash
repopilot scan . --max-file-loc 500
repopilot scan . --max-directory-modules 25
repopilot scan . --max-directory-depth 6
```
## Baseline Workflow
Existing repositories often have findings that cannot all be fixed before adopting a new audit tool. A baseline stores accepted existing findings so future scans can distinguish new findings from existing ones.
```bash
repopilot baseline create .
repopilot scan . --baseline .repopilot/baseline.json
repopilot scan . --baseline .repopilot/baseline.json --fail-on new-high
```
By default, `baseline create` writes `.repopilot/baseline.json` and creates the `.repopilot/` directory if needed. Use `--output ./baseline.json` for a custom path. Existing baseline files are not overwritten unless you pass `--force`.
Baseline files store accepted existing findings. Future scans can mark findings as `new` or `existing`, which is useful for legacy repositories and CI. Do not refresh a baseline blindly unless the team accepts those findings as technical debt.
## Review Workflow
Use `review` when you want RepoPilot to focus on findings that touch changed Git diff lines.
```bash
repopilot review .
repopilot review . --format json --output review.json
repopilot review . --baseline .repopilot/baseline.json --fail-on new-high
```
By default, `review` compares the working tree against `HEAD`, including staged, unstaged, and untracked files. For branch or CI review, pass a base ref:
```bash
repopilot review . --base origin/main
repopilot review . --base origin/main --head HEAD --format markdown
```
Review mode still scans the repository with the normal rules, but separates findings into in-diff and out-of-diff groups. When `--fail-on` is used, the CI gate evaluates only in-diff findings.
## Output Formats
```bash
repopilot scan . --format console
repopilot scan . --format json --output report.json
repopilot scan . --format markdown --output report.md
repopilot scan . --format html --output report.html
```
Compare two JSON reports:
```bash
repopilot scan . --format json --output before.json
repopilot scan . --format json --output after.json
repopilot compare before.json after.json
repopilot compare before.json after.json --format markdown
repopilot compare before.json after.json --format json --output diff.json
```
## CI Usage
Use `--fail-on new-high` to fail CI only when new high or critical findings are introduced. Supported new-finding thresholds are `new-low`, `new-medium`, `new-high`, and `new-critical`.
When `--fail-on new-*` is used without `--baseline`, RepoPilot treats all current findings as new. For baseline-based adoption, commit an accepted baseline and scan against it in CI.
```yaml
name: RepoPilot
on:
pull_request:
jobs:
repopilot:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Rust
uses: dtolnay/rust-toolchain@stable
- name: Install RepoPilot
run: cargo install repopilot
- name: Run RepoPilot
run: repopilot scan . --baseline .repopilot/baseline.json --fail-on new-high
```
## Roadmap
These are planned ideas, not current features:
- Change Risk Map
- AI-ready review context export
- Better architecture drift detection
- GitHub Action integration
## Documentation
| [docs/rulesets.md](docs/rulesets.md) | Implemented audit rules, categories, and severity levels |
| [docs/release.md](docs/release.md) | Manual release process |
| [docs/distribution.md](docs/distribution.md) | Distribution channels |
| [docs/github-ruleset.md](docs/github-ruleset.md) | GitHub branch ruleset configuration |
| [CHANGELOG.md](CHANGELOG.md) | Version history |
## License
RepoPilot is licensed under MIT OR Apache-2.0.