From 21497eb0417fb3da44ec37fdf8d68088d7bde171 Mon Sep 17 00:00:00 2001 From: Cole Tebou Date: Sun, 17 May 2026 20:26:54 +0000 Subject: [PATCH 1/2] chore(report): add total/results aliases for json output, document deprecation `clawpatch report --json` previously returned `{ findings: , output, items: [...] }`, which mixed a count called `findings` with an array under `items` and broke common shell pipelines like `jq '.findings | length'`. Add additive aliases so existing callers keep working: - `total: ` mirrors `findings`. - `results: ` is the same reference as `items` (parity with `{count, results}` consumers). The legacy `findings: ` key is kept but documented as deprecated; v0.4 will drop `findings: ` and `results`, landing on `{ total, items, output }`. --- CHANGELOG.md | 1 + README.md | 22 ++++++++++++++++++++++ src/app.ts | 5 ++++- src/workflow.test.ts | 10 ++++++++++ 4 files changed, 37 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 570182c..3153299 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ - Added `clawpatch open-pr --patch ` to turn an applied patch attempt into an explicit GitHub pull request. - Added review prompt provenance and budget accounting for included files, omitted files, prompt bytes, and approximate tokens. - Hardened review ingestion so provider findings must cite included files with valid line ranges and matching evidence quotes. +- Added `total` and `results` aliases on `clawpatch report --json` output (`total` mirrors `findings`, `results` is the same reference as `items`); the legacy `findings: ` key is kept but deprecated and will be removed in v0.4. - Fixed `clawpatch open-pr` so repositories without default-branch metadata use a dedicated patch branch and let GitHub choose the PR base. - Fixed `clawpatch open-pr` retries to push the recorded patch commit instead of any later local branch tip. - Fixed first-time `clawpatch open-pr` branch creation to start from the recorded patch base. diff --git a/README.md b/README.md index 5ee40b4..517fea9 100644 --- a/README.md +++ b/README.md @@ -161,6 +161,28 @@ Useful flags: Unknown flags fail fast. +### `report --json` shape + +`clawpatch report --json` returns: + +```json +{ + "total": 12, + "items": [ + /* finding summaries */ + ], + "results": [ + /* alias for items */ + ], + "findings": 12, + "output": "/path/or/null" +} +``` + +- `total` and `items` are the canonical keys. +- `results` is an alias for `items` (identical reference) for parity with `{count, results}` consumers. +- `findings: ` is kept for backwards compatibility but is **deprecated**. Note that in `--json` output `findings` is a _count_, not the array — use `items` (or `results`) for the array. The next breaking release (v0.4) will drop `findings: ` and `results`, landing on `{ total, items, output }`. + ## State State is project-local by default: diff --git a/src/app.ts b/src/app.ts index 05be074..ebc1f6e 100644 --- a/src/app.ts +++ b/src/app.ts @@ -499,10 +499,13 @@ export async function reportCommand( await writeFile(outputPath, output, "utf8"); } if (context.options.json) { + const items = findingSummaries(filtered, scopedFeatures); return { findings: filtered.length, + total: filtered.length, output: outputPath, - items: findingSummaries(filtered, scopedFeatures), + items, + results: items, }; } return { diff --git a/src/workflow.test.ts b/src/workflow.test.ts index 0f37312..2f49cac 100644 --- a/src/workflow.test.ts +++ b/src/workflow.test.ts @@ -426,6 +426,7 @@ describe("workflow", () => { }); expect(jsonReport).toMatchObject({ findings: 1, + total: 1, items: [ { id: expect.stringMatching(/^fnd_/u), @@ -439,6 +440,15 @@ describe("workflow", () => { ], }); expect(reviewedFeature?.analysisHistory.at(-1)?.summary).toContain("prompt="); + const aliased = jsonReport as { + findings: number; + total: number; + items: unknown[]; + results: unknown[]; + }; + expect(aliased.total).toBe(aliased.findings); + expect(aliased.total).toBe(aliased.items.length); + expect(aliased.results).toBe(aliased.items); delete process.env["CLAWPATCH_PROVIDER"]; }); From 1e1b413fd305852090467c80b3cc1f48722b98e3 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 20 May 2026 03:29:58 +0100 Subject: [PATCH 2/2] docs(changelog): note report json aliases --- CHANGELOG.md | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 87684ea..3089702 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,7 @@ - Added review prompt provenance and budget accounting for included files, omitted files, prompt bytes, and approximate tokens. - Added retries for transient acpx JSON review failures via `--prompt-retries` and `CLAWPATCH_REVIEW_RETRIES`, thanks @coletebou. - Hardened review ingestion so provider findings must cite included files with valid line ranges and matching evidence quotes. -- Added `total` and `results` aliases on `clawpatch report --json` output (`total` mirrors `findings`, `results` is the same reference as `items`); the legacy `findings: ` key is kept but deprecated and will be removed in v0.4. +- Added `total` and `results` aliases on `clawpatch report --json` output while keeping the legacy `findings` count, thanks @coletebou. - Fixed `clawpatch open-pr` so repositories without default-branch metadata use a dedicated patch branch and let GitHub choose the PR base. - Fixed `clawpatch open-pr` retries to push the recorded patch commit instead of any later local branch tip. - Fixed first-time `clawpatch open-pr` branch creation to start from the recorded patch base. diff --git a/README.md b/README.md index 59204e5..642c661 100644 --- a/README.md +++ b/README.md @@ -183,7 +183,7 @@ Unknown flags fail fast. ``` - `total` and `items` are the canonical keys. -- `results` is an alias for `items` (identical reference) for parity with `{count, results}` consumers. +- `results` is an alias for `items` with the same array for parity with `{count, results}` consumers. - `findings: ` is kept for backwards compatibility but is **deprecated**. Note that in `--json` output `findings` is a _count_, not the array — use `items` (or `results`) for the array. The next breaking release (v0.4) will drop `findings: ` and `results`, landing on `{ total, items, output }`. ## State