@erclx/canon 5.32.0 → 5.34.0

package/src/pr/lift.ts

@@ -0,0 +1,418 @@
+import type { ChecksState } from '@/targets/pulls'
+import {
+  coversHead,
+  type ReviewRow,
+  resolveReviewScope,
+  resolveUiScope,
+} from '@/pr/review-scope'
+
+/** How long `--wait` holds for a pending CI run, in seconds, when none is named. */
+export const DEFAULT_WAIT_SECONDS = 1200
+
+/** The gap between two reads of the check runs while the verb waits on them. */
+export const CHECKS_POLL_MS = 30_000
+
+/** Why the verb did not lift, in the order the gates are read. */
+export type LiftRefusal =
+  | 'pull-closed'
+  | 'review-missing'
+  | 'review-open'
+  | 'review-unmarked'
+  | 'review-behind'
+  | 'ui-missing'
+  | 'ui-open'
+  | 'ui-unmarked'
+  | 'ui-behind'
+  | 'evidence-owed'
+  | 'standing-stale'
+  | 'standing-conflict'
+  | 'standing-unknown'
+  | 'ci-pending'
+  | 'ci-failing'
+  | 'ci-conflicted'
+  | 'ci-timeout'
+  | 'head-moved'
+  | 'gh-failed'
+
+/** The gates a pull request clears, named so a record can report each one. */
+export type GateName = 'review' | 'ui' | 'evidence' | 'standing' | 'ci'
+
+export interface GateResult {
+  readonly gate: GateName
+  readonly isOk: boolean
+  /** Absent when the gate passed. */
+  readonly reason?: LiftRefusal
+}
+
+/** How the head sits against the base the pull request targets. */
+export type Standing = 'fresh' | 'stale' | 'conflict' | 'unknown'
+
+export interface PullState {
+  readonly isDraft: boolean
+  readonly isOpen: boolean
+  /** The id the ready-for-review mutation takes. */
+  readonly nodeId: string
+  readonly branch: string
+  /** The head the pull request object reports, which lags the tip. */
+  readonly head: string
+}
+
+/** What the evidence check says about the comment the ship chain posts. */
+export interface EvidenceGate {
+  readonly isSettled: boolean
+  readonly owed: readonly string[]
+  /** Whether the marked comment carries a visual checklist, which binds the UI gate. */
+  readonly hasChecklist: boolean
+}
+
+export interface ChecksGate {
+  readonly state: ChecksState
+  readonly isConflicted: boolean
+}
+
+/**
+ * Everything the verb reads or writes, injected so the gates and the wait run
+ * without a network. A read that failed returns undefined, and the verb
+ * refuses `gh-failed` rather than reading absence as a pass.
+ */
+export interface LiftApi {
+  readPull(): Promise<PullState | undefined>
+  /** The branch tip from the remote, which is the authority for the head. */
+  readTip(branch: string): Promise<string | undefined>
+  readReviews(): Promise<readonly ReviewRow[] | undefined>
+  readEvidence(): Promise<EvidenceGate | undefined>
+  readStanding(head: string): Promise<Standing>
+  readChecks(tip: string): Promise<ChecksGate | undefined>
+  /** The one GraphQL call the verb makes. */
+  markReady(nodeId: string): Promise<boolean>
+  sleep(ms: number): Promise<void>
+  now(): number
+}
+
+export interface LiftOptions {
+  readonly isCheck: boolean
+  readonly waitSeconds: number
+  readonly pollMs?: number
+}
+
+export interface LiftRecord {
+  readonly reason: 'lifted' | 'already-ready' | 'clear' | LiftRefusal
+  readonly isLifted: boolean
+  /** Whether the caller can treat the pull request as ready afterwards. */
+  readonly isOk: boolean
+  readonly head?: string
+  readonly gates: readonly GateResult[]
+  readonly waitedSeconds: number
+}
+
+function pass(gate: GateName): GateResult {
+  return { gate, isOk: true }
+}
+
+function fail(gate: GateName, reason: LiftRefusal): GateResult {
+  return { gate, isOk: false, reason }
+}
+
+/**
+ * The code review gate. A pass with no marker is refused rather than lifted,
+ * since the commit it covers is a stamp GitHub wrote at submission, which the
+ * marker exists to replace.
+ */
+function reviewGate(reviews: readonly ReviewRow[], head: string): GateResult {
+  const scope = resolveReviewScope({ reviews })
+  if (scope.state === 'none') return fail('review', 'review-missing')
+  if (scope.state === 'open') return fail('review', 'review-open')
+  if (scope.source !== 'marker') return fail('review', 'review-unmarked')
+  if (scope.commit === undefined || !coversHead(scope.commit, head)) {
+    return fail('review', 'review-behind')
+  }
+  return pass('review')
+}
+
+/** Binds only where the evidence record carries a checklist to drive. */
+function uiGate(
+  reviews: readonly ReviewRow[],
+  head: string,
+  hasChecklist: boolean,
+): GateResult {
+  if (!hasChecklist) return pass('ui')
+
+  const scope = resolveUiScope({ reviews })
+  if (scope.state === 'none') return fail('ui', 'ui-missing')
+  if (scope.state === 'open') return fail('ui', 'ui-open')
+  if (scope.source !== 'marker') return fail('ui', 'ui-unmarked')
+  if (scope.commit === undefined || !coversHead(scope.commit, head)) {
+    return fail('ui', 'ui-behind')
+  }
+  return pass('ui')
+}
+
+function standingGate(standing: Standing): GateResult {
+  if (standing === 'fresh') return pass('standing')
+  return fail('standing', `standing-${standing}`)
+}
+
+type CiOutcome =
+  | { readonly kind: 'passing'; readonly waited: number }
+  | {
+      readonly kind: 'refused'
+      readonly reason: LiftRefusal
+      readonly waited: number
+    }
+
+/**
+ * Reads the check runs until they conclude, the deadline passes, or a run can
+ * no longer start. A conflicted branch gets no merge ref, so no run ever
+ * starts and waiting on it is the one wait that cannot end.
+ */
+async function waitForChecks(
+  api: LiftApi,
+  tip: string,
+  waitSeconds: number,
+  pollMs: number,
+): Promise<CiOutcome> {
+  const started = api.now()
+  const deadline = started + waitSeconds * 1000
+
+  for (;;) {
+    const reading = await api.readChecks(tip)
+    const waited = Math.round((api.now() - started) / 1000)
+    if (reading === undefined) {
+      return { kind: 'refused', reason: 'gh-failed', waited }
+    }
+    if (reading.state === 'passing') return { kind: 'passing', waited }
+    if (reading.state === 'failing') {
+      return { kind: 'refused', reason: 'ci-failing', waited }
+    }
+    if (reading.isConflicted) {
+      return { kind: 'refused', reason: 'ci-conflicted', waited }
+    }
+    if (api.now() + pollMs > deadline) {
+      return { kind: 'refused', reason: 'ci-timeout', waited }
+    }
+    await api.sleep(pollMs)
+  }
+}
+
+function refused(
+  reason: LiftRefusal,
+  gates: readonly GateResult[],
+  head: string | undefined,
+  waitedSeconds = 0,
+): LiftRecord {
+  return {
+    reason,
+    isLifted: false,
+    isOk: false,
+    ...(head !== undefined && { head }),
+    gates,
+    waitedSeconds,
+  }
+}
+
+/**
+ * Lifts the draft mark when every gate reads clear at the head.
+ *
+ * The reads that need no wait all run before the CI wait, so a reviewer whose
+ * partner is still driving refuses at once rather than holding a turn through
+ * a CI run. The head and the reviews are read again after the wait and before
+ * the mutation, since a push during the wait moves the head off the commit
+ * every earlier gate cleared.
+ */
+export async function lift(
+  api: LiftApi,
+  opts: LiftOptions,
+): Promise<LiftRecord> {
+  const pollMs = opts.pollMs ?? CHECKS_POLL_MS
+
+  const pull = await api.readPull()
+  if (pull === undefined) return refused('gh-failed', [], undefined)
+  if (!pull.isOpen) return refused('pull-closed', [], pull.head)
+  if (!pull.isDraft) {
+    return {
+      reason: 'already-ready',
+      isLifted: false,
+      isOk: true,
+      head: pull.head,
+      gates: [],
+      waitedSeconds: 0,
+    }
+  }
+
+  // The tip, not the object's head, since the object lags the ref by up to a
+  // minute after a push and a review marker names the commit it read.
+  const tip = await api.readTip(pull.branch)
+  if (tip === undefined) return refused('gh-failed', [], pull.head)
+
+  const [reviews, evidence, standing] = await Promise.all([
+    api.readReviews(),
+    api.readEvidence(),
+    api.readStanding(tip),
+  ])
+  if (reviews === undefined || evidence === undefined) {
+    return refused('gh-failed', [], tip)
+  }
+
+  const gates: GateResult[] = [
+    reviewGate(reviews, tip),
+    uiGate(reviews, tip, evidence.hasChecklist),
+    evidence.isSettled ? pass('evidence') : fail('evidence', 'evidence-owed'),
+    standingGate(standing),
+  ]
+  const blocked = gates.find((gate) => !gate.isOk)
+
+  if (opts.isCheck) {
+    const reading = await api.readChecks(tip)
+    if (reading === undefined) {
+      return refused('gh-failed', gates, tip)
+    }
+    const ci =
+      reading.state === 'passing'
+        ? pass('ci')
+        : reading.state === 'failing'
+          ? fail('ci', 'ci-failing')
+          : reading.isConflicted
+            ? fail('ci', 'ci-conflicted')
+            : fail('ci', 'ci-pending')
+    const all = [...gates, ci]
+    const first = all.find((gate) => !gate.isOk)
+    if (first?.reason !== undefined) return refused(first.reason, all, tip)
+    return {
+      reason: 'clear',
+      isLifted: false,
+      isOk: true,
+      head: tip,
+      gates: all,
+      waitedSeconds: 0,
+    }
+  }
+
+  if (blocked?.reason !== undefined) return refused(blocked.reason, gates, tip)
+
+  const ci = await waitForChecks(api, tip, opts.waitSeconds, pollMs)
+  if (ci.kind === 'refused') {
+    return refused(ci.reason, [...gates, fail('ci', ci.reason)], tip, ci.waited)
+  }
+  const cleared = [...gates, pass('ci')]
+
+  // The re-read: whatever the gates cleared above was cleared at `tip`.
+  const [nowPull, nowTip, nowReviews] = await Promise.all([
+    api.readPull(),
+    api.readTip(pull.branch),
+    api.readReviews(),
+  ])
+  if (
+    nowPull === undefined ||
+    nowTip === undefined ||
+    nowReviews === undefined
+  ) {
+    return refused('gh-failed', cleared, tip, ci.waited)
+  }
+  if (!nowPull.isDraft) {
+    return {
+      reason: 'already-ready',
+      isLifted: false,
+      isOk: true,
+      head: nowTip,
+      gates: cleared,
+      waitedSeconds: ci.waited,
+    }
+  }
+  if (nowTip !== tip) return refused('head-moved', cleared, nowTip, ci.waited)
+
+  const reread = [
+    reviewGate(nowReviews, nowTip),
+    uiGate(nowReviews, nowTip, evidence.hasChecklist),
+  ].find((gate) => !gate.isOk)
+  if (reread?.reason !== undefined) {
+    return refused(reread.reason, cleared, nowTip, ci.waited)
+  }
+
+  // Standing is read again too, since a sibling merging during the wait can
+  // leave a branch that read fresh before it stale.
+  const laterStanding = standingGate(await api.readStanding(nowTip))
+  if (laterStanding.reason !== undefined) {
+    return refused(laterStanding.reason, cleared, nowTip, ci.waited)
+  }
+
+  const isMarked = await api.markReady(pull.nodeId)
+  if (!isMarked) return refused('gh-failed', cleared, nowTip, ci.waited)
+
+  return {
+    reason: 'lifted',
+    isLifted: true,
+    isOk: true,
+    head: nowTip,
+    gates: cleared,
+    waitedSeconds: ci.waited,
+  }
+}
+
+/** One git invocation, answering its stdout or undefined when it failed. */
+export type GitRunner = (args: readonly string[]) => Promise<string | undefined>
+
+function nonEmptyLines(output: string): string[] {
+  return output.split('\n').filter((line) => line !== '')
+}
+
+/**
+ * Reads where a head stands against the base, ported from the orchestrator
+ * poll's own read so the lift and the poll answer one question the same way.
+ *
+ * merge-tree answers locally, because `mergeable_state` reads unknown while
+ * GitHub computes it, which is exactly when a verb asks. Only a change to a
+ * path the branch writes makes it stale, since re-testing after every merge to
+ * the base is a merge queue's cost without its batching. A head or base that
+ * does not resolve, which a fork or a deleted head leaves, reads `unknown`.
+ */
+export async function readBaseStanding(
+  git: GitRunner,
+  number: number,
+  head: string,
+  ref: string,
+): Promise<Standing> {
+  // The base is fetched as well as the head. A tracking ref is only as current
+  // as the last fetch, so a sibling merging since then would read as fresh.
+  const baseBranch = ref.startsWith('origin/')
+    ? ref.slice('origin/'.length)
+    : ref
+  await git(['fetch', '-q', 'origin', baseBranch])
+  await git(['fetch', '-q', 'origin', `pull/${number}/head`])
+
+  const hasHead =
+    (await git(['cat-file', '-e', `${head}^{commit}`])) !== undefined
+  const hasRef = (await git(['rev-parse', '--verify', '-q', ref])) !== undefined
+  if (!hasHead || !hasRef) return 'unknown'
+
+  const merged = await git(['merge-tree', '--write-tree', ref, head])
+  if (merged === undefined) return 'conflict'
+
+  const forkPoint = (await git(['merge-base', ref, head]))?.trim()
+  if (forkPoint === undefined || forkPoint === '') return 'unknown'
+
+  const written = await git([
+    'diff',
+    '--name-only',
+    '--no-renames',
+    forkPoint,
+    head,
+  ])
+  if (written === undefined) return 'unknown'
+
+  const paths = nonEmptyLines(written)
+  if (paths.length === 0) return 'fresh'
+
+  const moved = await git([
+    '--literal-pathspecs',
+    'diff',
+    '--name-only',
+    '--no-renames',
+    forkPoint,
+    ref,
+    '--',
+    ...paths,
+  ])
+  if (moved === undefined) return 'unknown'
+
+  return nonEmptyLines(moved).length > 0 ? 'stale' : 'fresh'
+}

