package api
import "craftdesign.group/quarry/internal/index"
// The landing's CI verdict, in one place.
//
// A landing is judged on its MERGE: the branch tip merged into the
// target, the thing an accept writes. The rows judged are exactly the
// rows landing.get lists (checksOn on the landing's subject), so a
// reader never sees a verdict that a listed run does not explain.
//
// The rule, in plain words:
//
// - A run that failed (or ended in error) on the merge being judged is
// a failure, whatever the branch tip's own run says. The merge is what
// lands, so when the merge has answered it outranks the tip: a tip
// that failed while the current merge passed reads as pass, and a tip
// that passed while the merge failed reads as fail.
// - A run still going, queued, deferred or waiting for a runner is never
// a failure. It makes the verdict "ci-waiting".
// - A cancelled run (usually superseded by a newer push) is neither for
// nor against: it counts as no run.
// - A merge whose target has moved since it was tested is stale. A stale
// merge counts neither for nor against; the verdict falls back to what
// the tip alone says, and a required check is waiting. (The accept
// gate asks about staleness separately and refuses on it; Unmet below
// is about the listed runs only.)
// - With required checks, only the runs that match a required name
// count: all green is pass, one failed is fail, and a required check
// with no run (or only a cancelled one) is waiting, never pass.
// - Without required checks, every listed run counts: any failed is
// fail, else any going is waiting, else any passed is pass.
// - When nothing on the merge has spoken (no listed run, only cancelled
// ones, or a stale merge) the branch tip's recorded verdict stands: a
// failed tip is fail, otherwise a required set is waiting and an
// unrequired one reads the tip's own pass, or nothing.
//
// Several runs of one pipeline are the newest one (newestRuns); two
// pipelines answer separately, and a failure in either is a failure.
// checkClass is what a run's status says about a check.
type checkClass int
const (
checkGoing checkClass = iota // no answer yet, started or not
checkPass // answered green
checkFail // answered red
checkStopped // cancelled: no answer, none coming
)
// classifyStatus reads a run's or an external check's status. Anything
// that is not a settled answer is going, so a status read for the first
// time can never be mistaken for a failure.
func classifyStatus(status string) checkClass {
switch status {
case "completed", "succeeded", "success":
return checkPass
case "failed", "error", "errored", "failure":
return checkFail
case "cancelled", "canceled":
return checkStopped
}
return checkGoing
}
// judgeIn is what a landing's verdict is computed from.
type judgeIn struct {
// Tip is the branch tip's own recorded verdict (ci-pass, ci-fail
// or ""). It speaks only when the merge has not.
Tip string
// Required are the check names the landing must pass; empty when
// nothing is required.
Required []string
// Rows are the listed checks of the landing's subject, as checksOn
// returns them.
Rows []CIRun
// Merge says the rows are about a merge with the target, not the
// bare tip; Stale says that merge's target has since moved.
Merge, Stale bool
}
// judgement is the verdict and the lists the accept gate and the arm's
// notices read from the same rows.
type judgement struct {
// Verdict is ci-pass, ci-fail, ci-waiting, or "" (nothing known).
Verdict string
// Unmet are the required checks not green; Failed the ones among
// them whose newest run failed; NoRun the ones with no run that
// could still answer (none at all, or only cancelled).
Unmet, Failed, NoRun []string
}
// rowAnswers says a listed row answers a required check: an external
// report by its context exactly, an engine run by CheckNameMatches.
func rowAnswers(name string, r CIRun) bool { return CheckAnswers(name, r.Workflow, r.Pipeline) }
// CheckAnswers is rowAnswers for a caller holding the row's fields: the
// landing page counts the same rows the verdict does.
func CheckAnswers(name, workflow, pipeline string) bool {
if pipeline == "external" {
return workflow == name
}
return CheckNameMatches(name, workflow, pipeline)
}
// judgeRows is the one rule above, over rows already gathered.
func judgeRows(in judgeIn) judgement {
var j judgement
rows := newestRuns(in.Rows)
for _, name := range in.Required {
var green, failed, going bool
for _, r := range rows {
if !rowAnswers(name, r) {
continue
}
switch classifyStatus(r.Status) {
case checkPass:
green = true
case checkFail:
failed = true
case checkGoing:
going = true
}
}
// A failure in any matching run is a failure; green needs every
// matching run green (a workflow name may cover two pipelines).
if failed {
green = false
} else if going {
green = false
}
switch {
case green:
case failed:
j.Unmet, j.Failed = append(j.Unmet, name), append(j.Failed, name)
case going:
j.Unmet = append(j.Unmet, name)
default:
j.Unmet, j.NoRun = append(j.Unmet, name), append(j.NoRun, name)
}
}
// What the merge's own runs say: "", "ci-pass", "ci-fail" or "ci-waiting".
said := ""
if len(in.Required) > 0 {
switch {
case len(j.Failed) > 0:
said = "ci-fail"
case len(j.Unmet) == 0:
said = "ci-pass"
case len(j.Unmet) > len(j.NoRun):
said = "ci-waiting" // a required check is in flight
}
} else {
var pass, fail, going bool
for _, r := range rows {
switch classifyStatus(r.Status) {
case checkPass:
pass = true
case checkFail:
fail = true
case checkGoing:
going = true
}
}
switch {
case fail:
said = "ci-fail"
case going:
said = "ci-waiting"
case pass:
said = "ci-pass"
}
}
if in.Merge && in.Stale {
said = ""
}
switch {
case said != "":
j.Verdict = said
case in.Tip == "ci-fail":
j.Verdict = "ci-fail"
case len(in.Required) > 0:
j.Verdict = "ci-waiting"
default:
j.Verdict = in.Tip
}
return j
}
// landingRows gathers what a landing's checks are about and the rows
// landing.get lists for it: the same call for every reader, so the rows
// judged and the rows shown cannot differ. tip "" reads the branch tip
// from the index.
func (d Deps) landingRows(repoName string, l index.LandingSummary, tip string) (subject string, pair bool, rows []CIRun) {
subject, pair = d.ciSubjectAt(repoName, l, tip)
if subject == "" {
return "", false, nil
}
return subject, pair, d.checksOn(repoName, subject, pair)
}
// judgeLanding is the verdict of a landing at the branch tip hash at
// ("" reads it from the index), given the tip's recorded verdict.
func (d Deps) judgeLanding(repoName string, l index.LandingSummary, tipVerdict, at string) judgement {
var required []string
if d.Checks != nil {
required = d.requiredForLanding(repoName, l)
}
subject, pair, rows := d.landingRows(repoName, l, at)
in := judgeIn{Tip: tipVerdict, Required: required, Rows: rows, Merge: pair}
if pair {
in.Stale = d.mergeAgeFor(repoName, l, subject).Stale
}
return judgeRows(in)
}