@jphutchins/code-review 0.1.0-alpha.6 → 0.1.0-alpha.8

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 (8) hide show
  1. package/README.md +12 -10
  2. package/dist/index.js +445 -215
  3. package/dist/index.js.map +1 -1
  4. package/package.json +2 -1
  5. package/schema/VERSIONING.md +2 -1
  6. package/schema/findings.schema.json +23 -14
  7. package/templates/comment.eta +24 -6
  8. package/templates/inline.eta +16 -9
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,9 +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 |
45
- | `lower-suggestions` | Validate each finding's `patch` against the real PR-head file and lower it to an exact `suggestion` + line range, or drop it |
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 |
46
47
  | `cost` | Recompute USD cost from the envelope's per-model token counts + a price map |
47
48
  | `validate` | Validate findings JSON against the published schema |
48
49
  | `print-schema` | Print a bundled schema (findings, triage, prices) |
@@ -63,16 +64,17 @@ in [templates/](templates/). See [docs/adapters.md](docs/adapters.md) for the ad
63
64
  letting the CLI pick where your key gets sent.
64
65
  3. Commit `.github/prices.json` (fork [schema/prices.example.json](schema/prices.example.json) and
65
66
  fill in your provider's per-token rates) — without it the cost footer renders **$0**
66
- ([SPEC §6.2](SPEC.md#62-price-map)).
67
+ ([SPEC §4.4](SPEC.md#44-required-controls-conformance)).
67
68
  4. Merge to your default branch first — `workflow_run` only fires from the default branch, so the
68
69
  introducing PR won't review itself — then open a test PR.
69
70
  5. First run: consider `egress-policy: audit` to discover the real allowlist, then switch to `block`
70
- ([SPEC §8.4](SPEC.md#84-egress-allowlist)).
71
+ ([SPEC Appendix A](SPEC.md#appendix-a--reference-realization-github-actions-non-normative)).
71
72
 
72
73
  Every model knob is committed step `env` on the workflow's triage and review steps — models,
73
74
  efforts, the subagent model, and the tier aliases, right where each is consumed — edited and
74
- PR-reviewed like the rest of the file ([SPEC §8.5](SPEC.md#85-model-backend-env)). Only the backend
75
- 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
76
78
  another provider requires adding that provider's API host to the workflow's egress allowlist in the
77
79
  same reviewed PR.
78
80
 
@@ -87,8 +89,8 @@ links to:
87
89
  downstream tool) SHOULD base64-decode and parse that marker rather than parse the comment's prose.
88
90
  Embedding in the comment (rather than only linking the artifact) keeps the pointer from expiring
89
91
  with artifact retention; when the encoded findings are too large to embed, the sticky falls back to
90
- a `<!-- code-review:findings-json <url> -->` link marker instead
91
- ([SPEC §5.1 item 7](SPEC.md#51-sticky-summary-comment)).
92
+ a `<!-- code-review:findings-json <url> -->` link marker instead — the shared serializer is
93
+ [`src/surface.ts`](src/surface.ts).
92
94
  - **`code-review-transcript`** — the full Claude Code session transcripts for the triage and review
93
95
  phases. This is advisory/auditability only: it is never read by the comment job and never affects
94
96
  what gets posted.