commit-roaster 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- commit_roaster-0.1.0/LICENSE +21 -0
- commit_roaster-0.1.0/PKG-INFO +238 -0
- commit_roaster-0.1.0/README.md +207 -0
- commit_roaster-0.1.0/pyproject.toml +101 -0
- commit_roaster-0.1.0/setup.cfg +4 -0
- commit_roaster-0.1.0/src/commit_roaster/__init__.py +10 -0
- commit_roaster-0.1.0/src/commit_roaster/__main__.py +5 -0
- commit_roaster-0.1.0/src/commit_roaster/cli.py +240 -0
- commit_roaster-0.1.0/src/commit_roaster/config.py +110 -0
- commit_roaster-0.1.0/src/commit_roaster/diff.py +221 -0
- commit_roaster-0.1.0/src/commit_roaster/exceptions.py +62 -0
- commit_roaster-0.1.0/src/commit_roaster/git.py +96 -0
- commit_roaster-0.1.0/src/commit_roaster/models.py +74 -0
- commit_roaster-0.1.0/src/commit_roaster/prompts.py +54 -0
- commit_roaster-0.1.0/src/commit_roaster/py.typed +0 -0
- commit_roaster-0.1.0/src/commit_roaster/render.py +90 -0
- commit_roaster-0.1.0/src/commit_roaster/roaster.py +106 -0
- commit_roaster-0.1.0/src/commit_roaster.egg-info/PKG-INFO +238 -0
- commit_roaster-0.1.0/src/commit_roaster.egg-info/SOURCES.txt +28 -0
- commit_roaster-0.1.0/src/commit_roaster.egg-info/dependency_links.txt +1 -0
- commit_roaster-0.1.0/src/commit_roaster.egg-info/entry_points.txt +2 -0
- commit_roaster-0.1.0/src/commit_roaster.egg-info/requires.txt +9 -0
- commit_roaster-0.1.0/src/commit_roaster.egg-info/top_level.txt +1 -0
- commit_roaster-0.1.0/tests/test_cli.py +202 -0
- commit_roaster-0.1.0/tests/test_config.py +57 -0
- commit_roaster-0.1.0/tests/test_diff.py +152 -0
- commit_roaster-0.1.0/tests/test_git.py +98 -0
- commit_roaster-0.1.0/tests/test_prompts_and_models.py +71 -0
- commit_roaster-0.1.0/tests/test_render.py +48 -0
- commit_roaster-0.1.0/tests/test_roaster.py +138 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 dileeppdkr
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: commit-roaster
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A grumpy senior dev in your terminal: roasts your git diff, then writes the commit message.
|
|
5
|
+
Author: dileeppdkr
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/dileeppdkr/commit-roaster
|
|
8
|
+
Project-URL: Issues, https://github.com/dileeppdkr/commit-roaster/issues
|
|
9
|
+
Keywords: git,commit,cli,claude,llm
|
|
10
|
+
Classifier: Environment :: Console
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Operating System :: OS Independent
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
17
|
+
Classifier: Topic :: Software Development :: Version Control :: Git
|
|
18
|
+
Classifier: Typing :: Typed
|
|
19
|
+
Requires-Python: >=3.12
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Requires-Dist: anthropic<3,>=2.9
|
|
23
|
+
Requires-Dist: pydantic<3,>=2.7
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: mypy>=1.11; extra == "dev"
|
|
26
|
+
Requires-Dist: pre-commit>=3.7; extra == "dev"
|
|
27
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
28
|
+
Requires-Dist: pytest-cov>=5.0; extra == "dev"
|
|
29
|
+
Requires-Dist: ruff==0.17.5; extra == "dev"
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
|
|
32
|
+
# commit-roaster
|
|
33
|
+
|
|
34
|
+
A grumpy senior dev in your terminal. `roast` reads your git diff, roasts it, lists the
|
|
35
|
+
real problems it spots, and writes the commit message you should have written.
|
|
36
|
+
|
|
37
|
+
```text
|
|
38
|
+
$ git add app.py
|
|
39
|
+
$ roast
|
|
40
|
+
The roast (cringe score: 6/10)
|
|
41
|
+
A print statement labelled DEBUG, sitting in the middle of add(). Bold move,
|
|
42
|
+
shipping your diary to production. The function adds two numbers; it does not
|
|
43
|
+
need a narrator.
|
|
44
|
+
|
|
45
|
+
Issues spotted
|
|
46
|
+
- Leftover debug print in add() will spam stdout on every call.
|
|
47
|
+
|
|
48
|
+
Suggested commit message
|
|
49
|
+
Add debug output to add()
|
|
50
|
+
|
|
51
|
+
Prints both operands before summing them, to trace a wrong total.
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
The roast is always about the code, never the person.
|
|
55
|
+
|
|
56
|
+
## Install
|
|
57
|
+
|
|
58
|
+
Needs Python 3.12+ and git. Install it once, as a command-line tool, and `roast` works in
|
|
59
|
+
every git repository on your machine:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
pipx install commit-roaster # or: uv tool install commit-roaster
|
|
63
|
+
|
|
64
|
+
# Before the first PyPI release, install straight from GitHub:
|
|
65
|
+
pipx install git+https://github.com/dileeppdkr/commit-roaster.git
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Then set your Anthropic API key (get one at https://platform.claude.com/settings/keys),
|
|
69
|
+
for example in your shell profile:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
export ANTHROPIC_API_KEY=sk-ant-...
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Use it in your project
|
|
76
|
+
|
|
77
|
+
Run `roast` in any repository after `git add`. To get roasted on every commit, add it as a
|
|
78
|
+
[pre-commit](https://pre-commit.com) hook. In your project's `.pre-commit-config.yaml`:
|
|
79
|
+
|
|
80
|
+
```yaml
|
|
81
|
+
repos:
|
|
82
|
+
- repo: https://github.com/dileeppdkr/commit-roaster
|
|
83
|
+
rev: v0.1.0
|
|
84
|
+
hooks:
|
|
85
|
+
- id: roast
|
|
86
|
+
# Optional: these replace the default args, so keep --exit-zero.
|
|
87
|
+
# args: [--exit-zero, --spice, savage, --model, claude-sonnet-5-5]
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Then run `pre-commit install`. Each `git commit` now prints the roast before the commit is
|
|
91
|
+
made. Everyone who commits needs `ANTHROPIC_API_KEY` set. Without it, they see an error
|
|
92
|
+
and the commit still goes through, because the hook passes `--exit-zero`. Every commit
|
|
93
|
+
makes one API call, so skip a run with `SKIP=roast git commit ...`.
|
|
94
|
+
|
|
95
|
+
## Usage
|
|
96
|
+
|
|
97
|
+
| Command | What it does |
|
|
98
|
+
|---|---|
|
|
99
|
+
| `roast` | Roast your staged changes (what the next commit will contain) |
|
|
100
|
+
| `roast --spice mild` / `savage` | Turn the heat down or up (default `medium`) |
|
|
101
|
+
| `roast --range HEAD~3..HEAD` | Roast any revision or range git understands |
|
|
102
|
+
| `git show abc123 \| roast --stdin` | Roast any diff you can pipe in |
|
|
103
|
+
| `roast --commit` | Roast, then commit with the suggested message (asks first) |
|
|
104
|
+
| `roast --commit --yes` | Same, without asking |
|
|
105
|
+
| `roast --json` | Machine-readable output for scripts |
|
|
106
|
+
| `roast --exit-zero` | Report errors but always exit 0 (for git hooks) |
|
|
107
|
+
| `roast -v` / `-vv` | Show request ID and token usage / full debug logs |
|
|
108
|
+
|
|
109
|
+
Run `roast --help` for every flag.
|
|
110
|
+
|
|
111
|
+
### Configuration
|
|
112
|
+
|
|
113
|
+
CLI flags win over environment variables, which win over defaults.
|
|
114
|
+
|
|
115
|
+
| Env var | Flag | Default | Meaning |
|
|
116
|
+
|---|---|---|---|
|
|
117
|
+
| `ANTHROPIC_API_KEY` | | (required) | Your API key |
|
|
118
|
+
| `ROAST_MODEL` | `--model` | `claude-haiku-5-5` | Claude model ID |
|
|
119
|
+
| `ROAST_EFFORT` | `--effort` | `low` | Thinking effort: `low` `medium` `high` `xhigh` `max` |
|
|
120
|
+
| `ROAST_MAX_DIFF_CHARS` | `--max-diff-chars` | `60000` | Larger diffs are cut, with a warning |
|
|
121
|
+
| `NO_COLOR` | | unset | Set it to turn off colors |
|
|
122
|
+
|
|
123
|
+
Lock files and minified assets (`*.lock`, `package-lock.json`, `*.min.js`, ...) are left
|
|
124
|
+
out of the diff, so you don't pay to send noise.
|
|
125
|
+
|
|
126
|
+
### Exit codes
|
|
127
|
+
|
|
128
|
+
| Code | Meaning |
|
|
129
|
+
|---|---|
|
|
130
|
+
| 0 | Success |
|
|
131
|
+
| 1 | Runtime error (API or git failure) |
|
|
132
|
+
| 2 | Usage or configuration error (bad flag, missing key, not a git repo) |
|
|
133
|
+
| 3 | Nothing to roast (empty diff) |
|
|
134
|
+
| 130 | Interrupted with Ctrl+C |
|
|
135
|
+
|
|
136
|
+
### Cost
|
|
137
|
+
|
|
138
|
+
Each run makes one API call. Cost grows with diff size. On the default `claude-haiku-5-5`
|
|
139
|
+
at `low` effort, even a maximum-size diff costs well under a cent. For sharper roasts, try
|
|
140
|
+
`--model claude-sonnet-5-5` or `claude-opus-5-5` (roughly 20 to 40 times the price).
|
|
141
|
+
|
|
142
|
+
## How it works
|
|
143
|
+
|
|
144
|
+
The code is small and object-oriented. Each class has one job and gets its collaborators
|
|
145
|
+
passed in, so every part can be tested on its own.
|
|
146
|
+
|
|
147
|
+
```text
|
|
148
|
+
cli.CommitRoasterCLI parses flags, wires everything up, maps errors to exit codes
|
|
149
|
+
├─ config.Settings immutable settings: defaults → env vars → flags
|
|
150
|
+
├─ diff.DiffSource (ABC) where the diff comes from (template method)
|
|
151
|
+
│ ├─ StagedDiffSource
|
|
152
|
+
│ ├─ RevisionRangeDiffSource
|
|
153
|
+
│ └─ StdinDiffSource
|
|
154
|
+
│ └─ git.GitClient runs git with argument lists, never a shell
|
|
155
|
+
├─ roaster.Roaster the only class that calls the Claude API
|
|
156
|
+
│ └─ prompts.PromptBuilder
|
|
157
|
+
├─ models.RoastResult Pydantic model; Claude must return exactly this shape
|
|
158
|
+
└─ render.Renderer (ABC) TextRenderer | JsonRenderer
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
A few decisions worth knowing:
|
|
162
|
+
|
|
163
|
+
- **Structured output.** `Roaster` asks Claude for JSON that matches `RoastResult`, and the
|
|
164
|
+
SDK validates it. No regex parsing of free text.
|
|
165
|
+
- **Refusal fallback.** Requests opt in to the API's server-side fallback
|
|
166
|
+
(`fallbacks="default"`). If the model's safety classifier declines a diff, the API retries
|
|
167
|
+
it on a fallback model in the same call. If every model declines, you get a clear error.
|
|
168
|
+
Haiku models have no fallback, so a declined diff gives the error right away.
|
|
169
|
+
- **Prompt injection.** The diff is wrapped in `<diff>` tags and the system prompt tells
|
|
170
|
+
Claude to treat anything inside as code to review, not as instructions.
|
|
171
|
+
- **No silent truncation.** Oversized diffs are cut at a line boundary, you get a warning,
|
|
172
|
+
and Claude is told that it only saw part of the change.
|
|
173
|
+
- **Expected errors vs bugs.** Expected failures raise a `CommitRoasterError` subclass and
|
|
174
|
+
become a one-line message plus an exit code. Anything else shows a full traceback,
|
|
175
|
+
because it's a bug.
|
|
176
|
+
|
|
177
|
+
## Development
|
|
178
|
+
|
|
179
|
+
```bash
|
|
180
|
+
git clone https://github.com/dileeppdkr/commit-roaster.git
|
|
181
|
+
cd commit-roaster
|
|
182
|
+
make install # creates .venv, installs the package and dev tools, sets up pre-commit
|
|
183
|
+
source .venv/bin/activate
|
|
184
|
+
|
|
185
|
+
make check # lint + type check + tests: the same steps CI runs
|
|
186
|
+
make format # auto-fix and format
|
|
187
|
+
make test # pytest with coverage (fails under 90%)
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
- Lint and format: [ruff](https://docs.astral.sh/ruff/)
|
|
191
|
+
- Types: mypy in `--strict` mode
|
|
192
|
+
- Tests: pytest. Tests never call the real API: the Claude client and git are swapped for
|
|
193
|
+
fakes in `tests/fakes.py`. The git tests also run against throwaway repos in a temp dir.
|
|
194
|
+
- CI: GitHub Actions on Python 3.12, 3.13 and 3.14 (`.github/workflows/ci.yml`)
|
|
195
|
+
- Pre-commit hooks run ruff and mypy before each commit (`make install` sets them up)
|
|
196
|
+
|
|
197
|
+
```text
|
|
198
|
+
src/commit_roaster/
|
|
199
|
+
cli.py entry point and wiring
|
|
200
|
+
config.py Settings
|
|
201
|
+
diff.py DiffSource classes
|
|
202
|
+
git.py GitClient
|
|
203
|
+
models.py SpiceLevel, RoastResult
|
|
204
|
+
prompts.py PromptBuilder
|
|
205
|
+
roaster.py Roaster (Claude API)
|
|
206
|
+
render.py TextRenderer, JsonRenderer
|
|
207
|
+
exceptions.py error types and exit codes
|
|
208
|
+
tests/ one test module per source module
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
### Releasing
|
|
212
|
+
|
|
213
|
+
Pushing a version tag publishes the package to PyPI through
|
|
214
|
+
`.github/workflows/release.yml`. It uses PyPI trusted publishing, so no token is stored in
|
|
215
|
+
GitHub.
|
|
216
|
+
|
|
217
|
+
One-time setup:
|
|
218
|
+
|
|
219
|
+
1. Create an account on [pypi.org](https://pypi.org).
|
|
220
|
+
2. Under *Your projects → Publishing*, add a pending trusted publisher: project
|
|
221
|
+
`commit-roaster`, owner `dileeppdkr`, repository `commit-roaster`, workflow
|
|
222
|
+
`release.yml`, environment `pypi`.
|
|
223
|
+
3. In the GitHub repo, go to *Settings → Environments* and create an environment named
|
|
224
|
+
`pypi`.
|
|
225
|
+
|
|
226
|
+
For each release, bump `version` in `pyproject.toml`, commit, then:
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
git tag v0.1.0
|
|
230
|
+
git push origin main v0.1.0
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
The workflow refuses to publish if the tag does not match the version. The same tag is
|
|
234
|
+
what pre-commit users put in `rev:`.
|
|
235
|
+
|
|
236
|
+
## License
|
|
237
|
+
|
|
238
|
+
MIT
|
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
# commit-roaster
|
|
2
|
+
|
|
3
|
+
A grumpy senior dev in your terminal. `roast` reads your git diff, roasts it, lists the
|
|
4
|
+
real problems it spots, and writes the commit message you should have written.
|
|
5
|
+
|
|
6
|
+
```text
|
|
7
|
+
$ git add app.py
|
|
8
|
+
$ roast
|
|
9
|
+
The roast (cringe score: 6/10)
|
|
10
|
+
A print statement labelled DEBUG, sitting in the middle of add(). Bold move,
|
|
11
|
+
shipping your diary to production. The function adds two numbers; it does not
|
|
12
|
+
need a narrator.
|
|
13
|
+
|
|
14
|
+
Issues spotted
|
|
15
|
+
- Leftover debug print in add() will spam stdout on every call.
|
|
16
|
+
|
|
17
|
+
Suggested commit message
|
|
18
|
+
Add debug output to add()
|
|
19
|
+
|
|
20
|
+
Prints both operands before summing them, to trace a wrong total.
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The roast is always about the code, never the person.
|
|
24
|
+
|
|
25
|
+
## Install
|
|
26
|
+
|
|
27
|
+
Needs Python 3.12+ and git. Install it once, as a command-line tool, and `roast` works in
|
|
28
|
+
every git repository on your machine:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
pipx install commit-roaster # or: uv tool install commit-roaster
|
|
32
|
+
|
|
33
|
+
# Before the first PyPI release, install straight from GitHub:
|
|
34
|
+
pipx install git+https://github.com/dileeppdkr/commit-roaster.git
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Then set your Anthropic API key (get one at https://platform.claude.com/settings/keys),
|
|
38
|
+
for example in your shell profile:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
export ANTHROPIC_API_KEY=sk-ant-...
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Use it in your project
|
|
45
|
+
|
|
46
|
+
Run `roast` in any repository after `git add`. To get roasted on every commit, add it as a
|
|
47
|
+
[pre-commit](https://pre-commit.com) hook. In your project's `.pre-commit-config.yaml`:
|
|
48
|
+
|
|
49
|
+
```yaml
|
|
50
|
+
repos:
|
|
51
|
+
- repo: https://github.com/dileeppdkr/commit-roaster
|
|
52
|
+
rev: v0.1.0
|
|
53
|
+
hooks:
|
|
54
|
+
- id: roast
|
|
55
|
+
# Optional: these replace the default args, so keep --exit-zero.
|
|
56
|
+
# args: [--exit-zero, --spice, savage, --model, claude-sonnet-5-5]
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Then run `pre-commit install`. Each `git commit` now prints the roast before the commit is
|
|
60
|
+
made. Everyone who commits needs `ANTHROPIC_API_KEY` set. Without it, they see an error
|
|
61
|
+
and the commit still goes through, because the hook passes `--exit-zero`. Every commit
|
|
62
|
+
makes one API call, so skip a run with `SKIP=roast git commit ...`.
|
|
63
|
+
|
|
64
|
+
## Usage
|
|
65
|
+
|
|
66
|
+
| Command | What it does |
|
|
67
|
+
|---|---|
|
|
68
|
+
| `roast` | Roast your staged changes (what the next commit will contain) |
|
|
69
|
+
| `roast --spice mild` / `savage` | Turn the heat down or up (default `medium`) |
|
|
70
|
+
| `roast --range HEAD~3..HEAD` | Roast any revision or range git understands |
|
|
71
|
+
| `git show abc123 \| roast --stdin` | Roast any diff you can pipe in |
|
|
72
|
+
| `roast --commit` | Roast, then commit with the suggested message (asks first) |
|
|
73
|
+
| `roast --commit --yes` | Same, without asking |
|
|
74
|
+
| `roast --json` | Machine-readable output for scripts |
|
|
75
|
+
| `roast --exit-zero` | Report errors but always exit 0 (for git hooks) |
|
|
76
|
+
| `roast -v` / `-vv` | Show request ID and token usage / full debug logs |
|
|
77
|
+
|
|
78
|
+
Run `roast --help` for every flag.
|
|
79
|
+
|
|
80
|
+
### Configuration
|
|
81
|
+
|
|
82
|
+
CLI flags win over environment variables, which win over defaults.
|
|
83
|
+
|
|
84
|
+
| Env var | Flag | Default | Meaning |
|
|
85
|
+
|---|---|---|---|
|
|
86
|
+
| `ANTHROPIC_API_KEY` | | (required) | Your API key |
|
|
87
|
+
| `ROAST_MODEL` | `--model` | `claude-haiku-5-5` | Claude model ID |
|
|
88
|
+
| `ROAST_EFFORT` | `--effort` | `low` | Thinking effort: `low` `medium` `high` `xhigh` `max` |
|
|
89
|
+
| `ROAST_MAX_DIFF_CHARS` | `--max-diff-chars` | `60000` | Larger diffs are cut, with a warning |
|
|
90
|
+
| `NO_COLOR` | | unset | Set it to turn off colors |
|
|
91
|
+
|
|
92
|
+
Lock files and minified assets (`*.lock`, `package-lock.json`, `*.min.js`, ...) are left
|
|
93
|
+
out of the diff, so you don't pay to send noise.
|
|
94
|
+
|
|
95
|
+
### Exit codes
|
|
96
|
+
|
|
97
|
+
| Code | Meaning |
|
|
98
|
+
|---|---|
|
|
99
|
+
| 0 | Success |
|
|
100
|
+
| 1 | Runtime error (API or git failure) |
|
|
101
|
+
| 2 | Usage or configuration error (bad flag, missing key, not a git repo) |
|
|
102
|
+
| 3 | Nothing to roast (empty diff) |
|
|
103
|
+
| 130 | Interrupted with Ctrl+C |
|
|
104
|
+
|
|
105
|
+
### Cost
|
|
106
|
+
|
|
107
|
+
Each run makes one API call. Cost grows with diff size. On the default `claude-haiku-5-5`
|
|
108
|
+
at `low` effort, even a maximum-size diff costs well under a cent. For sharper roasts, try
|
|
109
|
+
`--model claude-sonnet-5-5` or `claude-opus-5-5` (roughly 20 to 40 times the price).
|
|
110
|
+
|
|
111
|
+
## How it works
|
|
112
|
+
|
|
113
|
+
The code is small and object-oriented. Each class has one job and gets its collaborators
|
|
114
|
+
passed in, so every part can be tested on its own.
|
|
115
|
+
|
|
116
|
+
```text
|
|
117
|
+
cli.CommitRoasterCLI parses flags, wires everything up, maps errors to exit codes
|
|
118
|
+
├─ config.Settings immutable settings: defaults → env vars → flags
|
|
119
|
+
├─ diff.DiffSource (ABC) where the diff comes from (template method)
|
|
120
|
+
│ ├─ StagedDiffSource
|
|
121
|
+
│ ├─ RevisionRangeDiffSource
|
|
122
|
+
│ └─ StdinDiffSource
|
|
123
|
+
│ └─ git.GitClient runs git with argument lists, never a shell
|
|
124
|
+
├─ roaster.Roaster the only class that calls the Claude API
|
|
125
|
+
│ └─ prompts.PromptBuilder
|
|
126
|
+
├─ models.RoastResult Pydantic model; Claude must return exactly this shape
|
|
127
|
+
└─ render.Renderer (ABC) TextRenderer | JsonRenderer
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
A few decisions worth knowing:
|
|
131
|
+
|
|
132
|
+
- **Structured output.** `Roaster` asks Claude for JSON that matches `RoastResult`, and the
|
|
133
|
+
SDK validates it. No regex parsing of free text.
|
|
134
|
+
- **Refusal fallback.** Requests opt in to the API's server-side fallback
|
|
135
|
+
(`fallbacks="default"`). If the model's safety classifier declines a diff, the API retries
|
|
136
|
+
it on a fallback model in the same call. If every model declines, you get a clear error.
|
|
137
|
+
Haiku models have no fallback, so a declined diff gives the error right away.
|
|
138
|
+
- **Prompt injection.** The diff is wrapped in `<diff>` tags and the system prompt tells
|
|
139
|
+
Claude to treat anything inside as code to review, not as instructions.
|
|
140
|
+
- **No silent truncation.** Oversized diffs are cut at a line boundary, you get a warning,
|
|
141
|
+
and Claude is told that it only saw part of the change.
|
|
142
|
+
- **Expected errors vs bugs.** Expected failures raise a `CommitRoasterError` subclass and
|
|
143
|
+
become a one-line message plus an exit code. Anything else shows a full traceback,
|
|
144
|
+
because it's a bug.
|
|
145
|
+
|
|
146
|
+
## Development
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
git clone https://github.com/dileeppdkr/commit-roaster.git
|
|
150
|
+
cd commit-roaster
|
|
151
|
+
make install # creates .venv, installs the package and dev tools, sets up pre-commit
|
|
152
|
+
source .venv/bin/activate
|
|
153
|
+
|
|
154
|
+
make check # lint + type check + tests: the same steps CI runs
|
|
155
|
+
make format # auto-fix and format
|
|
156
|
+
make test # pytest with coverage (fails under 90%)
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
- Lint and format: [ruff](https://docs.astral.sh/ruff/)
|
|
160
|
+
- Types: mypy in `--strict` mode
|
|
161
|
+
- Tests: pytest. Tests never call the real API: the Claude client and git are swapped for
|
|
162
|
+
fakes in `tests/fakes.py`. The git tests also run against throwaway repos in a temp dir.
|
|
163
|
+
- CI: GitHub Actions on Python 3.12, 3.13 and 3.14 (`.github/workflows/ci.yml`)
|
|
164
|
+
- Pre-commit hooks run ruff and mypy before each commit (`make install` sets them up)
|
|
165
|
+
|
|
166
|
+
```text
|
|
167
|
+
src/commit_roaster/
|
|
168
|
+
cli.py entry point and wiring
|
|
169
|
+
config.py Settings
|
|
170
|
+
diff.py DiffSource classes
|
|
171
|
+
git.py GitClient
|
|
172
|
+
models.py SpiceLevel, RoastResult
|
|
173
|
+
prompts.py PromptBuilder
|
|
174
|
+
roaster.py Roaster (Claude API)
|
|
175
|
+
render.py TextRenderer, JsonRenderer
|
|
176
|
+
exceptions.py error types and exit codes
|
|
177
|
+
tests/ one test module per source module
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### Releasing
|
|
181
|
+
|
|
182
|
+
Pushing a version tag publishes the package to PyPI through
|
|
183
|
+
`.github/workflows/release.yml`. It uses PyPI trusted publishing, so no token is stored in
|
|
184
|
+
GitHub.
|
|
185
|
+
|
|
186
|
+
One-time setup:
|
|
187
|
+
|
|
188
|
+
1. Create an account on [pypi.org](https://pypi.org).
|
|
189
|
+
2. Under *Your projects → Publishing*, add a pending trusted publisher: project
|
|
190
|
+
`commit-roaster`, owner `dileeppdkr`, repository `commit-roaster`, workflow
|
|
191
|
+
`release.yml`, environment `pypi`.
|
|
192
|
+
3. In the GitHub repo, go to *Settings → Environments* and create an environment named
|
|
193
|
+
`pypi`.
|
|
194
|
+
|
|
195
|
+
For each release, bump `version` in `pyproject.toml`, commit, then:
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
git tag v0.1.0
|
|
199
|
+
git push origin main v0.1.0
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
The workflow refuses to publish if the tag does not match the version. The same tag is
|
|
203
|
+
what pre-commit users put in `rev:`.
|
|
204
|
+
|
|
205
|
+
## License
|
|
206
|
+
|
|
207
|
+
MIT
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "commit-roaster"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "A grumpy senior dev in your terminal: roasts your git diff, then writes the commit message."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.12"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
authors = [{ name = "dileeppdkr" }]
|
|
14
|
+
keywords = ["git", "commit", "cli", "claude", "llm"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Environment :: Console",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.12",
|
|
21
|
+
"Programming Language :: Python :: 3.13",
|
|
22
|
+
"Programming Language :: Python :: 3.14",
|
|
23
|
+
"Topic :: Software Development :: Version Control :: Git",
|
|
24
|
+
"Typing :: Typed",
|
|
25
|
+
]
|
|
26
|
+
dependencies = [
|
|
27
|
+
"anthropic>=2.9,<3",
|
|
28
|
+
"pydantic>=2.7,<3",
|
|
29
|
+
]
|
|
30
|
+
|
|
31
|
+
[project.optional-dependencies]
|
|
32
|
+
dev = [
|
|
33
|
+
"mypy>=1.11",
|
|
34
|
+
"pre-commit>=3.7",
|
|
35
|
+
"pytest>=8.0",
|
|
36
|
+
"pytest-cov>=5.0",
|
|
37
|
+
"ruff==0.17.5", # keep in sync with the ruff-pre-commit rev in .pre-commit-config.yaml
|
|
38
|
+
]
|
|
39
|
+
|
|
40
|
+
[project.urls]
|
|
41
|
+
Homepage = "https://github.com/dileeppdkr/commit-roaster"
|
|
42
|
+
Issues = "https://github.com/dileeppdkr/commit-roaster/issues"
|
|
43
|
+
|
|
44
|
+
[project.scripts]
|
|
45
|
+
roast = "commit_roaster.cli:main"
|
|
46
|
+
|
|
47
|
+
[tool.setuptools.packages.find]
|
|
48
|
+
where = ["src"]
|
|
49
|
+
|
|
50
|
+
[tool.setuptools.package-data]
|
|
51
|
+
commit_roaster = ["py.typed"]
|
|
52
|
+
|
|
53
|
+
# ---------------------------------------------------------------- ruff
|
|
54
|
+
[tool.ruff]
|
|
55
|
+
line-length = 100
|
|
56
|
+
target-version = "py312"
|
|
57
|
+
src = ["src", "tests"]
|
|
58
|
+
|
|
59
|
+
[tool.ruff.lint]
|
|
60
|
+
select = [
|
|
61
|
+
"E", # pycodestyle errors
|
|
62
|
+
"W", # pycodestyle warnings
|
|
63
|
+
"F", # pyflakes
|
|
64
|
+
"I", # isort
|
|
65
|
+
"B", # bugbear
|
|
66
|
+
"UP", # pyupgrade
|
|
67
|
+
"SIM", # simplify
|
|
68
|
+
"N", # pep8 naming
|
|
69
|
+
"S", # bandit (security)
|
|
70
|
+
"PT", # pytest style
|
|
71
|
+
"RUF", # ruff-specific
|
|
72
|
+
]
|
|
73
|
+
|
|
74
|
+
[tool.ruff.lint.per-file-ignores]
|
|
75
|
+
# The git module shells out to git on purpose, always with an argument list (never a shell).
|
|
76
|
+
"src/commit_roaster/git.py" = ["S603"]
|
|
77
|
+
"tests/**" = ["S101", "S603", "S607"]
|
|
78
|
+
|
|
79
|
+
# ---------------------------------------------------------------- mypy
|
|
80
|
+
[tool.mypy]
|
|
81
|
+
python_version = "3.12"
|
|
82
|
+
strict = true
|
|
83
|
+
files = ["src"]
|
|
84
|
+
plugins = ["pydantic.mypy"]
|
|
85
|
+
|
|
86
|
+
# ---------------------------------------------------------------- pytest
|
|
87
|
+
[tool.pytest.ini_options]
|
|
88
|
+
testpaths = ["tests"]
|
|
89
|
+
addopts = "-ra --strict-markers --cov=commit_roaster --cov-report=term-missing"
|
|
90
|
+
|
|
91
|
+
[tool.coverage.run]
|
|
92
|
+
branch = true
|
|
93
|
+
|
|
94
|
+
[tool.coverage.report]
|
|
95
|
+
fail_under = 90
|
|
96
|
+
show_missing = true
|
|
97
|
+
exclude_also = [
|
|
98
|
+
"if TYPE_CHECKING:",
|
|
99
|
+
"raise NotImplementedError",
|
|
100
|
+
"@abstractmethod",
|
|
101
|
+
]
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
"""commit-roaster: roast a git diff and suggest a proper commit message."""
|
|
2
|
+
|
|
3
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
4
|
+
|
|
5
|
+
try:
|
|
6
|
+
__version__ = version("commit-roaster")
|
|
7
|
+
except PackageNotFoundError: # running from a source checkout without installing
|
|
8
|
+
__version__ = "0.0.0+unknown"
|
|
9
|
+
|
|
10
|
+
__all__ = ["__version__"]
|