@erclx/canon 5.46.0 → 5.48.0

package/src/pr/merge.ts

@@ -0,0 +1,175 @@
+import type { ChecksGate } from '@/pr/lift'
+import { readSection } from '@/pr/paths'
+import { UI_PASS_MARKER } from '@/pr/tick'
+
+/** Why the verb did not merge, in the order the refusals are read. */
+export type MergeRefusal =
+  | 'pull-closed'
+  | 'pull-draft'
+  | 'missing-summary'
+  | 'missing-key-changes'
+  | 'ci-failing'
+  | 'ci-conflicted'
+  | 'ci-pending'
+  | 'head-moved'
+  | 'not-mergeable'
+  | 'gh-failed'
+
+export interface MergePull {
+  readonly isOpen: boolean
+  readonly isDraft: boolean
+  readonly title: string
+  readonly body: string
+  /** The head the merge is pinned to, so a push after the read refuses. */
+  readonly head: string
+}
+
+export interface MergeRequest {
+  readonly title: string
+  readonly description: string
+  readonly sha: string
+}
+
+/** What the merge endpoint answered, with 409 and 405 told apart from a merge. */
+export type MergeOutcome =
+  | { readonly kind: 'merged'; readonly sha: string }
+  | { readonly kind: 'head-moved' }
+  | { readonly kind: 'not-mergeable' }
+  | { readonly kind: 'failed' }
+
+/**
+ * Everything the verb reads or writes, injected so every refusal runs without
+ * a network. A read that failed returns undefined, and the verb refuses
+ * `gh-failed` rather than reading absence as a pass.
+ */
+export interface MergeApi {
+  readPull(): Promise<MergePull | undefined>
+  readChecks(head: string): Promise<ChecksGate | undefined>
+  putMerge(request: MergeRequest): Promise<MergeOutcome>
+}
+
+export interface MergeOptions {
+  readonly number: number
+  readonly isDryRun: boolean
+}
+
+export interface MergeRecord {
+  readonly reason: 'merged' | 'dry-run' | MergeRefusal
+  readonly isOk: boolean
+  readonly number: number
+  readonly title?: string
+  readonly description?: string
+  /** The squash commit, present only on a merge. */
+  readonly sha?: string
+}
+
+export type Composed =
+  | { readonly kind: 'composed'; readonly description: string }
+  | {
+      readonly kind: 'refused'
+      readonly reason: 'missing-summary' | 'missing-key-changes'
+    }
+
+/** A section's text with the UI pass line dropped, or undefined when nothing is left. */
+function keptSection(body: string, title: string): string | undefined {
+  const text = readSection(body, title)
+    ?.split('\n')
+    .filter((line) => !line.includes(UI_PASS_MARKER))
+    .join('\n')
+    .trim()
+  return text === undefined || text === ''
+    ? undefined
+    : `## ${title}\n\n${text}`
+}
+
+/**
+ * The squash description: Summary, Key changes, and Technical context, in that
+ * order, under their headings. Testing, the reviewer requests, and the UI pass
+ * line describe the review rather than the change, so none reaches the trunk.
+ * Technical context is optional, and an empty one leaves no bare heading.
+ */
+export function composeDescription(body: string): Composed {
+  const summary = keptSection(body, 'Summary')
+  if (summary === undefined)
+    return { kind: 'refused', reason: 'missing-summary' }
+  const keyChanges = keptSection(body, 'Key changes')
+  if (keyChanges === undefined) {
+    return { kind: 'refused', reason: 'missing-key-changes' }
+  }
+  const context = keptSection(body, 'Technical context')
+  return {
+    kind: 'composed',
+    description: [summary, keyChanges, context]
+      .filter((block) => block !== undefined)
+      .join('\n\n'),
+  }
+}
+
+/** The suffix the web merge adds and the trunk log carries. */
+export function mergeTitle(title: string, number: number): string {
+  return `${title} (#${number})`
+}
+
+function refused(
+  reason: MergeRefusal,
+  number: number,
+  message: { title?: string; description?: string } = {},
+): MergeRecord {
+  return { reason, isOk: false, number, ...message }
+}
+
+/**
+ * Squash-merges one ready pull request with a message carrying only the
+ * change. Every refusal is read before the one write, and the write sends the
+ * head it read as `sha`, so GitHub refuses rather than merging a commit pushed
+ * after the checks were read. The verb reads the draft flag and not the review
+ * comments, since a ready pull request already passed the lift's gates.
+ */
+export async function merge(
+  api: MergeApi,
+  opts: MergeOptions,
+): Promise<MergeRecord> {
+  const { number } = opts
+
+  const pull = await api.readPull()
+  if (pull === undefined) return refused('gh-failed', number)
+  if (!pull.isOpen) return refused('pull-closed', number)
+  if (pull.isDraft) return refused('pull-draft', number)
+
+  const title = mergeTitle(pull.title, number)
+  const composed = composeDescription(pull.body)
+  if (composed.kind === 'refused') {
+    return refused(composed.reason, number, { title })
+  }
+  const message = { title, description: composed.description }
+
+  const checks = await api.readChecks(pull.head)
+  if (checks === undefined) return refused('gh-failed', number, message)
+  if (checks.state === 'failing') return refused('ci-failing', number, message)
+  if (checks.state !== 'passing') {
+    return refused(
+      checks.isConflicted ? 'ci-conflicted' : 'ci-pending',
+      number,
+      message,
+    )
+  }
+
+  if (opts.isDryRun)
+    return { reason: 'dry-run', isOk: true, number, ...message }
+
+  const outcome = await api.putMerge({ ...message, sha: pull.head })
+  if (outcome.kind === 'merged') {
+    return {
+      reason: 'merged',
+      isOk: true,
+      number,
+      ...message,
+      sha: outcome.sha,
+    }
+  }
+  return refused(
+    outcome.kind === 'failed' ? 'gh-failed' : outcome.kind,
+    number,
+    message,
+  )
+}

