@erclx/canon 5.73.0 → 5.75.0

package/src/pr/lift.ts

@@ -83,8 +83,19 @@ export interface EvidenceGate {
 }
 
 export interface ChecksGate {
+  /** The state over the checks the base requires, or every check when none were read. */
   readonly state: ChecksState
   readonly isConflicted: boolean
+  /** Failing checks outside the required set, which are reported and never gate. */
+  readonly advisory?: readonly string[]
+}
+
+/** The advisory field a record carries, absent when no advisory check failed. */
+export function advisoryOf(reading: ChecksGate): {
+  advisory?: readonly string[]
+} {
+  const advisory = reading.advisory ?? []
+  return advisory.length > 0 ? { advisory } : {}
 }
 
 /**
@@ -129,6 +140,8 @@ export interface LiftRecord {
   readonly carriedFrom?: string
   readonly paintedPaths?: readonly string[]
   readonly drivenPaths?: readonly string[]
+  /** Failing checks the base does not require, named so a reader sees them before merging. */
+  readonly advisory?: readonly string[]
   readonly isLifted: boolean
   /** Whether the caller can treat the pull request as ready afterwards. */
   readonly isOk: boolean
@@ -247,7 +260,11 @@ function standingGate(standing: Standing): GateResult {
 }
 
 type CiOutcome =
-  | { readonly kind: 'passing'; readonly waited: number }
+  | {
+      readonly kind: 'passing'
+      readonly waited: number
+      readonly reading: ChecksGate
+    }
   | {
       readonly kind: 'refused'
       readonly reason: LiftRefusal
@@ -274,7 +291,9 @@ async function waitForChecks(
     if (reading === undefined) {
       return { kind: 'refused', reason: 'gh-failed', waited }
     }
-    if (reading.state === 'passing') return { kind: 'passing', waited }
+    if (reading.state === 'passing') {
+      return { kind: 'passing', waited, reading }
+    }
     if (reading.state === 'failing') {
       return { kind: 'refused', reason: 'ci-failing', waited }
     }
@@ -422,6 +441,7 @@ export async function lift(
       gates: all,
       waitedSeconds: 0,
       ...carried(all),
+      ...advisoryOf(reading),
     }
   }
 
@@ -485,6 +505,7 @@ export async function lift(
     gates: cleared,
     waitedSeconds: ci.waited,
     ...carried(cleared),
+    ...advisoryOf(ci.reading),
   }
 }
 

package/src/pr/merge.ts

@@ -1,4 +1,4 @@
-import type { ChecksGate } from '@/pr/lift'
+import { advisoryOf, type ChecksGate } from '@/pr/lift'
 import { readSection } from '@/pr/paths'
 import { UI_PASS_MARKER } from '@/pr/tick'
 
@@ -67,6 +67,8 @@ export interface MergeRecord {
   readonly description?: string
   /** The squash commit, present only on a merge. */
   readonly sha?: string
+  /** Failing checks the base does not require, which the merge went past. */
+  readonly advisory?: readonly string[]
 }
 
 export type Composed =
@@ -230,8 +232,15 @@ export async function merge(
     )
   }
 
-  if (opts.isDryRun)
-    return { reason: 'dry-run', isOk: true, number, ...message }
+  if (opts.isDryRun) {
+    return {
+      reason: 'dry-run',
+      isOk: true,
+      number,
+      ...message,
+      ...advisoryOf(checks),
+    }
+  }
 
   const outcome = await api.putMerge({ ...message, sha: pull.head })
   if (outcome.kind === 'merged') {
@@ -241,6 +250,7 @@ export async function merge(
       number,
       ...message,
       sha: outcome.sha,
+      ...advisoryOf(checks),
     }
   }
   return refused(

package/src/take/encode.ts

@@ -97,11 +97,17 @@ export function openFrameEncoder(out: string, fps: number): FrameEncoder {
   }
 }
 
