@jphutchins/code-review 0.1.0-alpha.65 → 0.1.0-alpha.67

package/package.json

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

@@ -75,7 +75,7 @@ ignored); a version outside the supported set degrades to a §5.5 sticky notice.
 | `v0.6.0` | superseded | Adds optional `systemic_problems` — an array of cross-cutting observations that tie findings together and are hard to express with a line range, each item with required `title`/`description`/`severity`/`reasoning`/`confidence` and optional `code`/`code_url`/`finding_codes`/`paths` (no line anchors). Refocuses `summary` on justifying the overall verdict rather than restating findings. Backwards-compatible (a `0.5` document is a valid `0.6` document); the CLI keeps resolving `0.4`/`0.5` via identity upcasts. |
 | `v0.9.0` | superseded (frozen at `schema/v0.9/`) | Adds a REQUIRED `likelihood` (0..1) to every finding and systemic problem (issue #163): the probability the triggering input/state actually occurs — distinct from `confidence` (whether the defect is real) — folded into the convergence score as a second multiplier. **Breaking**: a pre-0.9 document lacks `likelihood` and no longer validates, so a stale sticky degrades to a sentinel-only seed (one cold re-review) rather than seeding. The draft axis skips `0.7`/`0.8`: those are the surface-signal axis's versions (below), so the draft jumps past them to keep the two version spaces distinct — a draft must never be mistaken for a legacy surfaced blob (issue #156). |
 | `v0.10.0` | superseded | Renames the mechanism identifier `code` → `id` and makes it **required** on every finding (issue #246), so every finding is always trackable across rounds and discussions. Systemic problems rename `code`/`finding_codes` → `id`/`finding_ids`; convergence rounds rename `codes` → `ids`; `scope_metastasis.recurring` renames `code` → `id`. `change_size.code` (the role bucket) and `code_url` keep their names. **Breaking**: a pre-0.10 document lacks `id` — the registry upcasts every pre-0.10 minor through one tolerant legacy codec (`code` → `id`, or a synthesized content-derived id — sha256 of path+title — when a finding carried none), so a legacy sticky still seeds a re-review with its ids intact, and the pre-0.10 shape stays frozen at `schema/v0.9/` (above). |
-| `v0.11.0` | **current** (draft) | Adds an optional `rebuttal` to every finding and systemic problem: on a re-raise, the reviewer's answer to the response recorded against that id (the review dialogue, #247). A re-raise that carries a non-blank `rebuttal` is never a verbatim re-raise. A rebuttal answers one round's response, so the re-review seed strips rebuttals from the prior review it carries forward, and a re-raise must supply its own. The legacy codec drops a `rebuttal` on a pre-0.10 document, which the frozen `v0.9` file rejects: the one deliberate codec-only tolerance, since only a hybrid document ever carries one. The systemic `id` description now states that a re-raise of the same class reuses the id. Backwards-compatible: a `0.10` document is a valid `0.11` document, so both minors resolve through the same live file and codec, the way `0.4`–`0.9` share the frozen legacy file. Draft until the next release, so the dialogue's later phases may still add to it. |
+| `v0.11.0` | **current** (draft) | Adds an optional `rebuttal` to every finding and systemic problem: on a re-raise, the reviewer's answer to the response recorded against that id (the review dialogue, #247). A re-raise that carries a non-blank `rebuttal` is never a verbatim re-raise. A rebuttal answers one round's response, so the re-review seed strips rebuttals from the prior review it carries forward, and a re-raise must supply its own. The legacy codec drops a `rebuttal` on a pre-0.10 document, which the frozen `v0.9` file rejects: the one deliberate codec-only tolerance, since only a hybrid document ever carries one. The systemic `id` description now states that a re-raise of the same class reuses the id. Adds an optional top-level `unfinished`: the checks a review planned but did not complete, rendered beside the convergence badge. Backwards-compatible: a `0.10` document is a valid `0.11` document, so both minors resolve through the same live file and codec, the way `0.4`–`0.9` share the frozen legacy file. Draft until the next release, so the dialogue's later phases may still add to it. |
 
 ### Surface channel (stop signal)
 

package/schema/findings.schema.json

@@ -176,6 +176,11 @@
         }
       }
     },
+    "unfinished": {
+      "type": "array",
+      "description": "Checks this review planned but did not complete, one entry each.",
+      "items": { "type": "string", "pattern": "\\S" }
+    },
     "change_size": {
       "type": "object",
       "additionalProperties": false,

package/templates/comment.eta

@@ -47,22 +47,88 @@
 <% } -%>
 
 <%~ it.findings.summary %>
