@erclx/canon 5.27.0 → 5.29.0

package/src/pr/evidence.ts

@@ -29,8 +29,17 @@ const BASE_PREFIX = '**Base:**'
 const CHECKLIST_HEADING = '## What to look at'
 
 /** Delimiters around the checklist, so a re-render can read back what a reviewer has already ticked. */
-const CHECKLIST_START = '<!-- pr-checklist:start -->'
-const CHECKLIST_END = '<!-- pr-checklist:end -->'
+export const CHECKLIST_START = '<!-- pr-checklist:start -->'
+export const CHECKLIST_END = '<!-- pr-checklist:end -->'
+
+/** One checklist line, a list marker then a box that GitHub renders for `x` in either case. */
+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)'
 
 /** A `#issuecomment-<id>` suffix, which is the REST comment id `gh pr view` never returns directly. */
 const ISSUE_COMMENT_ID = /#issuecomment-(\d+)$/
@@ -38,8 +47,8 @@ const ISSUE_COMMENT_ID = /#issuecomment-(\d+)$/
 /**
  * The image extensions this module embeds. An `evidence/` folder holds
  * whatever else a project keeps beside its captures, such as a README, a
- * capture script, or a raw data file, and none of those render as
- * `![](url)` without producing a broken embed.
+ * capture script, or a raw data file, and none of those render as an
+ * `<img>` without producing a broken embed.
  */
 const IMAGE_EXTENSION = /\.(png|jpe?g|gif|webp|avif|svg)$/i
 
