suite

type Composite struct {
	// Obs receives the gate's progress (may be nil).
	Obs interfaces.ExecutionObserver

	// Suites builds a suite reference's jobs: the product's suite gate under the
	// reference's flags, selection and strictness. A nil Suites makes every reference
	// one failing job.
	Suites func(ref types.SuiteRef) []interfaces.AnyJob

	// Jobs maps the names a phase's Jobs may carry to their builders; a builder
	// returning nil withholds its job (a phase the run's options skip). An unknown name
	// is one failing job, so a typo in the data fails the gate rather than dropping a
	// check.
	Jobs map[string]func() interfaces.AnyJob

	// Decs decorates the gate.
	Decs decorate.Decorations

	// Spec is the composite definition.
	Spec types.Composite
}

type Entry struct {
	// Job builds the entry's job under env.
	Job func(env Env) interfaces.AnyJob

	// Name identifies the entry; selections match it.
	Name string

	// Verb is the command that owns the entry (lint, check); selections match it.
	Verb string

	// Group is the phase the entry runs in.
	Group string

	// Kind is the entry's source (run, guard, procedure, step).
	Kind string

	// Tags are the labels selections match.
	Tags []string

	// Tools are the binaries the entry shells (a run's tool, a guard's, a step's).
	Tools []string
}

type Env struct {
	// Decs decorates each job.
	Decs decorate.Decorations

	// Snapshot memoizes per-invocation work the jobs share.
	Snapshot *codebase.Snapshot

	// Component prefixes each job's decoration component (<component>.<verb>.<name>).
	Component string

	// Opts are the run options every entry runs under.
	Opts types.RunOptions
}

type Gate struct {
	// Obs receives the gate's progress (may be nil).
	Obs interfaces.ExecutionObserver

	// Err is a composition failure (no such suite, no codebase): the gate is one failing
	// job reporting it.
	Err error

	// Env is what every entry's job is built against; a nil Snapshot gets a fresh one.
	Env Env

	// Suite is the suite definition.
	Suite types.Suite

	// Catalog is every entry the suite may select.
	Catalog []Entry

	// Flags are the set selector and modifier flag names.
	Flags []string
}

type PlannedPhase struct {
	// Group is the phase name.
	Group string

	// Entries are the phase's entries, in catalog order.
	Entries []Entry

	// Serial runs them one at a time.
	Serial bool
}

type Step struct {
	// Run is the step's work.
	Run func(ctx context.Context, env StepEnv) (types.StepResults, error)

	// Group is the phase the step runs in.
	Group string

	// Tags are matched against the suite's selection like a row's.
	Tags []string

	// Tools are the binaries the step shells, for provisioning.
	Tools []string
}

type StepEnv struct {
	// Runner runs the step's commands (the gate's runner).
	Runner interfaces.CommandRunner

	// Env is the suite environment.
	Env

	// Root is the repository root (the gate's root).
	Root string
}