cigate

type Check struct {
	Name string
	Lane Lane

	// 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
	// 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
	// Dir is project-relative; empty is the project root.
	Dir string
	Env []string

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

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

type Lane string

type Options struct {
	// Out receives the checks' own output and the summary. 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.
	Groups bool
	// Env is the base environment; nil is os.Environ().
	Env []string
}

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
}

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
	// Tail is the end of a failed command's output, for the job summary.
	Tail string
}

type Status string

type Tally struct{ Passed, 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
}