@erclx/canon 5.72.1 → 5.74.0

package/src/pr/checks.ts

@@ -1,4 +1,8 @@
-import { type ChecksState, type RawCheck, rollup } from '@/targets/pulls'
+import {
+  type ChecksState,
+  type RawCheck,
+  rollupRequired,
+} from '@/targets/pulls'
 
 /** One row of `repos/{owner}/{repo}/commits/<sha>/check-runs`. */
 export interface RawCheckRun {
@@ -9,6 +13,12 @@ export interface RawCheckRun {
   readonly id?: number
 }
 
+/** One row of `repos/{owner}/{repo}/commits/<sha>/status`, newest per context already. */
+export interface RawStatus {
+  readonly context?: string
+  readonly state?: string
+}
+
 /** What that endpoint returns, count and rows apart. */
 export interface CheckRunListing {
   readonly total_count?: number
@@ -27,6 +37,41 @@ export interface ChecksReading {
   readonly reported: number
   /** Runs `matched` carried for a check name this reading already kept a newer run for. */
   readonly collapsed: number
+  /**
+   * Failing checks outside the required set, present only when a required set
+   * was read, so a reading over every check keeps its old shape.
+   */
+  readonly advisory?: readonly string[]
+}
+
+/**
+ * Reads the check names a base branch's rules require, from
+ * `repos/{owner}/{repo}/rules/branches/<base>`.
+ *
+ * Undefined when the answer is not a rule list, which a repository without
+ * rulesets or a refused read returns, so the caller falls back to every check.
+ * Classic branch protection is not read, and falls back the same way.
+ */
+export function requiredChecks(
+  rules: unknown,
+): ReadonlySet<string> | undefined {
+  if (!Array.isArray(rules)) return undefined
+
+  const names = new Set<string>()
+  for (const rule of rules as readonly RequiredRule[]) {
+    if (rule?.type !== 'required_status_checks') continue
+    for (const check of rule.parameters?.required_status_checks ?? []) {
+      if (typeof check.context === 'string') names.add(check.context)
+    }
+  }
+  return names
+}
+
+interface RequiredRule {
+  readonly type?: string
+  readonly parameters?: {
+    readonly required_status_checks?: readonly { readonly context?: unknown }[]
+  }
 }
 
 export interface ConflictedReading extends ChecksReading {
@@ -68,6 +113,7 @@ export function withMergeState(
  */
 function adapt(run: RawCheckRun): RawCheck {
   return {
+    ...(run.name !== undefined && { name: run.name }),
     ...(run.status !== undefined && { status: run.status.toUpperCase() }),
     ...(run.conclusion !== undefined &&
       run.conclusion !== null && {
@@ -125,10 +171,22 @@ function newestPerCheck(runs: readonly RawCheckRun[]): {
  * rolls up from `newestPerCheck`'s kept rows rather than from `matched`
  * directly, so a stale failing run left behind by a rerun no longer outvotes
  * the passing run beside it.
+ *
+ * A required set narrows only that last rollup. The foreign and partial
+ * listing guards still read every run, since either says the set in hand is
+ * incomplete whichever checks gate.
+ *
+ * A ruleset can require a commit status, which the check-run listing never
+ * carries, so the statuses join the rollup by `context` once a non-empty
+ * required set was read. An unread or empty set keeps them out, since the
+ * every-check fallback is the reading these verbs gave before rules were read
+ * and it saw no status.
  */
 export function collapseChecks(
   tip: string,
   listing: CheckRunListing,
+  required?: ReadonlySet<string>,
+  statuses: readonly RawStatus[] = [],
 ): ChecksReading {
   const runs = listing.check_runs ?? []
   const matched = runs.filter((run) => run.head_sha === tip)
@@ -139,6 +197,7 @@ export function collapseChecks(
     foreign: runs.length - matched.length,
     reported: listing.total_count ?? runs.length,
     collapsed,
+    ...(required !== undefined && { advisory: [] }),
   }
 
   if (reading.foreign > 0) return { ...reading, state: 'pending' }
@@ -149,7 +208,20 @@ export function collapseChecks(
   // sitting outside of, which is the false green keyed on a sha alone.
   if (reading.reported > runs.length) return { ...reading, state: 'pending' }
 
-  if (matched.length === 0) return { ...reading, state: 'pending' }
+  const statusRows: RawCheck[] =
+    required === undefined || required.size === 0
+      ? []
+      : statuses.map((status) => ({
+          ...(status.context !== undefined && { name: status.context }),
+          state: (status.state ?? '').toUpperCase(),
+        }))
+  const rows = [...kept.map(adapt), ...statusRows]
+  if (rows.length === 0) return { ...reading, state: 'pending' }
 
-  return { ...reading, state: rollup(kept.map(adapt)) ?? 'pending' }
+  const { state, advisory } = rollupRequired(rows, required)
+  return {
+    ...reading,
+    state: state ?? 'pending',
+    ...(required !== undefined && { advisory }),
+  }
 }

package/src/pr/evidence.ts

@@ -25,6 +25,12 @@ const REEL_PREFIX = '**Reel** filmed at'
 const REEL_LINE =
   /^\*\*Reel\*\* filmed at `([0-9a-f]{7,40})`:<br><img src="([^"]+)"/
 
+/** How the line naming why no local address was posted opens. */
+const LOCAL_SKIP_PREFIX = '**No local preview:**'
+
+/** How the line naming why no reel was filmed opens. */
+const REEL_SKIP_PREFIX = '**No reel:**'
+
 /** The width a reel is filmed at, which it asks for in the comment. */
 const REEL_WIDTH = 960
 
@@ -198,6 +204,15 @@ function escapeCell(text: string): string {
     .replaceAll('|', '&#124;')
 }
 
+function unescapeCell(text: string): string {
+  return text
+    .replaceAll('&#124;', '|')
+    .replaceAll('&quot;', '"')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&amp;', '&')
+}
+
 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}">`
@@ -449,6 +464,18 @@ function reelLine(reel: EvidenceReel): string {
   return `${REEL_PREFIX} \`${head}\`:<br><img src="${escapeCell(reel.link)}" width="${REEL_WIDTH}" alt="reel filmed at ${head}">`
 }
 
+/** Why a render carries no local address or no reel, each a reason code and any one-line message the caller joined to it. */
+export interface EvidenceSkips {
+  readonly local?: string
+  readonly reel?: string
+}
+
+/** A skip line, or nothing for an empty reason. A reason is folded onto one line, since a line break would end the address region early. */
+function skipLines(prefix: string, reason: string | undefined): string[] {
+  const text = reason?.replace(/\s+/g, ' ').trim() ?? ''
+  return text === '' ? [] : [`${prefix} ${escapeCell(text)}`, '']
+}
+
 export function evidenceMarker(head: string): string {
   return `${MARKER_PREFIX} head=${head} -->`
 }
@@ -480,6 +507,10 @@ export function evidenceMarker(head: string): string {
  *
  * A reel sits on its own line under the addresses, labeled with the head it
  * was filmed at, so a reel carried past a later push never reads as current.
+ *
+ * A skip names why the local address or the reel is missing, on its own line
+ * where that address or reel would sit. Each is dropped whenever its address
+ * or reel renders, carried or passed, so a skip never outlives its cause.
  */
 export function renderEvidenceBody(
   states: readonly EvidenceState[],
@@ -490,6 +521,7 @@ export function renderEvidenceBody(
   checklist?: string,
   local?: string,
   reel?: EvidenceReel,
+  skips: EvidenceSkips = {},
 ): string {
   const segments = [
     ...(preview === undefined ? [] : [`${PREVIEW_PREFIX} ${preview}`]),
@@ -499,7 +531,10 @@ export function renderEvidenceBody(
     EVIDENCE_HEADING,
     '',
     ...(segments.length === 0 ? [] : [segments.join(ADDRESS_SEPARATOR), '']),
-    ...(reel === undefined ? [] : [reelLine(reel), '']),
+    ...(local === undefined ? skipLines(LOCAL_SKIP_PREFIX, skips.local) : []),
+    ...(reel === undefined
+      ? skipLines(REEL_SKIP_PREFIX, skips.reel)
+      : [reelLine(reel), '']),
   ]
   const closing =
     checklist === undefined
@@ -756,6 +791,32 @@ export function findEvidenceReel(
   return undefined
 }
 
+/**
+ * The skips the marked comment already carries, read from the address region
+ * only, so a line quoted in a checklist is never taken for one. A re-render
+ * passing no skip carries these forward the way it carries an address.
+ */
+export function findEvidenceSkips(
+  comments: readonly EvidenceComment[],
+): EvidenceSkips {
+  const marked = findMarked(comments)
+  if (marked === undefined) return {}
+  let local: string | undefined
+  let reel: string | undefined
+  for (const raw of marked.body.split('\n')) {
+    const line = raw.trim()
+    if (REGION_ENDS.some((end) => line.startsWith(end))) break
+    const ownSkip = readSegment(line, LOCAL_SKIP_PREFIX)
+    const reelSkip = readSegment(line, REEL_SKIP_PREFIX)
+    if (ownSkip !== undefined) local ??= unescapeCell(ownSkip)
+    if (reelSkip !== undefined) reel ??= unescapeCell(reelSkip)
+  }
+  return {
+    ...(local !== undefined && { local }),
+    ...(reel !== undefined && { reel }),
+  }
+}
+
 /**
  * The reel a render embeds: a passed link, filmed at this head, replaces
  * whatever the comment carries, and with none passed the posted reel carries

package/src/pr/lift.ts

@@ -83,8 +83,19 @@ export interface EvidenceGate {
 }
 
 export interface ChecksGate {
+  /** The state over the checks the base requires, or every check when none were read. */
   readonly state: ChecksState
   readonly isConflicted: boolean
+  /** Failing checks outside the required set, which are reported and never gate. */
+  readonly advisory?: readonly string[]
+}
+
+/** The advisory field a record carries, absent when no advisory check failed. */
+export function advisoryOf(reading: ChecksGate): {
+  advisory?: readonly string[]
+} {
+  const advisory = reading.advisory ?? []
+  return advisory.length > 0 ? { advisory } : {}
 }
 
 /**
@@ -129,6 +140,8 @@ export interface LiftRecord {
   readonly carriedFrom?: string
   readonly paintedPaths?: readonly string[]
   readonly drivenPaths?: readonly string[]
+  /** Failing checks the base does not require, named so a reader sees them before merging. */
+  readonly advisory?: readonly string[]
   readonly isLifted: boolean
   /** Whether the caller can treat the pull request as ready afterwards. */
   readonly isOk: boolean
@@ -247,7 +260,11 @@ function standingGate(standing: Standing): GateResult {
 }
 
 type CiOutcome =
-  | { readonly kind: 'passing'; readonly waited: number }
+  | {
+      readonly kind: 'passing'
+      readonly waited: number
+      readonly reading: ChecksGate
+    }
   | {
       readonly kind: 'refused'
       readonly reason: LiftRefusal
@@ -274,7 +291,9 @@ async function waitForChecks(
     if (reading === undefined) {
       return { kind: 'refused', reason: 'gh-failed', waited }
     }
-    if (reading.state === 'passing') return { kind: 'passing', waited }
+    if (reading.state === 'passing') {
+      return { kind: 'passing', waited, reading }
+    }
     if (reading.state === 'failing') {
       return { kind: 'refused', reason: 'ci-failing', waited }
     }
@@ -422,6 +441,7 @@ export async function lift(
       gates: all,
       waitedSeconds: 0,
       ...carried(all),
+      ...advisoryOf(reading),
     }
   }
 
@@ -485,6 +505,7 @@ export async function lift(
     gates: cleared,
     waitedSeconds: ci.waited,
     ...carried(cleared),
+    ...advisoryOf(ci.reading),
   }
 }
 

package/src/pr/merge.ts

@@ -1,4 +1,4 @@
-import type { ChecksGate } from '@/pr/lift'
+import { advisoryOf, type ChecksGate } from '@/pr/lift'
 import { readSection } from '@/pr/paths'
 import { UI_PASS_MARKER } from '@/pr/tick'
 
@@ -67,6 +67,8 @@ export interface MergeRecord {
   readonly description?: string
   /** The squash commit, present only on a merge. */
   readonly sha?: string
+  /** Failing checks the base does not require, which the merge went past. */
+  readonly advisory?: readonly string[]
 }
 
 export type Composed =
@@ -230,8 +232,15 @@ export async function merge(
     )
   }
 
-  if (opts.isDryRun)
-    return { reason: 'dry-run', isOk: true, number, ...message }
+  if (opts.isDryRun) {
+    return {
+      reason: 'dry-run',
+      isOk: true,
+      number,
+      ...message,
+      ...advisoryOf(checks),
+    }
+  }
 
   const outcome = await api.putMerge({ ...message, sha: pull.head })
   if (outcome.kind === 'merged') {
@@ -241,6 +250,7 @@ export async function merge(
       number,
       ...message,
       sha: outcome.sha,
+      ...advisoryOf(checks),
     }
   }
   return refused(

package/src/records/backup.ts

@@ -107,6 +107,7 @@ export const EXCLUDED_ENTRIES = [
 /** Media under a video workspace, remade from its plan and composition, so never backed up. */
 export const MEDIA_PATHSPECS = [
   ':(exclude,glob)video/*/takes/**',
+  ':(exclude,glob)video/*/scratch/**',
   ':(exclude,glob)video/**/renders/**',
   ':(exclude,glob)video/**/snapshots/**',
   ':(exclude,glob)video/**/node_modules/**',

package/src/targets/pulls.ts

@@ -94,6 +94,8 @@ interface RawPull {
  * rather than writing a second collapse beside `rollup`.
  */
 export interface RawCheck {
+  /** The check-run name, which a ruleset's required context matches. */
+  readonly name?: string
   readonly status?: string
   readonly conclusion?: string
   readonly state?: string
@@ -137,6 +139,46 @@ export function rollup(checks: readonly RawCheck[]): ChecksState | null {
   return running ? 'pending' : 'passing'
 }
 
+/** A head's state over the checks the base requires, with failing others named apart. */
+export interface RequiredRollup {
+  readonly state: ChecksState | null
+  /** Names of checks outside the required set that failed, which never gate. */
+  readonly advisory: readonly string[]
+}
+
+/**
+ * Collapses a head's checks over the set the base branch's rules require.
+ *
+ * An unread or empty set gates by every check, which is `rollup` itself and
+ * the safe default for a repository whose rules list nothing. A required name
+ * with no run on the head reads pending rather than passing, since a run not
+ * yet created has not cleared anything.
+ */
+export function rollupRequired(
+  checks: readonly RawCheck[],
+  required: ReadonlySet<string> | undefined,
+): RequiredRollup {
+  if (required === undefined || required.size === 0) {
+    return { state: rollup(checks), advisory: [] }
+  }
+
+  const isRequired = (check: RawCheck): boolean =>
+    check.name !== undefined && required.has(check.name)
+  const gating = checks.filter(isRequired)
+  const advisory = checks
+    .filter((check) => !isRequired(check) && rollup([check]) === 'failing')
+    .map((check) => check.name ?? '')
+
+  const state = rollup(gating)
+  const isMissing = [...required].some(
+    (name) => !gating.some((check) => check.name === name),
+  )
+  return {
+    state: state !== 'failing' && isMissing ? 'pending' : state,
+    advisory,
+  }
+}
+
 /**
  * Reads the heading of the newest pass carrying one, matching on the first line
  * alone the way `poll.ts` does.