repopilot 0.10.0

Local-first CLI for repository audit, architecture risk detection, baseline tracking, and CI-friendly code review.
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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165

# Reports

RepoPilot can render scan results as console, JSON, Markdown, HTML, and SARIF.

Use JSON when another tool, CI job, script, or future RepoPilot command needs to
read scan output.

```bash
repopilot scan . --format json --output repopilot-report.json
```

## JSON report schema

Starting with RepoPilot 0.9, JSON scan reports include explicit schema metadata:

```json
{
  "schema_version": "0.9",
  "repopilot_version": "0.10.0",
  "root_path": ".",
  "files_count": 42,
  "directories_count": 12,
  "lines_of_code": 3200,
  "languages": [],
  "findings": []
}
```

### Top-level metadata

| Field | Type | Description |
|---|---|---|
| `schema_version` | string | RepoPilot JSON report schema version. |
| `repopilot_version` | string | RepoPilot binary version that produced the report. |

`schema_version` is intentionally separate from the binary version. Patch releases
may fix bugs without changing the report schema, while future minor releases can
evolve the schema in a documented way.

### Compatibility

RepoPilot 0.9 keeps the existing scan summary fields at the top level of the JSON
document. The schema metadata is additive:

- existing consumers can continue reading fields such as `findings`,
  `files_count`, and `lines_of_code`;
- `repopilot compare` continues to read older JSON reports that do not contain
  `schema_version`;
- future tools can branch on `schema_version` when parsing reports.

## Baseline JSON reports

When a scan is rendered with a baseline, the JSON report also includes the same
schema metadata:

```bash
repopilot scan . \
  --baseline .repopilot/baseline.json \
  --format json \
  --output repopilot-baseline-report.json
```

Example shape:

```json
{
  "schema_version": "0.9",
  "repopilot_version": "0.10.0",
  "root_path": ".",
  "files_count": 42,
  "baseline": {
    "path": ".repopilot/baseline.json",
    "new_findings": 2,
    "existing_findings": 10
  },
  "findings": []
}
```

## Audit receipt JSON

Use `--receipt` when a CI job, release process, or audit trail needs compact
evidence of what RepoPilot scanned without storing the full report:

```bash
repopilot scan . \
  --format markdown \
  --output repopilot-report.md \
  --receipt .repopilot/receipt.json
```

Receipt JSON is intentionally smaller than a scan report and has its own schema:

```json
{
  "schema_version": 1,
  "tool": "repopilot",
  "version": "0.10.0",
  "generated_at": "2026-05-16T00:00:00Z",
  "root_path": ".",
  "git": {
    "is_git_repo": true,
    "branch": "main",
    "commit": "abc123",
    "dirty": false
  },
  "scope": {
    "files_discovered": 42,
    "files_analyzed": 40,
    "directories_count": 12,
    "lines_of_code": 3200
  },
  "findings": {
    "total": 3,
    "critical": 0,
    "high": 1,
    "medium": 2,
    "low": 0,
    "info": 0
  },
  "languages": [],
  "health_score": 91
}
```

Receipts do not replace reports. Use reports for human review or downstream
finding details, and receipts for provenance, release evidence, and artifact
upload.

## Finding fields

Every finding includes stable fields documented in [rulesets.md](rulesets.md):

| Field | Type | Description |
|---|---|---|
| `id` | string | Stable finding ID derived from rule, path, and line. |
| `rule_id` | string | Stable rule identifier, for example `security.secret-candidate`. |
| `title` | string | Short human-readable summary. |
| `description` | string | Explanation of why the finding matters. |
| `recommendation` | string | Concrete remediation guidance. Older reports without this field still deserialize, but new reports include it. |
| `category` | string | Finding category. |
| `severity` | string | One of `INFO`, `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`. |
| `confidence` | string | One of `LOW`, `MEDIUM`, or `HIGH`; used to separate impact from certainty. |
| `docs_url` | string? | Optional documentation link for the rule. |
| `workspace_package` | string? | Optional monorepo package name. |
| `evidence` | array | One or more evidence locations. |

SARIF output carries the same category, recommendation, confidence, baseline
status, and workspace package metadata in result properties when available.

## Recommended usage

For local review:

```bash
repopilot scan . --format markdown --output repopilot-report.md
```

For scripts and comparisons:

```bash
repopilot scan . --format json --output before.json
repopilot scan . --format json --output after.json
repopilot compare before.json after.json --format markdown
```