-/** Re-encodes a recorded clip to the same H.264 output at a constant `fps`. */
+/**
+ * Re-encodes a recorded clip to the same H.264 output at a constant `fps`, cut
+ * at `ms`. Playwright's recorder pads its webm past the last frame by at least
+ * a second, so the cut is what ends the clip where the take's clock stopped.
+ * A shorter input stays as it is, since `-t` never extends one.
+ */
 export async function transcode(
   input: string,
   out: string,
   fps: number,
+  ms: number,
 ): Promise<void> {
   const proc = spawn(
     'ffmpeg',
@@ -111,6 +117,8 @@ export async function transcode(
       'error',
       '-i',
       input,
+      '-t',
+      (ms / 1000).toFixed(3),
       '-r',
       String(fps),
       ...OUTPUT,

package/src/take/film.ts

@@ -11,7 +11,7 @@ import {
   type TakeLog,
   VIEWPORT,
 } from '@/take/log'
-import { TargetMissing } from '@/take/perform'
+import { TargetMissing, TargetOffscreen, TargetRefused } from '@/take/perform'
 import type { Beat, Route, TakePlan } from '@/take/plan'
 import { filmScreencast } from '@/take/screencast'
 import { ShellMissing, findShell } from '@/take/shell'
@@ -30,6 +30,8 @@ export type TakeRefusal =
   | 'browser-missing'
   | 'server-unreachable'
   | 'target-missing'
+  | 'target-offscreen'
+  | 'over-cap'
   | 'take-failed'
 
 export interface FilmedBeat {
@@ -74,6 +76,8 @@ export interface TakeRequest {
   readonly env?: NodeJS.ProcessEnv
   /** How long one stepped frame may take before its beat falls back to a screencast. */
   readonly stallMs?: number
+  /** The filmed seconds the beats may sum to, past which the take refuses. */
+  readonly maxSeconds?: number
 }
 
 const REACH_TIMEOUT_MS = 5000
@@ -127,7 +131,7 @@ export async function take(request: TakeRequest): Promise<TakeResult> {
       )
     } catch (error) {
       const cause = error instanceof FellBack ? error.error : error
-      const shot = cause instanceof TargetMissing ? cause.still : undefined
+      const shot = cause instanceof TargetRefused ? cause.still : undefined
       const still = shot ? join(dir, 'still.jpg') : undefined
       if (shot && still) writeFileSync(join(out, still), shot)
       return {
@@ -136,6 +140,16 @@ export async function take(request: TakeRequest): Promise<TakeResult> {
         ...(still ? { still } : {}),
       }
     }
+    // Checked after each beat rather than once at the end, so a take refused
+    // on its first beat films nothing past it.
+    const frames = beats.reduce((sum, filmed) => sum + filmed.frames, 0)
+    if (request.maxSeconds !== undefined && frames > request.maxSeconds * FPS) {
+      return failed(
+        'over-cap',
+        `the beats through ${beat.name} run ${(frames / FPS).toFixed(2)} s, past the ${request.maxSeconds} s cap`,
+        beat.name,
+      )
+    }
   }
 
   writeFileSync(
@@ -231,6 +245,7 @@ class FellBack extends Error {
 
 function classify(error: unknown): TakeRefusal {
   if (error instanceof TargetMissing) return 'target-missing'
+  if (error instanceof TargetOffscreen) return 'target-offscreen'
   if (error instanceof ShellMissing || isBrowserMissing(error)) {
     return 'browser-missing'
   }

package/src/take/fixtures/busy.html

@@ -0,0 +1,107 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Busy</title>
+    <!--
+      A hero canvas that redraws every frame and spends busy=<ms> of main
+      thread work on each, so a frame takes about that long to render. A card
+      sits about 2900px down, below the window, and the rail link scrolls to it.
+      With timed=1 each frame spins on performance.now() instead, as the
+      groundwork page did, which never ends once the stepper pauses virtual
+      time.
+    -->
+    <style>
+      html {
+        scroll-behavior: smooth;
+      }
+
+      body {
+        margin: 0;
+        font-family: sans-serif;
+      }
+
+      nav {
+        position: fixed;
+        top: 10px;
+        right: 10px;
+        z-index: 2;
+      }
+
+      nav a {
+        display: block;
+        padding: 12px 20px;
+        background: #fff;
+      }
+
+      canvas {
+        display: block;
+        width: 100vw;
+        height: 100vh;
+      }
+
+      section {
+        height: 900px;
+        border-top: 1px solid #ccc;
+        padding: 40px;
+      }
+
+      .card {
+        width: 400px;
+        height: 240px;
+        background: #ddd;
+      }
+
+      .card:hover {
+        background: #f60;
+      }
+    </style>
+  </head>
+  <body>
+    <nav><a id="rail" href="#cards">Cards</a></nav>
+    <canvas id="hero"></canvas>
+    <section>one</section>
+    <section>two</section>
+    <section id="cards"><div class="card" id="card">card</div></section>
+    <section>four</section>
+    <script>
+      const params = new URLSearchParams(location.search)
+      const busy = Number(params.get('busy') || 0)
+      const timed = params.get('timed') === '1'
+      const hero = document.getElementById('hero')
+      hero.width = innerWidth
+      hero.height = innerHeight
+      const context = hero.getContext('2d')
+      // The work is a count calibrated in real time on load, since a loop
+      // timed by performance.now() never ends under a paused virtual clock.
+      let sink = 0
+      const spin = (count) => {
+        for (let i = 0; i < count; i += 1) sink += Math.sqrt(i)
+      }
+      const measure = (ms) => {
+        let count = 0
+        const start = performance.now()
+        while (performance.now() - start < ms) {
+          spin(10000)
+          count += 10000
+        }
+        return count / ms
+      }
+      // Warmed first, so the count matches the optimized loop a frame runs.
+      measure(100)
+      const work = Math.round(busy * measure(200))
+      const draw = (time) => {
+        if (timed) {
+          const start = performance.now()
+          while (performance.now() - start < busy) {}
+        } else {
+          spin(work)
+        }
+        context.fillStyle = `hsl(${(time / 10) % 360}, 60%, 50%)`
+        context.fillRect(0, 0, hero.width, hero.height)
+        requestAnimationFrame(draw)
+      }
+      requestAnimationFrame(draw)
+    </script>
+  </body>
+</html>

package/src/take/perform.ts

@@ -3,6 +3,7 @@ import {
   FPS,
   type LogEvent,
   type Point,
+  VIEWPORT,
   along,
   travelMs,
 } from '@/take/log'
@@ -74,13 +75,40 @@ export interface Stage {
   evaluate<T>(expression: string): Promise<T>
 }
 
-/** A target that resolved to nothing, which refuses rather than films a guess. */
-export class TargetMissing extends Error {
+/** A target the pointer cannot reach, which refuses rather than films a guess. */
+export class TargetRefused extends Error {
   /** The page as it stood when the lookup failed, as a JPEG, when the route caught one. */
   still?: Buffer
 
-  constructor(readonly target: string) {
-    super(`nothing on the page matches ${target}`)
+  constructor(
+    readonly target: string,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+/** A target that resolved to nothing. */
+export class TargetMissing extends TargetRefused {
+  constructor(target: string) {
+    super(target, `nothing on the page matches ${target}`)
+  }
+}
+
+/**
+ * A target whose center lies outside the window, so the pointer would aim at
+ * a point the clip never shows, or for a scroll, a target with no part inside
+ * it. A setup step brings it into view first.
+ */
+export class TargetOffscreen extends TargetRefused {
+  constructor(
+    target: string,
+    readonly at: Point,
+  ) {
+    super(
+      target,
+      `${target} is centered at (${Math.round(at.x)}, ${Math.round(at.y)}), outside the ${VIEWPORT.width}x${VIEWPORT.height} window, so a setup step must bring it into view first`,
+    )
   }
 }
 
@@ -155,19 +183,12 @@ export async function performSteps(
         break
       }
       case 'scroll': {
-        const at = center(await boxOf(stage, step.target))
+        const at = await scrollPoint(stage, step.target)
         await moveTo(stage, state, at)
         const frames = Math.round(SCROLL_MS / FRAME_MS)
-        state.log?.push({
-          t: stage.now(),
-          kind: 'scroll',
-          at,
-          dx: 0,
-          dy: step.dy,
-          ms: frames * FRAME_MS,
-        })
+        const start = stage.now()
         let sent = 0
-        for (let frame = 1; frame <= frames; frame += 1) {
+        await paced(stage, frames, async (frame) => {
           const want = along(
             { x: 0, y: 0 },
             { x: 0, y: step.dy },
@@ -175,7 +196,15 @@ export async function performSteps(
           ).y
           await stage.pointer({ type: 'wheel', ...at, dy: want - sent })
           sent = want
-        }
+        })
+        state.log?.push({
+          t: start,
+          kind: 'scroll',
+          at,
+          dx: 0,
+          dy: step.dy,
+          ms: stage.now() - start,
+        })
         break
       }
       case 'wait':
@@ -194,21 +223,35 @@ async function moveTo(
   const from = state.pointer
   if (Math.hypot(to.x - from.x, to.y - from.y) < 1) return
   const frames = Math.max(1, Math.round(travelMs(from, to) / FRAME_MS))
-  state.log?.push({
-    t: stage.now(),
-    kind: 'move',
-    from,
-    to,
-    ms: frames * FRAME_MS,
-  })
   const pressed = held
     ? { held: true as const, ...withModifiers(held.modifiers) }
     : {}
-  for (let frame = 1; frame <= frames; frame += 1) {
+  const start = stage.now()
+  await paced(stage, frames, async (frame) => {
     state.pointer = along(from, to, frame / frames)
     await stage.pointer({ type: 'move', ...state.pointer, ...pressed })
-  }
+  })
   state.pointer = to
+  state.log?.push({ t: start, kind: 'move', from, to, ms: stage.now() - start })
+}
+
+/**
+ * Runs a motion planned as `frames` inputs, sending each at the frame the
+ * stage's clock has reached, so a page slower than a frame per input skips the
+ * points it is behind on and the motion still ends near its planned length. A
+ * clock advancing one frame per input, as the stepper's does, gets every frame.
+ */
+async function paced(
+  stage: Stage,
+  frames: number,
+  input: (frame: number) => Promise<void>,
+): Promise<void> {
+  const start = stage.now()
+  for (let frame = 0; frame < frames;) {
+    const reached = Math.round((stage.now() - start) / FRAME_MS)
+    frame = Math.min(frames, Math.max(frame + 1, reached + 1))
+    await input(frame)
+  }
 }
 
 async function click(
@@ -315,12 +358,43 @@ function center(box: Box): Point {
   return { x: box.x + box.width / 2, y: box.y + box.height / 2 }
 }
 
-async function boxOf(stage: Stage, target: string): Promise<Box> {
+function inWindow(at: Point): boolean {
+  return (
+    at.x >= 0 && at.x <= VIEWPORT.width && at.y >= 0 && at.y <= VIEWPORT.height
+  )
+}
+
+async function foundBox(stage: Stage, target: string): Promise<Box> {
   const box = await stage.evaluate<Box | null>(boxExpression(target))
   if (!box) throw new TargetMissing(target)
   return box
 }
 
+async function boxOf(stage: Stage, target: string): Promise<Box> {
+  const box = await foundBox(stage, target)
+  const at = center(box)
+  if (!inWindow(at)) throw new TargetOffscreen(target, at)
+  return box
+}
+
+/**
+ * Aims a wheel at the target's center, or, when that lies outside the window,
+ * at the center of the part the window shows. A wheel scrolls whatever sits
+ * under it, so any visible point of the target serves, and a page-tall element
+ * such as `body` has a center no setup step can bring into view.
+ */
+async function scrollPoint(stage: Stage, target: string): Promise<Point> {
+  const box = await foundBox(stage, target)
+  const at = center(box)
+  if (inWindow(at)) return at
+  const left = Math.max(box.x, 0)
+  const right = Math.min(box.x + box.width, VIEWPORT.width)
+  const top = Math.max(box.y, 0)
+  const bottom = Math.min(box.y + box.height, VIEWPORT.height)
+  if (right <= left || bottom <= top) throw new TargetOffscreen(target, at)
+  return { x: (left + right) / 2, y: (top + bottom) / 2 }
+}
+
 /**
  * Finds a target's box in CSS pixels, reading `text=<words>` as the first
  * innermost element with a size whose whole text is those words, so a hidden

package/src/take/screencast.ts

@@ -7,7 +7,7 @@ import { FPS, type LogEvent, START, VIEWPORT } from '@/take/log'
 import {
   type PointerInput,
   type Stage,
-  TargetMissing,
+  TargetRefused,
   performSteps,
 } from '@/take/perform'
 import type { Beat } from '@/take/plan'
@@ -92,13 +92,14 @@ export async function filmScreencast(request: {
       log: events,
     })
     await recording.hold(HOLD_MS)
+    const filmedMs = recording.now()
     await page.screencast.stop()
 
-    await transcode(webm, request.clip, FPS)
+    await transcode(webm, request.clip, FPS, filmedMs)
     const frames = await probeFrames(request.clip)
     return { frames, events, still: await lastFrame(request.clip, frames) }
   } catch (error) {
-    if (error instanceof TargetMissing && still) error.still = await still()
+    if (error instanceof TargetRefused && still) error.still = await still()
     throw error
   } finally {
     await browser.close()

package/src/take/stepper.ts

@@ -5,7 +5,7 @@ import {
   type KeyInput,
   type PointerInput,
   type Stage,
-  TargetMissing,
+  TargetRefused,
   performSteps,
 } from '@/take/perform'
 import type { Beat } from '@/take/plan'
@@ -25,7 +25,10 @@ import { type ShellPage, openShell } from '@/take/shell'
  * - Frame time continues Chromium's monotonic clock, since a frame stamped on
  *   any other base leaves every CSS animation at its first frame
  * - No frame is begun before the load event, since one sent mid-navigation can
- *   go unanswered, and each loading frame is capped so a lost one cannot hang
+ *   go unanswered
+ * - A frame is begun only once the one before it settles, since Chromium
+ *   refuses a second while one is pending, and a frame left pending past the
+ *   stall limit falls the beat back rather than hanging it
  */
 
 const FRAME_MS = 1000 / FPS
@@ -41,7 +44,6 @@ export const HOLD_MS = 600
 
 const LOAD_CAP_MS = 15_000
 const SETTLE_MS = 2500
-const LOADING_FRAME_CAP_MS = 250
 
 /** How long a refusal waits on the frame it shows, since the page may be wedged. */
 const STILL_CAP_MS = 2000
@@ -81,19 +83,25 @@ export async function filmStepped(
   let still: (() => Promise<Buffer | undefined>) | undefined
   try {
     let ticks = await load(page, request.url)
-    const beginFrame = (screenshot: boolean) =>
-      page.send<{ screenshotData?: string }>(
-        'HeadlessExperimental.beginFrame',
-        {
-          frameTimeTicks: (ticks += FRAME_MS),
-          interval: FRAME_MS,
-          ...(screenshot
-            ? { screenshot: { format: 'jpeg', quality: 95 } }
-            : {}),
-        },
+    let outstanding: Promise<unknown> = Promise.resolve()
+    const beginFrame = (screenshot: boolean) => {
+      const reply = outstanding.then(() =>
+        page.send<{ screenshotData?: string }>(
+          'HeadlessExperimental.beginFrame',
+          {
+            frameTimeTicks: (ticks += FRAME_MS),
+            interval: FRAME_MS,
+            ...(screenshot
+              ? { screenshot: { format: 'jpeg', quality: 95 } }
+              : {}),
+          },
+        ),
       )
+      outstanding = reply.catch(() => {})
+      return reply
+    }
     still = () => frameStill(beginFrame)
-    await pump(beginFrame, SETTLE_MS)
+    await pump(beginFrame, SETTLE_MS, stallMs)
 
     const live = liveStage(page, beginFrame, stallMs)
     await performSteps(live, request.beat.setup, { pointer: START })
@@ -163,7 +171,7 @@ export async function filmStepped(
     return { frames, events, still: last }
   } catch (error) {
     encoder.abort()
-    if (error instanceof TargetMissing && still) error.still = await still()
+    if (error instanceof TargetRefused && still) error.still = await still()
     throw error
   } finally {
     page.close()
@@ -215,17 +223,22 @@ async function load(page: ShellPage, url: string): Promise<number> {
   return timestamp
 }
 
-/** Begins frames in real time so loading, fonts, and layout settle. */
+/**
+ * Begins frames in real time so loading, fonts, and layout settle. Each frame
+ * is awaited, so a slow page stretches the settle rather than overlapping it.
+ */
 async function pump(
   beginFrame: (screenshot: boolean) => Promise<unknown>,
   ms: number,
+  stallMs: number,
 ): Promise<void> {
   const end = Date.now() + ms
   while (Date.now() < end) {
-    await Promise.race([
+    await withinStall(
       beginFrame(false).catch(() => {}),
-      sleep(LOADING_FRAME_CAP_MS),
-    ])
+      0,
+      stallMs,
+    )
     await sleep(12)
   }
 }
@@ -242,7 +255,7 @@ function liveStage(
   const started = Date.now()
   return {
     now: () => Date.now() - started,
-    hold: (ms) => pump(beginFrame, ms),
+    hold: (ms) => pump(beginFrame, ms, stallMs),
     pointer: (input) => {
       const sent = page.send('Input.dispatchMouseEvent', mouseEvent(input))
       return withinStall(

package/src/targets/pulls.ts

@@ -94,6 +94,8 @@ interface RawPull {
  * rather than writing a second collapse beside `rollup`.
  */
 export interface RawCheck {
+  /** The check-run name, which a ruleset's required context matches. */
+  readonly name?: string
   readonly status?: string
   readonly conclusion?: string
   readonly state?: string
@@ -137,6 +139,46 @@ export function rollup(checks: readonly RawCheck[]): ChecksState | null {
   return running ? 'pending' : 'passing'
 }
 
+/** A head's state over the checks the base requires, with failing others named apart. */
+export interface RequiredRollup {
+  readonly state: ChecksState | null
+  /** Names of checks outside the required set that failed, which never gate. */
+  readonly advisory: readonly string[]
+}
+
+/**
+ * Collapses a head's checks over the set the base branch's rules require.
+ *
+ * An unread or empty set gates by every check, which is `rollup` itself and
+ * the safe default for a repository whose rules list nothing. A required name
+ * with no run on the head reads pending rather than passing, since a run not
+ * yet created has not cleared anything.
+ */
+export function rollupRequired(
+  checks: readonly RawCheck[],
+  required: ReadonlySet<string> | undefined,
+): RequiredRollup {
+  if (required === undefined || required.size === 0) {
+    return { state: rollup(checks), advisory: [] }
+  }
+
+  const isRequired = (check: RawCheck): boolean =>
+    check.name !== undefined && required.has(check.name)
+  const gating = checks.filter(isRequired)
+  const advisory = checks
+    .filter((check) => !isRequired(check) && rollup([check]) === 'failing')
+    .map((check) => check.name ?? '')
+
+  const state = rollup(gating)
+  const isMissing = [...required].some(
+    (name) => !gating.some((check) => check.name === name),
+  )
+  return {
+    state: state !== 'failing' && isMissing ? 'pending' : state,
+    advisory,
+  }
+}
+
 /**
  * Reads the heading of the newest pass carrying one, matching on the first line
  * alone the way `poll.ts` does.