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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jphutchins/code-review",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "description": "Deterministic commenter for agentic PR review — gather, render, inline, post, adapt, extract, cost, validate, print-schema",
   "type": "module",
   "license": "MIT",
@@ -48,6 +48,7 @@
     "eslint-config-prettier": "^10.1.8",
     "prettier": "^3.9.4",
     "tsup": "^8.3.5",
+    "tsx": "^4.23.0",
     "typescript": "^5.7.3",
     "typescript-eslint": "^8.62.1",
     "vitest": "^3.0.4"

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/JPHutchins/code-review/main/schema/findings.schema.json",
   "title": "Code Review — findings",
-  "description": "Structured output of an agentic PR review. The review agent emits this object (e.g. via a coding-agent CLI's structured-output mode, such as Claude Code's `--json-schema`, whose result lands in `.structured_output`); a deterministic commenter renders it into a sticky summary comment and inline PR review comments. Agent- and provider-agnostic: any model driven by a compatible CLI adapter may produce it. Kept free of $ref/$defs so the same file works for both JSON-Schema validators and CLI structured-output enforcement.",
+  "description": "Structured output of an agentic PR code review. The review agent emits this object (e.g. via a coding-agent CLI's structured-output mode, such as Claude Code's `--json-schema`, whose result lands in `.structured_output`, or a file).",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema_version", "summary", "verdict", "findings"],
@@ -10,24 +10,33 @@
     "schema_version": {
       "type": "string",
       "pattern": "^(0|[1-9]\\d*)\\.(\\d+)\\.(\\d+)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$",
-      "description": "Semver version of this findings schema the object conforms to (e.g. \"0.1.0\"). Lets a commenter detect a version mismatch rather than silently dropping fields."
+      "description": "Semver version of this findings schema the object conforms to (e.g. \"0.1.0\")."
     },
     "summary": {
       "type": "string",
-      "description": "Markdown walkthrough of the change and the overall assessment; rendered as the body of the sticky summary comment."
+      "description": "1-4 sentence markdown walkthrough of the overall assessment."
     },
     "verdict": {
       "type": "string",
       "enum": ["approve", "comment", "changes"],
-      "description": "Overall stance. Advisory only: a conforming commenter posts the GitHub review as COMMENT and never REQUEST_CHANGES, surfacing this value as a badge."
+      "description": "Overall stance."
     },
     "findings": {
       "type": "array",
-      "description": "Zero or more specific findings. Each becomes one inline review comment when its line is inside the diff; otherwise it is demoted into the summary.",
+      "description": "Zero or more specific findings.",
       "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": "1-3 sentence markdown explanation of what is wrong. Details belong in `reasoning`."
           },
-          "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": "1-2 sentence markdown prose describing what to do about the finding — 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."
+            "description": "Optional single-hunk unified diff of one mechanical fix to this file, expressed against its current (post-change) content — e.g. the `git diff` of just that edit after you apply it. It MUST be exactly one hunk and one contiguous change, and its context and removed lines MUST match the file verbatim so it applies cleanly. Omit this field when there is no clean mechanical fix — never invent one; put prose guidance in `recommendation` instead."
           }
         }
       }

package/templates/comment.eta

@@ -1,12 +1,13 @@
 <!-- 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) %>
+<% if (it.postedAt) { -%>
+Reviewed `<%= it.reviewedSha.slice(0, 7) %>` · <%= it.postedAt %>
+<% } -%>
 
 <% const meta = [] %><% if (it.route) { meta.push('**Route:** ' + it.route) } %><% if (it.effort) { meta.push('**effort:** ' + it.effort) } %><% if (it.usageAvailable) { meta.push('**turns:** ' + it.envelope.turns); meta.push('**wall:** ' + it.formatDuration(it.envelope.duration_ms)); meta.push('**models:** ' + it.modelNames); meta.push('**cost:** ' + it.formatCost(it.costReport.totalCostUSD)) } else { meta.push('_usage unavailable_') } %><%~ meta.join(' · ') %>
 
@@ -36,8 +37,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 <%= it.formatConfidence(f.confidence) %>
   <details><summary>Reasoning</summary>
 
 <% f.reasoning.split("\n").forEach(function(rl) { -%>
@@ -45,6 +45,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 +97,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/schema/prices.example.json) 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.severityEmoji(it.severity) %> <%= it.severity.charAt(0).toUpperCase() + it.severity.slice(1) %>: **<%= it.title %>** · <%= it.formatConfidence(it.confidence) %> confidence
 
-<%~ 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 %>.
 > <details>
 > <summary>Reasoning</summary>
 >
@@ -22,4 +30,3 @@
 <% }) -%>
 >
 > </details>
-<% } -%>