package/src/pr/rest.ts

@@ -13,6 +13,7 @@ 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 title?: string
   readonly body?: string | null
   readonly head?: { readonly ref?: string; readonly sha?: string }
   readonly base?: { readonly ref?: string }
@@ -42,6 +43,7 @@ export interface PullIdentity {
   readonly head?: string
   readonly base?: string
   readonly mergeState?: string
+  readonly body?: string
 }
 
 export type BranchPull =
@@ -70,6 +72,7 @@ export function identityOf(row: RestPull): PullIdentity {
     ...(row.head?.sha !== undefined && { head: row.head.sha }),
     ...(row.base?.ref !== undefined && { base: row.base.ref }),
     ...(mergeState !== undefined && { mergeState }),
+    ...(typeof row.body === 'string' && { body: row.body }),
   }
 }
 

package/src/pr/review-scope.ts

@@ -136,11 +136,21 @@ export const UI_HEADINGS = ['## UI review', '## UI review closed'] as const
 
 export type UiHeading = (typeof UI_HEADINGS)[number]
 
+/** The four totals on a verdict's count line. */
+export interface UiCounts {
+  readonly failed: number
+  readonly eyes: number
+  readonly passed: number
+  readonly notDriven: number
+}
+
 export interface UiScope {
   readonly heading?: UiHeading
   readonly state: ReviewState
   /** The head the verdict covered, a full or abbreviated sha. */
   readonly commit?: string
+  /** The counts the verdict wrote, absent when its count line does not parse. */
+  readonly counts?: UiCounts
   /** `marker` is the verdict's own record, `fallback` is GitHub's stamp. */
   readonly source: ScopeSource
 }