package/src/pr/paths.ts

@@ -3,12 +3,12 @@ import { findBacktickSpans } from '@/markdown/backticks'
 /**
  * The heading whose bullets state what a branch changed.
  *
- * Read alone, and never widened to a sibling section. `## Technical Context`
+ * Read alone, and never widened to a sibling section. `## Technical context`
  * legitimately names files a branch never touched, such as an install stamp
  * inside a target, so a reader that took the whole body would manufacture a
  * finding out of every argument the author made for the change.
  */
-export const KEY_CHANGES = 'Key Changes'
+export const KEY_CHANGES = 'Key changes'
 
 /** What one bullet claimed, kept with its bullet so a finding can quote it. */
 export interface PathClaim {
@@ -86,7 +86,7 @@ const BARE_LINE = /^:\d+(?:-\d+)?$/
  * `canon markdown audit .claude/rules --json` carries a slash and names no file.
  * Angle brackets answer a second, since `.canon/plans/feature-<slug>.md`
  * describes a shape rather than naming a file. A glob and a caret describe a
- * shape too, `^src/` being a grep pattern one body spelled in Key Changes, and
+ * shape too, `^src/` being a grep pattern one body spelled in Key changes, and
  * a leading anchor names something outside this repository.
  *
  * Deliberately not shared with `classifySpan` in `@/gov/citations`, which asks
@@ -307,7 +307,7 @@ function resolveSpan(span: string): ResolvedSpan | undefined {
 }
 
 /**
- * Every path the `## Key Changes` section claims a change to.
+ * Every path the `## Key changes` section claims a change to.
  *
  * `roots` names the entries the tree holds at its top level, which is what
  * separates a whole path from one written partially. It is passed in rather

package/src/pr/rest.ts

@@ -17,6 +17,9 @@ export interface RestPull {
   readonly head?: { readonly ref?: string; readonly sha?: string }
   readonly base?: { readonly ref?: string }
   readonly mergeable_state?: string
+  readonly state?: string
+  readonly draft?: boolean
+  readonly node_id?: string
 }
 
 /** One row of `repos/{owner}/{repo}/pulls/<n>/reviews`. */

package/src/pr/review-scope.ts

@@ -131,6 +131,82 @@ function markerOf(
   return { commit, readAt }
 }
 
+/** The two headings `review-ui` posts a verdict under. */
+export const UI_HEADINGS = ['## UI review', '## UI review closed'] as const
+
+export type UiHeading = (typeof UI_HEADINGS)[number]
+
+export interface UiScope {
+  readonly heading?: UiHeading
+  readonly state: ReviewState
+  /** The head the verdict covered, a full or abbreviated sha. */
+  readonly commit?: string
+  /** `marker` is the verdict's own record, `fallback` is GitHub's stamp. */
+  readonly source: ScopeSource
+}
+
+/**
+ * The marker `review-ui` writes as the last line of every verdict. It names the
+ * head the pass drove, since the submission stamp moves onto a commit pushed
+ * while the pass was driving.
+ */
+const UI_MARKER = /^<!--\s*review-ui:\s*head=([0-9a-f]{7,40})\s*-->$/
+
+function lastLine(body: string): string | undefined {
+  const lines = body.split('\n')
+
+  let index = lines.length - 1
+  while (index >= 0 && (lines[index] ?? '').trim() === '') index -= 1
+  if (index < 0) return undefined
+
+  return (lines[index] ?? '').trim()
+}
+
+/**
+ * Resolves the newest UI verdict and the head it covered.
+ *
+ * Read off `reviews` like the code review family, since `review-ui` posts each
+ * verdict as a pull request review. The first line is matched for equality so
+ * `## UI review closed` is never taken for the open heading by prefix.
+ */
+export function resolveUiScope(listing: ReviewListing): UiScope {
+  let newest: { heading: UiHeading; row: ReviewRow } | undefined
+
+  for (const row of listing.reviews ?? []) {
+    const first = ((row.body ?? '').split('\n')[0] ?? '').replace(/\r$/, '')
+    const heading = UI_HEADINGS.find((candidate) => candidate === first)
+    if (heading !== undefined) newest = { heading, row }
+  }
+
+  if (newest === undefined) return { state: 'none', source: 'none' }
+
+  const { heading, row } = newest
+  const state: ReviewState = heading === '## UI review' ? 'open' : 'closed'
+  const line = lastLine(row.body ?? '')
+  const match = line === undefined ? null : UI_MARKER.exec(line)
+  const marked = match?.[1]
+
+  if (marked !== undefined) {
+    return { heading, state, commit: marked, source: 'marker' }
+  }
+
+  const oid = row.commit?.oid
+  return {
+    heading,
+    state,
+    ...(oid === undefined || oid === '' ? {} : { commit: oid }),
+    source: 'fallback',
+  }
+}
+
+/**
+ * Whether a covered commit names the head. A marker may carry a short sha, so
+ * coverage is a prefix match on the head.
+ */
+export function coversHead(commit: string, head: string): boolean {
+  return commit !== '' && head !== '' && head.startsWith(commit)
+}
+
 /**
  * Resolves what the newest review pass covered.
  *

package/src/records/backup.ts

@@ -30,7 +30,7 @@ import { type BlockedPath, guardPayload } from '@/records/push-guard'
  * rather than named here. That is what keeps this list at one line per surface
  * as archives spread, which a sibling-per-archive layout could not.
  *
- * `RECORD_KINDS` in `validate.ts` overlaps this on five names and carries one
+ * `RECORD_KINDS` in `validate.ts` overlaps this on four names and carries one
  * more that no backup reaches. The two lists differ on purpose: one is what a
  * standard governs, this is what a disk loss would take, and `standards` is
  * tracked so a backup would carry a second copy of committed files.
@@ -39,7 +39,6 @@ export const BACKED_FOLDERS = [
   'diagrams',
   'groundwork',
   'intake',
-  'memory',
   'plans',
   'proposals',
   'review',
@@ -51,6 +50,15 @@ export const BACKED_FOLDERS = [
   'walkthroughs',
 ] as const
 
+/**
+ * Folders a retired kind left at a legacy `.claude` root that the allowlist
+ * must still read, so a half-finished move that strands one still trips
+ * `split-roots`. Absent from `BACKED_FOLDERS` because nothing writes them, and
+ * absent from `RETIRED_FOLDERS` because that list stages a deletion and this
+ * folder is an archive to keep.
+ */
+const LEGACY_RECORD_FOLDERS = ['memory'] as const
+
 /**
  * Names that have left `BACKED_FOLDERS` and whose removal still has to reach a
  * records history once.
@@ -124,7 +132,9 @@ function isExcluded(name: string): boolean {
  */
 function foldersAt(dir: string): string[] {
   if (basename(dir) === '.claude') {
-    return BACKED_FOLDERS.filter((folder) => existsSync(join(dir, folder)))
+    return [...BACKED_FOLDERS, ...LEGACY_RECORD_FOLDERS].filter((folder) =>
+      existsSync(join(dir, folder)),
+    )
   }
 
   const entries = existsSync(dir)
@@ -378,7 +388,7 @@ async function enclosingRemotes(
  * Clears the four gates both verbs share and returns the records remote URL.
  *
  * The last two are the ones the payload depends on. This repository is public,
- * so a records branch on any of its remotes serves the memory pen and the
+ * so a records branch on any of its remotes serves the plans and the
  * groundwork trails to anyone who fetches all refs. Comparing the configured
  * URL against every remote of the enclosing repository is what keeps a
  * misconfigured `origin` from publishing them, and refusing when that list
@@ -416,7 +426,7 @@ async function resolveRemote(
   if (!enclosing) {
     return refuse(
       'remote-unreadable',
-      `Cannot read the remotes of the project at ${root}, so the records origin cannot be checked against them. Records carry the memory pen and the groundwork trails, and an unchecked origin risks publishing them.`,
+      `Cannot read the remotes of the project at ${root}, so the records origin cannot be checked against them. Records carry the plans and the groundwork trails, and an unchecked origin risks publishing them.`,
     )
   }
 
@@ -424,7 +434,7 @@ async function resolveRemote(
   if (enclosing.identities.includes(url)) {
     return refuse(
       'remote-shared',
-      `The records origin ${remote.text} is a remote of this project. Records carry the memory pen and the groundwork trails, so they need a repository of their own.`,
+      `The records origin ${remote.text} is a remote of this project. Records carry the plans and the groundwork trails, so they need a repository of their own.`,
     )
   }
 

package/src/records/stale-canonical.ts

@@ -3,7 +3,6 @@ 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 '@/roots/surface'
 
 /** The record whose drift is identity rather than a stale path. */
@@ -22,6 +21,37 @@ export interface CanonicalDoc {
   readonly latestRelease: string | null
 }
 
+const REVIEWED_FIELD = /^reviewed:[ \t]*(.*?)[ \t]*$/m
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/
+const RAW_FRONTMATTER = /^---\n([\s\S]*?)\n---/
+
+/**
+ * Reads `reviewed` off the raw block rather than the parsed fields, for the
+ * reason `hasOpeningDate` in the validator gives: a YAML parser resolves a
+ * bare `YYYY-MM-DD` to a date on one schema and a string on another.
+ *
+ * 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(
+  text: string,
+): Pick<CanonicalDoc, 'reviewed' | 'invalidReviewed'> {
+  const block = RAW_FRONTMATTER.exec(text)?.[1]
+  const match = block ? REVIEWED_FIELD.exec(block) : null
+  if (!match) return { reviewed: null }
+
+  const value = match[1].replace(/^(['"])(.*)\1$/, '$2')
+  const parsed = Date.parse(`${value}T00:00:00Z`)
+  const isDate =
+    ISO_DATE.test(value) &&
+    Number.isFinite(parsed) &&
+    new Date(parsed).toISOString().slice(0, 10) === value
+
+  return isDate
+    ? { reviewed: value }
+    : { reviewed: null, invalidReviewed: value }
+}
+
 export interface CanonicalReport {
   readonly ok: true
   readonly root: string