@erclx/canon 5.76.0 → 5.78.0

package/src/pr/evidence.ts

@@ -31,6 +31,9 @@ const LOCAL_SKIP_PREFIX = '**No local preview:**'
 /** How the line naming why no reel was filmed opens. */
 const REEL_SKIP_PREFIX = '**No reel:**'
 
+/** How the line naming the painted paths changed with no capture opens. */
+const UNCAPTURED_PREFIX = '**Uncaptured:**'
+
 /** The width a reel is filmed at, which it asks for in the comment. */
 const REEL_WIDTH = 960
 
@@ -59,8 +62,11 @@ const BOX_LINE = /^(\s*[-*+] \[)([ xX])(\] )(.*)$/
 /** The trailing segment a tick carries, naming the commit the box passed at. Matched only at the end of a line, so a box whose own text says `passed at` is left alone. */
 const STAMP = / · passed at `([0-9a-f]{7,40})`$/
 
-/** What ends the text of a box that a person has to judge by eye. */
-const TASTE_SUFFIX = '(taste)'
+/** The marker a box a person has to judge by eye carries among its trailing markers. */
+const TASTE_MARKER = '(taste)'
+
+/** The run of parenthesized markers that ends a box, such as `(taste) (local only)`, in any order. */
+const TRAILING_MARKERS = /(?:\s*\([^()]*\))+$/
 
 /** A `#issuecomment-<id>` suffix, which is the REST comment id `gh pr view` never returns directly. */
 const ISSUE_COMMENT_ID = /#issuecomment-(\d+)$/
@@ -476,6 +482,22 @@ function skipLines(prefix: string, reason: string | undefined): string[] {
   return text === '' ? [] : [`${prefix} ${escapeCell(text)}`, '']
 }
 
+/**
+ * The uncaptured line, or nothing once the list is empty or a reel filmed at
+ * this head shows the change. A reel at an earlier head leaves it, since a
+ * later push may have added the path.
+ */
+function uncapturedLines(
+  uncaptured: readonly string[],
+  head: string,
+  reel: EvidenceReel | undefined,
+): string[] {
+  if (uncaptured.length === 0) return []
+  if (reel !== undefined && head.startsWith(reel.head)) return []
+  const paths = uncaptured.map((path) => `\`${path}\``).join(', ')
+  return [`${UNCAPTURED_PREFIX} ${paths}`, '']
+}
+
 export function evidenceMarker(head: string): string {
   return `${MARKER_PREFIX} head=${head} -->`
 }
@@ -511,6 +533,10 @@ export function evidenceMarker(head: string): string {
  * A skip names why the local address or the reel is missing, on its own line
  * where that address or reel would sit. Each is dropped whenever its address
  * or reel renders, carried or passed, so a skip never outlives its cause.
+ *
+ * The uncaptured line names each painted path changed with no capture, under
+ * the reel, and is computed fresh on every render rather than carried, so it
+ * drops on the first render after a capture or a reel at the head lands.
  */
 export function renderEvidenceBody(
   states: readonly EvidenceState[],
@@ -522,6 +548,7 @@ export function renderEvidenceBody(
   local?: string,
   reel?: EvidenceReel,
   skips: EvidenceSkips = {},
+  uncaptured: readonly string[] = [],
 ): string {
   const segments = [
     ...(preview === undefined ? [] : [`${PREVIEW_PREFIX} ${preview}`]),
@@ -535,6 +562,7 @@ export function renderEvidenceBody(
     ...(reel === undefined
       ? skipLines(REEL_SKIP_PREFIX, skips.reel)
       : [reelLine(reel), '']),
+    ...uncapturedLines(uncaptured, head, reel),
   ]
   const closing =
     checklist === undefined
@@ -859,7 +887,7 @@ export interface ChecklistBox {
   readonly isTicked: boolean
   /** The short sha a tick names, absent on an empty box or a tick nothing stamped. */
   readonly stamp?: string
-  /** Whether the box ends in `(taste)`, which no driver ticks. */
+  /** Whether the box's trailing marker run holds `(taste)`, which no driver ticks. */
   readonly isTaste: boolean
 }
 
@@ -906,12 +934,23 @@ export function readChecklistBoxes(checklist: string): ChecklistBox[] {
       text: parsed.text,
       isTicked: parsed.isTicked,
       ...(parsed.stamp !== undefined && { stamp: parsed.stamp }),
-      isTaste: parsed.text.endsWith(TASTE_SUFFIX),
+      isTaste: hasTasteMarker(parsed.text),
     })
   })
   return boxes
 }
 