@@ -152,6 +162,32 @@ export interface UiScope {
  */
 const UI_MARKER = /^<!--\s*review-ui:\s*head=([0-9a-f]{7,40})\s*-->$/
 
+/**
+ * The count line `review-ui`'s `post.md` fixes as the verdict's first line
+ * under the heading. It is model-written prose, so a body that drifts from the
+ * form reads as no counts and a caller treats that as unchecked.
+ */
+const UI_COUNTS =
+  /^(\d+) failed · (\d+) need your eyes · (\d+) passed · (\d+) not driven$/
+
+export function readUiCounts(body: string): UiCounts | undefined {
+  for (const raw of body.split('\n').slice(1, 6)) {
+    const match = UI_COUNTS.exec(raw.trim())
+    if (match === null) continue
+    const [, failed, eyes, passed, notDriven] = match.map(Number)
+    if (
+      failed === undefined ||
+      eyes === undefined ||
+      passed === undefined ||
+      notDriven === undefined
+    ) {
+      return undefined
+    }
+    return { failed, eyes, passed, notDriven }
+  }
+  return undefined
+}
+
 function lastLine(body: string): string | undefined {
   const lines = body.split('\n')
 
@@ -185,9 +221,11 @@ export function resolveUiScope(listing: ReviewListing): UiScope {
   const line = lastLine(row.body ?? '')
   const match = line === undefined ? null : UI_MARKER.exec(line)
   const marked = match?.[1]
+  const counts = readUiCounts(row.body ?? '')
+  const counted = counts === undefined ? {} : { counts }
 
   if (marked !== undefined) {
-    return { heading, state, commit: marked, source: 'marker' }
+    return { heading, state, commit: marked, ...counted, source: 'marker' }
   }
 
   const oid = row.commit?.oid
@@ -195,6 +233,7 @@ export function resolveUiScope(listing: ReviewListing): UiScope {
     heading,
     state,
     ...(oid === undefined || oid === '' ? {} : { commit: oid }),
+    ...counted,
     source: 'fallback',
   }
 }

package/src/pr/tick.ts

@@ -1,11 +1,120 @@
 import {
+  type ChecklistBox,
   CHECKLIST_END,
   CHECKLIST_START,
   parseBoxLine,
   readChecklistBoxes,
+  SHORT_SHA_LENGTH,
   writeBoxLine,
 } from '@/pr/evidence'
 
+export const UI_PASS_MARKER = '<!-- pr-ui-pass -->'
+const TESTING_HEADING = /^## Testing\s*$/
+const SECTION_HEADING = /^## /
+const REVIEWER_HEADING = /^## For the reviewer\s*$/
+const UI_PASS_HEAD = /at `([0-9a-f]+)`/
+
+/** What the UI pass line reports, either a pass or a reset to a head nobody has driven. */
+export type UiPassSummary =
+  | {
+      readonly kind: 'passed'
+      /** Driven boxes ticked, taste boxes excluded. */
+      readonly passed: number
+      /** Boxes a driver can run, taste boxes excluded. */
+      readonly total: number
+      readonly taste: number
+      readonly head: string
+    }
+  | { readonly kind: 'reset'; readonly head: string }
+
+/**
+ * The one `## Testing` line a UI pass owns. It is ticked only when every box
+ * a driver can run passed, so a failed box never reads as done, and taste
+ * boxes are counted apart so a full pass never reads as one box failed.
+ */
+export function uiPassLine(summary: UiPassSummary): string {
+  const at = `\`${summary.head.slice(0, SHORT_SHA_LENGTH)}\``
+  if (summary.kind === 'reset') {
+    return `- [ ] UI pass, not run at ${at} ${UI_PASS_MARKER}`
+  }
+  const taste =
+    summary.taste === 0
+      ? ''
+      : `${summary.taste} taste ${summary.taste === 1 ? 'box' : 'boxes'} left to the operator`
+  if (summary.total === 0) {
+    return `- [ ] UI pass, no box a driver can run, ${taste} at ${at} ${UI_PASS_MARKER}`
+  }
+  const box = summary.passed === summary.total ? 'x' : ' '
+  const tail = taste === '' ? '' : `, ${taste}`
+  return `- [${box}] UI pass, ${summary.passed} of ${summary.total} boxes passed at ${at}${tail} ${UI_PASS_MARKER}`
+}
+
+/**
+ * The driven boxes ticked at the head. A tick counts as this pass's only when
+ * stamped at the head, since an unstamped one is the author's claim and an
+ * older stamp names another head. Taste boxes are left out, as the body line
+ * leaves them out.
+ */
+export function countTicksAtHead(
+  boxes: readonly ChecklistBox[],
+  head: string,
+): number {
+  return boxes.filter(
+    (box) =>
+      !box.isTaste &&
+      box.isTicked &&
+      box.stamp !== undefined &&
+      head.startsWith(box.stamp),
+  ).length
+}
+
+/** The short sha the marked line names, absent when the body carries no such line. */
+export function readUiPassHead(body: string): string | undefined {
+  const line = body.split('\n').find((row) => row.includes(UI_PASS_MARKER))
+  return line === undefined ? undefined : UI_PASS_HEAD.exec(line)?.[1]
+}
+
+/**
+ * Puts the UI pass line in a pull request body and touches nothing else.
+ * The marked line is replaced where it stands, else appended to the end of
+ * `## Testing`, which is created ahead of `## For the reviewer` when absent.
+ */
+export function writeUiPassLine(body: string, summary: UiPassSummary): string {
+  const line = uiPassLine(summary)
+  const lines = body.split('\n')
+
+  const marked = lines.findIndex((row) => row.includes(UI_PASS_MARKER))
+  if (marked !== -1) {
+    lines[marked] = line
+    return lines.join('\n')
+  }
+
+  const heading = lines.findIndex((row) => TESTING_HEADING.test(row))
+  if (heading === -1) {
+    const reviewer = lines.findIndex((row) => REVIEWER_HEADING.test(row))
+    if (reviewer === -1) {
+      return `${body.trimEnd()}\n\n## Testing\n\n${line}\n`
+    }
+    lines.splice(reviewer, 0, '## Testing', '', line, '')
+    return lines.join('\n')
+  }
+
+  const next = lines.findIndex(
+    (row, index) => index > heading && SECTION_HEADING.test(row),
+  )
+  let last = next === -1 ? lines.length - 1 : next - 1
+  while (last > heading && lines[last]?.trim() === '') last -= 1
+
+  if (last > heading) {
+    lines.splice(last + 1, 0, line)
+  } else if (lines[heading + 1] === '') {
+    lines.splice(heading + 2, 0, line)
+  } else {
+    lines.splice(heading + 1, 0, '', line)
+  }
+  return lines.join('\n')
+}
+
 export type TickRefusal = 'no-checklist' | 'no-box' | 'taste-box'
 
 export type TickResult =

package/src/sessions/live.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync, readlinkSync } from 'node:fs'
+import { createConnection } from 'node:net'
 import type { SessionRecord } from '@/sessions/registry'
 
 /**
@@ -35,6 +36,12 @@ export interface LivenessProbes {
   readonly ownDomain?: () => string | null
   /** Whether the messaging socket a foreign record names still exists. */
   readonly socketExists?: (path: string) => boolean
+  /**
+   * Whether something accepts a connection on the socket within the timeout.
+   * Async, so `liveness()` never calls it and a caller with no use for it, such
+   * as the gate's lock, states nothing.
+   */
+  readonly listens?: (path: string, timeoutMs: number) => Promise<boolean>
 }
 
 /**
@@ -74,11 +81,30 @@ function ownDomain(): string | null {
   }
 }
 
+/**
+ * Connects and closes without writing, so the peer sees no bytes. The socket is
+ * destroyed on connect rather than waited on, since a listener that accepts and
+ * never closes would otherwise hold the probe open past its timeout.
+ */
+function listens(path: string, timeoutMs: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = createConnection(path)
+    const settle = (accepted: boolean): void => {
+      socket.destroy()
+      resolve(accepted)
+    }
+    socket.setTimeout(timeoutMs, () => settle(false))
+    socket.once('connect', () => settle(true))
+    socket.once('error', () => settle(false))
+  })
+}
+
 export const SYSTEM_PROBES: LivenessProbes = {
   procStartOf,
   responds,
   ownDomain,
   socketExists: existsSync,
+  listens,
 }
 
 /**

package/src/sessions/resolve.ts

@@ -23,11 +23,18 @@ export interface ResolvedSession {
   readonly kind: string
   readonly status: string
   /**
-   * What decided the row was live. `socket` means the record belongs to another
-   * pid namespace and only its messaging socket answered, so the row can be a
-   * crashed session's leftover and no start time backs it.
+   * What decided the row was live. `pid` is a start time matched or a pid that
+   * answered, `socket` means the record belongs to another pid namespace and
+   * only its messaging socket file existed, so the row can be a crashed
+   * session's leftover, and `listener` means the messaging socket accepted a
+   * connection, which confirms the row wherever the start time cannot be read.
    */
