repopilot 0.7.0

# RepoPilot

[![Crates.io](https://img.shields.io/crates/v/repopilot.svg)](https://crates.io/crates/repopilot)
[![npm](https://img.shields.io/npm/v/repopilot.svg)](https://www.npmjs.com/package/repopilot)
[![Docs.rs](https://docs.rs/repopilot/badge.svg)](https://docs.rs/repopilot)
[![CI](https://github.com/MykytaStel/repopilot/actions/workflows/ci.yaml/badge.svg)](https://github.com/MykytaStel/repopilot/actions)
[![GitHub Release](https://img.shields.io/github/v/release/MykytaStel/repopilot)](https://github.com/MykytaStel/repopilot/releases)
[![License](https://img.shields.io/crates/l/repopilot.svg)](LICENSE)

Local-first CLI for repository audit, architecture risk detection, baseline tracking, and CI-friendly code review.

RepoPilot runs on your machine and 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 findings: oversized files, deep nesting, too many modules per directory
- Coupling analysis: excessive fan-out, high-instability hubs, circular dependencies
- Code quality findings: cyclomatic complexity density, long functions, TODO/FIXME/HACK markers
- Security findings: hardcoded secret candidates, committed private keys, committed `.env` files
- Testing findings: missing test folder, source files without test counterparts
- Framework findings for JavaScript, React, React Native, and Expo projects
- React Native architecture profile: project kind, New Architecture, Hermes, Codegen, platform mismatch, and package manager signals
- Workspace scanning (`--workspace`) for npm, yarn, pnpm, and Cargo workspaces with per-package risk summary
- Evidence-backed findings with stable rule IDs, severity, file paths, line numbers, and snippets
- 36 built-in rules with titles, descriptions, recommendations, and docs links
- `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, HTML, and SARIF (2.1.0) scan output — SARIF includes per-result category and workspace package properties
- First-party GitHub Action wrapper with optional SARIF upload
- Compare mode for diffing two JSON scan reports

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

## Installation

```bash
cargo install repopilot
```

Install with npm:

```bash
npm install -g repopilot
```

Upgrade:

```bash
cargo install repopilot --force
npm update -g repopilot
```

Build from source:

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

## Quick Start

```bash
repopilot init
repopilot scan .
```

React Native quick scan:

```bash
repopilot scan . --format markdown --output repopilot-report.md
repopilot review . --base origin/main --baseline .repopilot/baseline.json --fail-on new-high
```

Reduce scan noise while iterating:

```bash
repopilot scan . --min-severity high
repopilot scan . --workspace --min-severity medium
```

## AI-Assisted Workflow

RepoPilot is a local-first safety layer for AI-assisted and vibe-coded changes. Run it after generating or refactoring code to catch newly introduced high-risk findings, workspace hotspots, missing tests, and architecture drift without uploading source code to an external service.

```bash
repopilot review . --base origin/main --baseline .repopilot/baseline.json --fail-on new-high
repopilot scan . --workspace --min-severity medium --format markdown --output repopilot-report.md
```

The v0.7.0 release does not add new `vibe`, `harden`, or AI prompt commands. Those are planned as deterministic post-0.7 workflows built on the existing scan and review data.

## Commands

| Command | Alias | Description |
|---------|-------|-------------|
| `repopilot scan <path>` | `s` | Scan a project, folder, or file for findings |
| `repopilot review [path]` | `r` | Review findings that touch changed Git diff lines |
| `repopilot compare <before> <after>` | `cmp` | Compare two JSON scan reports and show what changed |
| `repopilot baseline create <path>` | `bl` | Scan a path and store current findings as accepted debt |
| `repopilot init` | — | Generate a default `repopilot.toml` configuration file |

Use `--help` on any command for the full description and examples:

```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"
]
max_file_bytes = 2097152

[architecture]
max_file_lines = 300
huge_file_lines = 1000
max_directory_modules = 20
max_directory_depth = 5
max_function_lines = 50
max_fan_out = 15
instability_hub_min_fan_in = 5
instability_hub_min_instability_pct = 75

[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 import coupling data is available, it also shows blast radius: files that import changed files and may need extra review. 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
repopilot scan . --format sarif --output repopilot.sarif
```

### SARIF output

```bash
repopilot scan . --format sarif --output repopilot.sarif
```

If your installed RepoPilot version does not support `--output`, redirect stdout instead:

```bash
repopilot scan . --format sarif > repopilot.sarif
```

Use JSON when custom scripts need to parse RepoPilot results. Use Markdown for human-readable reports. Use SARIF for CI and code scanning integrations, including GitHub Code Scanning.

See [docs/integrations/github-code-scanning.md](docs/integrations/github-code-scanning.md) for a copy-paste GitHub Actions workflow, required permissions, and local validation commands.

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.

To upload RepoPilot findings to GitHub Code Scanning, generate SARIF and use `github/codeql-action/upload-sarif`. The workflow must include `security-events: write`.

```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

      - name: Run RepoPilot (SARIF)
        run: repopilot scan . --format sarif --output repopilot.sarif

      - name: Upload to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: repopilot.sarif
```

## Roadmap

These are planned ideas, not current features:

- Vibe Check command for AI-assisted codebase readiness
- Hardening Plan output based on existing findings
- AI-agent prompt/context export
- Change Risk Map
- Better architecture drift detection
- Optional per-platform npm binary packages for faster installs

## Documentation

| Document | Description |
|---|---|
| [docs/cli.md](docs/cli.md) | Complete CLI reference — all commands, flags, and exit codes |
| [docs/commands.md](docs/commands.md) | Task-oriented command guide and common patterns |
| [docs/rulesets.md](docs/rulesets.md) | Implemented audit rules, categories, and severity levels |
| [docs/react-native.md](docs/react-native.md) | React Native and Expo detection, findings, and limitations |
| [docs/integrations/github-code-scanning.md](docs/integrations/github-code-scanning.md) | GitHub Code Scanning SARIF workflow |
| [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.