@jphutchins/code-review 0.1.0-alpha.50 → 0.1.0-alpha.52

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jphutchins/code-review",
-  "version": "0.1.0-alpha.50",
-  "description": "Deterministic commenter for agentic PR review — gather, render, inline, post, adapt, extract, cost, validate, print-schema",
+  "version": "0.1.0-alpha.52",
+  "description": "Deterministic commenter for agentic PR review \u2014 gather, render, inline, post, adapt, extract, cost, validate, print-schema",
   "type": "module",
   "license": "MIT",
   "author": "JP Hutchins <jp@intercreate.io>",

package/schema/VERSIONING.md

@@ -107,13 +107,40 @@ policy; the `main` `$id` tracks latest, tagged releases pin to the version. Its
 | Version | Status | Notes |
 |---|---|---|
 | `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. |
+| `v0.2.0` | superseded | 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. |
+| `v0.3.0` | **current** | Optional `weekend_slots` beside `slots` (issue #216): a second partition, same shape and same 24h-partition requirement, selected on Saturdays and Sundays in **Beijing** time (Friday 16:00 UTC → Sunday 16:00 UTC — a day-of-week rule, not a timezone axis). A model without it uses `slots` every day. Additive for readers that know the key; see the delivery rule below for readers that do not. |
 
 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
 future `cache_write_5m`) is a MINOR schema bump; updating a price value is only an `_updated`
 change.
 
+Every rate in a map states **current** pricing. Recomputing an old envelope reprices it at today's
+rates, so a cost recomputed long after the run is not a record of what was billed — this applies to
+the `weekend_slots` axis exactly as it applies to the numbers.
+
+#### Adding a key to a shipped map: the delivery-order rule
+
+A price map and the CLI that reads it travel by **different routes**. `.github/prices.json` is read
+from the default-branch checkout and takes effect the moment it merges; the CLI is installed from
+npm at the pinned `CODE_REVIEW_VERSION` and takes effect only when a release ships. The price codecs
+are strict-keyed by design (`SlottedModelPricesStrict` requires every key to be `slots`), so a map
+carrying a key the pinned CLI predates does not degrade — `PriceMapCodec` returns `Left` and `post`
+throws, taking down every review between the merge and the release.
+
+So a map key MUST NOT reach the default branch before the CLI that parses it:
+
+1. Merge the codec, schema, and tests on their own — safe in any order, since a newer CLI reads
+   every older map.
+2. Put the **data** change in the release commit itself, beside the `CODE_REVIEW_VERSION` bump, so
+   the map and the CLI that understands it land in the same commit and the same tag.
+3. Only then roll consumers — pin and map together, one commit each (a consumer's map is copied
+   from the tag).
+
+Verify before merging a map change: install the pinned version and decode the new map with it —
+`npx @jphutchins/code-review@$CODE_REVIEW_VERSION cost <envelope> --prices <new-map>` prints a cost
+if the pinned CLI accepts it and `prices does not match expected shape` if it does not.
+
 ## Compatibility with CLI structured-output enforcement
 
 The schema is **inlined** — no `$ref`, `$defs`, or `$id` fragments. This is an intentional

package/schema/prices.example.json

@@ -1,14 +1,38 @@
 {
-  "_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.",
+  "_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), optionally with a \"weekend_slots\" partition for a provider that prices weekends differently (issue #216) — see schema/prices.schema.json, whose field descriptions are the spec: 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-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
+    },
     "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 }
+        {
+          "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

@@ -5,7 +5,11 @@
   "description": "A date-stamped map of per-model token prices (USD per 1M tokens) the commenter uses to recompute canonical cost from the abstract result envelope's `models` array (SPEC §6.1). The CLI's `vendor_cost_usd` is vendor-priced and wrong for non-Anthropic backends; this map is the recomputation source. Kept free of $ref/$defs to match the findings schema's house style (inlining is not strictly required here — the price map is never passed to a model — but consistency with findings.schema.json is preferred).",
   "type": "object",
   "additionalProperties": false,
-  "required": ["_updated", "_unit", "models"],
+  "required": [
+    "_updated",
+    "_unit",
+    "models"
+  ],
   "properties": {
     "_comment": {
       "type": "string",
@@ -21,13 +25,18 @@
     },
     "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`. 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.",
