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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jphutchins/code-review",
-  "version": "0.1.0-alpha.5",
+  "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

@@ -65,7 +65,9 @@ ignored); a version outside the supported set degrades to a §5.5 sticky notice.
 | Version | Status | Notes |
 |---|---|---|
 | `v0.1.0` | superseded | Initial schema. Matches the proven camas reference implementation. |
-| `v0.2.0` | **current** | Adds required `schema_version`; optional `code`/`code_url` finding fields; normative `suggestion` `""`/`null` semantics; abstract vendor-neutral envelope (see SPEC §6.1). |
+| `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` | 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",
@@ -47,7 +56,7 @@
             "type": "string",
             "enum": ["RIGHT", "LEFT"],
             "default": "RIGHT",
-            "description": "RIGHT for added/changed lines, LEFT for removed lines; matches the GitHub pulls reviews API."
+            "description": "As in a unified-diff view: RIGHT for added/changed lines, LEFT for removed lines."
           },
           "severity": {
             "type": "string",
@@ -67,19 +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": "null = no mechanical fix (render no suggestion block); \"\" (empty string) = delete start_line..end_line (render an empty suggestion block); non-empty = exact replacement text for start_line..end_line (render a GitHub suggestion block). A suggestion spanning more than GitHub's single-block line limit is demoted to the summary."
+          "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": "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", "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/schema/v0.2/findings.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/JPHutchins/code-review/schema-v0.2.0/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.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "summary", "verdict", "findings"],
+  "properties": {
+    "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."
+    },
+    "summary": {
+      "type": "string",
+      "description": "Markdown walkthrough of the change and the overall assessment; rendered as the body of the sticky summary comment."
+    },
+    "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."
+    },
+    "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.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "start_line", "end_line", "severity", "title", "body"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Repo-relative file path the finding anchors to."
+          },
+          "start_line": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "1-indexed first line of the anchored range (post-change state when side is RIGHT)."
+          },
+          "end_line": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "1-indexed last line of the range; MUST be >= start_line. A suggestion replaces exactly start_line..end_line."
+          },
+          "side": {
+            "type": "string",
+            "enum": ["RIGHT", "LEFT"],
+            "default": "RIGHT",
+            "description": "RIGHT for added/changed lines, LEFT for removed lines; matches the GitHub pulls reviews API."
+          },
+          "severity": {
+            "type": "string",
+            "enum": ["critical", "major", "minor", "nit"],
+            "description": "Used for grouping and for folding nits into a collapsed section."
+          },
+          "code": {
+            "type": "string",
+            "description": "Stable rule identifier (e.g. \"null-check-missing\") for rule-based filtering, suppression, and cross-run dedup."
+          },
+          "code_url": {
+            "type": "string",
+            "format": "uri",
+            "description": "URL documenting the rule named by code."
+          },
+          "title": {
+            "type": "string",
+            "description": "One-line summary of the finding."
+          },
+          "body": {
+            "type": "string",
+            "description": "Markdown explanation; rendered as the inline comment body."
+          },
+          "suggestion": {
+            "type": ["string", "null"],
+            "description": "null = no mechanical fix (render no suggestion block); \"\" (empty string) = delete start_line..end_line (render an empty suggestion block); non-empty = exact replacement text for start_line..end_line (render a GitHub suggestion block). A suggestion spanning more than GitHub's single-block line limit is demoted to the summary."
+          },
+          "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."
+          }
+        }
+      }
+    }
+  }
+}

package/templates/comment.eta

@@ -1,9 +1,12 @@
 <!-- code-review -->
 <!-- reviewed-sha: <%= it.reviewedSha %> -->
+<% if (it.findingsPointer) { -%>
+<%~ it.findingsPointer %>
+<% } -%>
 
 ### <%= it.verdictBadge(it.findings.verdict) %>
 
-<% 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)) } else { meta.push('_usage unavailable_') } %><%~ meta.join(' · ') %>
+<% 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(' · ') %>
 
 <%~ it.findings.summary %>
 
