provider

type APIError struct {
	Status  int
	Method  string
	Path    string
	Message string
}

type CommitState string

type CommitStatus struct {
	Repo Repo
	// SHA is the commit being reported on — the one Flux applied, not the one
	// that built the image. Hecate does not know the latter.
	SHA string
	// State is the outcome.
	State CommitState
	// Context names the check, and is what the host de-duplicates on. One per
	// Gate, so `production` and `staging` do not overwrite each other.
	Context string
	// Description is the one-line summary shown beside the check.
	Description string
	// TargetURL is where a human goes for detail. Optional.
	TargetURL string
}

type Config struct {
	// BaseURL is the API root. Empty means the public host's. Set it for GitHub
	// Enterprise Server and self-managed GitLab — the organisations that care
	// most about promotion gates are mostly not on the public hosts.
	BaseURL string
	// Token authenticates. A personal, project or installation access token.
	Token string
}

type Kind string

type Provider interface {
	// Kind is which host flavour this is.
	Kind() Kind
	// EnsurePullRequest opens a pull request, or returns the one already open
	// for the same head branch.
	//
	// Not "Create": a step is re-entrant (D19), so it will call this again
	// after a requeue, and a second identical pull request is worse than none.
	EnsurePullRequest(ctx context.Context, spec PullRequestSpec) (*PullRequest, error)
	// PullRequest reads one back.
	PullRequest(ctx context.Context, repo Repo, number int) (*PullRequest, error)
	// SetCommitStatus reports an outcome against a commit.
	//
	// Idempotent, because steps are re-entrant (D19): reporting the same state
	// twice must succeed rather than fail the crossing over a duplicate.
	SetCommitStatus(ctx context.Context, status CommitStatus) error
}

type PullRequest struct {
	Number int
	URL    string
	State  State
	// MergeCommit is the commit the merge produced, once it has merged. It is
	// what a later flux-wait waits for — the branch commit never lands on the
	// base branch under its own hash when the host squashes.
	MergeCommit string
	// Head is the branch the change is on.
	Head string
}

type PullRequestSpec struct {
	Repo   Repo
	Head   string
	Base   string
	Title  string
	Body   string
	Labels []string
}

type Repo struct {
	// Host is the API host, e.g. github.com or gitlab.example.com.
	Host string
	// Owner is the user, organisation or group path. GitLab groups nest, so
	// this can contain slashes.
	Owner string
	// Name is the repository itself.
	Name string
}

type State string