Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

9.4 KB
Raw Blame
/**
 * Each checker's verdict on a task check (Diego, 2026-11-03, #2311): Review and Test record the same checks in parallel, so
 * a later pass by one checker used to erase another's failure and its evidence. A check keeps every checker's latest
 * verdict; `passedBy` and `evidence`, which every older reader reads, are derived from them with a failure winning.
 *
 * A verdict counts only at the pull request head it read (Dee, #3394): a newer head stops it counting unless the pull
 * request's own patch is the same (a plain rebase, or a main merge that leaves its diff unchanged). It replaces reading a
 * verdict's text: a stale pass passes nothing, and a stale failure fails nothing, until someone checks the new head.
 */
import { codePullRequests, pullRequestLinks, type Check, type CheckVerdict, type Conversation, type PullRequestHead } from './model.js'

/** Each linked pull request's head as the PR watch last read it (Conversation.pullRequestHeads). */
export type PullRequestHeads = Readonly<Record<string, PullRequestHead>>

/** Whether [head] is [full]: the whole commit id, never a shortening a commit could be ground to share (security review of
 *  #3218). */
const sameHead = (full: string, head: string) => full.toLowerCase() === head.toLowerCase()

/** The most pull request heads a task keeps (keepHead): the most recently read. */
export const HEADS_KEPT = 50

/** The head a verdict's pull request is at now: its own pull request's, or for one recorded with none (from before heads,
 *  or before the task linked one), the one its task's watch read last. Undefined while the task was never watched; null
 *  once it was, but has no head of the verdict's own pull request (not read yet, or no longer watched: review of #3218,
 *  round 3, even when no head is left). */
function currentHead(verdict: CheckVerdict, heads: PullRequestHeads | undefined): PullRequestHead | null | undefined {
  if (heads === undefined) return undefined
  if (verdict.pullRequest) return heads[verdict.pullRequest] ?? null
  const watched = Object.values(heads)
  return watched.length ? watched.reduce((a, b) => b.at > a.at ? b : a) : null
}

/** Whether [verdict] counts against [heads]. While its task was never watched, it counts as verdicts always did. Then only
 *  at the head it names of its own pull request, or at a head whose patch id is its own; a patch nobody could read (null)
 *  matches nothing, so only that exact head counts there. A verdict naming no head counts at none (security review of #3218:
 *  the head watched last may be a push nobody read), and one whose pull request has no watched head is unverified (review of
 *  #3218), so one from before heads needs a new check once its task is watched. */
export function verdictCounts(verdict: CheckVerdict, heads: PullRequestHeads | undefined): boolean {
  const current = currentHead(verdict, heads)
  if (current === undefined) return true
  if (!current || !verdict.head) return false
  // A pull request closed unmerged (task #3953) counts nothing while another linked one is open: closing a reviewed pull request
  // and opening its replacement leaves no Yes behind.
  if (current.closed && heads && Object.values(heads).some(other => other !== current && !other.closed)) return false
  // Its head counts only on the base it names (security review of #3218, round 4; review round 7): naming none, on none once a
  // base is watched. A patch id names its base. A head that is git's own merge of its head and main carries it, on that same
  // base only (mergeCarry.ts, task #3553).
  const read = sameHead(current.head, verdict.head) || !!current.carries?.some(carried => sameHead(carried, verdict.head!))
  return (read && verdict.base === current.base) || (!!verdict.patch && current.patch === verdict.patch)
}

/**
 * The pull request [task]'s checks and verdicts count at (task #3953): not simply its newest link, which a wrong link (another
 * task's pull request, a closed duplicate) captured, so its reviewers' Yes on the real one counted nowhere. In order, the
 * newest linked, not closed one that its Engineer's latest status names (the Ready line), else the newest in its code list
 * (codePullRequests), else the newest not closed; each preferring one the watch has read. Only when every link is closed, the
 * newest link, as before.
 */
export function checkedPullRequest(task: Partial<Pick<Conversation, 'pullRequestUrls' | 'pullRequestHeads' | 'codePullRequestUrls' | 'assignment'>>,
  repositoryUrl: string | null): string | undefined {
  const urls = task.pullRequestUrls ?? [], heads = task.pullRequestHeads
  const open = urls.filter(url => !heads?.[url]?.closed)
  const newest = (list: readonly string[]) => list.findLast(url => heads?.[url]) ?? list.at(-1)
  const named = pullRequestLinks(task.assignment?.result ?? '', repositoryUrl), code = codePullRequests(task)
  return newest(open.filter(url => named.includes(url))) ?? newest(open.filter(url => code.includes(url))) ?? newest(open) ?? newest(urls)
}

