@erclx/canon 5.24.0 → 5.26.0

package/src/pr/evidence.ts

@@ -1,6 +1,12 @@
 /** The path segment that marks an image as evidence a pull request should compare. */
 const EVIDENCE_SEGMENT = 'evidence'
 
+/** The most images a comment carries and still opens its states, since past it the page is a wall of screenshots. */
+const EVIDENCE_OPEN_LIMIT = 6
+
+/** Length of the commit names the visible line shows, the width `git` abbreviates to. */
+const SHORT_SHA_LENGTH = 7
+
 /** Prefix of the trailing marker this module writes and reads back. */
 const MARKER_PREFIX = '<!-- pr-evidence:'
 
@@ -120,10 +126,14 @@ export function evidenceMarker(head: string): string {
 }
 
 /**
- * Renders the whole comment body: one collapsed `<details>` block per state,
- * a Base/Head row per case, and the trailing marker naming the head this body
- * describes. Every image URL is pinned to a commit sha rather than a branch,
- * so the comment keeps showing what it claimed even after the branch moves.
+ * Renders the whole comment body: one `<details>` block per state, a Base/Head
+ * row per case, and the trailing marker naming the head this body describes.
+ * Every state opens while the comment carries at most `EVIDENCE_OPEN_LIMIT`
+ * images, one per row for the head plus one per row not added, and every state
+ * closes past it, so a comment is never half open. A visible line under
+ * `## Evidence` names the base and head as short shas. Every image URL is
+ * pinned to a commit sha rather than a branch, so the comment keeps showing
+ * what it claimed even after the branch moves.
  *
  * A preview address opens the body, and with no states it is the whole body
  * apart from the marker, so a pull request whose screenshots did not change
@@ -157,6 +167,14 @@ export function renderEvidenceBody(
     return [...opening, ...closing, evidenceMarker(head)].join('\n')
   }
 
+  const imageCount = states.reduce(
+    (total, entry) =>
+      total + entry.items.reduce((sum, item) => sum + (item.added ? 1 : 2), 0),
+    0,
+  )
+  const opener =
+    imageCount <= EVIDENCE_OPEN_LIMIT ? '<details open>' : '<details>'
+
   const sections = states.map((entry) => {
     const rows = entry.items.map((item) => {
       const before = item.added
@@ -167,7 +185,7 @@ export function renderEvidenceBody(
     })
 
     return [
-      '<details>',
+      opener,
       `<summary>${entry.state === '' ? 'evidence' : entry.state} (${entry.items.length})</summary>`,
       '',
       '| Case | Base | Head |',
@@ -182,6 +200,8 @@ export function renderEvidenceBody(
     ...opening,
     '## Evidence',
     '',
+    `**Base:** \`${base.slice(0, SHORT_SHA_LENGTH)}\` · **Head:** \`${head.slice(0, SHORT_SHA_LENGTH)}\``,
+    '',
     ...sections,
     '',
     ...closing,

package/src/pr/rest.ts

@@ -0,0 +1,137 @@
+/**
+ * The REST shapes `canon pr` reads a pull request through, put into the shapes
+ * its readers already take.
+ *
+ * A cloud session's GitHub proxy refuses GraphQL and serves REST, and every
+ * `gh pr view` runs on GraphQL. The verbs therefore read the pulls, reviews,
+ * and issue-comments endpoints, and this module is the one boundary where
+ * those payloads meet the field names the rest of `src/pr/` was written
+ * against.
+ */
+import type { ReviewRow } from '@/pr/review-scope'
+
+/** One row of `repos/{owner}/{repo}/pulls/<n>` or of the pulls listing. */
+export interface RestPull {
+  readonly number?: number
+  readonly body?: string | null
+  readonly head?: { readonly ref?: string; readonly sha?: string }
+  readonly base?: { readonly ref?: string }
+  readonly mergeable_state?: string
+}
+
+/** One row of `repos/{owner}/{repo}/pulls/<n>/reviews`. */
+export interface RestReview {
+  readonly body?: string | null
+  readonly commit_id?: string | null
+  readonly submitted_at?: string | null
+}
+
+/** One row of `repos/{owner}/{repo}/issues/<n>/comments`. */
+export interface RestComment {
+  readonly html_url?: string
+  readonly body?: string | null
+}
+
+/** The head branch, reported head, and base of the pull request a caller named. */
+export interface PullIdentity {
+  readonly number: number | undefined
+  readonly branch: string
+  readonly head?: string
+  readonly base?: string
+  readonly mergeState?: string
+}
+
+export type BranchPull =
+  | { readonly kind: 'found'; readonly number: number }
+  | {
+      readonly kind: 'refused'
+      readonly reason: 'gh-failed' | 'ambiguous-pull'
+    }
+
+/**
+ * Spells `mergeable_state` the way GraphQL's `mergeStateStatus` spells it.
+ *
+ * The two vocabularies hold the same values in different cases, so the
+ * mapping is a case change. `unknown` stays `UNKNOWN`, which `withMergeState`
+ * already reads as not conflicted while GitHub computes the state lazily.
+ */
+export function mergeStateOf(state: string | undefined): string | undefined {
+  return state === undefined || state === '' ? undefined : state.toUpperCase()
+}
+
+export function identityOf(row: RestPull): PullIdentity {
+  const mergeState = mergeStateOf(row.mergeable_state)
+  return {
+    number: row.number,
+    branch: row.head?.ref ?? '',
+    ...(row.head?.sha !== undefined && { head: row.head.sha }),
+    ...(row.base?.ref !== undefined && { base: row.base.ref }),
+    ...(mergeState !== undefined && { mergeState }),
+  }
+}
+
+/**
+ * The one open pull request a branch carries.
+ *
+ * Two open pull requests on one head against different bases refuse rather
+ * than resolving to the first, since the listing's order says nothing about
+ * which one the caller meant.
+ */
+export function selectBranchPull(rows: readonly RestPull[]): BranchPull {
+  const numbers = rows
+    .map((row) => row.number)
+    .filter((number): number is number => number !== undefined)
+  if (numbers.length > 1) return { kind: 'refused', reason: 'ambiguous-pull' }
+  const [number] = numbers
+  return number === undefined
+    ? { kind: 'refused', reason: 'gh-failed' }
+    : { kind: 'found', number }
+}
+
+/**
+ * A pending review carries no `submitted_at`, which reads as null the way the
+ * GraphQL listing reported it.
+ */
+export function reviewRowOf(review: RestReview): ReviewRow {
+  return {
+    body: review.body ?? '',
+    commit:
+      review.commit_id === undefined || review.commit_id === null
+        ? null
+        : { oid: review.commit_id },
+    submittedAt: review.submitted_at ?? null,
+  }
+}
+
+/** `html_url` ends in the same `#issuecomment-<id>` anchor GraphQL's `url` did. */
+export function commentRowOf(comment: RestComment): {
+  readonly url?: string
+  readonly body: string
+} {
+  return {
+    ...(comment.html_url !== undefined && { url: comment.html_url }),
+    body: comment.body ?? '',
+  }
+}
+
+/**
+ * Parses the output of `gh api --paginate --jq '.[] | @json'`, one compact
+ * object per line across every page.
+ *
+ * A filter that reshapes each row makes `--paginate` emit one value per page
+ * rather than one merged array, so a line per row is the form that survives
+ * paging. A line that does not parse refuses the whole listing, since a list
+ * short by one review reads as a thread missing its newest pass.
+ */
+export function parseJsonLines<T>(stdout: string): T[] | undefined {
+  const rows: T[] = []
+  for (const line of stdout.split('\n')) {
+    if (line.trim() === '') continue
+    try {
+      rows.push(JSON.parse(line) as T)
+    } catch {
+      return undefined
+    }
+  }
+  return rows
+}

