wachiman 1.12.0 → 1.14.0
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.
- package/README.md +132 -101
- package/bin/wachiman.js +1 -1
- package/package.json +2 -3
- package/skills/wachiman-loop/SKILL.md +91 -0
- package/skills/wachiman-review/SKILL.md +2 -2
- package/src/call-message.ts +26 -3
- package/src/cli.ts +113 -18
- package/src/config.ts +99 -32
- package/src/connectors/local-git.ts +102 -14
- package/src/cost.ts +48 -1
- package/src/doctor/checks.ts +1 -1
- package/src/engine.ts +910 -89
- package/src/estimate.ts +64 -0
- package/src/fidelity/block.ts +263 -0
- package/src/fidelity/claims-call.ts +172 -0
- package/src/fidelity/claims.ts +69 -0
- package/src/fidelity/digest.ts +80 -0
- package/src/fidelity/grade.ts +242 -0
- package/src/fidelity/inert.ts +25 -0
- package/src/fidelity/rules.ts +166 -0
- package/src/fidelity/sink.ts +135 -0
- package/src/fidelity/summary.ts +16 -0
- package/src/fidelity/types.ts +93 -0
- package/src/formats.ts +16 -3
- package/src/history/fingerprint.ts +1 -1
- package/src/history/store.ts +44 -6
- package/src/init/options.ts +1 -1
- package/src/ledger.ts +306 -0
- package/src/local.ts +23 -5
- package/src/loop/command.ts +441 -0
- package/src/loop/state.ts +88 -0
- package/src/loop/stop-rule.ts +98 -0
- package/src/providers/claude-code.ts +48 -13
- package/src/providers/codex.ts +8 -7
- package/src/providers/index.ts +6 -3
- package/src/providers/types.ts +13 -3
- package/src/sinks/common.ts +3 -3
- package/src/sinks/json.ts +13 -2
- package/src/skills/install.ts +4 -4
- package/src/status/command.ts +1 -1
- package/src/store/command.ts +109 -0
- package/src/store/figures.ts +153 -0
- package/src/store/html.ts +138 -0
- package/src/store/index.ts +298 -0
- package/templates/caller-workflow.yml +84 -57
- package/templates/wachiman-review-caller.yml +13 -0
package/README.md
CHANGED
|
@@ -2,13 +2,127 @@
|
|
|
2
2
|
|
|
3
3
|
<img src="docs/assets/wachi.png" alt="Wachiman, a cartoon watchman with a cap and a whistle" width="96" align="right">
|
|
4
4
|
|
|
5
|
-
Advisory code reviews by an agent CLI
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
watchman who warns you and lets you decide; the Spanish word comes from the English one.
|
|
5
|
+
Advisory code reviews by an agent CLI. Review a branch on your laptop with your own Claude
|
|
6
|
+
subscription, or review every pull request inside your own GitHub Actions with your own API key or Claude subscription token.
|
|
7
|
+
One engine, same findings either way. Wachiman never approves or blocks a merge: it warns, you
|
|
8
|
+
decide.
|
|
10
9
|
|
|
11
|
-
|
|
10
|
+
**Documentation: [wachiman.dev/docs](https://wachiman.dev/docs/what-it-is/)** ·
|
|
11
|
+
[npm](https://www.npmjs.com/package/wachiman) · [Changelog](CHANGELOG.md)
|
|
12
|
+
|
|
13
|
+
Wachiman (pronounced *watchman*) is named after the Peruvian *wachimán*, the street watchman who
|
|
14
|
+
warns you and lets you decide; the Spanish word comes from the English one.
|
|
15
|
+
|
|
16
|
+
## Contents
|
|
17
|
+
|
|
18
|
+
- [Install](#install)
|
|
19
|
+
- [What you can do with it](#what-you-can-do-with-it)
|
|
20
|
+
- [Documentation](#documentation)
|
|
21
|
+
- [What a pull request review looks like](#what-a-pull-request-review-looks-like)
|
|
22
|
+
- [What it will not do](#what-it-will-not-do)
|
|
23
|
+
- [The trust decision, in brief](#the-trust-decision-in-brief)
|
|
24
|
+
- [Providers and platforms](#providers-and-platforms)
|
|
25
|
+
- [License](#license)
|
|
26
|
+
- [Commit messages](#commit-messages)
|
|
27
|
+
|
|
28
|
+
## Install
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
npm i -g wachiman # or: bun add -g wachiman
|
|
32
|
+
wachiman --version
|
|
33
|
+
wachiman init # set up this project: local reviews, GitHub Actions, or both
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
You need Node 20 or later and, for local reviews, Claude Code (`claude`) signed in. The package
|
|
37
|
+
installs [Bun](https://bun.sh) for you through its `bun` dependency (a 23 to 42 MB download); with
|
|
38
|
+
`--ignore-scripts` it uses a Bun already on your `PATH`. No API key is needed for local reviews.
|
|
39
|
+
Details, the supply-chain note and installing from a clone: [docs/local-review.md](docs/local-review.md#3-install).
|
|
40
|
+
|
|
41
|
+
`wachiman init` asks which mode you want. Local setup uses your current Claude session (or a
|
|
42
|
+
separate profile), checks the machine and account, and prints the first review command. GitHub
|
|
43
|
+
setup writes the workflow file; adding the secret and pushing the workflow stay manual steps.
|
|
44
|
+
See [project setup](docs/local-review.md#configure-this-project).
|
|
45
|
+
|
|
46
|
+
## What you can do with it
|
|
47
|
+
|
|
48
|
+
| Way | Where it runs | What you need | Guide |
|
|
49
|
+
| --- | --- | --- | --- |
|
|
50
|
+
| `wachiman local` | Your laptop, on a branch or commit; nothing is posted | Claude Code signed in; no API key | [docs/local-review.md](docs/local-review.md) |
|
|
51
|
+
| Reusable GitHub Actions workflow | Your repository's runners, on each pull request | A provider API key, or a Claude subscription token, as a secret | [docs/install.md](docs/install.md) |
|
|
52
|
+
|
|
53
|
+
A GitHub App is a design only; it is not implemented.
|
|
54
|
+
|
|
55
|
+
**Review your branch before you push.** `wachiman local` reviews the committed change on your
|
|
56
|
+
branch with your own signed-in `claude` and prints the findings in the terminal, or writes them as
|
|
57
|
+
Markdown or JSON. Nothing is posted, no GitHub requests are made and no telemetry is sent; your
|
|
58
|
+
code goes to your configured Claude account. Read [docs/local-review.md](docs/local-review.md)
|
|
59
|
+
before running it on an employer's code.
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
wachiman local # current branch against origin's default branch
|
|
63
|
+
wachiman local --commit abc1234 # exactly one commit
|
|
64
|
+
wachiman local --from abc1234 # that commit and everything after it
|
|
65
|
+
wachiman local --format markdown --output review.md
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**Loop until clean.** `wachiman loop --base main` runs one review round per call and exits `0`
|
|
69
|
+
when nothing keeps it open, `10` while findings do and `11` when it stopped without converging; a
|
|
70
|
+
coding agent fixes between calls and the CLI never edits code ([docs/cli.md](docs/cli.md#loop)).
|
|
71
|
+
|
|
72
|
+
**Ask about a change.** `wachiman ask "<question>"` answers one question about the same local
|
|
73
|
+
change, grounded in its stored review when there is one; with no question it walks you through the
|
|
74
|
+
change ([docs/cli.md](docs/cli.md#ask)).
|
|
75
|
+
|
|
76
|
+
**See what local runs cost.** `wachiman status` shows the cost of the runs kept on this laptop
|
|
77
|
+
([docs/cli.md](docs/cli.md#status)); workflow runs are not in it. `wachiman dashboard` writes one
|
|
78
|
+
offline HTML page (or JSON) with the spend per day and repository, the findings by severity and
|
|
79
|
+
verdict and the loop rounds ([docs/local-dashboard.md](docs/local-dashboard.md)).
|
|
80
|
+
|
|
81
|
+
**Let your coding agent run it.** `wachiman skills install` copies the `wachiman-review` agent
|
|
82
|
+
skill, which teaches Claude Code or Codex to pick the range from what you ask, run a local review
|
|
83
|
+
and present the findings, and the `wachiman-loop` skill, which fixes between loop rounds ([docs/local-review.md](docs/local-review.md#let-your-coding-agent-run-it)).
|
|
84
|
+
|
|
85
|
+
**Review every pull request in GitHub Actions.** A short caller file in your repository pins a
|
|
86
|
+
release, passes your key and names the operator. Start with [docs/install.md](docs/install.md),
|
|
87
|
+
from an empty repository to a posted review; the caller file is
|
|
88
|
+
[`templates/wachiman-review-caller.yml`](templates/wachiman-review-caller.yml). Already copied the
|
|
89
|
+
engine into a repository? [docs/setup-copy.md](docs/setup-copy.md) explains how to move to the
|
|
90
|
+
maintained workflow.
|
|
91
|
+
|
|
92
|
+
## Documentation
|
|
93
|
+
|
|
94
|
+
The guides are published at **[wachiman.dev/docs](https://wachiman.dev/docs/what-it-is/)**. The
|
|
95
|
+
same material, in this repository:
|
|
96
|
+
|
|
97
|
+
| I want to… | Read |
|
|
98
|
+
| --- | --- |
|
|
99
|
+
| Get a first review on a repository | [docs/install.md](docs/install.md) |
|
|
100
|
+
| Know what I am trusting, and what is unverified | [SECURITY.md](SECURITY.md) |
|
|
101
|
+
| Look up an input, a default or an environment setting | [docs/configuration.md](docs/configuration.md) |
|
|
102
|
+
| Find out why there was no review, or an error | [docs/troubleshooting.md](docs/troubleshooting.md) |
|
|
103
|
+
| Ask for reviews, scope them, read the results | [docs/reviews.md](docs/reviews.md) |
|
|
104
|
+
| Understand what a run can cost and what coverage means | [docs/costs.md](docs/costs.md) |
|
|
105
|
+
| Read the PR Confidence grade in a description (trial) | [docs/pr-confidence.md](docs/pr-confidence.md) |
|
|
106
|
+
| Tell the reviewer what matters in my repository | [docs/review-policy.md](docs/review-policy.md) |
|
|
107
|
+
| Adopt a new release, or roll one back | [docs/upgrading.md](docs/upgrading.md) |
|
|
108
|
+
| Turn it off and remove it | [docs/uninstall.md](docs/uninstall.md) |
|
|
109
|
+
| Quick answers and limitations | [docs/faq.md](docs/faq.md) |
|
|
110
|
+
| Run the engine from the command line | [docs/cli.md](docs/cli.md) |
|
|
111
|
+
| Review a branch on my laptop, on my own Claude subscription | [docs/local-review.md](docs/local-review.md) |
|
|
112
|
+
| See the spend, findings and loops of my local reviews on one page | [docs/local-dashboard.md](docs/local-dashboard.md) |
|
|
113
|
+
| See what a provider adapter runs and inherits | [docs/providers/claude-code.md](docs/providers/claude-code.md), [docs/providers/codex.md](docs/providers/codex.md) |
|
|
114
|
+
| Move from a copied installation | [docs/setup-copy.md](docs/setup-copy.md) |
|
|
115
|
+
| Understand how a review is built | [docs/architecture.md](docs/architecture.md) |
|
|
116
|
+
| Measure false positives | [docs/precision.md](docs/precision.md) |
|
|
117
|
+
| See how it compares with Pullfrog and CodeRabbit | [wachiman-benchmarks](https://github.com/niway-dev/wachiman-benchmarks) |
|
|
118
|
+
| See what changed in a release | [CHANGELOG.md](CHANGELOG.md) |
|
|
119
|
+
| Cut a release (maintainers) | [docs/releasing.md](docs/releasing.md) |
|
|
120
|
+
|
|
121
|
+
Design decisions are recorded as ADRs in [docs/adr/](docs/adr/), starting with
|
|
122
|
+
[ADR 0001: distribution and trust](docs/adr/0001-distribution-and-trust.md) and
|
|
123
|
+
[ADR 0002: TypeScript on Bun, no runtime dependencies besides Bun itself](docs/adr/0002-typescript-on-bun-zero-dependencies.md).
|
|
124
|
+
|
|
125
|
+
## What a pull request review looks like
|
|
12
126
|
|
|
13
127
|
A GitHub Actions workflow that reads a pull request and posts one GitHub review on it. Each
|
|
14
128
|
finding is an inline comment on its line, labelled with a severity (when to act: Blocker, Fix,
|
|
@@ -66,107 +180,24 @@ you do:
|
|
|
66
180
|
This is not a sandbox. What is enforced, what the tests show and what is still unverified:
|
|
67
181
|
[SECURITY.md](SECURITY.md).
|
|
68
182
|
|
|
69
|
-
##
|
|
183
|
+
## Providers and platforms
|
|
70
184
|
|
|
71
|
-
The current release is
|
|
72
|
-
([docs/cli.md](docs/cli.md)) and the
|
|
73
|
-
|
|
74
|
-
|
|
185
|
+
The current release is on [npm](https://www.npmjs.com/package/wachiman) and in
|
|
186
|
+
[CHANGELOG.md](CHANGELOG.md). The command-line contract ([docs/cli.md](docs/cli.md)) and the
|
|
187
|
+
provider adapter boundary are in place. The older `CLAUDE_REVIEW_*` variables,
|
|
188
|
+
`.github/claude-review.md`, `/wachi` and the `@claude` mention are still
|
|
189
|
+
read with a notice; see [docs/upgrading.md](docs/upgrading.md).
|
|
75
190
|
|
|
76
191
|
- **Claude Code** (`claude -p`) is the provider the reusable workflow installs and runs, with
|
|
77
|
-
`ANTHROPIC_API_KEY`
|
|
192
|
+
`ANTHROPIC_API_KEY`, or `CLAUDE_CODE_OAUTH_TOKEN` to run on a Claude subscription
|
|
193
|
+
([docs/providers/claude-code.md](docs/providers/claude-code.md)).
|
|
78
194
|
- **Codex CLI** (`codex exec`, for OpenAI models) is a second adapter, available only from the
|
|
79
195
|
command line. The reusable workflow does not install it or pass an OpenAI key
|
|
80
196
|
([docs/providers/codex.md](docs/providers/codex.md)).
|
|
81
|
-
- **npm:**
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
Installing from source (`scripts/install-local.sh`) still works. macOS and Linux are covered by CI;
|
|
86
|
-
Windows is not tested in CI, and is expected to work wherever Node and Bun run.
|
|
87
|
-
|
|
88
|
-
## Ways to run it
|
|
89
|
-
|
|
90
|
-
One review engine, started from different places. Same findings, same labels, your own account each
|
|
91
|
-
time.
|
|
92
|
-
|
|
93
|
-
| Way | Where it runs | What you need | Status |
|
|
94
|
-
| --- | --- | --- | --- |
|
|
95
|
-
| Reusable GitHub Actions workflow | Your repository's runners, on each pull request | A provider API key as a secret | Shipped; [docs/install.md](docs/install.md) |
|
|
96
|
-
| `wachiman local` | Your laptop, on a branch or commit; nothing is posted | Claude Code signed in; no API key | Shipped; [docs/local-review.md](docs/local-review.md) |
|
|
97
|
-
| GitHub App | Not available | | A design only, not implemented |
|
|
98
|
-
|
|
99
|
-
After a local run, `wachiman status` shows what the runs kept on this laptop cost
|
|
100
|
-
([docs/cli.md](docs/cli.md#status)); runs by the workflow are not in it.
|
|
101
|
-
|
|
102
|
-
## Install
|
|
103
|
-
|
|
104
|
-
The recommended way is the reusable workflow: a short caller file in your repository pins a
|
|
105
|
-
release, passes your key and names the operator.
|
|
106
|
-
|
|
107
|
-
**Start here: [docs/install.md](docs/install.md)**, the first advisory review from an empty
|
|
108
|
-
repository to a posted review. The caller file itself is
|
|
109
|
-
[`templates/wachiman-review-caller.yml`](templates/wachiman-review-caller.yml).
|
|
110
|
-
|
|
111
|
-
Already copied the engine into a repository? That setup still runs, and
|
|
112
|
-
[docs/setup-copy.md](docs/setup-copy.md) explains how to move to the maintained workflow.
|
|
113
|
-
|
|
114
|
-
### Review locally on your own subscription
|
|
115
|
-
|
|
116
|
-
`wachiman local` reviews the branch you have checked out, on your own signed-in `claude`, and
|
|
117
|
-
prints the review in the terminal or writes it as Markdown or JSON. No API key, no GitHub token,
|
|
118
|
-
nothing posted: Wachiman sends no telemetry and makes no GitHub requests in local mode; your code
|
|
119
|
-
is sent to your configured Claude account for the review. Read
|
|
120
|
-
[docs/local-review.md](docs/local-review.md) before running it on an employer's code.
|
|
121
|
-
|
|
122
|
-
Install it from npm (below), or from source: run `scripts/install-local.sh` once from your clone. The npm package
|
|
123
|
-
(`npm i -g wachiman` or `bun add -g wachiman`; it is written to work on Windows (Git Bash, PowerShell), and it is expected to work wherever Node and Bun run, but it is not tested in CI: it ships the
|
|
124
|
-
TypeScript source and a small Node launcher, and it installs Bun for you by depending on the
|
|
125
|
-
official npm package `bun`, which means installing it downloads Bun, 23 to 42 MB compressed; with
|
|
126
|
-
`--ignore-scripts` it uses a Bun already on your `PATH`; details and the supply-chain note are in
|
|
127
|
-
[docs/local-review.md](docs/local-review.md#from-npm)) is published. Both give a global `wachiman local …`
|
|
128
|
-
command; the script also links the `wachiman-review` agent skill, usable from any project, and the
|
|
129
|
-
`wachiman-audit` skill, which compares Wachiman's findings with another reviewer's on the same
|
|
130
|
-
commits (data and procedure in
|
|
131
|
-
[wachiman-benchmarks](https://github.com/niway-dev/wachiman-benchmarks)). Details and the Windows
|
|
132
|
-
note are in [docs/local-review.md](docs/local-review.md#3-install).
|
|
133
|
-
|
|
134
|
-
Configure an existing project with `wachiman init`: choose local reviews, GitHub Actions, or
|
|
135
|
-
both. Local setup offers your current Claude session and checks the machine/account before
|
|
136
|
-
suggesting the first review command. GitHub setup writes the workflow; adding the secret and
|
|
137
|
-
submitting the workflow remain manual. See [project setup](docs/local-review.md#configure-this-project).
|
|
138
|
-
|
|
139
|
-
`wachiman ask "<question>"` answers one question about the same local change (or walks through it
|
|
140
|
-
with no question), grounded in the stored review of that change when there is one. It is in
|
|
141
|
-
[docs/cli.md](docs/cli.md#ask).
|
|
142
|
-
|
|
143
|
-
## Documentation map
|
|
144
|
-
|
|
145
|
-
| I want to… | Read |
|
|
146
|
-
| --- | --- |
|
|
147
|
-
| Get a first review on a repository | [docs/install.md](docs/install.md) |
|
|
148
|
-
| Know what I am trusting, and what is unverified | [SECURITY.md](SECURITY.md) |
|
|
149
|
-
| Look up an input, a default or an environment setting | [docs/configuration.md](docs/configuration.md) |
|
|
150
|
-
| Find out why there was no review, or an error | [docs/troubleshooting.md](docs/troubleshooting.md) |
|
|
151
|
-
| Ask for reviews, scope them, read the results | [docs/reviews.md](docs/reviews.md) |
|
|
152
|
-
| Understand what a run can cost and what coverage means | [docs/costs.md](docs/costs.md) |
|
|
153
|
-
| Tell the reviewer what matters in my repository | [docs/review-policy.md](docs/review-policy.md) |
|
|
154
|
-
| Adopt a new release, or roll one back | [docs/upgrading.md](docs/upgrading.md) |
|
|
155
|
-
| Turn it off and remove it | [docs/uninstall.md](docs/uninstall.md) |
|
|
156
|
-
| Quick answers and limitations | [docs/faq.md](docs/faq.md) |
|
|
157
|
-
| Run the engine from the command line | [docs/cli.md](docs/cli.md) |
|
|
158
|
-
| Review a branch on my laptop, on my own Claude subscription | [docs/local-review.md](docs/local-review.md) |
|
|
159
|
-
| See what a provider adapter runs and inherits | [docs/providers/claude-code.md](docs/providers/claude-code.md), [docs/providers/codex.md](docs/providers/codex.md) |
|
|
160
|
-
| Move from a copied installation | [docs/setup-copy.md](docs/setup-copy.md) |
|
|
161
|
-
| Understand how a review is built | [docs/architecture.md](docs/architecture.md) |
|
|
162
|
-
| Measure false positives | [docs/precision.md](docs/precision.md) |
|
|
163
|
-
| See how it compares with Pullfrog and CodeRabbit | [wachiman-benchmarks](https://github.com/niway-dev/wachiman-benchmarks) |
|
|
164
|
-
| See what changed in a release | [CHANGELOG.md](CHANGELOG.md) |
|
|
165
|
-
| Cut a release (maintainers) | [docs/releasing.md](docs/releasing.md) |
|
|
166
|
-
|
|
167
|
-
Design decisions are recorded as ADRs in [docs/adr/](docs/adr/), starting with
|
|
168
|
-
[ADR 0001: distribution and trust](docs/adr/0001-distribution-and-trust.md) and
|
|
169
|
-
[ADR 0002: TypeScript on Bun, no runtime dependencies besides Bun itself](docs/adr/0002-typescript-on-bun-zero-dependencies.md).
|
|
197
|
+
- **npm releases:** version 1.10.0 was published by hand, without a provenance statement; the
|
|
198
|
+
release workflow publishes later versions with one.
|
|
199
|
+
- **Platforms:** macOS and Linux are covered by CI. Windows (Git Bash, PowerShell) is not tested
|
|
200
|
+
in CI and is expected to work wherever Node and Bun run.
|
|
170
201
|
|
|
171
202
|
## License
|
|
172
203
|
|
package/bin/wachiman.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
// The npm `bin` for `wachiman
|
|
2
|
+
// The npm `bin` for `wachiman`: finds Bun on PATH and runs this package's
|
|
3
3
|
// TypeScript engine with it. All logic is in ./launcher-args.js.
|
|
4
4
|
import { dirname } from "node:path";
|
|
5
5
|
import { fileURLToPath } from "node:url";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "wachiman",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.14.0",
|
|
4
4
|
"description": "Advisory pull request reviews by an agent CLI, run in your own GitHub Actions with your own key, or locally on your own Claude subscription",
|
|
5
5
|
"private": false,
|
|
6
6
|
"type": "module",
|
|
@@ -10,8 +10,7 @@
|
|
|
10
10
|
"url": "git+https://github.com/niway-dev/wachiman.git"
|
|
11
11
|
},
|
|
12
12
|
"bin": {
|
|
13
|
-
"wachiman": "bin/wachiman.js"
|
|
14
|
-
"agent-review": "bin/wachiman.js"
|
|
13
|
+
"wachiman": "bin/wachiman.js"
|
|
15
14
|
},
|
|
16
15
|
"files": [
|
|
17
16
|
"bin/wachiman.js",
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: wachiman-loop
|
|
3
|
+
description: Use when the developer asks you to review your own change with Wachiman and keep fixing what it finds until it is clean ("loop until clean", "run the wachiman loop", "fix what wachiman reports and run it again") on their laptop. Not for a single review or for judging a finding outside a loop; that is wachiman-review.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Fix a branch with the Wachiman loop
|
|
7
|
+
|
|
8
|
+
## Why
|
|
9
|
+
|
|
10
|
+
`wachiman loop` runs **one review round per call** on the developer's signed-in `claude` and
|
|
11
|
+
tells you whether to stop. The CLI keeps the books: round count, which findings are still open,
|
|
12
|
+
retries and the stop rule. **You fix the code between calls; the CLI never edits it, and you never
|
|
13
|
+
review the code yourself.** Choose the account the way `wachiman-review` does ("Choose the
|
|
14
|
+
profile"): ask `wachiman project show --json`, never read inside a profile directory.
|
|
15
|
+
|
|
16
|
+
## The command
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
env -u ANTHROPIC_API_KEY wachiman loop --repo-dir <clone> --base <ref> --format json \
|
|
20
|
+
[--profile <name>] [--max-rounds <n>] 2> <tmp>/loop.log
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
- `--base <ref>` **starts** a loop: round 1 reviews the whole branch range from that ref (the
|
|
24
|
+
default branch, unless the developer names another). Run it from a directory outside the clone.
|
|
25
|
+
- The same command **without** `--base` continues the open loop of the branch: it reviews only the
|
|
26
|
+
commits made since the previous round. **Commit your fix first**; uncommitted work is not reviewed.
|
|
27
|
+
- Three rounds by default. Raise `--max-rounds` only when the developer says so.
|
|
28
|
+
|
|
29
|
+
## Read the exit code first
|
|
30
|
+
|
|
31
|
+
| Exit | Meaning | You do |
|
|
32
|
+
| --- | --- | --- |
|
|
33
|
+
| `0` | Converged: nothing keeps the loop open | Report it as below |
|
|
34
|
+
| `10` | Findings still open | Work through `open[]`, commit, call again |
|
|
35
|
+
| `11` | Stopped without converging (`outcome.reason`: `round cap` or `review failed`) | Stop. Report the reason and what is still open. Do not call again unless the developer says so |
|
|
36
|
+
| `2` | Usage error (no loop open, detached HEAD, bad flag) | Read stderr and fix the call |
|
|
37
|
+
|
|
38
|
+
A stop is never an approval. `0` means the rule found nothing open in the commits reviewed; it is
|
|
39
|
+
not a statement that the branch is safe to merge.
|
|
40
|
+
|
|
41
|
+
## Between rounds (exit 10)
|
|
42
|
+
|
|
43
|
+
The JSON has `open[]` (each with `id`, `path`, `line`, `severity`, `title`, `status`), `released[]`
|
|
44
|
+
(findings that no longer count, with `why`) and `notes[]` (🟡 and ⚪, which never keep the loop
|
|
45
|
+
open). For each finding in `open[]`:
|
|
46
|
+
|
|
47
|
+
1. Read the cited code in the repository and decide whether the finding is true.
|
|
48
|
+
2. **True:** fix it at that place and commit. The next round has to see the change; a finding at
|
|
49
|
+
lines nobody changed stays open even if the reviewer does not repeat it.
|
|
50
|
+
3. **False, and you can say why in one sentence:** judge it, with the reason:
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
wachiman history --repo-dir <clone> --verdict <id> wrong --reason "<why it is not a defect>"
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
A `wrong` verdict without a reason does not release the finding.
|
|
57
|
+
4. **Not sure:** do not guess. Ask the developer, and leave the finding open.
|
|
58
|
+
|
|
59
|
+
**Never judge a finding `wrong` to make the loop converge.** The reason must be something you
|
|
60
|
+
checked in the code, not "out of scope" or "not worth fixing". Every finding you judge `wrong`
|
|
61
|
+
appears in the outcome, and the owner reads that list.
|
|
62
|
+
|
|
63
|
+
Then call `wachiman loop` again without `--base`. A call with no new commit makes no review call
|
|
64
|
+
(and still counts as a round), so use it only after a verdict, never to wait.
|
|
65
|
+
|
|
66
|
+
## At the end
|
|
67
|
+
|
|
68
|
+
Tell the developer, in this order:
|
|
69
|
+
|
|
70
|
+
1. The exit code and `outcome.message`, in your own words but with every caveat. A loop that
|
|
71
|
+
converged at round 1 says "Round 1 reviewed the whole range". A loop that converged later says
|
|
72
|
+
"converged on incremental rounds": round 1 read the whole range and later rounds only your fix
|
|
73
|
+
commits; interactions with code outside them were not re-read. Pass on whichever caveat it
|
|
74
|
+
printed.
|
|
75
|
+
2. What you fixed, with the commit of each.
|
|
76
|
+
3. Every finding in `released[]` with `why: "judged wrong"`, with its reason, so they can overrule
|
|
77
|
+
you. Also name the findings released as `probably-fixed`: that is inferred from the code
|
|
78
|
+
changing, not proved.
|
|
79
|
+
4. The `notes[]`, one line each, as optional.
|
|
80
|
+
|
|
81
|
+
## Never
|
|
82
|
+
|
|
83
|
+
| Tempting | Instead |
|
|
84
|
+
| --- | --- |
|
|
85
|
+
| Editing code inside the CLI, or asking it to apply a fix | You edit and commit; the CLI only reviews |
|
|
86
|
+
| Marking findings `wrong` until exit 0 | Fix the true ones; give a checked reason for the false ones; ask when unsure |
|
|
87
|
+
| Calling again after exit 11 to "try once more" | Report the stop; the developer decides |
|
|
88
|
+
| Running `wachiman review <pr>`, `gh` or a GitHub token | `loop` is local; nothing is posted |
|
|
89
|
+
| Running with `ANTHROPIC_API_KEY` set | `env -u ANTHROPIC_API_KEY wachiman loop ...`; the subscription pays |
|
|
90
|
+
| Editing files under `~/.wachiman` to reset or close a loop | `--base <ref>` starts a new loop |
|
|
91
|
+
| Claiming the branch is approved or safe | Report the outcome and its limits |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: wachiman-review
|
|
3
|
-
description: Use when the developer asks to review, audit or "analyse" their own code with Wachiman
|
|
3
|
+
description: Use when the developer asks to review, audit or "analyse" their own code with Wachiman on their laptop — a branch, one commit, or a range from a commit — including on employer code that must not reach GitHub, when they ask Wachiman to explain or answer a question about such a change ("explain this change", "ask about this branch"), and when they judge a finding from such a review as right or wrong.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Review local code with Wachiman
|
|
@@ -119,7 +119,7 @@ wachiman history --repo-dir <clone> --verdict <id> correct|partial|wrong --reaso
|
|
|
119
119
|
|
|
120
120
|
| Tempting | Instead |
|
|
121
121
|
| --- | --- |
|
|
122
|
-
| `wachiman review <pr>`, `
|
|
122
|
+
| `wachiman review <pr>`, `WACHIMAN_DRY_RUN`, `gh`, a GitHub token | `local`: the GitHub modes post to the PR and need the code on GitHub |
|
|
123
123
|
| A verdict as a PR comment or `Verdict:` reply | `history --verdict`: it stays on the laptop |
|
|
124
124
|
| Running with `ANTHROPIC_API_KEY` set | `env -u ANTHROPIC_API_KEY wachiman local ...`: `local` refuses a key; the subscription pays |
|
|
125
125
|
| `--max-depth 1000` because "review everything" | A closer start commit, or the number the developer chose |
|
package/src/call-message.ts
CHANGED
|
@@ -3,7 +3,9 @@
|
|
|
3
3
|
* scripts parse. The JSON stays the contract; this line is for the person reading the log.
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
|
+
import { isEstimate } from "./cost";
|
|
6
7
|
import type { ProviderErrorClass } from "./providers/errors";
|
|
8
|
+
import type { ProviderAuth } from "./providers/types";
|
|
7
9
|
|
|
8
10
|
export interface CallSummary {
|
|
9
11
|
/** Which call: `batch 1/2`, `threads`, `question`. */
|
|
@@ -15,6 +17,8 @@ export interface CallSummary {
|
|
|
15
17
|
durationMs: number;
|
|
16
18
|
providerError?: ProviderErrorClass;
|
|
17
19
|
errorText?: string;
|
|
20
|
+
/** What paid for the call; absent means `api-key`. */
|
|
21
|
+
credential?: ProviderAuth;
|
|
18
22
|
}
|
|
19
23
|
|
|
20
24
|
const MAX_TEXT = 300;
|
|
@@ -29,18 +33,37 @@ const turnsText = (n: number) => `${n} turn${n === 1 ? "" : "s"}`;
|
|
|
29
33
|
const seconds = (ms: number) => `${(ms / 1000).toFixed(1)} s`;
|
|
30
34
|
const dollars = (usd: number) => `$${usd.toFixed(2)}`;
|
|
31
35
|
|
|
36
|
+
/** The messages for a call refused on a subscription token: its credential is not an API key, so nothing here names one. */
|
|
37
|
+
function describeTokenRefusal(head: string, providerError: ProviderErrorClass | undefined, api: string): string | undefined {
|
|
38
|
+
switch (providerError) {
|
|
39
|
+
case "auth":
|
|
40
|
+
return `❌ ${head}: Claude refused the call: the subscription token was rejected. Check the CLAUDE_CODE_OAUTH_TOKEN secret (a token lasts a year; make a new one with \`claude setup-token\`).${api}`;
|
|
41
|
+
case "billing":
|
|
42
|
+
return `❌ ${head}: Claude refused the call: the subscription's usage limit or plan access stopped it. Wait for the limit to reset, then re-run this job; the review does not fall back to an API key.${api}`;
|
|
43
|
+
case "rate_limit":
|
|
44
|
+
return `⏳ ${head}: Claude rate-limited the call. This is usually temporary.${api}`;
|
|
45
|
+
default:
|
|
46
|
+
return undefined;
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
|
|
32
50
|
export function describeCall(call: CallSummary): string {
|
|
33
51
|
const head = call.label;
|
|
52
|
+
const estimate = isEstimate(call.credential);
|
|
34
53
|
if (!call.isError && call.terminalReason === "success")
|
|
35
|
-
return `✅ ${head}: finished in ${turnsText(call.turns)}, ${seconds(call.durationMs)}, ${dollars(call.costUsd)}.`;
|
|
54
|
+
return `✅ ${head}: finished in ${turnsText(call.turns)}, ${seconds(call.durationMs)}, ${dollars(call.costUsd)}${estimate ? " (API-price estimate)" : ""}.`;
|
|
36
55
|
if (call.terminalReason === "budget")
|
|
37
|
-
return `💸 ${head}: stopped at its budget after ${turnsText(call.turns)}, ${dollars(call.costUsd)}.`;
|
|
56
|
+
return `💸 ${head}: stopped at its budget after ${turnsText(call.turns)}, ${dollars(call.costUsd)}${estimate ? " (API-price estimate)" : ""}.`;
|
|
38
57
|
if (call.terminalReason === "turns")
|
|
39
|
-
return `⏹️ ${head}: hit the turn limit after ${turnsText(call.turns)}, ${dollars(call.costUsd)}.`;
|
|
58
|
+
return `⏹️ ${head}: hit the turn limit after ${turnsText(call.turns)}, ${dollars(call.costUsd)}${estimate ? " (API-price estimate)" : ""}.`;
|
|
40
59
|
if (call.terminalReason === "timeout") return `⏱️ ${head}: killed at the time limit after ${seconds(call.durationMs)}.`;
|
|
41
60
|
|
|
42
61
|
const said = quoted(call.errorText);
|
|
43
62
|
const api = said ? ` API said: ${said}` : "";
|
|
63
|
+
if (call.credential === "oauth-token") {
|
|
64
|
+
const line = describeTokenRefusal(head, call.providerError, api);
|
|
65
|
+
if (line) return line;
|
|
66
|
+
}
|
|
44
67
|
switch (call.providerError) {
|
|
45
68
|
case "billing":
|
|
46
69
|
return `❌ ${head}: the Anthropic API refused the call: the account has no credit. Top up, then re-run this job.${api}`;
|