@erclx/canon 5.77.0 → 5.79.0

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,
   }
 }

package/src/commands/fixtures/gh.sh

@@ -1,64 +0,0 @@
-#!/usr/bin/env bash
-# Fake gh for src/commands/pr.test.ts. Reads FAKE_GH_FX, FAKE_GH_COMMENTS, and FAKE_GH_API_LOG.
-set -o pipefail
-fx="$FAKE_GH_FX"
-f=.
-p=
-for a in "$@"; do
-  [ "$p" = --jq ] && f=$a
-  p=$a
-done
-case "$*" in
-*graphql* | "pr "* | "repo view"*) exit 1 ;;
-api*pulls/7/files*)
-  echo "$*" >>"$fx/files-calls.log"
-  [ -f "$fx/files-fail" ] && exit 1
-  {
-    if [ -f "$fx/files.tsv" ]; then
-      cat "$fx/files.tsv"
-    else
-      git diff --name-status --no-renames main...HEAD | sed -e 's/^A/added/' -e 's/^M/modified/' -e 's/^D/removed/'
-    fi
-  } | jq -Rn '[inputs | select(length > 0) | split("\t") | {status: .[0], filename: .[1]}]' | jq -r "$f"
-  ;;
-api*git/trees/*)
-  [ -f "$fx/base-tree.json" ] || exit 1
-  jq -r "$f" "$fx/base-tree.json"
-  ;;
-api*contents/*)
-  a="$*"
-  p=${a##*contents/}
-  p=${p%%\?*}
-  r=${a##*ref=}
-  [ -f "$fx/img/$r-$(basename "$p")" ] && cat "$fx/img/$r-$(basename "$p")" || exit 1
-  ;;
-api*compare/*)
-  if [ -f "$fx/merge-base" ]; then cat "$fx/merge-base"; else git merge-base main HEAD; fi
-  ;;
-"api -X PUT repos/{owner}/{repo}/pulls/7/reviews/"*)
-  id=${4##*/}
-  echo "$id" >>"$fx/review-puts.log"
-  [ -f "$fx/review-put-fail-$id" ] && exit 1
-  printf '%s\n' "${@: -1}" >>"$fx/review-bodies.log"
-  echo "{}"
-  ;;
-api*pulls/7/reviews*) [ -f "$fx/ui-reviews.json" ] && jq -r "$f" "$fx/ui-reviews.json" ;;
-api*issues/7/comments*) jq '[.comments[] | {html_url: .url, body}]' "$FAKE_GH_COMMENTS" | jq -r "$f" ;;
-"api -X PATCH repos/{owner}/{repo}/pulls/7 "*)
-  [ -f "$fx/body-fail" ] && exit 1
-  printf '%s' "${@: -1}" >"$fx/body-write.log"
-  echo "{}"
-  ;;
-"api repos/{owner}/{repo}/pulls/7")
-  if [ -f "$fx/head" ]; then h=$(cat "$fx/head"); else h=$(git rev-parse HEAD); fi
-  b=
-  [ -f "$fx/pr-body" ] && b=$(cat "$fx/pr-body")
-  jq -n --arg h "$h" --arg b "$b" '{number:7,head:{ref:"feat/x",sha:$h},base:{ref:"main"},mergeable_state:"clean",body:$b}'
-  ;;
-"api repos/{owner}/{repo}") echo "{\"full_name\":\"o/r\"}" ;;
-api*)
-  printf '%s' "${@: -1}" >"$FAKE_GH_API_LOG"
-  echo "{}"
-  ;;
-*) exit 1 ;;
-esac

package/src/take/fixtures/busy.html

@@ -1,107 +0,0 @@
-<!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/fixtures/fade.html

@@ -1,49 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>Fade</title>
-    <!--
-      A band that fades from black to white over exactly one second of page
-      time once the button is pressed, so its brightness frame by frame reads
-      how much page time each frame of a take advanced.
-    -->
-    <style>
-      body {
-        margin: 0;
-        background: #808080;
-      }
-
-      #go {
-        position: absolute;
-        left: 100px;
-        top: 100px;
-        width: 200px;
-        height: 60px;
-      }
-
-      #band {
-        position: absolute;
-        left: 0;
-        top: 300px;
-        width: 1920px;
-        height: 780px;
-        background-color: #000;
-        transition: background-color 1000ms linear;
-      }
-
-      #band.lit {
-        background-color: #fff;
-      }
-    </style>
-  </head>
-  <body>
-    <button id="go">Go</button>
-    <div id="band"></div>
-    <script>
-      document.getElementById('go').addEventListener('click', () => {
-        document.getElementById('band').classList.add('lit')
-      })
-    </script>
-  </body>
-</html>

package/src/take/fixtures/fetch.html

@@ -1,38 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>Fetch</title>
-    <!--
-      A button whose press starts a fetch the server answers slowly, the way
-      a page switch in an app loads what the next view shows. A take must keep
-      stepping frames while the fetch is in flight.
-    -->
-    <style>
-      body {
-        margin: 0;
-        background: #808080;
-      }
-
-      #go {
-        position: absolute;
-        left: 100px;
-        top: 100px;
-        width: 200px;
-        height: 60px;
-      }
-    </style>
-  </head>
-  <body>
-    <button id="go">Load</button>
-    <p id="status">idle</p>
-    <script>
-      document.getElementById('go').addEventListener('click', () => {
-        document.getElementById('status').textContent = 'loading'
-        fetch('/slow').then(() => {
-          document.getElementById('status').textContent = 'loaded'
-        })
-      })
-    </script>
-  </body>
-</html>

package/src/take/fixtures/input.html

