@erclx/canon 5.78.0 → 5.79.0

package/src/take/screencast.ts

@@ -1,8 +1,8 @@
-import { mkdtempSync, rmSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 import { chromium } from 'playwright-core'
-import { lastFrame, probeFrames, transcode } from '@/take/encode'
+import { lastFrame, openFrameEncoder, probeFrames } from '@/take/encode'
+import { frameStamp, slotFrames } from '@/take/frame-clock'
 import { FPS, type LogEvent, START, VIEWPORT } from '@/take/log'
 import {
   type PointerInput,
@@ -51,8 +51,13 @@ export async function filmScreencast(request: {
   readonly beat: Beat
   readonly clip: string
 }): Promise<ScreencastTake> {
-  const scratch = mkdtempSync(join(tmpdir(), 'canon-take-cast-'))
-  const browser = await chromium.launch()
+  // Ahead of the launch, so a folder that refuses leaves no browser holding the
+  // process open past its refusal.
+  const scratch = openSpool(request.clip)
+  const browser = await chromium.launch().catch((error: unknown) => {
+    scratch.remove()
+    throw error
+  })
   let still: (() => Promise<Buffer | undefined>) | undefined
   try {
     const page = await browser.newPage({ viewport: VIEWPORT })
@@ -97,9 +102,33 @@ export async function filmScreencast(request: {
     if (request.beat.setup.length > 0) await live.hold(1000)
     const lag = await calibrate(page)
 
-    const webm = join(scratch, 'take.webm')
     const events: LogEvent[] = []
-    await page.screencast.start({ path: webm, size: VIEWPORT, fps: FPS })
+    const spool: SpooledFrame[] = []
+    let spoolFailure: unknown
+    await page.screencast.start({
+      size: VIEWPORT,
+      // The docs tie this to `path`, but 1.64.1 still reads it here, where it
+      // doubles the frames Chromium may hold unacknowledged.
+      fps: FPS,
+      // Spooled rather than held, since a busy page sends about 19 MB a second.
+      // The write stays synchronous, so the acknowledgement Chromium paces its
+      // frames on waits for no encoder. Playwright calls this from a listener
+      // nothing awaits, so a throw here would surface as an unhandled rejection.
+      onFrame: ({ data, timestamp }) => {
+        const stamp = frameStamp({
+          presentedWall: timestamp,
+          wallNow: Date.now(),
+          monoNow: performance.now(),
+        })
+        const path = join(scratch.folder, `${spool.length}.jpg`)
+        try {
+          writeFileSync(path, data)
+          spool.push({ path, stamp })
+        } catch (error) {
+          spoolFailure ??= error
+        }
+      },
+    })
     const started = performance.now()
     const recording = stageOn(() => performance.now() - started)
     await recording.hold(HOLD_MS)
@@ -110,8 +139,9 @@ export async function filmScreencast(request: {
     await recording.hold(HOLD_MS)
     const filmedMs = recording.now()
     await page.screencast.stop()
+    if (spoolFailure !== undefined) throw spoolFailure
 
-    await transcode(webm, request.clip, FPS, filmedMs)
+    await encodeSpool(spool, request.clip, started, filmedMs)
     const frames = await probeFrames(request.clip)
     const closing = await lastFrame(request.clip, frames)
     if (lag === undefined) return { frames, events, still: closing }
@@ -126,13 +156,86 @@ export async function filmScreencast(request: {
     throw error
   } finally {
     await browser.close()
-    rmSync(scratch, { recursive: true, force: true })
+    scratch.remove()
   }
 }
 
 type Page = import('playwright-core').Page
 type Mouse = import('playwright-core').Mouse
 
+interface SpooledFrame {
+  readonly path: string
+  /** When the frame was presented, on the monotonic clock. */
+  readonly stamp: number
+}
+
+/**
+ * Opens the folder holding one take's frames, beside its clip rather than in a
+ * temp folder nothing sweeps, since a 34 s beat on a busy page spools about
+ * 650 MB. A take killed outright runs no handler, so it leaves the folder where
+ * its owner looks, and the next take of that beat clears it.
+ */
+function openSpool(clip: string): { folder: string; remove: () => void } {
+  const folder = join(dirname(clip), 'spool')
+  rmSync(folder, { recursive: true, force: true })
+  mkdirSync(folder, { recursive: true })
+  const remove = (): void => {
+    process.off('exit', remove)
+    process.off('SIGINT', interrupt)
+    process.off('SIGTERM', interrupt)
+    rmSync(folder, { recursive: true, force: true })
+  }
+  // A signal skips the exit event, so it removes the folder and then re-raises
+  // itself with this handler gone, ending the process as it would have.
+  const interrupt = (signal: NodeJS.Signals): void => {
+    remove()
+    process.kill(process.pid, signal)
+  }
+  process.on('exit', remove)
+  process.once('SIGINT', interrupt)
+  process.once('SIGTERM', interrupt)
+  return { folder, remove }
+}
+
+/**
+ * Writes the clip from the spool, one frame per slot of the stage clock, so its
+ * length is the take's rather than whatever the frames span. Refuses when no
+ * frame arrived, since there is nothing true to show.
+ */
+async function encodeSpool(
+  spool: readonly SpooledFrame[],
+  clip: string,
+  startMs: number,
+  lengthMs: number,
+): Promise<void> {
+  const slots = slotFrames(
+    spool.map((frame) => frame.stamp),
+    { startMs, lengthMs, frameMs: FRAME_MS },
+  )
+  if (slots.length === 0) {
+    throw new Error(
+      `the screencast delivered no frame in ${(lengthMs / 1000).toFixed(2)} s of filming`,
+    )
+  }
+  const encoder = openFrameEncoder(clip, FPS)
+  try {
+    let shown = -1
+    let jpeg = Buffer.alloc(0)
+    for (const index of slots) {
+      const frame = spool[index]
+      if (frame && index !== shown) {
+        jpeg = readFileSync(frame.path)
+        shown = index
+      }
+      await encoder.write(jpeg)
+    }
+    await encoder.close()
+  } catch (error) {
+    encoder.abort()
+    throw error
+  }
+}
+
 /**
  * The page time of its next animation frame, or undefined when none comes
  * within `capMs`, as on a hidden page, or the page closed first.
@@ -155,7 +258,7 @@ const PAINTED = '__canonTakePainted'
  * How long a move takes to show in the clip, measured by sending one aligned
  * move to `START` and reading the animation frame after its handler against
  * the frame it was aligned to. Both readings are page time, so no clock mapping
- * is needed. The recorder captures a frame once it is presented, one page
+ * is needed. The screencast captures a frame once it is presented, one page
  * frame after that frame begins, so the lag counts one page frame past the
  * readings, read off two consecutive animation frames rather than assumed from
  * the clip's rate. That held a dragged box within 7 px on every run where the

package/src/tasks/holders.ts

@@ -0,0 +1,198 @@
+import { execa } from 'execa'
+import { gitEnv } from '@/git/env'
+import {
+  repositoryOf,
+  resolveSessions,
+  type SessionReport,
+} from '@/sessions/resolve'
+
+/**
+ * Bounds the one network read `canon tasks validate --live` takes, shorter than
+ * the archive's own, since the sweep waits on it and a slow answer reads the
+ * same as no answer.
+ */
+const GH_TIMEOUT_MS = 5_000
+
+/** `gh pr list` caps at 30 by default, and a truncated list would read as clean. */
+const PULL_LIMIT = 1_000
+
+/**
+ * Who holds each branch, named for a person reading the report. `undefined`
+ * means the source could not be read, which has to stay apart from an empty map:
+ * an unreachable source that degraded to "nobody holds it" would report a held
+ * row as clean.
+ */
+export type HolderReader = () => Promise<
+  ReadonlyMap<string, string> | undefined
+>
+
+/** Whether a merged pull request names a branch, `undefined` when GitHub could not say. */
+export type MergedReader = (branch: string) => Promise<boolean | undefined>
+
+export interface LiveReaders {
+  readonly sessions: HolderReader
+  readonly pulls: HolderReader
+  readonly merged: MergedReader
+}
+
+export interface SessionHolderOptions {
+  readonly resolve?: () => Promise<SessionReport>
+  readonly repository?: (root: string) => Promise<string | null>
+}
+
+/**
+ * Reads the roster scoped to `root`'s repository, since a branch name says
+ * nothing across a machine and another project's worker on the same name holds
+ * nothing here. Two rows leave the liveness undecided, a foreign record whose
+ * socket is gone and a row resting only on a socket file a crash can leave, so
+ * either reads the whole roster as unread rather than as a hold or as clear.
+ */
+export function sessionHolders(
+  root: string,
+  opts: SessionHolderOptions = {},
+): HolderReader {
+  const resolve = opts.resolve ?? resolveSessions
+  const repository = opts.repository ?? repositoryOf
+
+  return async () => {
+    try {
+      const [report, repo] = await Promise.all([resolve(), repository(root)])
+      if (
+        report.kind !== 'resolved' ||
+        report.foreignDead > 0 ||
+        report.sessions.some((session) => session.via === 'socket') ||
+        !repo
+      ) {
+        return undefined
+      }
+
+      return new Map(
+        report.sessions.flatMap((session) =>
+          session.repository === repo && session.branch
+            ? [[session.branch, `session ${session.name}`] as const]
+            : [],
+        ),
+      )
+    } catch {
+      return undefined
+    }
+  }
+}
+
+export type GhRunner = (
+  cwd: string,
+  args: readonly string[],
+) => Promise<string | undefined>
+
+const runGh: GhRunner = async (cwd, args) => {
+  if (Bun.which('gh') === null) return undefined
+
+  try {
+    // `gh` resolves its repository through git, so a hook's resolution
+    // variables would point it at another repository than `cwd`.
+    const result = await execa('gh', [...args], {
+      cwd,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    })
+    return result.stdout
+  } catch {
+    return undefined
+  }
+}
+
+interface ListedPull {
+  readonly number: number
+  readonly headRefName: string
+  readonly isCrossRepository: boolean
+}
+
+function isListedPull(value: unknown): value is ListedPull {
+  if (typeof value !== 'object' || value === null) return false
+  const pull = value as Record<string, unknown>
+
+  return (
+    typeof pull.number === 'number' &&
+    typeof pull.headRefName === 'string' &&
+    typeof pull.isCrossRepository === 'boolean'
+  )
+}
+
+function parsePulls(stdout: string): readonly ListedPull[] | undefined {
+  try {
+    const parsed: unknown = JSON.parse(stdout)
+    return Array.isArray(parsed) && parsed.every(isListedPull)
+      ? parsed
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Reads open pull requests off GitHub. A list reaching the limit may have cut
+ * off the one that holds a row, so it reads as unread. A fork's head names a
+ * branch in another repository, which holds nothing here however it is spelled.
+ */
+export function pullHolders(root: string, run: GhRunner = runGh): HolderReader {
+  return async () => {
+    const stdout = await run(root, [
+      'pr',
+      'list',
+      '--state',
+      'open',
+      '--limit',
+      String(PULL_LIMIT),
+      '--json',
+      'number,headRefName,isCrossRepository',
+    ])
+    if (stdout === undefined) return undefined
+
+    const pulls = parsePulls(stdout)
+    if (!pulls || pulls.length >= PULL_LIMIT) return undefined
+
+    return new Map(
+      pulls
+        .filter((pull) => !pull.isCrossRepository)
+        .map((pull) => [pull.headRefName, `pull request #${pull.number}`]),
+    )
+  }
+}
+
+/**
+ * Asks about one branch at a time rather than listing merged pull requests,
+ * since a list long enough to reach an old merge costs every run, and only a
+ * branch a session already holds against a row takes this read.
+ */
+export function mergedBranches(
+  root: string,
+  run: GhRunner = runGh,
+): MergedReader {
+  return async (branch) => {
+    const stdout = await run(root, [
+      'pr',
+      'list',
+      '--state',
+      'merged',
+      '--head',
+      branch,
+      '--limit',
+      String(PULL_LIMIT),
+      '--json',
+      'number,headRefName,isCrossRepository',
+    ])
+    if (stdout === undefined) return undefined
+
+    const pulls = parsePulls(stdout)
+    return pulls?.some((pull) => !pull.isCrossRepository)
+  }
+}
+
+export function liveReaders(root: string): LiveReaders {
+  return {
+    sessions: sessionHolders(root),
+    pulls: pullHolders(root),
+    merged: mergedBranches(root),
+  }
+}

package/src/tasks/validate.ts

@@ -1,6 +1,7 @@
 import { existsSync, statSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
+import { readFrontmatterSource } from '@/indexes/frontmatter'
 import { codeSpans, unbrokenRun } from '@/markdown/tables'
 import {
   archiveDir,
@@ -21,6 +22,8 @@ import {
   renderedLength,
   WAITING_LIMIT,
 } from '@/tasks/board'
+import { branchOfPlan } from '@/tasks/branch'
+import type { HolderReader, LiveReaders, MergedReader } from '@/tasks/holders'
 import { gitTrunkReader, type TrunkReader } from '@/tasks/trunk'
 
 const ORDERING_FILE = 'priority.md'
@@ -61,6 +64,7 @@ export const FINDING_KINDS = [
   'row-untabled',
   'row-misordered',
   'row-unranked',
+  'row-held',
   'touches-unstated',
   'touches-stale',
   'columns-mismatched',
@@ -69,6 +73,7 @@ export const FINDING_KINDS = [
   'blocker-unresolved',
   'blocker-declined',
   'sessions-misshapen',
+  'frontmatter-invalid',
 ] as const
 
 export type FindingKind = (typeof FINDING_KINDS)[number]
@@ -177,6 +182,18 @@ export interface BoardRow {
   readonly cells: readonly string[]
 }
 
+/**
+ * What each source behind the held-row check answered. `unread` is a source the
+ * run asked and could not read, so a board carrying no `row-held` finding beside
+ * it is untested rather than clean. `not-asked` is a run without the live read.
+ */
+export type LiveState = 'read' | 'unread' | 'not-asked'
+
+export interface LiveReading {
+  readonly sessions: LiveState
+  readonly pulls: LiveState
+}
+
 export interface ValidateReport {
   readonly ok: true
   readonly rows: number
@@ -189,6 +206,7 @@ export interface ValidateReport {
   readonly shared: readonly SharedFiles[]
   readonly wide: readonly WideToken[]
   readonly unplaced: readonly Unplaced[]
+  readonly live: LiveReading
 }
 
 export interface ValidateRefused {
@@ -877,6 +895,34 @@ async function checkSessions(
   return found.filter((finding): finding is Finding => finding !== undefined)
 }
 
+/**
+ * Reports a task file whose frontmatter block will not parse, which the index
+ * regeneration would otherwise surface only after the row was placed. A file
+ * with no block is left alone, since the index walker owns that report.
+ */
+async function checkFrontmatter(
+  stems: readonly string[],
+  dir: string,
+): Promise<Finding[]> {
+  const found = await Promise.all(
+    stems.map(async (stem): Promise<Finding | undefined> => {
+      const reading = readFrontmatterSource(
+        await readFile(join(dir, `${stem}.md`), 'utf8'),
+      )
+      if (reading.kind !== 'invalid') return undefined
+
+      return {
+        kind: 'frontmatter-invalid',
+        group: undefined,
+        subject: stem,
+        message: `frontmatter is not valid YAML: ${reading.message}. Double any apostrophe inside the single-quoted title.`,
+      }
+    }),
+  )
+
+  return found.filter((finding): finding is Finding => finding !== undefined)
+}
+
 /**
  * Tests the claim a group name makes about a plan. `## Needs a plan` says none
  * is live and `## Up next` says one is written, and neither group has a `Plan`
@@ -1611,6 +1657,95 @@ export async function groupRuleFindings(
   ]
 }
 
+/**
+ * Reports a row outside `## Run now` whose task a live session or an open pull
+ * request holds, tied through the branch each live plan on its `Plan:` line
+ * derives. A row whose worker renamed its branch has nothing to match, and an
+ * archived plan's branch is finished work, so neither is reported.
+ *
+ * A session outlives its merge, so a session still on a branch a merged pull
+ * request names is finished work too, until the merge reaches this clone and the
+ * hook archives the row. A merged read that fails leaves the hold standing, since
+ * the session is still there, and reads `pulls` as unread, since that hold may be
+ * finished work the open list could not rule out.
+ */
+async function checkHeld(
+  rows: readonly BoardRow[],
+  live: LiveRead,
+  dir: string,
+  root: string,
+): Promise<{ readonly findings: Finding[]; readonly mergedUnread: boolean }> {
+  let mergedUnread = false
+
+  const holdersOf = async (branch: string): Promise<string[]> => {
+    const session = live.sessions?.get(branch)
+    const merged = session ? await live.merged?.(branch) : false
+    if (merged === undefined) mergedUnread = true
+
+    return [session && !merged ? session : undefined, live.pulls?.get(branch)]
+      .filter((name): name is string => name !== undefined)
+      .map((name) => `${name} on ${branch}`)
+  }
+
+  const found = await Promise.all(
+    rows.map(async (row): Promise<Finding | undefined> => {
+      if (row.group === 'Run now' || !row.stem) return undefined
+      const file = join(dir, `${row.stem}.md`)
+      if (!existsSync(file)) return undefined
+
+      const targets = readPlanTargets(await readFile(file, 'utf8'))
+      const branches = targets.flatMap((target) => {
+        const path = target.split('#')[0] || target
+        return resolveLivePlan(path, dir, root) === undefined
+          ? []
+          : [branchOfPlan(path)]
+      })
+      const held = (await Promise.all(branches.map(holdersOf))).flat()
+      if (held.length === 0) return undefined
+
+      return {
+        kind: 'row-held',
+        group: row.group,
+        subject: row.stem,
+        message: `sits under ${row.group} and is held by ${held.join(' and ')}. A row with a worker belongs under Run now.`,
+      }
+    }),
+  )
+
+  return {
+    findings: found.filter(
+      (finding): finding is Finding => finding !== undefined,
+    ),
+    mergedUnread,
+  }
+}
+
+/** What each source answered, `undefined` where it was not asked or failed. */
+interface LiveRead {
+  readonly reading: LiveReading
+  readonly sessions?: Awaited<ReturnType<HolderReader>>
+  readonly pulls?: Awaited<ReturnType<HolderReader>>
+  readonly merged?: MergedReader
+}
+
+/** Takes each source once, since a failed read answers undefined rather than throws. */
+async function readLive(live: LiveReaders | undefined): Promise<LiveRead> {
+  if (!live) {
+    return { reading: { sessions: 'not-asked', pulls: 'not-asked' } }
+  }
+
+  const stateOf = (read: Awaited<ReturnType<HolderReader>>): LiveState =>
+    read ? 'read' : 'unread'
+  const [sessions, pulls] = await Promise.all([live.sessions(), live.pulls()])
+
+  return {
+    reading: { sessions: stateOf(sessions), pulls: stateOf(pulls) },
+    sessions,
+    pulls,
+    merged: live.merged,
+  }
+}
+
 function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
   return { ok: false, reason, message }
 }
@@ -1618,6 +1753,12 @@ function refuse(reason: ValidateRefusal, message: string): ValidateRefused {
 export interface ValidateOptions {
   /** Overridden by tests, which supply the trunk rather than reaching for git. */
   readonly trunk?: TrunkReader
+  /**
+   * The roster and GitHub reads behind the held-row check. Absent by default,
+   * since the board's write hook runs this on every edit and a network read
+   * there costs every write.
+   */
+  readonly live?: LiveReaders
 }
 
 /**
@@ -1668,6 +1809,8 @@ export async function validateBoard(
     ? await listTaskStems(declinedPath)
     : []
   const parked = await checkParked(rows, root, trunk)
+  const live = await readLive(options.live)
+  const held = await checkHeld(rows, live, dir, root)
 
   const findings = [
     ...shapeFindings,
@@ -1675,10 +1818,12 @@ export async function validateBoard(
     ...(await groupRuleFindings(rows, root)),
     ...(await checkPlanAgreement(rows, dir, root)),
     ...(await checkSessions(rows, dir)),
+    ...(await checkFrontmatter(stems, dir)),
     ...(await checkStaleTouches(rows, root)),
     ...checkCellWidth(rows),
     ...checkOrdering(rows),
     ...parked.findings,
+    ...held.findings,
   ]
 
   return {
@@ -1693,5 +1838,8 @@ export async function validateBoard(
     shared: checkSharedFiles(rows),
     wide: checkWideTokens(rows),
     unplaced: checkUnplaced(rows, backlog, stems),
+    live: held.mergedUnread
+      ? { ...live.reading, pulls: 'unread' }
+      : live.reading,
   }
 }