/** The links of a task its PR watch reads: its newest HEADS_KEPT (review of #3218: one task links 369 pull requests in
 *  production), the same each pass until it links another, so the heads kept are exactly the heads read (keepHead). */
export const watchedLinks = (links: readonly string[]): string[] => links.slice(-HEADS_KEPT)

/** [heads] with [url] at [entry]: only the pull requests the watch reads of the task's [links] (watchedLinks), so never more
 *  than HEADS_KEPT, and never one dropped that the next pass reads again (review of #3218, round 2). A verdict on one no
 *  longer read is unverified (verdictCounts), never valid for every head. */
export function keepHead(heads: PullRequestHeads | undefined, url: string, entry: PullRequestHead, links: readonly string[]): Record<string, PullRequestHead> {
  const linked = new Set(watchedLinks(links))
  const kept = Object.entries({ ...heads, [url]: entry }).filter(([key]) => key === url || linked.has(key))
    .sort(([, a], [, b]) => b.at - a.at).slice(0, HEADS_KEPT)
  return Object.fromEntries(kept)
}

/** [verdict] learns the patch id of the head it read from [known], when that is its head on the base it names: the id names
 *  the base, so another base's is another diff. */
function learnPatch(verdict: CheckVerdict, known: PullRequestHead | undefined): void {
  if (!verdict.head || !known || !sameHead(known.head, verdict.head) || verdict.base !== known.base) return
  if (!verdict.patch && known.patch) verdict.patch = known.patch
}

/** Derives [check]'s `passedBy` and `evidence` from the verdicts that count against [heads], and marks the others stale
 *  with the head they stopped at. It passes only while no counting verdict failed: its latest counting passer; its evidence
 *  is the latest counting failure's, else that pass's, else none (a check nobody checked at this head reads unchecked). */
export function deriveCheck(check: Check, heads: PullRequestHeads | undefined): void {
  const verdicts = check.verdicts ?? []
  for (const verdict of verdicts) {
    if (verdictCounts(verdict, heads)) delete verdict.stale
    else verdict.stale = currentHead(verdict, heads)?.head ?? ''
  }
  const live = verdicts.filter(v => v.stale === undefined)
  const failed = live.findLast(v => !v.passed), passed = live.findLast(v => v.passed)
  check.passedBy = failed ? null : passed?.by ?? null
  check.evidence = (failed ?? passed)?.evidence ?? null
}

/** Records [verdict] on [check], in place of its checker's earlier one (`earlier`, undefined on its first). The verdicts are
 *  kept oldest first. A pass kept from before verdicts were is its checker's verdict; a failure from then names no checker,
 *  so it is not kept. A pass also drops the failures of the checkers [clears] names, and returns them (`cleared`) for the
 *  caller to record: those who left the Swarm, when someone accountable for the task passes it (#2656), as nobody else
 *  could ever pass it in their place. [heads]: the task's pull requests' heads, which the verdicts count against. */
export function recordCheckVerdict(check: Check, verdict: CheckVerdict, clears: (by: string) => boolean = () => false,
  heads?: PullRequestHeads): { earlier: CheckVerdict | undefined; cleared: CheckVerdict[] } {
  const kept = check.verdicts ?? (check.passedBy ? [{ by: check.passedBy, passed: true, evidence: check.evidence ?? '', at: 0 }] : [])
  const earlier = kept.find(v => v.by === verdict.by)
  const cleared = verdict.passed ? kept.filter(v => v !== earlier && !v.passed && clears(v.by)) : []
  if (verdict.pullRequest) learnPatch(verdict, heads?.[verdict.pullRequest])
  check.verdicts = [...kept.filter(v => v !== earlier && !cleared.includes(v)), verdict]
  deriveCheck(check, heads)
  return { earlier, cleared }
}

/** The PR watch read a new head of [url] (its head before: [previous]; every head now: [heads]): each verdict on it learns
 *  the patch id of the head it read, when the watch knows it, and [checks] are derived again. The checks that passed before
 *  and do not now, for the caller to tell. */
export function refreshChecks(checks: readonly Check[], url: string, previous: PullRequestHead | undefined, heads: PullRequestHeads): Check[] {
  const stopped: Check[] = []
  for (const check of checks) {
    if (!check.verdicts?.length) continue
    for (const verdict of check.verdicts) {
      if (verdict.pullRequest !== url || !verdict.head) continue
      learnPatch(verdict, previous)
      learnPatch(verdict, heads[url])
    }
    const before = check.passedBy
    deriveCheck(check, heads)
    if (before && !check.passedBy) stopped.push(check)
  }
  return stopped
}