@@ -48,6 +57,10 @@ export interface EvidenceItem {
   readonly stem: string
   /** True when `path` did not exist at the comparison's base commit. */
   readonly added: boolean
+  /** Pixel width of the head image, read from its PNG header. Absent when unread. */
+  readonly width?: number
+  /** Pixel width of the base image, absent for an added case or an unread header. */
+  readonly baseWidth?: number
 }
 
 export interface EvidenceState {
@@ -130,6 +143,57 @@ function rawUrl(repo: string, sha: string, path: string): string {
   return `https://github.com/${repo}/blob/${sha}/${path}?raw=true`
 }
 
+/**
+ * The most pixels a screenshot asks for. GitHub sizes a comment table to its
+ * content and clamps an image to its cell, so a width past any comment fills
+ * the cell, where `width="100%"` leaves a narrow screenshot narrow. An image
+ * asks for the smaller of its own width and this ceiling, so a small crop
+ * shows at its true size and is never scaled up. An image whose width was not
+ * read asks for the ceiling.
+ */
+const IMAGE_WIDTH = 1000
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
+
+/** Bytes of a PNG that reach the end of IHDR's width field. */
+export const PNG_HEADER_BYTES = 24
+
+/**
+ * The pixel width in a PNG's IHDR chunk, or undefined for bytes that are not
+ * a PNG with a header or that carry a zero width.
+ */
+export function readPngWidth(bytes: Uint8Array): number | undefined {
+  if (bytes.length < PNG_HEADER_BYTES) return undefined
+  if (PNG_SIGNATURE.some((byte, index) => bytes[index] !== byte)) {
+    return undefined
+  }
+  const width = new DataView(bytes.buffer, bytes.byteOffset).getUint32(16)
+  return width > 0 ? width : undefined
+}
+
+/** A table cell and an attribute value share one escape, since a stem is a path segment placed in both. */
+function escapeCell(text: string): string {
+  return text
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('|', '&#124;')
+}
+
+function evidenceImage(url: string, alt: string, width?: number): string {
+  const shown = Math.min(width ?? IMAGE_WIDTH, IMAGE_WIDTH)
+  return `<img src="${url}" width="${shown}" alt="${alt}">`
+}
+
+const EVIDENCE_IMAGE = String.raw`(?:!\[\]\([^)]*\)|<img [^>]*>)`
+
+/** A case row in any shape a render has posted: a Base cell before the head image, or the head image alone. */
+const EVIDENCE_ROW_PATTERN = new RegExp(
+  String.raw`^\| .+ \| (?:(?:\*\(new\)\*|${EVIDENCE_IMAGE}) \| )?${EVIDENCE_IMAGE} \|$`,
+  'gm',
+)
+
 export function evidenceMarker(head: string): string {
   return `${MARKER_PREFIX} head=${head} -->`
 }
@@ -189,20 +253,32 @@ export function renderEvidenceBody(
     imageCount <= EVIDENCE_OPEN_LIMIT ? '<details open>' : '<details>'
 
   const sections = states.map((entry) => {
+    const hasBase = entry.items.some((item) => !item.added)
     const rows = entry.items.map((item) => {
+      const stem = escapeCell(item.stem)
       const before = item.added
         ? '*(new)*'
-        : `![](${rawUrl(repo, base, item.path)})`
-      const after = `![](${rawUrl(repo, head, item.path)})`
-      return `| ${item.stem} | ${before} | ${after} |`
+        : evidenceImage(
+            rawUrl(repo, base, item.path),
+            `${stem} base`,
+            item.baseWidth,
+          )
+      const after = evidenceImage(
+        rawUrl(repo, head, item.path),
+        `${stem} head`,
+        item.width,
+      )
+      return hasBase
+        ? `| ${stem} | ${before} | ${after} |`
+        : `| ${stem} | ${after} |`
     })
 
     return [
       opener,
       `<summary>${entry.state === '' ? 'evidence' : entry.state} (${entry.items.length})</summary>`,
       '',
-      '| Case | Base | Head |',
-      '| --- | --- | --- |',
+      hasBase ? '| Case | Base | Head |' : '| Case | Head |',
+      hasBase ? '| --- | --- | --- |' : '| --- | --- |',
       ...rows,
       '',
       '</details>',
@@ -221,16 +297,14 @@ export function renderEvidenceBody(
 }
 
 /**
- * How many case rows a rendered body carries, read off the same row shape
+ * How many case rows a rendered body carries, read off the row shapes
  * `renderEvidenceBody` writes. A row always ends in a head image, which a
- * checklist line or a preview address never does.
+ * checklist line or a preview address never does. The pattern also reads the
+ * `![](url)` three-column shape an earlier render posted, so a comment posted
+ * before the change still counts its cases and the `would-empty` guard holds.
  */
 export function countEvidenceCases(body: string): number {
-  return (
-    body.match(
-      /^\| .+ \| (?:\*\(new\)\*|!\[\]\([^)]*\)) \| !\[\]\([^)]*\) \|$/gm,
-    )?.length ?? 0
-  )
+  return body.match(EVIDENCE_ROW_PATTERN)?.length ?? 0
 }
 
 export interface EvidenceComment {
@@ -410,3 +484,101 @@ export function findEvidenceChecklist(
     marked.body.slice(start + CHECKLIST_START.length, end).trim() || undefined
   )
 }
+
+export interface ChecklistBox {
+  /** One-based position among the checklist's boxes, in the order they appear. */
+  readonly number: number
+  /** Index of the box's line within the checklist. */
+  readonly line: number
+  /** The box text with any stamp removed. */
+  readonly text: string
+  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. */
+  readonly isTaste: boolean
+}
+
+export interface BoxLine {
+  readonly before: string
+  readonly isTicked: boolean
+  readonly text: string
+  readonly stamp?: string
+}
+
+/** Splits one checklist line into its box parts, or undefined when the line is not a box. */
+export function parseBoxLine(line: string): BoxLine | undefined {
+  const match = BOX_LINE.exec(line)
+  if (match === null) return undefined
+  const rest = (match[4] ?? '').trimEnd()
+  const stamped = STAMP.exec(rest)
+  return {
+    before: match[1] ?? '',
+    isTicked: (match[2] ?? ' ') !== ' ',
+    text: stamped === null ? rest : rest.slice(0, stamped.index),
+    ...(stamped?.[1] !== undefined && { stamp: stamped[1] }),
+  }
+}
+
+/** The box line for the given parts, written back in the one shape the reader accepts. */
+export function writeBoxLine(
+  box: Pick<BoxLine, 'before' | 'text'>,
+  stampedAt?: string,
+): string {
+  return stampedAt === undefined
+    ? `${box.before} ] ${box.text}`
+    : `${box.before}x] ${box.text} · passed at \`${stampedAt.slice(0, SHORT_SHA_LENGTH)}\``
+}
+
+/** Every box of a checklist in order, numbered the way `canon pr tick` takes them. */
+export function readChecklistBoxes(checklist: string): ChecklistBox[] {
+  const boxes: ChecklistBox[] = []
+  checklist.split('\n').forEach((line, index) => {
+    const parsed = parseBoxLine(line)
+    if (parsed === undefined) return
+    boxes.push({
+      number: boxes.length + 1,
+      line: index,
+      text: parsed.text,
+      isTicked: parsed.isTicked,
+      ...(parsed.stamp !== undefined && { stamp: parsed.stamp }),
+      isTaste: parsed.text.endsWith(TASTE_SUFFIX),
+    })
+  })
+  return boxes
+}
+
+/** The head the marked comment's trailing marker names. */
+export function findEvidenceHead(
+  comments: readonly EvidenceComment[],
+): string | undefined {
+  const marked = comments.find((comment) => hasEvidenceMarker(comment.body))
+  if (marked === undefined) return undefined
+  const lines = marked.body.trimEnd().split('\n')
+  const match = /head=(\S+)/.exec(lines[lines.length - 1] ?? '')
+  return match?.[1]
+}
+
+/**
+ * Clears every tick the render's head has not earned. A stamped tick stays
+ * while its sha is a prefix of the head. An unstamped one names no head, so
+ * it stays only while the comment it came from described this same head.
+ */
+export function settleChecklist(
+  checklist: string,
+  head: string,
+  carriedHead: string | undefined,
+): string {
+  return checklist
+    .split('\n')
+    .map((line) => {
+      const parsed = parseBoxLine(line)
+      if (parsed === undefined || !parsed.isTicked) return line
+      const isEarned =
+        parsed.stamp === undefined
+          ? carriedHead === head
+          : head.startsWith(parsed.stamp)
+      return isEarned ? line : writeBoxLine(parsed)
+    })
+    .join('\n')
+}

package/src/pr/tick.ts

@@ -0,0 +1,56 @@
+import {
+  CHECKLIST_END,
+  CHECKLIST_START,
+  parseBoxLine,
+  readChecklistBoxes,
+  writeBoxLine,
+} from '@/pr/evidence'
+
+export type TickRefusal = 'no-checklist' | 'no-box' | 'taste-box'
+
+export type TickResult =
+  | { readonly kind: 'ticked'; readonly body: string }
+  | { readonly kind: 'refused'; readonly reason: TickRefusal }
+
+/**
+ * Ticks the named boxes of a marked body's checklist and stamps each with the
+ * commit it passed at. A refusal writes nothing, so a taste box named among
+ * passed ones leaves every box as it was. A box already ticked is restamped,
+ * which makes a repeat at one head a no-op.
+ */
+export function tickBoxes(
+  body: string,
+  numbers: readonly number[],
+  head: string,
+): TickResult {
+  const start = body.indexOf(CHECKLIST_START)
+  const end = body.indexOf(CHECKLIST_END, start)
+  if (start === -1 || end === -1) {
+    return { kind: 'refused', reason: 'no-checklist' }
+  }
+
+  const from = start + CHECKLIST_START.length
+  const region = body.slice(from, end)
+  const boxes = readChecklistBoxes(region)
+
+  const named = numbers.map((number) =>
+    boxes.find((box) => box.number === number),
+  )
+  if (named.some((box) => box === undefined)) {
+    return { kind: 'refused', reason: 'no-box' }
+  }
+  if (named.some((box) => box?.isTaste === true)) {
+    return { kind: 'refused', reason: 'taste-box' }
+  }
+
+  const lines = region.split('\n')
+  for (const box of named) {
+    if (box === undefined) continue
+    const parsed = parseBoxLine(lines[box.line] ?? '')
+    if (parsed !== undefined) lines[box.line] = writeBoxLine(parsed, head)
+  }
+  return {
+    kind: 'ticked',
+    body: `${body.slice(0, from)}${lines.join('\n')}${body.slice(end)}`,
+  }
+}

package/src/process/harness.ts

@@ -1,7 +1,7 @@
 import { spawnSync } from 'node:child_process'
 import { readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
-import { PROJECT_ROOT } from '@/project-root'
+import { PROJECT_ROOT } from '@/roots/project'
 import { stateDir } from '@/targets/registry'
 
 const CLI = join(PROJECT_ROOT, 'src/cli.ts')

package/src/records/backup.ts

@@ -2,7 +2,7 @@ import { existsSync, lstatSync, readdirSync } from 'node:fs'
 import { basename, join, relative, resolve } from 'node:path'
 import { $ } from 'bun'
 import { gitEnv } from '@/git/env'
-import { RECORD_ROOTS, recordRoot, SCRATCH } from '@/record-root'
+import { RECORD_ROOTS, recordRoot, SCRATCH } from '@/roots/record'
 import { type BlockedPath, guardPayload } from '@/records/push-guard'
 
 /**

package/src/records/ordinal.ts

@@ -1,6 +1,6 @@
 import { mkdir, readdir, rm, stat } from 'node:fs/promises'
 import { extractOrdinal } from '@/intake/folder'
-import { recordDir } from '@/record-root'
+import { recordDir } from '@/roots/record'
 
 /**
  * The two record folders that share one ordinal sequence, per

package/src/records/prune.ts

@@ -3,7 +3,7 @@ import { readdir, rm, stat } from 'node:fs/promises'
 import { join, relative } from 'node:path'
 import { RECORD_LAYOUT_MOVES } from '@/migrate/record-layout'
 import { PROMOTED_FOLDERS } from '@/migrate/scratch-evidence'
-import { RECORD_ROOTS, recordDir, SCRATCH } from '@/record-root'
+import { RECORD_ROOTS, recordDir, SCRATCH } from '@/roots/record'
 import { day, newestMtime } from '@/records/size'
 
 const DAY_MS = 24 * 60 * 60 * 1000

package/src/records/size.ts

@@ -1,7 +1,7 @@
 import { existsSync, type Stats } from 'node:fs'
 import { readdir, stat } from 'node:fs/promises'
 import { join } from 'node:path'
-import { RECORD_ROOTS, recordDir, SCRATCH } from '@/record-root'
+import { RECORD_ROOTS, recordDir, SCRATCH } from '@/roots/record'
 import { candidateFolders } from '@/records/backup'
 
 /**

package/src/records/stale-canonical.ts

@@ -4,7 +4,7 @@ import { readFile } from 'node:fs/promises'
 import { relative } from 'node:path'
 import { gitEnv } from '@/git/env'
 import { readReviewed } from '@/records/stale'
-import { surfaceDir } from '@/surface-root'
+import { surfaceDir } from '@/roots/surface'
 
 /** The two records whose drift is identity rather than a stale path. */
 const CANONICAL_DOCS = ['REQUIREMENTS.md', 'ARCHITECTURE.md'] as const

package/src/records/stale.ts

@@ -8,7 +8,7 @@ import {
   recordDir,
   SCRATCH,
   spell,
-} from '@/record-root'
+} from '@/roots/record'
 
 /** The window after which a reviewed entry is due again, in days. */
 export const DEFAULT_REVIEW_DAYS = 30

package/src/records/validate.ts

@@ -6,7 +6,7 @@ import { linesOutsideFences } from '@/markdown/scan'
 import {
   recordDir as resolveRecordDir,
   recordDirs as resolveRecordDirs,
-} from '@/record-root'
+} from '@/roots/record'
 import { ATTRIBUTE_MARKER, governedPaths, readScope } from '@/standards/scope'
 import {
   TEACH_GLOSSARY,
@@ -39,7 +39,7 @@ export type RecordKind = (typeof RECORD_KINDS)[number]
  * the second, so one order serves both.
  *
  * Every other kind is a session record and takes the record roots instead,
- * resolved by `@/record-root`. Standards is the one kind that is tracked, so it
+ * resolved by `@/roots/record`. Standards is the one kind that is tracked, so it
  * does not move and spells its own two candidates here.
  */
 const STANDARDS_FOLDERS: readonly string[] = [

package/src/{project-root.ts → roots/project.ts}

@@ -16,7 +16,7 @@ import { fileURLToPath } from 'node:url'
  */
 export const PROJECT_ROOT = resolve(
   dirname(fileURLToPath(import.meta.url)),
-  '..',
+  '../..',
 )
 
 const readPackageName = (root: string): string | undefined => {
@@ -72,7 +72,7 @@ export function findCheckoutMismatch(startDir: string): string | undefined {
  * The warning line every verb that answers from `PROJECT_ROOT` emits when the
  * caller's cwd sits inside a second checkout, or `undefined` when it does not.
  *
- * It returns the string rather than logging it so this module keeps no `@/ui`
+ * It returns the string rather than logging it so this module keeps no `@/cli/ui`
  * dependency and the wording is unit-testable on its own. The wording names
  * both roots and no subcommand: the four chokepoints that carry it stand under
  * eight-plus verbs each, so a per-verb suffix would cost a parameter at every

package/src/{record-root.ts → roots/record.ts}

@@ -57,7 +57,7 @@ const CANON_SCRATCH = 'tmp'
  * record root, which is the rule the move ran on. `rules`, `skills`, and
  * `hooks` stay under `.claude/` because the vendor reads them there, while
  * `context`, `wireframes`, and the loose documents are tracked surfaces that
- * `surface-root.ts` resolves under `canon/` instead. A seed and a
+ * `surface.ts` resolves under `canon/` instead. A seed and a
  * superseded-layout report each ask this rather than assuming a root.
  */
 export const RECORD_ENTRIES: readonly string[] = [

package/src/sandbox/coverage.ts

@@ -1,5 +1,10 @@
 import { existsSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
+import {
+  FIXTURES_DIR,
+  listCategories,
+  listScenarioFiles,
+} from '@/sandbox/scenario'
 
 /**
  * The arm a scenario declares when it carries no named arm. `expectFilePath`
@@ -8,9 +13,6 @@ import { join } from 'node:path'
  */
 export const DEFAULT_ARM = '(default)'
 
-/** Holds fixture content rather than scenarios. Twin of the filter in `sandbox.ts`. */
-const FIXTURES_DIR = 'fixtures'
-
 export interface ScenarioCoverage {
   readonly category: string
   readonly command: string
@@ -41,15 +43,12 @@ function directories(path: string): string[] {
 function listScenarios(sandboxDir: string): ScenarioCoverage[] {
   const scenarios: ScenarioCoverage[] = []
 
-  for (const category of directories(sandboxDir)) {
-    if (category === FIXTURES_DIR) continue
-
-    const commands = readdirSync(join(sandboxDir, category), {
-      withFileTypes: true,
-    })
-      .filter((entry) => entry.isFile() && entry.name.endsWith('.sh'))
-      .map((entry) => entry.name.replace(/\.sh$/, ''))
-      .sort()
+  for (const category of listCategories(sandboxDir)) {
+    // A stem in both forms counts once, and provisioning refuses it by name.
+    const { scenarios: files, ambiguous } = listScenarioFiles(
+      join(sandboxDir, category),
+    )
+    const commands = [...files.map((f) => f.command), ...ambiguous].sort()
 
     for (const command of commands) {
       scenarios.push({ category, command, armed: [] })

package/src/sandbox/equivalence.ts

@@ -17,11 +17,15 @@ import {
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { collectCoverage, DEFAULT_ARM } from '@/sandbox/coverage'
+import {
+  armNames,
+  listCategories,
+  listScenarioFiles,
+  loadScenario,
+  type ScenarioKind,
+} from '@/sandbox/scenario'
 import { createStubRemote, readStubManifest } from '@/sandbox/stub-remote'
 
-/** Holds fixture content rather than scenarios. Twin of the filter in `sandbox.ts`. */
-const FIXTURES_DIR = 'fixtures'
-
 /** One arm provisions inside this budget on each side, or reads as a failed run. */
 const PROVISION_TIMEOUT_MS = 120_000
 
@@ -149,13 +153,6 @@ export function armKey(arm: Arm): string {
   return arm.arm === undefined ? scenario : `${scenario}/${arm.arm}`
 }
 
-function directories(path: string): string[] {
-  return readdirSync(path, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => entry.name)
-    .sort()
-}
-
 /**
  * Reads the quoted arguments of `select_or_route_scenario`, joining a call that
  * continues across backslash-newline pairs. The first argument is the prompt and
@@ -201,6 +198,42 @@ function matchesArm(arm: Arm, targets: readonly string[]): boolean {
   return scoped.includes(armKey(arm))
 }
 
+/**
+ * Reads a scenario's arm names and anchor flag: off a bash file's source, and
+ * off a TypeScript module's own keys, which is what its stage routes on.
+ */
+function readArms(
+  file: string,
+  kind: ScenarioKind,
+):
+  | { ok: true; anchor: boolean; names: string[] }
+  | { ok: false; error: string } {
+  if (kind === 'sh') {
+    const source = readFileSync(file, 'utf8')
+
+    return {
+      ok: true,
+      anchor: /^use_anchor\s*\(\)/m.test(source),
+      names: parseArmNames(source),
+    }
+  }
+
+  try {
+    const definition = loadScenario(file)
+
+    return {
+      ok: true,
+      anchor: definition.anchor === true,
+      names: armNames(definition),
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
 /**
  * Lists every provision a target names, from the scenario source. An armed arm
  * that `canon sandbox coverage` reports and this list lacks is returned as an
@@ -216,25 +249,23 @@ export function enumerateArms(
   const errors: string[] = []
   const coverage = collectCoverage(root)
 
-  for (const category of directories(sandboxDir)) {
-    if (category === FIXTURES_DIR) continue
-
-    const commands = readdirSync(join(sandboxDir, category), {
-      withFileTypes: true,
-    })
-      .filter((f) => f.isFile() && f.name.endsWith('.sh'))
-      .map((f) => f.name.replace(/\.sh$/, ''))
-      .sort()
+  for (const category of listCategories(sandboxDir)) {
+    const { scenarios, ambiguous } = listScenarioFiles(
+      join(sandboxDir, category),
+    )
+    for (const command of ambiguous)
+      if (matchesTarget(category, command, targets))
+        errors.push(`${category}:${command} exists as both .sh and .ts`)
 
-    for (const command of commands) {
+    for (const { command, file, kind } of scenarios) {
       if (!matchesTarget(category, command, targets)) continue
 
-      const source = readFileSync(
-        join(sandboxDir, category, `${command}.sh`),
-        'utf8',
-      )
-      const anchor = /^use_anchor\s*\(\)/m.test(source)
-      const names = parseArmNames(source)
+      const declared = readArms(file, kind)
+      if (!declared.ok) {
+        errors.push(`${category}:${command} did not load: ${declared.error}`)
+        continue
+      }
+      const { anchor, names } = declared
 
       const found: Arm[] =
         names.length === 0

package/src/sandbox/headless/run.ts

@@ -37,7 +37,7 @@ import {
   logStep,
   logWarn,
   outro,
-} from '@/ui'
+} from '@/cli/ui'
 
 /**
  * The flags and budget every run takes, each overridable through its

package/src/sandbox/hooks.ts

@@ -2,7 +2,7 @@ import { spawnSync } from 'node:child_process'
 import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { PROJECT_ROOT } from '@/project-root'
+import { PROJECT_ROOT } from '@/roots/project'
 
 /**
  * The bash entry a scenario's hooks run through. Scenarios and the library they