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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jphutchins/code-review",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.6",
   "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,8 @@ 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` | **current** | Adds optional `reasoning` finding field. |
 
 ### Price-map schema
 

package/schema/findings.schema.json

@@ -47,7 +47,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",
@@ -73,13 +73,21 @@
           },
           "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."
+            "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."
           },
           "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."
+          },
+          "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."
+          },
+          "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."
           }
         }
       }

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,43 +1,52 @@
 <!-- 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 %> -->
+<% } -%>
 
 ### <%= 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 %>
 
 ---
 
-<% if (it.totalCount > 0) { %>
-#### 📊 Findings summary — <%= it.totalCount %> finding<%= it.totalCount === 1 ? '' : 's' %> on <%= it.fileCount %> file<%= it.fileCount === 1 ? '' : 's' %>
-
-<% if (it.visibleFindings.length > 0) { %>
-| Severity | File | Line | Summary |
-|---|---|---|---|
-<% it.visibleFindings.forEach(function(f) { %>
-| <%= it.severityEmoji(f.severity) %> <%= f.severity %> | `<%= f.path %>` | <%= f.start_line %><% if (f.start_line !== f.end_line) { %>–<%= f.end_line %><% } %> | <%= f.title %> |
-<% }) %>
+<% const c = it.severityCounts %><% const findingsTotal = c.critical + c.major + c.minor + c.nit %>
+<% if (findingsTotal > 0) { %>
+<% const parts = [] %><% if (c.critical) { parts.push(it.severityEmoji('critical') + ' ' + c.critical) } %><% if (c.major) { parts.push(it.severityEmoji('major') + ' ' + c.major) } %><% if (c.minor) { parts.push(it.severityEmoji('minor') + ' ' + c.minor) } %><% if (c.nit) { parts.push(it.severityEmoji('nit') + ' ' + c.nit) } %>
+**Findings:** <%~ parts.join(' · ') %>
+<% } else { %>
+_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) %>` — <% 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') { %>
+→ Inline review suppressed — `<%= it.inlineDisposition.sha.slice(0, 7) %>` was already reviewed.
 <% } %>
-<% if (it.nitFindings.length > 0) { %>
-<details>
-<summary>⚪ <%= it.nitFindings.length %> nit<%= it.nitFindings.length === 1 ? '' : 's' %> (folded)</summary>
 
-| File | Line | Summary |
-|---|---|---|
-<% it.nitFindings.forEach(function(f) { %>
-| `<%= f.path %>` | <%= f.start_line %><% if (f.start_line !== f.end_line) { %>–<%= f.end_line %><% } %> | <%= f.title %> |
-<% }) %>
+<% if (it.strays.length > 0) { %>
+#### ⚠️ Findings outside the diff
 
-</details>
-<% } %>
+These findings are on lines not in the diff, so they can't be anchored as inline comments:
 
-<% if (it.suggestionCount > 0) { %>
-<%= it.suggestionCount %> finding<%= it.suggestionCount === 1 ? '' : 's' %> included suggestions — see inline comments for details.
-<% } %>
-<% } else { %>
-_No findings — clean review._
+<% 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) { -%>
+  <details><summary>Reasoning</summary>
+
+<% f.reasoning.split("\n").forEach(function(rl) { -%>
+  <%= rl %>
+<% }) -%>
+
+  </details>
+<% } -%>
+<% }) %>
 <% } %>
 
 <% if (it.testReport) { %>
@@ -47,7 +56,7 @@ _No findings — clean review._
 <summary>📊 Test results — <%= it.testReport.passed %> passed, <%= it.testReport.failed %> failed</summary>
 
 <% if (it.testReport.failed > 0 && it.testReport.failures) { %>
-<% it.testReport.failures.forEach(function(f) { %>
+<% it.testReport.failures.forEach(function(f) { -%>
 - **<%= f.name %>**<% if (f.message) { %> — <%~ f.message %><% } %>
 <% }) %>
 <% } else { %>
@@ -59,24 +68,20 @@ All <%= it.testReport.total %> tests passed.
 
 ---
 
-<% if (it.usageAvailable && it.costReport.lines.length > 0) { %>
-<sub>
-
-| 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) %> |
-<% }) %>
-| **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 { %>
+> [!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) %> |
+<% }) -%>
+> | **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.
+<% } -%>
+>
+> _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,25 @@
+<% if (it.jsonUrl) { -%>
+<!-- code-review:findings-json <%~ it.jsonUrl %> -->
+<% } -%>
+<%= it.severityEmoji(it.severity) %> **<%= it.severity %>** — <%= it.title %>
+
 <%~ it.body %>
+<% if (it.suggestion !== null && it.suggestion !== undefined) { -%>
 
-<% if (it.suggestion !== null && it.suggestion !== undefined) { %>
 ```suggestion
 <%~ it.suggestion %>
 ```
-<% } %>
+<% } -%>
 
-<sub>🤖 AI-generated — advisory only</sub>
+> [!TIP]
+> Generated by <%~ it.modelsText %><% if (typeof it.confidence === "number") { %> at <%= it.confidence %> confidence<% } %>.
+<% if (it.reasoning) { -%>
+> <details>
+> <summary>Reasoning</summary>
+>
+<% it.reasoning.split("\n").forEach(function(rl) { -%>
+> <%= rl %>
+<% }) -%>
+>
+> </details>
+<% } -%>