@@ -1,138 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>Input</title>
-    <!--
-      One target per input a take performs, each posting what the page saw to
-      /report with a sequence number, so a test reads the inputs in the order
-      the page received them after the take has closed the browser.
-
-      - #handle follows a pointer-event drag and reports where it dropped and
-        how many of its moves carried the held button
-      - #frame reports each dblclick
-      - #layer reports pointerdown, pointerup, and click with the Shift flag
-      - #field takes focus for key steps, and every keyup reports its value
-    -->
-    <style>
-      body {
-        margin: 0;
-        background: #f4f4f4;
-        font: 24px sans-serif;
-      }
-
-      #handle {
-        position: absolute;
-        left: 200px;
-        top: 200px;
-        width: 80px;
-        height: 80px;
-        /* Neutral, so the reel's blue ring reads over it at any alpha. */
-        background: #444;
-        touch-action: none;
-      }
-
-      #lane {
-        position: absolute;
-        left: 700px;
-        top: 160px;
-        width: 300px;
-        height: 160px;
-        border: 2px dashed #555;
-        box-sizing: border-box;
-      }
-
-      #frame,
-      #layer {
-        position: absolute;
-        top: 500px;
-        width: 200px;
-        height: 100px;
-        background: #ddd;
-        user-select: none;
-      }
-
-      #frame {
-        left: 200px;
-      }
-
-      #layer {
-        left: 700px;
-      }
-
-      #field {
-        position: absolute;
-        left: 200px;
-        top: 750px;
-        width: 400px;
-        height: 48px;
-        font: inherit;
-      }
-    </style>
-  </head>
-  <body>
-    <div id="lane"></div>
-    <div id="handle"></div>
-    <div id="frame">Frame</div>
-    <div id="layer">Layer</div>
-    <input id="field" />
-    <script>
-      let seq = 0
-      const report = (entry) =>
-        fetch('/report', {
-          method: 'POST',
-          body: JSON.stringify({ seq: (seq += 1), ...entry }),
-          keepalive: true,
-        })
-
-      const handle = document.getElementById('handle')
-      const lane = document.getElementById('lane')
-      let drag = null
-      handle.addEventListener('pointerdown', (event) => {
-        handle.setPointerCapture(event.pointerId)
-        drag = { held: 0, hover: 0 }
-      })
-      handle.addEventListener('pointermove', (event) => {
-        if (!drag) return
-        if (event.buttons === 1) drag.held += 1
-        else drag.hover += 1
-        handle.style.left = `${event.clientX - 40}px`
-        handle.style.top = `${event.clientY - 40}px`
-      })
-      handle.addEventListener('pointerup', (event) => {
-        if (!drag) return
-        const box = lane.getBoundingClientRect()
-        const onTarget =
-          event.clientX >= box.left &&
-          event.clientX <= box.right &&
-          event.clientY >= box.top &&
-          event.clientY <= box.bottom
-        report({ type: 'drop', ...drag, onTarget, altKey: event.altKey })
-        drag = null
-      })
-
-      document
-        .getElementById('frame')
-        .addEventListener('dblclick', () => report({ type: 'dblclick' }))
-
-      const layer = document.getElementById('layer')
-      for (const type of ['pointerdown', 'pointerup', 'click']) {
-        layer.addEventListener(type, (event) =>
-          report({ type, shiftKey: event.shiftKey }),
-        )
-      }
-
-      const field = document.getElementById('field')
-      document.addEventListener('keydown', (event) =>
-        report({
-          type: 'keydown',
-          key: event.key,
-          ctrlKey: event.ctrlKey,
-        }),
-      )
-      document.addEventListener('keyup', (event) =>
-        report({ type: 'keyup', key: event.key, value: field.value }),
-      )
-    </script>
-  </body>
-</html>

package/src/take/zoom/NOTICE.md

@@ -1,45 +0,0 @@
-# Vendored zoom notice
-
-The files in this folder carry the zoom timing of [OpenScreen](https://github.com/siddharthvaddem/openscreen) at commit `ca8104c279da0d4b4481ec992ff103949e22c772`, under the MIT license below.
-
-## What came from where
-
-| File              | Source in OpenScreen, under `src/components/video-editor/videoPlayback/`                                 |
-| ----------------- | -------------------------------------------------------------------------------------------------------- |
-| `math-utils.ts`   | `mathUtils.ts`                                                                                           |
-| `region-utils.ts` | `zoomRegionUtils.ts`, with `TRANSITION_WINDOW_MS` and `ZOOM_IN_TRANSITION_WINDOW_MS` from `constants.ts` |
-| `spring.ts`       | `motionSmoothing.ts` and `zoomSpring.ts`                                                                 |
-
-## What changed
-
-- The file names are kebab-case, as this repository names every TypeScript file, and the code is reformatted to its style
-- `math-utils.ts` keeps `clamp01`, `cubicBezier`, and `easeOutScreenStudio`, and drops the easings nothing here calls
-- `region-utils.ts` keeps `computeRegionStrength`, the connected-pan easing, and the window and gap constants. It drops the dominant-region search, its cache, the 3D rotation, and the cursor-follow focus, since the camera here aims at clicks and holds its focus by its own rule.
-- The zoom-out window is 700 ms rather than 1015.05 ms, and the connected pan runs 600 ms rather than 1000 ms, both on the operator's eye in groundwork track `193-ui-record`. <!-- canon-keep-retired --> The zoom-in window keeps OpenScreen's 1522.575 ms.
-- `spring.ts` keeps the zoom spring's stiffness 320, damping 40, mass 0.92, its rest thresholds, the delta clamp, and the overshoot clamp from `stepAxis`. OpenScreen steps that spring through the `motion` package, and this solves it in closed form instead, so no dependency comes with it.
-
-## License
-
-```plaintext
-MIT License
-
-Copyright (c) 2025 Siddharth Vaddem
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```