-<% const c = it.severityCounts %><% const findingsTotal = c.critical + c.major + c.minor + c.nit %>
-<% if (it.teachesResponses && (findingsTotal > 0 || it.systemic.length > 0)) { -%>
+<% if (it.unfinished.length > 0) { -%>
 
-<sub><%~ it.responseTeaching %></sub>
+> [!WARNING]
+> **Unfinished checks** — this round did not complete every check it planned, so its convergence covers less than a full review:
+<% it.unfinished.forEach(function(check) { -%>
+> - <%~ check %>
+<% }) -%>
+<% } -%>
+<% const c = it.severityCounts %><% const findingsTotal = c.critical + c.major + c.minor + c.nit -%>
+<% if (it.strays.length > 0 || (!it.incomplete && (findingsTotal > 0 || it.systemic.length > 0 || it.contested.length > 0))) { -%>
+
+## <% if (it.strays.length === 0) { %>Findings<% } else if (it.inlineDisposition && (it.inlineDisposition.kind === 'disabled' || it.inlineDisposition.kind === 'whole-document')) { %>Findings<% } else if (it.inlineDisposition && it.inlineDisposition.kind === 'no-envelope') { %>Findings (no inline review — result envelope lost)<% } else { %><%= (it.unanchoredCount && it.unanchoredCount > 0) ? 'Findings' : 'Findings outside the diff' %><% } %>
+<% if (it.strays.length > 0) { %>
+<% if (it.inlineDisposition && it.inlineDisposition.kind === 'no-envelope') { %>
+<% if (it.shedCount === 0) { %>
+_Every finding is listed below — the inline review could not be built because the result envelope was missing._
+<% } -%>
+<% } else if (it.inlineDisposition && it.inlineDisposition.kind === 'whole-document') { %>
+_Every finding from this run<% if (it.inlineDisposition.inlineCount > 0) { %>, including the <%= it.inlineDisposition.inlineCount %> posted as inline comment<%= it.inlineDisposition.inlineCount === 1 ? '' : 's' %> on the diff<% } %><% if (it.inlineDisposition.rejectedCount > 0) { %>; <%= it.inlineDisposition.rejectedCount %> could not be anchored (GitHub rejected the position)<% } %>._
+<% } else if (it.unanchoredCount && it.unanchoredCount > 0) { %>
+_<%= it.unanchoredCount %> finding<%= it.unanchoredCount === 1 ? '' : 's' %> below couldn't be posted as inline comment<%= it.unanchoredCount === 1 ? '' : 's' %> (GitHub rejected the position)<% if (it.strays.length > it.unanchoredCount) { %>; the rest are outside the diff<% } %>._
+<% } %>
+<% } %>
+<% if (it.teachesResponses && (findingsTotal > 0 || it.systemic.length > 0 || it.contested.length > 0)) { -%>
+
+<details><summary>How to answer these findings</summary>
+
+<%~ it.responseTeaching %>
+</details>
+<% } -%>
+<% if (!it.incomplete && it.contested.length > 0) { -%>
+
+### ⚖️ Contested
+
+_The reviewer rebutted a maintainer's answer, and a maintainer answered again. Each stays in the score at a fixed weight, whether or not it is raised again, until a maintainer rules._
+<% if (it.teachesResponses) { -%>
+
+<%~ it.rulingTeaching %>
+<% } -%>
+
+<% it.contested.forEach(function(k) { -%>
+#### <%= it.severityEmoji(k.severity) %> (<%= k.severity %>) <%= k.title %>
+<sub><% if (k.reRaise && k.reRaise.location) { %>`<%~ k.reRaise.location %>` · <% } %>id `<%~ k.id %>` · [the maintainer's latest answer](<%~ k.answerUrl %>)</sub>
+<% if (k.reRaise) { -%>
+
+<%~ k.reRaise.description %>
+<% if (k.reRaise.rebuttal) { -%>
+
+**Rebuttal:** <%~ k.reRaise.rebuttal %>
 <% } -%>
 
+> <details><summary>Reasoning</summary>
+>
+<% k.reRaise.reasoning.split("\n").forEach(function(rl) { -%>
+> <%= rl %>
+<% }) -%>
+>
+> </details>
+<% } -%>
+<% if (k.discussionHtml) { -%>
+
+<details><summary>💬 Discussion</summary>
+
+<%~ k.discussionHtml %>
+</details>
+<% } -%>
+<% }) -%>
+<% } -%>
 <% if (!it.incomplete && it.systemic.length > 0) { -%>
 
-## 🔗 Systemic problems
+### 🔗 Systemic problems
 
 <% it.systemic.forEach(function(s) { -%>
-### <%= it.severityEmoji(s.severity) %> (<%= s.severity %>) <%= s.title %>
+#### <%= it.severityEmoji(s.severity) %> (<%= s.severity %>) <%= s.title %>
 <sub>confidence <%= it.formatConfidence(s.confidence) %><% if (s.id) { %> · id <% if (s.code_url) { %>[`<%~ s.id %>`](<%~ s.code_url %>)<% } else { %>`<%~ s.id %>`<% } %><% } %></sub>
 <% const meta = [] %><% if (s.paths && s.paths.length > 0) { meta.push('Affects: ' + s.paths.map(function(p) { return '`' + p + '`' }).join(', ')) } %><% if (s.finding_ids && s.finding_ids.length > 0) { meta.push('Ties together: ' + s.finding_ids.map(function(c) { return '`' + c + '`' }).join(', ')) } %><% if (meta.length > 0) { %>_<%~ meta.join(' · ') %>_<% } %>
 
 <%~ s.description %>
+<% if (s.answeredNote) { -%>
+
+> ↩️ <%~ s.answeredNote %>
+<% } -%>
 <% if (it.hasRebuttal(s)) { -%>
 
 **Rebuttal:** <%~ s.rebuttal %>
@@ -84,6 +150,7 @@
 > </details>
 <% }) -%>
 <% } -%>
+<% } -%>
 
 ---
 
@@ -99,7 +166,10 @@
 <% 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 if (!it.incomplete && it.systemic.length === 0 && !it.answeredReRaiseNote) { %>
+<% } else if (!it.incomplete && (it.systemic.length > 0 || it.contested.length > 0)) { %>
+<% const held = [] %><% if (it.contested.length > 0) { held.push(it.contested.length + ' contested item' + (it.contested.length === 1 ? '' : 's')) } %><% if (it.systemic.length > 0) { held.push(it.systemic.length + ' systemic problem' + (it.systemic.length === 1 ? '' : 's')) } %>
+_No findings beyond the <%= held.join(' and ') %> above._
+<% } else if (!it.incomplete && !it.answeredReRaiseNote) { %>
 <% if (it.unverifiedNoLogs) { %>_No findings — but no failing-job logs were staged, so this pass could not read the CI failure. "No findings" is not evidence of none._<% } else { %>_No findings — clean review._<% } %>
 <% } %>
 
@@ -118,16 +188,6 @@
 <% } %>
 
 <% if (it.strays.length > 0) { %>
-## <% if (it.inlineDisposition && (it.inlineDisposition.kind === 'disabled' || it.inlineDisposition.kind === 'whole-document')) { %>Findings<% } else if (it.inlineDisposition && it.inlineDisposition.kind === 'no-envelope') { %>Findings (no inline review — result envelope lost)<% } else { %><%= (it.unanchoredCount && it.unanchoredCount > 0) ? 'Findings' : 'Findings outside the diff' %><% } %>
-<% if (it.inlineDisposition && it.inlineDisposition.kind === 'no-envelope') { %>
-<% if (it.shedCount === 0) { %>
-_Every finding is listed below — the inline review could not be built because the result envelope was missing._
-<% } -%>
-<% } else if (it.inlineDisposition && it.inlineDisposition.kind === 'whole-document') { %>
-_Every finding from this run<% if (it.inlineDisposition.inlineCount > 0) { %>, including the <%= it.inlineDisposition.inlineCount %> posted as inline comment<%= it.inlineDisposition.inlineCount === 1 ? '' : 's' %> on the diff<% } %><% if (it.inlineDisposition.rejectedCount > 0) { %>; <%= it.inlineDisposition.rejectedCount %> could not be anchored (GitHub rejected the position)<% } %>._
-<% } else if (it.unanchoredCount && it.unanchoredCount > 0) { %>
-_<%= it.unanchoredCount %> finding<%= it.unanchoredCount === 1 ? '' : 's' %> below couldn't be posted as inline comment<%= it.unanchoredCount === 1 ? '' : 's' %> (GitHub rejected the position)<% if (it.strays.length > it.unanchoredCount) { %>; the rest are outside the diff<% } %>._
-<% } %>
 
 <% it.strays.forEach(function(f) { -%>
 ### <%= it.severityEmoji(f.severity) %> (<%= f.severity %>) `<%= f.path %>:<%= f.rangeLabel %><% if (f.side) { %> (<%= f.side %>)<% } %>` — <%= f.title %>