+      "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), optionally with a second `weekend_slots` partition (issue #216), for a provider with peak/off-peak rates.",
       "additionalProperties": {
         "oneOf": [
           {
             "type": "object",
             "additionalProperties": false,
-            "required": ["in", "out", "cache_read", "cache_write"],
+            "required": [
+              "in",
+              "out",
+              "cache_read",
+              "cache_write"
+            ],
             "properties": {
               "in": {
                 "type": "number",
@@ -54,8 +63,10 @@
           {
             "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).",
+            "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. Slot times are always UTC and there is no timezone or DST field in the data. `weekend_slots` is an optional second partition (issue #216), selected on Saturdays and Sundays in BEIJING time — a day-of-week RULE, not a timezone axis: the Beijing weekend runs Friday 16:00 UTC to Sunday 16:00 UTC, so weekend-ness is NOT a property of the UTC date. It must partition the day exactly as `slots` does. Like every rate here it states CURRENT pricing, so recomputing an envelope from before a pricing change reprices it at today's rates rather than what was billed. A model with no `weekend_slots` uses `slots` every day. Cost recomputation selects the map first, then 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",
@@ -63,7 +74,14 @@
                 "items": {
                   "type": "object",
                   "additionalProperties": false,
-                  "required": ["utc_from", "utc_to", "in", "out", "cache_read", "cache_write"],
+                  "required": [
+                    "utc_from",
+                    "utc_to",
+                    "in",
+                    "out",
+                    "cache_read",
+                    "cache_write"
+                  ],
                   "properties": {
                     "utc_from": {
                       "type": "string",
@@ -97,6 +115,55 @@
                     }
                   }
                 }
+              },
+              "weekend_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."
+                    }
+                  }
+                },
+                "description": "Optional: the slot partition used on Beijing Saturdays and Sundays. Same shape and same 24h-partition requirement as `slots`."
               }
             }
           }

package/templates/comment.eta

@@ -31,6 +31,7 @@
 ```
 
 </details>
+
 <% } -%>
 <% if (it.metastasisNote) { -%>
 <%~ it.metastasisNote %>
@@ -66,11 +67,19 @@
 ---
 
 <% const c = it.severityCounts %><% const findingsTotal = c.critical + c.major + c.minor + c.nit %>
+<% if (it.unverifiedNoLogs && findingsTotal > 0) { %>
+> [!WARNING]
+> **Unverified — no failing-job logs were available.** This route reads the failing CI job's log to
+> name the failure; none could be staged for this run, so every finding below was reasoned from the
+> diff alone. Treat them as hypotheses until the log is checked.
+
+<% } %>
+
 <% 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) { %>
-_No findings — clean review._
+<% 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._<% } %>
 <% } %>
 
 <% if (it.inlineDisposition && it.inlineDisposition.kind === 'posted') { %>
@@ -79,12 +88,16 @@ _No findings — clean review._
 → No inline comments — all findings are outside the diff (listed below).
 <% } else if (it.inlineDisposition && it.inlineDisposition.kind === 'inline-unavailable') { %>
 → ⚠️ Inline comments couldn't be posted for this review (GitHub rejected a comment's position) — every finding is listed below instead.
+<% } else if (it.inlineDisposition && it.inlineDisposition.kind === 'whole-document') { %>
+→ This run's <%= it.incomplete ? 'review record' : 'complete review' %><% if (it.reviewUrl) { %> — [see the review](<%~ it.reviewUrl %>)<% } %>.
 <% } %>
 
 <% if (it.strays.length > 0) { %>
-### <% 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 === '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') { %>
 _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<% } %>._
 <% } %>