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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jphutchins/code-review",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.7",
   "description": "Deterministic commenter for agentic PR review — gather, render, inline, post, adapt, extract, cost, validate, print-schema",
   "type": "module",
   "license": "MIT",

package/schema/VERSIONING.md

@@ -66,7 +66,8 @@ ignored); a version outside the supported set degrades to a §5.5 sticky notice.
 |---|---|---|
 | `v0.1.0` | superseded | Initial schema. Matches the proven camas reference implementation. |
 | `v0.2.0` | superseded | Adds required `schema_version`; optional `code`/`code_url` finding fields; normative `suggestion` `""`/`null` semantics; abstract vendor-neutral envelope (see SPEC §6.1). |
-| `v0.3.0` | **current** | Adds optional `reasoning` finding field. |
+| `v0.3.0` | superseded | Adds optional `reasoning` finding field. |
+| `v0.4.0` | **current** | Breaking: renames finding `body` → `description`; makes `reasoning` and `confidence` **required**; adds optional `recommendation` (prose fix); removes the free-text `suggestion` field (a `patch`, now `string \| null`, is the sole mechanical fix, projected into a suggestion by the commenter). The CLI supports only `0.4` — `0.2`/`0.3` documents cannot supply the now-required `reasoning`/`confidence`, so they degrade to a §5.5 unsupported-version notice rather than being upcast. |
 
 ### Price-map schema
 

package/schema/findings.schema.json

