cigate

type Affected struct {
	// Full means run everything; Reason says why.
	Full   bool
	Reason string
	// Packages are the import paths to test (affected mode).
	Packages []string
	// Total is how many packages in the module have tests.
	Total int
	// BaseRef is the ref diffed against (origin/main); Base its merge-base
	// with HEAD, short.
	BaseRef, Base string
	// Changed are the changed files, project-relative.
	Changed []string
}

type AffectedInput struct {
	Root string
	// Env is the environment go list runs with; nil is the process's.
	Env []string
	// Force, when non-empty, is the reason to run the full suite regardless
	// (CI_FULL=1, --full).
	Force string
	// BaseRef overrides origin/<default>: the ref a stacked branch diffs
	// against (CI_BASE / --base).
	BaseRef string
	// Ignore are ci.gate.affected_ignore's globs: files no Go test reads.
	Ignore []string
	// Git and GoList run the two tools; nil uses the real binaries. Tests
	// substitute.
	Git    func(ctx context.Context, dir string, args ...string) (string, error)
	GoList func(ctx context.Context, dir string, env []string) (io.Reader, error)
}

type CacheInput struct {
	// Root is the project root (a git work tree).
	Root string
	// Dir is the cache root ($FORGE_CI_CACHE_DIR); empty is
	// <user cache dir>/forge/ci-verdicts.
	Dir string
	// Forge identifies the judging forge binary.
	Forge string
	// Frontends are the project-relative frontend directories, whose
	// package.json `file:` / `link:` dependencies are outside inputs.
	Frontends []string
	// Env is the gate's base environment.
	Env []string
}

type Check struct {
	Name string
	Lane Lane
	// Group is the label CI_ONLY can select by, besides the name.
	Group string
	// After names checks that must finish (with any verdict) before this one
	// starts. Selecting this check with CI_ONLY selects them too.
	After []string
	// Heavy makes the check hold a host-wide heavy slot while it runs.
	Heavy bool
	// MutatesTree marks a check that writes tracked files: it runs alone,
	// ahead of every check that only reads the tree.
	MutatesTree bool
	// NoCache keeps the verdict cache from ever answering for this check:
	// its verdict depends on state outside the tree.
	NoCache bool

	// NotApplicable, when set, reports the row as N/A with this reason and
	// runs nothing.
	NotApplicable string
	// Done returns a non-empty note when the check's work is already done
	// (dependencies installed); the row is PASS and nothing runs.
	Done func() string
	// Prereq returns a non-empty reason when the check cannot run here. The
	// row is then SKIPPED, which fails the gate.
	Prereq func() string
	// Requires lists binaries that must resolve on the check's own PATH
	// (pinned tool dirs and ci.gate.path included); a missing one SKIPs it.
	Requires []string
	// Probe is a command that must succeed before the check runs; when it
	// fails the row is SKIPPED with ProbeReason.
	Probe       []string
	ProbeReason string
	// Tools are pinned tools the command needs. Each is resolved to its
	// pinned version before the command runs, and its directory is put first
	// on the command's PATH.
	Tools []Tool

	Argv []string
	// SlotArgv, when set, runs instead of Argv while the check holds a host
	// heavy slot of its own. A tool with its own machine-global mutex drops
	// it here, because the slot already bounds what the mutex protected
	// (golangci-lint: --allow-parallel-runners instead of
	// --allow-serial-runners). Without a slot of its own — the limit is off,
	// or the gate itself runs inside a parent's slot — Argv runs.
	SlotArgv []string
	// Dir is project-relative; empty is the project root.
	Dir string
	Env []string
	// SkipExitCode, when non-zero, is the exit status by which the command
	// says it could not run here: the row is SKIPPED with its last output
	// line as the reason.
	SkipExitCode int
	// Note annotates the row when the command runs: how it was narrowed
	// (affected-package mode) or anything else the reader needs.
	Note string

	// OnFail runs after the command failed, to undo what it left behind.
	OnFail func(out io.Writer)
}

type DurationHistory struct {
	// contains filtered or unexported fields
}

type ExecFunc func(ctx context.Context, dir string, env []string, argv []string, out io.Writer) error

type HeldSlot interface {
	// Env is what the check's command inherits, so the heavy commands it
	// runs in turn (`task test`'s `forge slot run`, verify-generated's
	// `forge generate`) run inside this slot instead of queueing for another.
	Env() []string
	// SetLabel names the check holding the slot, for waiters to see.
	SetLabel(label string)
	Release() error
}

type Lane string

