@jphutchins/code-review 0.1.0-alpha.1 → 0.1.0-alpha.10

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.
Files changed (9) hide show
  1. package/README.md +27 -7
  2. package/dist/index.js +1320 -186
  3. package/dist/index.js.map +1 -1
  4. package/package.json +3 -2
  5. package/schema/VERSIONING.md +3 -1
  6. package/schema/findings.schema.json +30 -13
  7. package/schema/v0.2/findings.schema.json +88 -0
  8. package/templates/comment.eta +69 -44
  9. package/templates/inline.eta +28 -5
package/README.md CHANGED
@@ -25,8 +25,9 @@ the security boundary, and the cost.
25
25
  ## The CLI
26
26
 
27
27
  The npm package is the **deterministic commenter** — the presentation and posting layer that no
28
- model should do, plus the adapter glue between an agent CLI's native output and the spec's abstract
29
- envelope ([SPEC §6.1](SPEC.md#61-result-envelope)).
28
+ model should do, plus the adapter glue between an agent CLI's native output and the abstract result
29
+ envelope defined in [`src/schema.ts`](src/schema.ts) (the deliverable of
30
+ [SPEC §3.2](SPEC.md#32-the-deliverable)).
30
31
 
31
32
  ```sh
32
33
  npm install -g @jphutchins/code-review
@@ -40,8 +41,9 @@ npx @jphutchins/code-review <subcommand>
40
41
  | `gather` | Resolve the PR from the CI head SHA and gather the review inputs (diff with git-diff fallback, PR context, prior bot review, failing-job logs) into the workspace for the agent |
41
42
  | `render` | Render the sticky-comment markdown from findings + usage + prices |
42
43
  | `inline` | Build the GitHub reviews `comments[]` payload from findings + diff (in-diff validation; strays demote to the summary) |
43
- | `adapt` | Map a native agent-CLI result envelope onto the abstract SPEC §6.1 envelope |
44
+ | `adapt` | Map a native agent-CLI result envelope onto the abstract result envelope (`src/schema.ts`) |
44
45
  | `extract` | Recover findings/triage JSON from a native envelope via the deterministic extraction ladder |
46
+ | `validate-patches` | Validate each finding's `patch` against the real PR-head file, aligning the finding's line range to it and keeping the patch (projected into a suggestion at render time), or dropping the patch |
45
47
  | `cost` | Recompute USD cost from the envelope's per-model token counts + a price map |
46
48
  | `validate` | Validate findings JSON against the published schema |
47
49
  | `print-schema` | Print a bundled schema (findings, triage, prices) |
@@ -62,19 +64,37 @@ in [templates/](templates/). See [docs/adapters.md](docs/adapters.md) for the ad
62
64
  letting the CLI pick where your key gets sent.
63
65
  3. Commit `.github/prices.json` (fork [schema/prices.example.json](schema/prices.example.json) and
64
66
  fill in your provider's per-token rates) — without it the cost footer renders **$0**
65
- ([SPEC §6.2](SPEC.md#62-price-map)).
67
+ ([SPEC §4.4](SPEC.md#44-required-controls-conformance)).
66
68
  4. Merge to your default branch first — `workflow_run` only fires from the default branch, so the
67
69
  introducing PR won't review itself — then open a test PR.
68
70
  5. First run: consider `egress-policy: audit` to discover the real allowlist, then switch to `block`
69
- ([SPEC §8.4](SPEC.md#84-egress-allowlist)).
71
+ ([SPEC Appendix A](SPEC.md#appendix-a--reference-realization-github-actions-non-normative)).
70
72
 
71
73
  Every model knob is committed step `env` on the workflow's triage and review steps — models,
72
74
  efforts, the subagent model, and the tier aliases, right where each is consumed — edited and
73
- PR-reviewed like the rest of the file ([SPEC §8.5](SPEC.md#85-model-backend-env)). Only the backend
74
- endpoint is a per-repo **Actions variable** (`API_BASE_URL`, required, no default); pointing it at
75
+ PR-reviewed like the rest of the file (implementation detail the spec deliberately leaves to this
76
+ repo — see [SPEC Appendix A](SPEC.md#appendix-a--reference-realization-github-actions-non-normative)).
77
+ Only the backend endpoint is a per-repo **Actions variable** (`API_BASE_URL`, required, no default); pointing it at
75
78
  another provider requires adding that provider's API host to the workflow's egress allowlist in the
76
79
  same reviewed PR.
77
80
 
81
+ ## Artifacts
82
+
83
+ The review job uploads two artifacts, each visible from the workflow run the sticky's disclosure
84
+ links to:
85
+
86
+ - **`code-review-findings`** — the findings JSON + result envelope the comment job renders. The
87
+ sticky comment embeds this same JSON directly, base64-encoded, in an
88
+ `<!-- code-review:findings-json;base64 <base64> -->` HTML comment — a reviewing agent (or any
89
+ downstream tool) SHOULD base64-decode and parse that marker rather than parse the comment's prose.
90
+ Embedding in the comment (rather than only linking the artifact) keeps the pointer from expiring
91
+ with artifact retention; when the encoded findings are too large to embed, the sticky falls back to
92
+ a `<!-- code-review:findings-json <url> -->` link marker instead — the shared serializer is
93
+ [`src/surface.ts`](src/surface.ts).
94
+ - **`code-review-transcript`** — the full Claude Code session transcripts for the triage and review
95
+ phases. This is advisory/auditability only: it is never read by the comment job and never affects
96
+ what gets posted.
97
+
78
98
  ## What's here
79
99
 
80
100
  - **[SPEC.md](SPEC.md)** — the normative, provider-agnostic specification.