@@ -18,7 +21,7 @@ _No findings — clean review._
 <% } %>
 
 <% if (it.inlineDisposition && it.inlineDisposition.kind === 'posted') { %>
-→ <%= it.inlineDisposition.count %> comment<%= it.inlineDisposition.count === 1 ? '' : 's' %> posted inline on `<%= it.inlineDisposition.sha.slice(0, 7) %>` — see the review.
+→ <%= it.inlineDisposition.count %> comment<%= it.inlineDisposition.count === 1 ? '' : 's' %> posted inline on `<%= it.inlineDisposition.sha.slice(0, 7) %>` — <% if (it.reviewUrl) { %>[see the review](<%~ it.reviewUrl %>)<% } else { %>see the review<% } %>.
 <% } else if (it.inlineDisposition && it.inlineDisposition.kind === 'none-in-diff') { %>
 → No inline comments — all findings are outside the diff (listed below).
 <% } else if (it.inlineDisposition && it.inlineDisposition.kind === 'suppressed-existing-review') { %>
@@ -31,7 +34,29 @@ _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 %>
+- <%= 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) { -%>
+  <%= rl %>
+<% }) -%>
+
+  </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 %>
+```
+<% } -%>
 <% }) %>
 <% } %>
 
@@ -54,24 +79,24 @@ All <%= it.testReport.total %> tests passed.
 
 ---
 
-<% if (it.usageAvailable && it.costReport.lines.length > 0) { %>
-<sub>
-
-| Model | Input | Output | Cache read | Cache write | Cost |
-|---|--:|--:|--:|--:|--:|
+> [!WARNING]
+> **LLM Disclosure** — this review was produced by <%= it.modelNames || "unknown model" %>.
+>
+<% if (it.usageAvailable && it.costReport.lines.length > 0) { -%>
+> | Model | Input | Output | Cache read | Cache write | Cost |
+> |---|--:|--:|--:|--:|--:|
 <% it.costReport.lines.forEach(function(l) { -%>
-| <%= l.model %> | <%= it.formatTokens(l.inputTokens) %> | <%= it.formatTokens(l.outputTokens) %> | <%= it.formatTokens(l.cacheReadTokens) %> | <%= it.formatTokens(l.cacheWriteTokens) %> | <%= it.formatCost(l.costUSD) %> |
+> | <%= l.model %> | <%= it.formatTokens(l.inputTokens) %> | <%= it.formatTokens(l.outputTokens) %> | <%= it.formatTokens(l.cacheReadTokens) %> | <%= it.formatTokens(l.cacheWriteTokens) %> | <%= it.formatCost(l.costUSD) %> |
 <% }) -%>
-| **Total** | **<%= it.formatTokens(it.costReport.totalInputTokens) %>** | **<%= it.formatTokens(it.costReport.totalOutputTokens) %>** | **<%= it.formatTokens(it.costReport.totalCacheReadTokens) %>** | **<%= it.formatTokens(it.costReport.totalCacheWriteTokens) %>** | **<%= it.formatCost(it.costReport.totalCostUSD) %>** |
-
-</sub>
-<% } else if (it.usageAvailable) { %>
-<sub>No per-model usage was recorded for this run.</sub>
-<% } else { %>
+> | **Total** | **<%= it.formatTokens(it.costReport.totalInputTokens) %>** | **<%= it.formatTokens(it.costReport.totalOutputTokens) %>** | **<%= it.formatTokens(it.costReport.totalCacheReadTokens) %>** | **<%= it.formatTokens(it.costReport.totalCacheWriteTokens) %>** | **<%= it.formatCost(it.costReport.totalCostUSD) %>** |
+<% } else if (it.usageAvailable) { -%>
+> No per-model usage was recorded for this run.
+<% } else { -%>
 > **Usage/cost unavailable** — the result envelope for this run was missing or malformed.
-<% } %>
-
-> [!NOTE]
-> **LLM Disclosure** — this review was produced by <%= it.modelNames || "unknown model" %> running
-> headless in an ephemeral, egress-locked CI runner with no write access to the repository. It is
-> advisory and does not block merge.
+<% } -%>
+<% 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,9 +1,32 @@
-<%~ it.body %>
+<% if (it.findingsPointer) { -%>
+<%~ it.findingsPointer %>
+<% } -%>
+<%= it.severityEmoji(it.severity) %> **<%= it.severity %>** — <%= it.title %>
+
+<%~ it.description %>
+<% if (it.recommendation) { -%>
+
+**Recommended fix:** <%~ it.recommendation %>
+<% } -%>
+<% if (it.patchProjection.kind === "suggestion") { -%>
 
-<% if (it.suggestion !== null && it.suggestion !== undefined) { %>
 ```suggestion
-<%~ it.suggestion %>
+<%~ it.patchProjection.text %>
+```
+<% } else if (it.patchProjection.kind === "patch") { -%>
+
+```patch
+<%~ it.patchProjection.raw %>
 ```
-<% } %>
+<% } -%>
 
-<sub>🤖 AI-generated — advisory only</sub>
+> [!TIP]
+> Generated by <%~ it.modelsText %> at <%= it.confidence %> confidence.
+> <details>
+> <summary>Reasoning</summary>
+>
+<% it.reasoning.split("\n").forEach(function(rl) { -%>
+> <%= rl %>
+<% }) -%>
+>
+> </details>