@@ -27,7 +27,16 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["path", "start_line", "end_line", "severity", "title", "body"],
+        "required": [
+          "path",
+          "start_line",
+          "end_line",
+          "severity",
+          "title",
+          "description",
+          "reasoning",
+          "confidence"
+        ],
         "properties": {
           "path": {
             "type": "string",
@@ -67,27 +76,27 @@
             "type": "string",
             "description": "One-line summary of the finding."
           },
-          "body": {
+          "description": {
             "type": "string",
-            "description": "Markdown explanation; rendered as the inline comment body."
+            "description": "Markdown explanation of what is wrong; rendered as the inline comment body."
           },
-          "suggestion": {
-            "type": ["string", "null"],
-            "description": "Proposed replacement text for start_line..end_line: null = no mechanical fix; \"\" (empty string) = the range should be deleted; a non-empty string = the exact, verbatim replacement text, so it must carry correct indentation."
+          "recommendation": {
+            "type": "string",
+            "description": "Markdown prose describing what to do about the finding, in human terms — distinct from `patch`, which is a machine-applicable unified diff. Use this when the fix is best explained rather than mechanically applied, or to accompany a `patch` with rationale."
           },
           "confidence": {
             "type": "number",
             "minimum": 0,
             "maximum": 1,
-            "description": "Optional 0..1 confidence; a commenter MAY suppress findings below a configurable threshold to control noise, but MUST NOT suppress a critical-severity finding on confidence alone."
+            "description": "0..1 confidence; a commenter MAY suppress findings below a configurable threshold to control noise, but MUST NOT suppress a critical-severity finding on confidence alone."
           },
           "reasoning": {
             "type": "string",
-            "description": "Optional rationale/evidence for why the finding holds, so a human or downstream agent can judge its soundness — distinct from `body`, which explains the finding to the reader."
+            "description": "Rationale/evidence for why the finding holds, so a human or downstream agent can judge its soundness — distinct from `description`, which explains the finding to the reader."
           },
           "patch": {
-            "type": "string",
-            "description": "Optional single-hunk unified diff of a mechanical fix, against this file's post-change (RIGHT-side) content. A machine-verifiable alternative to `suggestion`: because it can be validated exactly against the file, a consumer can derive a precise replacement from it or reject it if it no longer applies — preferred over a hand-authored `suggestion`, which is prone to wrong indentation or an over-wide range."
+            "type": ["string", "null"],
+            "description": "Single-hunk unified diff of a mechanical fix, against this file's post-change (RIGHT-side) content, or null when there is no mechanical fix. Validated exactly against the file and deterministically projected into a suggestion (or dropped) by the commenter, so it never posts with wrong indentation or an over-wide range."
           }
         }
       }

package/templates/comment.eta

@@ -1,9 +1,7 @@
 <!-- code-review -->
 <!-- reviewed-sha: <%= it.reviewedSha %> -->
-<% if (it.embeddedFindings) { -%>
-<!-- code-review:findings-json;base64 <%~ it.embeddedFindings %> -->
-<% } else if (it.jsonUrl) { -%>
-<!-- code-review:findings-json <%~ it.jsonUrl %> -->
+<% if (it.findingsPointer) { -%>
+<%~ it.findingsPointer %>
 <% } -%>
 
 ### <%= it.verdictBadge(it.findings.verdict) %>
@@ -36,8 +34,7 @@ _No findings — clean review._
 These findings are on lines not in the diff, so they can't be anchored as inline comments:
 
 <% it.strays.forEach(function(f) { -%>
-- <%= it.severityEmoji(f.severity) %> `<%= f.path %>:<%= f.start_line %><% if (f.start_line !== f.end_line) { %>–<%= f.end_line %><% } %>` — <%= f.title %><% if (typeof f.confidence === "number") { %> · confidence <%= f.confidence %><% } %>
-<% if (f.reasoning) { -%>
+- <%= it.severityEmoji(f.severity) %> `<%= f.path %>:<%= f.start_line %><% if (f.start_line !== f.end_line) { %>–<%= f.end_line %><% } %>` — <%= f.title %> · confidence <%= f.confidence %>
   <details><summary>Reasoning</summary>
 
 <% f.reasoning.split("\n").forEach(function(rl) { -%>
@@ -45,6 +42,20 @@ These findings are on lines not in the diff, so they can't be anchored as inline
 <% }) -%>
 
   </details>
+<% if (f.recommendation) { -%>
+
+  **Recommended fix:** <%~ f.recommendation %>
+<% } -%>
+<% if (f.patchProjection.kind === "suggestion") { -%>
+
+```suggestion
+<%~ f.patchProjection.text %>
+```
+<% } else if (f.patchProjection.kind === "patch") { -%>
+
+```patch
+<%~ f.patchProjection.raw %>
+```
 <% } -%>
 <% }) %>
 <% } %>
@@ -83,5 +94,9 @@ All <%= it.testReport.total %> tests passed.
 <% } else { -%>
 > **Usage/cost unavailable** — the result envelope for this run was missing or malformed.
 <% } -%>
+<% if (it.usageAvailable && !it.pricesProvided) { -%>
+>
+> _Cost shown as **N/A** — [No `.github/prices.json`](https://github.com/JPHutchins/code-review/blob/main/SPEC.md#62-price-map) price map to recompute from._
+<% } -%>
 >
 > _Generated by [code-review](https://github.com/JPHutchins/code-review)<% if (it.runUrl) { %> · [view the run & traces](<%~ it.runUrl %>)<% } %>._

package/templates/inline.eta

@@ -1,19 +1,27 @@
-<% if (it.jsonUrl) { -%>
-<!-- code-review:findings-json <%~ it.jsonUrl %> -->
+<% if (it.findingsPointer) { -%>
+<%~ it.findingsPointer %>
 <% } -%>
 <%= it.severityEmoji(it.severity) %> **<%= it.severity %>** — <%= it.title %>
 
-<%~ it.body %>
-<% if (it.suggestion !== null && it.suggestion !== undefined) { -%>
+<%~ it.description %>
+<% if (it.recommendation) { -%>
+
+**Recommended fix:** <%~ it.recommendation %>
+<% } -%>
+<% if (it.patchProjection.kind === "suggestion") { -%>
 
 ```suggestion
-<%~ it.suggestion %>
+<%~ it.patchProjection.text %>
+```
+<% } else if (it.patchProjection.kind === "patch") { -%>
+
+```patch
+<%~ it.patchProjection.raw %>
 ```
 <% } -%>
 
 > [!TIP]
-> Generated by <%~ it.modelsText %><% if (typeof it.confidence === "number") { %> at <%= it.confidence %> confidence<% } %>.
-<% if (it.reasoning) { -%>
+> Generated by <%~ it.modelsText %> at <%= it.confidence %> confidence.
 > <details>
 > <summary>Reasoning</summary>
 >
@@ -22,4 +30,3 @@
 <% }) -%>
 >
 > </details>
-<% } -%>