Skip to content
quarry Artifact [177bb81f3d]
Login

Artifact [177bb81f3d]

Artifact 177bb81f3dbd5fa56b4204b8d34aa315899623dfd34bf22b08ac0e42ffcf4667:


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.
//   - A required check with no run, while no required check has a run
//     going, is Untested: nothing is on the way. The verdict is still
//     waiting; the page says the merge has not been tested as it is now
//     and offers the re-run, rather than a wait that has no end.
//   - 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
	// Untested says a required check has no run for this merge and none
	// is queued or going to answer any required check: nothing is on
	// the way, and waiting will not change that. "Waiting" with a run
	// on its way is a different thing and stays Untested=false.
	Untested bool
}

// 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)
	var anyGoing bool
	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
		}
		anyGoing = anyGoing || going
		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)
		}
	}

	j.Untested = len(j.NoRun) > 0 && !anyGoing

	// 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)
}