repopilot 0.9.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

# 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.9.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.9.0",
  "root_path": ".",
  "files_count": 42,
  "baseline": {
    "path": ".repopilot/baseline.json",
    "new_findings": 2,
    "existing_findings": 10
  },
  "findings": []
}
```

## 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. |
| `category` | string | Finding category. |
| `severity` | string | One of `INFO`, `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`. |
| `docs_url` | string? | Optional documentation link for the rule. |
| `workspace_package` | string? | Optional monorepo package name. |
| `evidence` | array | One or more evidence locations. |

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