whogitit 0.1.0

Track AI-generated code at line-level granularity
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

# annotations

Generate annotations for GitHub Checks API integration.

## Usage

```bash
whogitit annotations [OPTIONS]
```

## Description

The `annotations` command generates annotation data suitable for the GitHub Checks API. This is primarily used in CI/CD pipelines to display AI attribution information directly in the GitHub PR diff view.

Annotations appear as colored markers in the "Files changed" tab, showing which lines were AI-generated and the prompts used.

## Options

| Option | Description |
|--------|-------------|
| `--base <COMMIT>` | Base commit (exclusive). Defaults to first commit if not specified |
| `--head <COMMIT>` | Head commit (inclusive). Default: `HEAD` |
| `--format <FORMAT>` | Output format: `github-checks` (default) or `json` |
| `--consolidate <MODE>` | Consolidation mode: `auto` (default), `file`, or `lines` |
| `--consolidate-threshold <THRESHOLD>` | AI coverage threshold for auto mode (0.0-1.0). Default: `0.7` |
| `--min-lines <N>` | Minimum AI lines to create an annotation. Default: `1` |
| `--max-annotations <N>` | Maximum annotations to output. Default: `50` (GitHub API limit) |
| `--ai-only` | Only annotate pure AI lines (not AI-modified) |

## Consolidation Modes

### Auto (default)

Smart consolidation that chooses between file-level and line-level annotations based on AI coverage:

- **File-level annotation** when:
  - File is new (no original lines), OR
  - AI coverage >= threshold (default 70%) AND only one prompt used

- **Line-level annotations** otherwise

### File

Creates one annotation per file, summarizing all AI attribution.

```bash
whogitit annotations --consolidate file
```

### Lines

Creates granular line-level annotations, grouping consecutive AI lines from the same prompt.

```bash
whogitit annotations --consolidate lines
```

## Examples

### Basic usage (for GitHub Actions)

```bash
whogitit annotations --base ${{ github.event.pull_request.base.sha }} --head ${{ github.sha }}
```

### JSON output for debugging

```bash
whogitit annotations --format json
```

### File-level consolidation for cleaner diffs

```bash
whogitit annotations --consolidate file --base main
```

### Custom threshold

```bash
whogitit annotations --consolidate-threshold 0.5  # Consolidate at 50%+ AI coverage
```

## Output Format

### GitHub Checks Format

```json
[
  {
    "path": "src/main.rs",
    "start_line": 42,
    "end_line": 48,
    "annotation_level": "notice",
    "title": "AI Generated (7 lines)",
    "message": "Lines 42-48 generated by claude-opus-4-5-20251101",
    "raw_details": "Prompt: Add error handling with retry logic..."
  }
]
```

### JSON Format

Same structure but without GitHub-specific formatting constraints.

## GitHub Actions Integration

See the [CI/CD Integration](../../workflows/ci-cd.md) guide for complete GitHub Actions workflow examples.

```yaml
- name: Generate annotations
  run: |
    ANNOTATIONS=$(whogitit annotations --base ${{ github.event.pull_request.base.sha }})
    echo "$ANNOTATIONS" > annotations.json

- name: Create Check Run
  uses: actions/github-script@v7
  with:
    script: |
      const annotations = JSON.parse(fs.readFileSync('annotations.json'));
      // ... create check run with annotations
```

## See Also

- [summary](./summary.md) - PR summary in Markdown format
- [CI/CD Integration](../../workflows/ci-cd.md) - Full workflow examples