type Options struct {
	// Out receives the progress lines and the checks' failure tails. Defaults
	// to os.Stdout.
	Out io.Writer
	// Skip names the checks the caller chose not to run.
	Skip []string
	// Resolver pins tools. Nil means checks that declare Tools cannot run.
	Resolver *Resolver
	// Exec runs one command. Nil uses os/exec; tests substitute.
	Exec ExecFunc
	// Root is the project root.
	Root string
	// Groups wraps each check's output in GitHub Actions ::group:: lines,
	// printed whole when the check finishes so concurrent checks never
	// interleave.
	Groups bool
	// Env is the base environment; nil is os.Environ().
	Env []string
	// Path is put first on every check's PATH, ahead of the pinned tools'
	// directories: the project's own declared tool directories
	// (ci.gate.path), which it chose over forge's pins on purpose.
	Path []string
	// Jobs caps how many checks run at once. Zero is DefaultJobs().
	Jobs int
	// Slot takes a host heavy slot for a Heavy check. Nil runs heavy checks
	// without one.
	Slot SlotFunc
	// Verdicts answers for checks whose PASS on this exact tree is already
	// recorded, and records new ones. Nil disables the cache.
	Verdicts Verdicts
	// LogDir receives one <check>.log per check that runs. Empty keeps the
	// output in memory only (tests).
	LogDir string
	// Clock stamps durations; nil is time.Now (tests substitute).
	Clock func() time.Time
	// Expected is how long each check took when it last ran
	// (DurationHistory). The checks that only read the tree start longest
	// path first by it; nil keeps plan order.
	Expected map[string]time.Duration
}

type PlanInput struct {
	// Root is the project root.
	Root string
	// CI is the data the scaffolded ci.yml renders with: which lints, scanners
	// and jobs the project has. The gate reads the same struct so a toggle
	// means the same thing in both.
	CI templates.CIWorkflowData
	// Cfg supplies the project's extra checks and its derived features.
	Cfg *config.ProjectConfig
	// Forge is the argv that re-enters this forge binary.
	Forge []string
}

type Report struct {
	Lane    string
	Results []Result
	// Head is the commit the gate judged ("" outside git); Dirty says the
	// working tree had uncommitted changes on top of it.
	Head  string
	Dirty bool
	// Wall is the gate's elapsed time.
	Wall time.Duration
}

type Resolver struct {
	// CacheRoot is where pinned tools are installed.
	CacheRoot string
	// ProjectDir selects the Go toolchain tools are built with: the one `go`
	// picks for the project, so a linter is never built with a Go older than
	// the module it must lint.
	ProjectDir string
	// Note receives one line per install, so a first-run build is explained.
	Note io.Writer

	LookPath func(string) (string, error)
	// Probe reports the version of the binary at path, or "".
	Probe func(path string, t Tool) string
	// Install builds t into dir.
	Install func(ctx context.Context, t Tool, dir, toolchain string) error
	// Toolchain reports the Go release `go` selects for ProjectDir.
	Toolchain func(ctx context.Context) string
	// ModuleGo is the project's go directive ("1.27.0"), "" when unknown.
	ModuleGo string
	// BuiltWith reports the Go release a binary was built with ("go1.27.2").
	BuiltWith func(path string) string
	// contains filtered or unexported fields
}

type Result struct {
	Name     string
	Lane     Lane
	Status   Status
	Duration time.Duration
	Note     string
	// Allowed marks a SKIPPED row the caller asked for (CI_SKIP), which does
	// not fail the gate.
	Allowed bool
	// Cached is the short commit a reused PASS was recorded at; "" when the
	// check ran.
	Cached string
	// Log is the check's output file, project-relative when under the root.
	Log string
	// Tail is the end of a failed command's output, for the job summary.
	Tail string
}

type SlotFunc func(ctx context.Context) (HeldSlot, error)

type Status string

type Tally struct{ Passed, Cached, Failed, Skipped, Allowed, NA int }

type Tool struct {
	Binary string
	// Module is the `go install` package path.
	Module string
	// BuildModule is the module path the binary's build info records, when
	// that differs from Module's directory (golangci-lint's /cmd/ suffix).
	BuildModule string
	// Version is the pin, with the leading "v".
	Version string
	// MatchGo requires the binary to have been built with a Go at least as
	// new as the project's go directive: golangci-lint cannot analyze Go newer
	// than the Go it was built with, so a PATH copy at the right VERSION but
	// built with an older Go is the wrong binary.
	MatchGo bool
	// VersionArgs and VersionRE read the version from the binary's own output
	// when its build info does not carry one (release builds record
	// "(devel)").
	VersionArgs []string
	VersionRE   *regexp.Regexp
}

type VerdictCache struct {
	// contains filtered or unexported fields
}

type Verdicts interface {
	// Lookup reports a recorded PASS for c on the tree being judged, and the
	// short commit it was recorded at.
	Lookup(c Check) (commit string, ok bool)
	// Record remembers a PASS c earned in this run.
	Record(c Check)
}