cardcontract

type Carry struct {
	Base   string // the base branch
	Tip    string // its tip on origin when the checkout was staged, a full sha
	Prev   string // the head carried: the last pushed head of any earlier attempt; "" when none pushed
	From   int    // the attempt Prev is the head of
	Staged string // the commit the checkout is at, the one the finish counts from
	State  string // CarryNone, CarryOK, CarryHeld or CarryConflict
}

type Frame struct {
	Kind       string   `json:"kind"` // work or read
	Card       string   `json:"card"`
	Attempt    int      `json:"attempt"`
	Tier       string   `json:"tier,omitempty"`
	Model      string   `json:"model"`
	Repo       string   `json:"repo"`                   // the clone URL or local path the card works in; "" when it names none
	BaseRef    string   `json:"base_ref,omitempty"`     // the ref the card's work is based on (a pull request's base)
	StageSha   string   `json:"stage_sha,omitempty"`    // the commit staged: a previous attempt's pushed head, a read's head under read, else the card's base sha
	Branch     string   `json:"branch"`                 // the branch the checkout is on: the card's sprint branch, a read's work branch
	PrevHead   string   `json:"prev_head,omitempty"`    // the last pushed head of any earlier attempt (sprint.BaseOf)
	PrevFrom   int      `json:"prev_attempt,omitempty"` // the attempt PrevHead is the head of
	Why        string   `json:"why,omitempty"`          // a rework: how the attempt before ended
	Finding    string   `json:"finding,omitempty"`      // a rework: what the readers of the attempt before found
	Fix        string   `json:"fix,omitempty"`          // a rework: what the coordinator asks of this attempt
	ReviewBase string   `json:"review_base,omitempty"`  // a read: the ref the change is reviewed against
	Stage      []string `json:"stage,omitempty"`        // the recipe files the brief's Stage: header lines name, relative to Recipes
	Recipes    string   `json:"recipes,omitempty"`      // the member's recipes directory, <root>/recipes
	// A decide read's bars on p(defect) (docs/SPEC-SPRINT.md section 6): native asks the
	// read decision over the card and the diff before any child and routes the read by
	// them; both empty for a strings read.
	DecideBounce string `json:"decide_bounce,omitempty"`
	DecideReview string `json:"decide_review,omitempty"`
	// A work card's gate decision bars (docs/SPEC-SPRINT.md section 5, the gate verdict):
	// native classifies a red gate's failures by them after the child, before the member
	// reports the take; both empty for none.
	DecideGateFlaky       string `json:"decide_gate_flaky,omitempty"`
	DecideGatePreexisting string `json:"decide_gate_preexisting,omitempty"`
}

type Gate struct {
	Packages []string // ./dir, sorted
	Runs     []GateRun
	Module   bool
}

type GateRun struct {
	Pkg   string   // ./dir
	Tests []string // the Test functions it runs, sorted
}

type Profile interface {
	Family() string
	JobText(f Frame, s Staged) string
	Shims(f Frame, s Staged) []Shim
}

type Shim struct {
	Name   string // the command it answers for: git, gh
	Script string // a POSIX sh script
}

type Staged struct {
	Job  string // <slot>/jobs/<label>
	Repo string // <job>/repo
	Head string // the full sha the checkout is at
	Git  string // the real git, absolute
	// Start is a read's: the commit the work under review started from, a full sha (the
	// merge base of Head and the review base, found when the checkout was staged), so the
	// read sees exactly the work's change however far the base branch has moved since;
	// "" for work, or when no merge base was found.
	Start   string
	GoCache string // the machine's shared build cache the child's GOCACHE names; "" when it has none
	Gate    *Gate  // a read's gate (ReadGate); nil: the card's
	// Carry is a rework's staging at the tip of its base branch (Carry); nil for a first
	// attempt, a read, and a rework whose base is a sha or a tag, which never moves.
	Carry *Carry
}