@jphutchins/code-review 0.1.0-alpha.46 → 0.1.0-alpha.48

package/package.json

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

@@ -76,21 +76,25 @@ ignored); a version outside the supported set degrades to a §5.5 sticky notice.
 
 The commenter embeds the agent's **complete** findings document verbatim in review comments
 (`<!-- code-review:findings-json -->`) — no surfaced copy, no added fields (issue #156). The
-deterministic stop signal an iterating author-agent needs rides its own compact
-`<!-- code-review:signal -->` marker beside the blob: the pipeline-computed `convergence` (`{score,
-threshold, converged}` — a literal boolean, so a decoding agent cannot re-derive the weights) and
-`round` (the count of completed full-review rounds) of the last completed full-review round. The
-agent never writes the signal (it cannot know the score — the weights and threshold are
-commenter-side), so the findings schema above describes the whole embedded document; the signal
-marker declares its own surface version:
+deterministic stop signal an iterating author-agent needs is the pipeline-stamped `convergence` field
+INSIDE that document (issue #174): `{score, threshold, converged}` (a literal boolean, so a decoding
+agent cannot re-derive the weights) plus the per-round `rounds` trajectory. It is the single source of
+truth — the agent never writes it (it cannot know the score; the weights and threshold are
+commenter-side), and the findings schema above describes the whole embedded document, `convergence`
+included. When an oversized review falls to the link form (the blob is a URL, not base64), the same
+stamped object rides a compact `<!-- code-review:convergence -->` marker beside the link (issue #185)
+so the trajectory and stop signal survive; the embedded blob always wins on read.
+
+Two older surface formats survive only as READ-ONLY migration inputs — a re-review may still parse a
+sticky posted by an earlier release. Nothing writes either anymore:
 
 | Version | Status | Notes |
 |---|---|---|
-| `v0.7.0` | superseded | The pre-#156 surface axis: the commenter embedded a **surfaced** copy of the findings document carrying `convergence` + `round` inside it (issue #141). A sticky written by a `0.7.0` release still seeds — `stripSurfaceFields` peels the surfaced copy back to the agent's draft. |
-| `v0.8.0` | **current** | The version the compact `code-review:signal` marker declares (and the version a legacy `0.8.0` surfaced blob declared). `0.8.0` added the agent-facing `scope_metastasis` entry (issue #150): per-code consecutive-round recurrence counts plus a decision prompt. Post-#156 that entry is embedded in no document — the re-review seed re-derives it from the rounds marker and delivers it to the next-round agent. The flat draft schema (now `v0.9.0`) accepts an optional `scope_metastasis` property so a seed-echoing draft validates — an in-place additive change, deliberately NOT a draft version bump: a draft sharing a `0.7.0`/`0.8.0` number would collide with the surface axis's version gate, so the draft axis skips past them to `0.9.0` (issue #163); the axes must stay distinct so `stripSurfaceFields`/`parseSurfaceSignal` can tell a legacy surfaced blob from a draft). |
+| `v0.7.0` | legacy (read-only) | The pre-#156 surface axis: the commenter embedded a **surfaced** copy of the findings document carrying `convergence` + `round` inside it (issue #141). A sticky written by a `0.7.0` release still seeds — `stripSurfaceFields` peels the surfaced copy back to the agent's draft. |
+| `v0.8.0` | legacy (read-only) | The version a compact `<!-- code-review:signal -->` marker declared (and a legacy `0.8.0` surfaced blob). Its writer is retired (issue #186); `parseSignalMarker` / `parseSurfaceSignal` still decode it so a pre-#185 sticky seeds. `0.8.0` also added the agent-facing `scope_metastasis` entry (issue #150): per-code consecutive-round recurrence counts plus a decision prompt. Post-#156 that entry is embedded in no document — the re-review seed re-derives it from the carried trajectory. The flat draft schema (now `v0.9.0`) accepts an optional `scope_metastasis` property so a seed-echoing draft validates — an in-place additive change, deliberately NOT a draft version bump: a draft sharing a `0.7.0`/`0.8.0` number would collide with the surface axis's version gate, so the draft axis skips past them to `0.9.0` (issue #163); the axes must stay distinct so `stripSurfaceFields`/`parseSurfaceSignal` can tell a legacy surfaced blob from a draft). |
 
-The surface axis is independent of the draft-version registry: `v0.8.0` is the signal marker's
-contract, while the agent-written document above is now `v0.9.0`. `stripSurfaceFields` and
+The surface axis is independent of the draft-version registry: it numbers the legacy read-only signal
+formats, while the agent-written document above is `v0.9.0`. `stripSurfaceFields` and
 `parseSurfaceSignal` are version-gated on the surface axis, so a future draft bump can never be
 mistaken for a legacy surfaced blob — and no fresh document is ever surfaced.
 
@@ -102,7 +106,8 @@ policy; the `main` `$id` tracks latest, tagged releases pin to the version. Its
 
 | Version | Status | Notes |
 |---|---|---|
-| `v0.1.0` | **current** | Initial price-map schema. Per-model `in`/`out`/`cache_read`/`cache_write` (USD per 1M tokens); `_updated` date; `_unit`. |
+| `v0.1.0` | superseded | Initial price-map schema. Per-model `in`/`out`/`cache_read`/`cache_write` (USD per 1M tokens); `_updated` date; `_unit`. |
+| `v0.2.0` | **current** | A model's value is now a `oneOf` (issue #170): the flat shape above, OR `{ "slots": [ { "utc_from", "utc_to", "in", "out", "cache_read", "cache_write" } ] }` — UTC time-of-day pricing (half-open `[utc_from, utc_to)` windows; `utc_to <= utc_from` wraps past midnight; slots must partition the 24h day). Additive/backward-compatible: every flat map keeps validating. |
 
 The `_updated` field inside a price-map instance tracks **price drift** (a data concern) and is
 distinct from the schema's semver version (a **contract** concern). Adding a new price field (e.g. a

package/schema/findings.schema.json

@@ -172,6 +172,40 @@
         }
       }
     },
+    "change_size": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Best-effort (issue #182): the change's added/removed line counts bucketed by ROLE. Fill this with a LOW-effort path heuristic, no file introspection: a file under a tests directory or matching *.test.* / *_test.* is `tests`; a *.md file, anything under docs/, or a license/config doc is `docs`; everything else is `code`. Sum the diff's added and removed lines per bucket. Omit a role that did not change, or omit the whole field if you cannot estimate it. Chrome only — never affects the verdict or the convergence score. (The per-language cloc table shown beside it is supplied deterministically by the pipeline, not by you.)",
+      "properties": {
+        "code": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["added", "removed"],
+          "properties": {
+            "added": { "type": "integer", "minimum": 0 },
+            "removed": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "tests": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["added", "removed"],
+          "properties": {
+            "added": { "type": "integer", "minimum": 0 },
+            "removed": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "docs": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["added", "removed"],
+          "properties": {
+            "added": { "type": "integer", "minimum": 0 },
+            "removed": { "type": "integer", "minimum": 0 }
+          }
+        }
+      }
+    },
     "findings": {
       "type": "array",
       "description": "Zero or more specific findings.",

package/schema/prices.example.json

@@ -1,9 +1,15 @@
 {
-  "_comment": "USD per 1,000,000 tokens. PRICES DRIFT — keep _updated current. cost = sum over models of (input*in + output*out + cache_read*cache_read + cache_write*cache_write) / 1e6. The CLI's vendor_cost_usd is vendor-priced and will be wrong for non-Anthropic backends; recompute from this map using the `models` array in the abstract result envelope (SPEC §6.1). Fill the zeros from your provider's pricing page.",
+  "_comment": "USD per 1,000,000 tokens. PRICES DRIFT — keep _updated current. cost = sum over models of (input*in + output*out + cache_read*cache_read + cache_write*cache_write) / 1e6. A model's value is EITHER a flat all-day price OR a { \"slots\": [...] } set of UTC time-of-day slots for peak/off-peak pricing (issue #170) — see schema/prices.schema.json for the rules: each slot is a half-open [utc_from, utc_to) UTC window, a slot whose utc_to <= utc_from wraps past midnight, and a model's slots must partition the 24h day with no gap or overlap. The CLI's vendor_cost_usd is vendor-priced and will be wrong for non-Anthropic backends; recompute from this map using the `models` array in the abstract result envelope (SPEC §6.1). Fill the zeros from your provider's pricing page.",
   "_updated": "2026-07-03",
   "_unit": "USD per 1M tokens",
   "models": {
     "deepseek-v4-pro": { "in": 0.0, "out": 0.0, "cache_read": 0.0, "cache_write": 0.0 },
-    "deepseek-v4-flash": { "in": 0.0, "out": 0.0, "cache_read": 0.0, "cache_write": 0.0 }
+    "deepseek-v4-flash": { "in": 0.0, "out": 0.0, "cache_read": 0.0, "cache_write": 0.0 },
+    "example-time-slotted-model": {
+      "slots": [
+        { "utc_from": "10:00", "utc_to": "01:00", "in": 0.0, "out": 0.0, "cache_read": 0.0, "cache_write": 0.0 },
+        { "utc_from": "01:00", "utc_to": "10:00", "in": 0.0, "out": 0.0, "cache_read": 0.0, "cache_write": 0.0 }
+      ]
+    }
   }
 }

package/schema/prices.schema.json

@@ -21,33 +21,86 @@
     },
     "models": {
       "type": "object",
-      "description": "Map of model identifier → per-token prices. Keys are the model identifiers as they appear in the result envelope's `models[].model`.",
+      "description": "Map of model identifier → per-token prices. Keys are the model identifiers as they appear in the result envelope's `models[].model`. A model's value is EITHER a flat all-day price (unchanged) OR a set of UTC time-of-day slots (issue #170), for a provider with peak/off-peak rates.",
       "additionalProperties": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["in", "out", "cache_read", "cache_write"],
-        "properties": {
-          "in": {
-            "type": "number",
-            "minimum": 0,
-            "description": "Price per 1M input tokens."
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["in", "out", "cache_read", "cache_write"],
+            "properties": {
+              "in": {
+                "type": "number",
+                "minimum": 0,
+                "description": "Price per 1M input tokens (cache-miss)."
+              },
+              "out": {
+                "type": "number",
+                "minimum": 0,
+                "description": "Price per 1M output tokens."
+              },
+              "cache_read": {
+                "type": "number",
+                "minimum": 0,
+                "description": "Price per 1M cache-read tokens (prompt-cache hits)."
+              },
+              "cache_write": {
+                "type": "number",
+                "minimum": 0,
+                "description": "Price per 1M cache-write tokens (prompt-cache population)."
+              }
+            }
           },
-          "out": {
-            "type": "number",
-            "minimum": 0,
-            "description": "Price per 1M output tokens."
-          },
-          "cache_read": {
-            "type": "number",
-            "minimum": 0,
-            "description": "Price per 1M cache-read tokens (prompt-cache hits)."
-          },
-          "cache_write": {
-            "type": "number",
-            "minimum": 0,
-            "description": "Price per 1M cache-write tokens (prompt-cache population)."
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["slots"],
+            "description": "UTC time-of-day pricing (issue #170). `slots` MUST partition the full 24h UTC day with no gap and no overlap: each is a half-open [utc_from, utc_to) window, and a slot whose utc_to <= utc_from wraps past midnight. Everything is UTC — there is no timezone or DST field. Cost recomputation selects the one slot covering the run's UTC instant; a run's time-of-day matching zero or more than one slot is a misconfiguration that warns loudly and prices that model at $0 (never silently wrong).",
+            "properties": {
+              "slots": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["utc_from", "utc_to", "in", "out", "cache_read", "cache_write"],
+                  "properties": {
+                    "utc_from": {
+                      "type": "string",
+                      "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
+                      "description": "Slot start, HH:MM in UTC (inclusive)."
+                    },
+                    "utc_to": {
+                      "type": "string",
+                      "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
+                      "description": "Slot end, HH:MM in UTC (exclusive); a value <= utc_from wraps past midnight."
+                    },
+                    "in": {
+                      "type": "number",
+                      "minimum": 0,
+                      "description": "Price per 1M input tokens (cache-miss) in this slot."
+                    },
+                    "out": {
+                      "type": "number",
+                      "minimum": 0,
+                      "description": "Price per 1M output tokens in this slot."
+                    },
+                    "cache_read": {
+                      "type": "number",
+                      "minimum": 0,
+                      "description": "Price per 1M cache-read tokens (prompt-cache hits) in this slot."
+                    },
+                    "cache_write": {
+                      "type": "number",
+                      "minimum": 0,
+                      "description": "Price per 1M cache-write tokens in this slot."
+                    }
+                  }
+                }
+              }
+            }
           }
-        }
+        ]
       }
     }
   }

package/templates/comment.eta

@@ -9,9 +9,6 @@
 <% if (it.findingsPointer) { -%>
 <%~ it.findingsPointer %>
 <% } -%>
-<% if (it.roundsMarker) { -%>
-<%~ it.roundsMarker %>
-<% } -%>
 
 ### <%= it.verdictBadge(it.findings.verdict) %>
 
@@ -23,6 +20,18 @@
 <% if (it.convergenceSummary) { -%>
 <sub><%~ it.convergenceSummary %></sub>
 <% } -%>
+<% if (it.changeSummary) { -%>
+<sub>**Changes:** <%~ it.changeSummary %></sub>
+<% } -%>
+<% if (it.clocDiff) { -%>
+<details><summary>📏 cloc</summary>
+
+```
+<%~ it.clocDiff %>
+```
+
+</details>
+<% } -%>
 <% if (it.metastasisNote) { -%>
 <%~ it.metastasisNote %>
 <% } -%>