+function hasTasteMarker(text: string): boolean {
+  const run = TRAILING_MARKERS.exec(text)?.[0] ?? ''
+  const markers: readonly string[] = run.match(/\([^()]*\)/g) ?? []
+  return markers.includes(TASTE_MARKER)
+}
+
+/** The boxes a driver can run, being every box but a taste one. */
+export function countDrivable(boxes: readonly ChecklistBox[]): number {
+  return boxes.filter((box) => !box.isTaste).length
+}
+
 /** The head the marked comment's trailing marker names. */
 export function findEvidenceHead(
   comments: readonly EvidenceComment[],

package/src/pr/frames.ts

@@ -1,4 +1,5 @@
 import { readFile } from 'node:fs/promises'
+import { REEL_MAX_BYTES } from '@/take/reel'
 
 /** The branch holding review frames. It never merges into a branch anyone checks out. */
 export const FRAMES_BRANCH = 'canon/frames'
@@ -13,12 +14,6 @@ const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
 const RIFF = [0x52, 0x49, 0x46, 0x46]
 const WEBP = [0x57, 0x45, 0x42, 0x50]
 
-/**
- * The largest reel an add takes, GitHub's cap on an image in a comment, so a
- * reel that would not render is refused before it reaches the branch.
- */
-export const REEL_MAX_BYTES = 10_000_000
-
 const SHORT_HEAD_LENGTH = 7
 
 const HEAD_PATTERN = /^[0-9a-f]{7,40}$/

package/src/pr/lift.ts

@@ -4,9 +4,11 @@ import {
   type ReviewRow,
   resolveReviewScope,
   resolveUiScope,
+  standingPasses,
   type UiCounts,
 } from '@/pr/review-scope'
 import { readCarry } from '@/pr/carry'
+import { readWaivers } from '@/pr/waiver'
 import { DEFAULT_PAINTED, isPainted, type PaintedPatterns } from '@/pr/painted'
 
 /** How long `--wait` holds for a pending CI run, in seconds, when none is named. */
@@ -28,6 +30,7 @@ export type LiftRefusal =
   | 'ui-behind'
   | 'ui-undriven'
   | 'evidence-owed'
+  | 'painted-uncaptured'
   | 'standing-stale'
   | 'standing-conflict'
   | 'standing-unknown'
@@ -52,6 +55,10 @@ export interface GateResult {
   readonly paintedPaths?: readonly string[]
   /** Every path a box can observe that kept a UI close from carrying forward. */
   readonly drivenPaths?: readonly string[]
+  /** The painted paths changed with no capture, reel at the head, or waiver, sorted. */
+  readonly uncaptured?: readonly string[]
+  /** The uncaptured paths a review waived, sorted. */
+  readonly waived?: readonly string[]
 }
 
 /** How an earlier commit sits against the head, and what changed since. */
@@ -78,8 +85,35 @@ export interface PullState {
 export interface EvidenceGate {
   readonly isSettled: boolean
   readonly owed: readonly string[]
-  /** Whether the marked comment carries a visual checklist, which binds the UI gate. */
-  readonly hasChecklist: boolean
+  /** Whether the marked comment's checklist holds a box a driver can run, which binds the UI gate. */
+  readonly hasDrivableBox: boolean
+  /**
+   * The painted paths changed while no evidence image did, absent where the
+   * base keeps no captures, which reads as unchecked and passes.
+   */
+  readonly uncaptured?: readonly string[]
+  /** The head the marked comment's reel was filmed at, when it embeds one. */
+  readonly reelHead?: string
+}
+
+/**
+ * Whether an evidence record binds the UI family. A checklist binds unless
+ * the record counts zero drivable boxes, so a missing or unreadable count
+ * fails closed rather than reading as unbound.
+ */
+export function readsDrivableBox(record: {
+  readonly checklist?: unknown
+  readonly drivable?: unknown
+}): boolean {
+  if (typeof record.checklist !== 'string' || record.checklist === '') {
+    return false
+  }
+  const { drivable } = record
+  return !(
+    typeof drivable === 'number' &&
+    Number.isInteger(drivable) &&
+    drivable === 0
+  )
 }
 
 export interface ChecksGate {
@@ -219,13 +253,14 @@ export async function uiGate(
   painted: PaintedPatterns,
   reviews: readonly ReviewRow[],
   head: string,
-  hasChecklist: boolean,
+  hasDrivableBox: boolean,
 ): Promise<GateResult> {
-  if (!hasChecklist) return pass('ui')
-
   const scope = resolveUiScope({ reviews })
-  if (scope.state === 'none') return fail('ui', 'ui-missing')
+  // An open verdict holds the gate even once no drivable box remains, so
+  // dropping the checklist or marking a failed box taste never clears it.
   if (scope.state === 'open') return fail('ui', 'ui-open')
+  if (!hasDrivableBox) return pass('ui')
+  if (scope.state === 'none') return fail('ui', 'ui-missing')
   if (scope.source !== 'marker') return fail('ui', 'ui-unmarked')
   if (scope.commit === undefined) return fail('ui', 'ui-behind')
   // Ahead of the head test so a close carried across commits is refused too.
@@ -254,6 +289,39 @@ export async function uiGate(
   }
 }
 
+/**
+ * The evidence gate. An owed step refuses first. Then every painted path the
+ * pull request changed with no capture refuses, unless a reel filmed at the
+ * head shows it or a standing pass waived it by the path as the list spells it.
+ * A reel at an earlier head clears nothing, since a later push may add the
+ * path, and for the same reason a waiver counts only while the newest pass of
+ * its family restates it.
+ */
+export function evidenceGate(
+  evidence: EvidenceGate,
+  reviews: readonly ReviewRow[],
+  head: string,
+): GateResult {
+  if (!evidence.isSettled) return fail('evidence', 'evidence-owed')
+
+  const isFilmed =
+    evidence.reelHead !== undefined && coversHead(evidence.reelHead, head)
+  const listed = isFilmed ? [] : (evidence.uncaptured ?? [])
+  const named = new Set(
+    readWaivers(standingPasses(reviews)).map((waiver) => waiver.path),
+  )
+  const waived = listed.filter((path) => named.has(path)).toSorted()
+  const uncaptured = listed.filter((path) => !named.has(path)).toSorted()
+
+  const lists = {
+    ...(uncaptured.length > 0 && { uncaptured }),
+    ...(waived.length > 0 && { waived }),
+  }
+  return uncaptured.length > 0
+    ? { ...fail('evidence', 'painted-uncaptured'), ...lists }
+    : { ...pass('evidence'), ...lists }
+}
+
 function standingGate(standing: Standing): GateResult {
   if (standing === 'fresh') return pass('standing')
   return fail('standing', `standing-${standing}`)
@@ -409,8 +477,8 @@ export async function lift(
 
   const gates: GateResult[] = [
     reviewGate(reviews, tip),
-    await uiGate(api, painted, reviews, tip, evidence.hasChecklist),
-    evidence.isSettled ? pass('evidence') : fail('evidence', 'evidence-owed'),
+    await uiGate(api, painted, reviews, tip, evidence.hasDrivableBox),
+    evidenceGate(evidence, reviews, tip),
     standingGate(standing),
   ]
   if (!pull.isDraft) return settleReady(api, opts, pull, tip, gates)
@@ -481,7 +549,7 @@ export async function lift(
 
   const reread = [
     reviewGate(nowReviews, nowTip),
-    await uiGate(api, painted, nowReviews, nowTip, evidence.hasChecklist),
+    await uiGate(api, painted, nowReviews, nowTip, evidence.hasDrivableBox),
   ].find((gate) => !gate.isOk)
   if (reread?.reason !== undefined) {
     return refused(reread.reason, cleared, nowTip, ci.waited)

package/src/pr/rest.ts

@@ -39,6 +39,7 @@ export interface RestReview {
   readonly body?: string | null
   readonly commit_id?: string | null
   readonly submitted_at?: string | null
+  readonly state?: string | null
 }
 
 /** One row of `repos/{owner}/{repo}/issues/<n>/comments`. */
@@ -117,6 +118,7 @@ export function reviewRowOf(review: RestReview): ReviewRow {
         ? null
         : { oid: review.commit_id },
     submittedAt: review.submitted_at ?? null,
+    ...(typeof review.state === 'string' && { state: review.state }),
   }
 }
 

package/src/pr/review-scope.ts

@@ -47,6 +47,8 @@ export interface ReviewRow {
   readonly body?: string
   readonly commit?: { readonly oid?: string } | null
   readonly submittedAt?: string | null
+  /** GitHub's review state, `DISMISSED` once the operator withdrew the pass. */
+  readonly state?: string | null
 }
 
 /**
@@ -238,6 +240,32 @@ export function resolveUiScope(listing: ReviewListing): UiScope {
   }
 }
 
+/**
+ * The newest code pass and the newest UI pass, each only when its own marker
+ * closes it, skipping any pass the operator dismissed. A body with no pass
+ * heading never stands, and neither does an older pass a newer one replaced,
+ * so a pass speaks only for the head it read.
+ */
+export function standingPasses(reviews: readonly ReviewRow[]): ReviewRow[] {
+  let code: ReviewRow | undefined
+  let ui: ReviewRow | undefined
+  for (const row of reviews) {
+    if (row.state === 'DISMISSED') continue
+    const body = row.body ?? ''
+    if (headingOf(body) !== undefined) code = row
+    else if (resolveUiScope({ reviews: [row] }).state !== 'none') ui = row
+  }
+
+  const passes: ReviewRow[] = []
+  if (code !== undefined && markerOf(code.body ?? '') !== undefined) {
+    passes.push(code)
+  }
+  if (ui !== undefined && UI_MARKER.test(lastLine(ui.body ?? '') ?? '')) {
+    passes.push(ui)
+  }
+  return passes
+}
+
 /**
  * Whether a covered commit names the head. A marker may carry a short sha, so
  * coverage is a prefix match on the head.

package/src/pr/review-state.ts

@@ -94,7 +94,7 @@ function familyOf(gate: GateResult, commit: string | undefined, tip: string) {
  */
 async function readAt(
   api: ReviewStateApi,
-  hasChecklist: boolean,
+  hasDrivableBox: boolean,
   painted: PaintedPatterns,
 ): Promise<ReviewStateRead> {
   const [tip, reviews] = await Promise.all([api.readTip(), api.readReviews()])
@@ -105,7 +105,7 @@ async function readAt(
   const listing: { reviews: readonly ReviewRow[] } = { reviews }
   const scope = resolveReviewScope(listing)
   const uiScope = resolveUiScope(listing)
-  const ui = await uiGate(api, painted, reviews, tip, hasChecklist)
+  const ui = await uiGate(api, painted, reviews, tip, hasDrivableBox)
   if (ui.reason === 'gh-failed') return { kind: 'refused', reason: 'gh-failed' }
 
   return {
@@ -117,7 +117,7 @@ async function readAt(
       ui: {
         ...uiScope,
         ...familyOf(ui, uiScope.commit, tip),
-        isBound: hasChecklist,
+        isBound: hasDrivableBox || uiScope.state === 'open',
         ...(ui.carriedFrom !== undefined && { carriedFrom: ui.carriedFrom }),
         ...(ui.paintedPaths !== undefined && { paintedPaths: ui.paintedPaths }),
         ...(ui.drivenPaths !== undefined && { drivenPaths: ui.drivenPaths }),
@@ -132,7 +132,7 @@ export async function readReviewState(
 ): Promise<ReviewStateRead> {
   const evidence = await api.readEvidence()
   if (evidence === undefined) return { kind: 'refused', reason: 'gh-failed' }
-  return readAt(api, evidence.hasChecklist, painted)
+  return readAt(api, evidence.hasDrivableBox, painted)
 }
 
 /**
@@ -158,7 +158,7 @@ export async function waitForReviews(
   }
 
   for (;;) {
-    const read = await readAt(api, evidence.hasChecklist, painted)
+    const read = await readAt(api, evidence.hasDrivableBox, painted)
     if (read.kind === 'refused') {
       return { ...read, waitedSeconds: waited() }
     }

package/src/pr/waiver.ts

@@ -0,0 +1,45 @@
+import type { ReviewRow } from '@/pr/review-scope'
+
+/** A painted path a review accepted as owing no capture, and why. */
+export interface Waiver {
+  readonly path: string
+  readonly reason: string
+}
+
+/**
+ * The line `review-pr` writes in a pass body to waive one path. The path is
+ * kept exactly as spelled, so a waiver matches an uncaptured path only when
+ * both spell it alike.
+ */
+const WAIVER_LINE = /^- \*\*Waived capture:\*\* `([^`]+)`:\s*(\S.*)$/
+
+const FENCE = /^\s*(```|~~~)/
+
+/**
+ * Every waiver in the review bodies, in order. A line inside a fenced block is
+ * a quoted sample rather than a waiver, so it never counts.
+ *
+ * Review bodies alone are read, never the pull request body or an issue
+ * comment, since every session posts as one account and a review is the one
+ * surface a worker never writes.
+ */
+export function readWaivers(reviews: readonly ReviewRow[]): Waiver[] {
+  const waivers: Waiver[] = []
+  for (const review of reviews) {
+    let fence: string | undefined
+    for (const line of (review.body ?? '').split('\n')) {
+      const opener = FENCE.exec(line)?.[1]
+      if (opener !== undefined) {
+        if (fence === undefined) fence = opener
+        else if (opener === fence) fence = undefined
+        continue
+      }
+      if (fence !== undefined) continue
+      const match = WAIVER_LINE.exec(line.trimEnd())
+      if (match?.[1] !== undefined && match[2] !== undefined) {
+        waivers.push({ path: match[1], reason: match[2] })
+      }
+    }
+  }
+  return waivers
+}