repopilot 0.1.0

Local-first codebase audit CLI with evidence-backed findings
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

# RepoPilot

[![CI](https://github.com/MykytaStel/repopilot/actions/workflows/ci.yaml/badge.svg)](https://github.com/MykytaStel/repopilot/actions/workflows/ci.yaml)

RepoPilot is a local-first CLI for auditing codebases.

The long-term goal is to scan projects, folders, or files and produce evidence-backed reports about architecture, code quality, tests, security, and performance.

## Features

- Gitignore-aware file walker
- File and directory counting with non-empty LOC measurement
- Language detection by file extension
- `TODO` / `FIXME` / `HACK` marker detection with per-line evidence
- Evidence-backed finding model (stable rule IDs, categories, severity, source snippets)
- Architecture, testing, and security audit rules with configurable thresholds
- `compare` command for diffing two JSON scan reports
- Console, JSON, Markdown, and HTML scan output formats
- `--output` flag to write reports to a file

See [docs/rulesets.md](docs/rulesets.md) for the full list of audit rules and severity levels.

## Installation

RepoPilot v0.1.0 is prepared for source installs, GitHub Release binaries, and crates.io publishing.
Until the first release is cut, install from source:

```bash
git clone https://github.com/MykytaStel/repopilot.git
cd repopilot
cargo build --release
# binary: ./target/release/repopilot
```

Or install directly with cargo:

```bash
cargo install --git https://github.com/MykytaStel/repopilot.git
```

See [docs/distribution.md](docs/distribution.md) for distribution channels. Homebrew support is planned after GitHub Release artifacts are available.

## Usage

```bash
cargo run -- scan .
cargo run -- scan . --format json
cargo run -- scan . --format markdown
cargo run -- scan . --format html --output report.html
cargo run -- --help
cargo run -- scan --help
```

Custom thresholds:

```bash
cargo run -- scan . --max-file-loc 500
cargo run -- scan . --max-directory-modules 25
cargo run -- scan . --max-directory-depth 6
```

Write report to file:

```bash
cargo run -- scan . --format markdown --output report.md
cargo run -- scan . --format json --output report.json
cargo run -- scan . --format html --output report.html
cargo run -- scan . --format console --output report.txt
```

Compare two JSON reports:

```bash
cargo run -- scan . --format json --output before.json
cargo run -- scan . --format json --output after.json
cargo run -- compare before.json after.json
cargo run -- compare before.json after.json --format markdown
cargo run -- compare before.json after.json --format json --output diff.json
```

## Findings

RepoPilot uses an evidence-first finding model. Every finding includes:

- Stable rule ID
- Title and description
- Category and severity
- Evidence (file path, line number, source snippet)

Current finding categories: `ARCHITECTURE`, `CODE_QUALITY`, `TESTING`, `SECURITY`, `PERFORMANCE`.

Current rules:

| Rule ID | Category | Severity |
|---|---|---|
| `code-marker.todo` | CODE_QUALITY | LOW |
| `code-marker.fixme` | CODE_QUALITY | MEDIUM |
| `code-marker.hack` | CODE_QUALITY | MEDIUM |
| `architecture.large-file` | ARCHITECTURE | MEDIUM / HIGH |
| `architecture.too-many-modules` | ARCHITECTURE | MEDIUM |
| `architecture.deep-nesting` | ARCHITECTURE | LOW |
| `testing.missing-test-folder` | TESTING | MEDIUM |
| `testing.source-without-test` | TESTING | LOW |
| `security.secret-candidate` | SECURITY | HIGH |
| `security.private-key-candidate` | SECURITY | CRITICAL |
| `security.env-file-committed` | SECURITY | HIGH |

The `architecture.large-file` rule uses a default threshold of 300 non-empty LOC. Override with `--max-file-loc`.
Directory architecture thresholds default to 20 files per directory and 5 directory levels below the scan root.

See [docs/rulesets.md](docs/rulesets.md) for full rule documentation.

## Documentation

| Document | Description |
|---|---|
| [docs/rulesets.md](docs/rulesets.md) | All audit rules, categories, and severity levels |
| [docs/release.md](docs/release.md) | How to cut a release |
| [docs/distribution.md](docs/distribution.md) | Distribution channels (current and planned) |
| [docs/github-ruleset.md](docs/github-ruleset.md) | GitHub branch ruleset configuration |
| [CHANGELOG.md](CHANGELOG.md) | Version history |

## Contributing

- Open a PR against `main`. All PRs require CI to pass and at least one review.
- Follow the [pull request template](.github/pull_request_template.md).
- Update `CHANGELOG.md` for any user-visible change.