package/src/record-root.ts

@@ -76,6 +76,7 @@ export const RECORD_ENTRIES: readonly string[] = [
   'proposals',
   'ready',
   'review',
+  'slides',
   'tasks',
   'teach',
   'transcripts',

package/src/records/backup.ts

@@ -43,6 +43,7 @@ export const BACKED_FOLDERS = [
   'plans',
   'proposals',
   'review',
+  'slides',
   'tasks',
   'teach',
   'transcripts',

package/src/records/push-guard.ts

@@ -1,6 +1,6 @@
 import { lstat, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { isBinary } from '@/binary'
+import { isBinary } from '@/sweep/binary'
 import { scanText } from '@/secrets/scan'
 
 /**

package/src/records/stale-canonical.ts

@@ -0,0 +1,146 @@
+import { $ } from 'bun'
+import { existsSync } from 'node:fs'
+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'
+
+/** The two records whose drift is identity rather than a stale path. */
+const CANONICAL_DOCS = ['REQUIREMENTS.md', 'ARCHITECTURE.md'] as const
+
+export interface CanonicalDoc {
+  /** Relative to the root, at whichever surface root carries the doc. */
+  readonly path: string
+  /** `YYYY-MM-DD`, or null when the doc carries no readable review date. */
+  readonly reviewed: string | null
+  /** The raw value of a `reviewed` field that is not a date, present only then. */
+  readonly invalidReviewed?: string
+  /** Release tags merged into HEAD after the reviewed day, or null when never reviewed. */
+  readonly releasesSince: number | null
+  /** The newest release tag merged into HEAD, or null when there is none. */
+  readonly latestRelease: string | null
+}
+
+export interface CanonicalReport {
+  readonly ok: true
+  readonly root: string
+  /** False when HEAD has merged no tag, so a zero count measured nothing. */
+  readonly tagged: boolean
+  readonly docs: readonly CanonicalDoc[]
+}
+
+export interface CanonicalRefused {
+  readonly ok: false
+  readonly reason: 'unreadable-tags'
+  readonly message: string
+}
+
+export type CanonicalOutcome = CanonicalReport | CanonicalRefused
+
+interface Release {
+  readonly tag: string
+  readonly day: string
+}
+
+/**
+ * A tag ending in a dotted version, bare or behind a component prefix such as
+ * `canon-v2.1.0`. An eval, deploy, or snapshot tag on the trunk names no
+ * release and would otherwise inflate the count.
+ */
+const RELEASE_TAG = /(?:^|[-/@_])v?\d+\.\d+(?:\.\d+)?(?:[-+][0-9A-Za-z.-]+)?$/
+
+/**
+ * A repository before its first commit has no HEAD for `--merged` to resolve,
+ * which git reports as a failed read. It has no tags either, so it reads as an
+ * empty history rather than an unreadable one.
+ */
+async function isUnborn(root: string): Promise<boolean> {
+  const [gitDir, head] = await Promise.all([
+    $`git -C ${root} rev-parse --git-dir`.env(gitEnv()).quiet().nothrow(),
+    $`git -C ${root} rev-parse --verify -q HEAD`
+      .env(gitEnv())
+      .quiet()
+      .nothrow(),
+  ])
+  return gitDir.exitCode === 0 && head.exitCode !== 0
+}
+
+/**
+ * Every release tag HEAD has merged, newest first, with the day it was created.
+ *
+ * The creator date is the tagging date on an annotated tag and the commit date
+ * on a lightweight one, so a history mixing both counts by two clocks.
+ */
+async function mergedReleases(root: string): Promise<Release[] | undefined> {
+  // Interpolated rather than inline, since Bun's shell parses the bare
+  // parentheses in `%(refname)` as syntax of its own.
+  const args = [
+    '--merged',
+    'HEAD',
+    '--sort=-creatordate',
+    '--format=%(creatordate:short) %(refname:short)',
+    'refs/tags',
+  ]
+  const result = await $`git -C ${root} for-each-ref ${args}`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  if (result.exitCode !== 0) return (await isUnborn(root)) ? [] : undefined
+
+  return result.stdout
+    .toString()
+    .split('\n')
+    .filter((line) => line.trim().length > 0)
+    .map((line) => {
+      const [day, tag] = line.trim().split(' ')
+      return { day, tag }
+    })
+    .filter((release) => RELEASE_TAG.test(release.tag))
+}
+
+/**
+ * Reports when each canonical doc was last reviewed and how many releases
+ * have shipped since, read from an optional `reviewed:` frontmatter field.
+ *
+ * The review point is a date rather than a commit, since a commit written on a
+ * feature branch never reaches a trunk that squash-merges. A release tagged on
+ * the reviewed day itself is not counted, as the review is read as covering
+ * that day. It reports and never writes.
+ */
+export async function staleCanonical(root: string): Promise<CanonicalOutcome> {
+  const releases = await mergedReleases(root)
+
+  if (releases === undefined) {
+    return {
+      ok: false,
+      reason: 'unreadable-tags',
+      message: `Could not read the release tags at ${root}, so no count can be taken.`,
+    }
+  }
+
+  const latestRelease = releases[0]?.tag ?? null
+  const present = CANONICAL_DOCS.map((entry) => surfaceDir(root, entry)).filter(
+    (path) => existsSync(path),
+  )
+
+  const docs = await Promise.all(
+    present.map(async (path): Promise<CanonicalDoc> => {
+      const text = (await readFile(path, 'utf8')).replaceAll('\r\n', '\n')
+      const review = readReviewed(text)
+      const { reviewed } = review
+
+      return {
+        path: relative(root, path),
+        ...review,
+        releasesSince:
+          reviewed === null
+            ? null
+            : releases.filter((release) => release.day > reviewed).length,
+        latestRelease,
+      }
+    }),
+  )
+
+  return { ok: true, root, tagged: releases.length > 0, docs }
+}

package/src/records/stale.ts

@@ -65,7 +65,7 @@ const RAW_FRONTMATTER = /^---\n([\s\S]*?)\n---/
  * A value that is not a calendar date reads as never reviewed and is carried
  * back so the review can see it, rather than throwing over one hand edit.
  */
-function readReviewed(
+export function readReviewed(
   text: string,
 ): Pick<StaleEntry, 'reviewed' | 'invalidReviewed'> {
   const block = RAW_FRONTMATTER.exec(text)?.[1]

package/src/sandbox/hooks.ts

@@ -0,0 +1,128 @@
+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'
+
+/**
+ * The bash entry a scenario's hooks run through. Scenarios and the library they
+ * call stay bash, so this contract is the whole of what the TypeScript harness
+ * knows about one: which hooks it declares and what `use_config` exports.
+ */
+const HOOK_SCRIPT = join(PROJECT_ROOT, 'scripts', 'sandbox-hook.sh')
+
+const ANCHOR_RECORD = '@anchor='
+
+export interface Probe {
+  readonly exports: Readonly<Record<string, string>>
+  readonly isAnchor: boolean
+}
+
+export type ProbeResult =
+  | ({ readonly ok: true } & Probe)
+  | { readonly ok: false; readonly status: number }
+
+/**
+ * Reads the NUL-separated `NAME=value` pairs the probe prints. NUL rather than a
+ * newline, since an exported value can hold one. The anchor record closes every
+ * well-formed probe, so output missing it is a probe that did not finish.
+ */
+export function parseProbe(stdout: string): Probe {
+  const { exports, anchor } = parsePairs(stdout)
+  if (anchor === undefined)
+    throw new Error('the probe printed no anchor record')
+
+  return { exports, isAnchor: anchor === '1' }
+}
+
+function parsePairs(text: string): {
+  exports: Record<string, string>
+  anchor: string | undefined
+} {
+  const exports: Record<string, string> = {}
+  let anchor: string | undefined
+
+  for (const record of text.split('\0')) {
+    if (record.startsWith(ANCHOR_RECORD)) {
+      anchor = record.slice(ANCHOR_RECORD.length)
+      continue
+    }
+    const split = record.indexOf('=')
+    if (split > 0) exports[record.slice(0, split)] = record.slice(split + 1)
+  }
+
+  return { exports, anchor }
+}
+
+/**
+ * Runs `use_config` and `use_anchor` in a child and returns what they exported.
+ * Stderr is inherited by default, so a hook that fails narrates into the same
+ * frame the harness writes. A non-zero status passes through rather than being
+ * flattened, since the harness exits with it.
+ */
+export function probeScenario(
+  file: string,
+  env: NodeJS.ProcessEnv,
+  stderr: 'inherit' | 'pipe' = 'inherit',
+): ProbeResult {
+  const result = spawnSync('bash', [HOOK_SCRIPT, 'probe', file], {
+    env,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', stderr],
+  })
+  const status = result.status ?? 1
+  if (status !== 0) return { ok: false, status }
+
+  return { ok: true, ...parseProbe(result.stdout) }
+}
+
+/**
+ * How `stage_setup` ended. The retired dispatcher ran it in its own shell, so
+ * an `exit` there ended provisioning through the frame-closing trap, and an
+ * `exec` replaced the harness outright, leaving its program's frame as the last
+ * one written. The harness reproduces both from this.
+ */
+export type StageEnding = 'returned' | 'exited' | 'replaced'
+
+export interface StageResult {
+  readonly status: number
+  readonly ending: StageEnding
+  readonly exports: Readonly<Record<string, string>>
+}
+
+const EXITED_RECORD = '@exited'
+
+/**
+ * Runs `stage_setup` inside the tree with every stream inherited, so a scenario
+ * prompting through `select_or_route_scenario` still reaches a terminal and its
+ * narration lands in order with the harness's own.
+ *
+ * The exports `stage_setup` changed come back through a file rather than a
+ * pipe. Stdout belongs to the scenario, and a background process a scenario
+ * starts would hold an extra pipe open past the child's exit.
+ */
+export function stageScenario(
+  file: string,
+  env: NodeJS.ProcessEnv,
+  stdio: 'inherit' | 'ignore' = 'inherit',
+): StageResult {
+  const scratch = mkdtempSync(join(tmpdir(), 'canon-sandbox-hook-'))
+  const report = join(scratch, 'exports')
+
+  try {
+    const result = spawnSync('bash', [HOOK_SCRIPT, 'stage', file, report], {
+      env,
+      stdio,
+    })
+    const status = result.status ?? 1
+    if (!existsSync(report)) return { status, ending: 'replaced', exports: {} }
+
+    const text = readFileSync(report, 'utf8')
+    if (text.split('\0').includes(EXITED_RECORD))
+      return { status, ending: 'exited', exports: {} }
+
+    return { status, ending: 'returned', exports: parsePairs(text).exports }
+  } finally {
+    rmSync(scratch, { recursive: true, force: true })
+  }
+}