-  readonly via: 'pid' | 'socket'
+  readonly via: 'pid' | 'socket' | 'listener'
+  /**
+   * How this row alone was decided, so a caller scoping the roster derives its
+   * confidence over the rows it keeps rather than over the whole machine.
+   */
+  readonly confidence: Confidence
   readonly startedAt: string | null
   /**
    * The stamp the record carries beside `status`, kept alongside the dwell it
@@ -80,6 +87,22 @@ export type SessionReport =
       readonly sessions: readonly ResolvedSession[]
     }
 
+/**
+ * The weakest confidence among the rows, so one read tells a caller whether
+ * every row it holds is an identity. A caller scoping the roster calls this on
+ * the rows it keeps, since one unrelated row it dropped must not weaken it.
+ */
+export function confidenceOf(
+  sessions: readonly Pick<ResolvedSession, 'confidence'>[],
+): Confidence {
+  return sessions.every((session) => session.confidence === 'confirmed')
+    ? 'confirmed'
+    : 'unverified'
+}
+
+/** A live socket here accepted in 2 ms, and every probe runs in parallel. */
+const LISTEN_TIMEOUT_MS = 250
+
 export interface ResolveOptions {
   readonly dir?: string
   readonly probes?: LivenessProbes
@@ -181,6 +204,7 @@ function present(
   located: Located,
   now: number,
   via: ResolvedSession['via'],
+  confidence: Confidence,
 ): ResolvedSession {
   return {
     name: record.name,
@@ -190,6 +214,7 @@ function present(
     kind: record.kind ?? 'unknown',
     status: record.status ?? 'unknown',
     via,
+    confidence,
     startedAt:
       record.startedAt === undefined
         ? null
@@ -228,8 +253,11 @@ export async function resolveSessions(
 
   if (registry.kind === 'absent') return { kind: 'absent', dir: registry.dir }
 
-  const live: { record: SessionRecord; via: ResolvedSession['via'] }[] = []
-  let confidence: Confidence = 'confirmed'
+  const live: {
+    record: SessionRecord
+    via: ResolvedSession['via']
+    confidence: Confidence
+  }[] = []
   let foreignDead = 0
 
   for (const record of registry.records) {
@@ -238,20 +266,43 @@ export async function resolveSessions(
       if (state.foreign) foreignDead += 1
       continue
     }
-    if (state.confidence === 'unverified') confidence = 'unverified'
-    live.push({ record, via: state.foreign ? 'socket' : 'pid' })
+    live.push({
+      record,
+      via: state.foreign ? 'socket' : 'pid',
+      confidence: state.confidence,
+    })
   }
 
+  // Only a row the start time left unverified is probed, so a machine that reads
+  // /proc pays nothing. An accept proves the session is running where a pid
+  // answering or a socket file existing does not.
+  const upgraded = await Promise.all(
+    live.map(async (row) => {
+      const socket = row.record.messagingSocketPath
+      if (
+        row.confidence === 'confirmed' ||
+        socket === undefined ||
+        probes.listens === undefined
+      ) {
+        return row
+      }
+      const accepted = await probes.listens(socket, LISTEN_TIMEOUT_MS)
+      return accepted
+        ? { ...row, via: 'listener' as const, confidence: 'confirmed' as const }
+        : row
+    }),
+  )
+
   const sessions = await Promise.all(
-    live.map(async ({ record, via }) =>
-      present(record, await find(record.cwd), now, via),
+    upgraded.map(async ({ record, via, confidence }) =>
+      present(record, await find(record.cwd), now, via, confidence),
     ),
   )
 
   return {
     kind: 'resolved',
     dir: registry.dir,
-    confidence,
+    confidence: confidenceOf(sessions),
     foreignDead,
     sessions,
   }