promote

type BranchCommit struct {
	Branch  string // prefix; a random suffix is always appended
	Subject string
	Body    string // optional second message paragraph
	// Edit returns the new content (dir-relative, slash-separated path ->
	// data) of every file to change. It is given the committed version of any
	// file via read, so uncommitted edits in the user's checkout never land in
	// the commit. A nil value deletes the file (an empty, non-nil one empties it).
	Edit func(read ReadFunc) (map[string][]byte, error)
}

type Change struct {
	Files map[string][]byte // repo-relative path -> new content
	Patch string
	// Edit re-applies just this change to whatever read returns (see
	// BranchCommit.Edit), e.g. to the committed version of each file.
	Edit func(read ReadFunc) (map[string][]byte, error)
}

type ClickHouse struct {
	URL      string // e.g. http://clickhouse:8123
	Database string
	User     string
	Password string
	Table    string       // default halo_metrics
	Client   *http.Client // default: 30s timeout
}

type Forge interface {
	PROpener
	PRFinder
}

type ForgeConfig struct {
	// Kind is gh, github, gitlab or empty (autodetect).
	Kind string
	// BaseURL overrides the API root: https://ghe.example.com/api/v3 for GitHub
	// Enterprise Server, https://gitlab.example.com/api/v4 for self-managed
	// GitLab. Empty derives it from the origin remote host. https only, or
	// http to a loopback host.
	BaseURL string
}

type ForgeOpener struct {
	Kind    string
	BaseURL string
	// Exec runs git (and gh); default Run.
	Exec RunFunc
	// HTTP is the API client; default has a 30s timeout.
	HTTP *http.Client
	// Getenv reads token variables; default os.Getenv.
	Getenv func(string) string
}

type GHOpener struct {
	// Exec runs a command in dir and returns stdout; default Run.
	Exec func(ctx context.Context, dir, name string, args ...string) ([]byte, error)
}

type GuardrailReport struct {
	Metric string                `json:"metric"`
	Source string                `json:"source,omitempty"`
	Result stats.GuardrailResult `json:"result"`
}

type MemorySource struct {
	Start    time.Time
	SpendUSD float64
	// Data is metric -> variant -> per-unit observations.
	Data map[string]map[string][]float64
	// Source is reported for every metric ("" = unknown, i.e. untrusted).
	Source string
}

type MetricSource interface {
	// Window reports when data first appeared and total spend so far.
	Window(ctx context.Context, experiment string) (Window, error)
	// Samples returns per-unit (user) observations of a halo.* metric, by
	// variant name, and their evidence source (SourceGateway | SourceCLI |
	// SourceEval; ""
	// = unknown, treated as untrusted).
	Samples(ctx context.Context, experiment, metric string) (map[string][]float64, string, error)
}

type OpenPRFinder interface {
	FindOpenPR(ctx context.Context, dir, marker string) (url string, found bool, err error)
}

type PRFinder interface {
	FindPR(ctx context.Context, dir, marker string) (url string, found bool, err error)
}

type PROpener interface {
	OpenPR(ctx context.Context, req PRRequest) (url string, err error)
}

type PRRequest struct {
	RepoDir string
	Base    string // base branch; empty = repo default
	Branch  string
	Title   string
	Body    string
	// CommitBody is an optional extra commit-message paragraph (e.g. the reason).
	CommitBody string
	Files      map[string][]byte
	// Labels and Reviewers (usernames) are optional; empty adds none.
	Labels    []string
	Reviewers []string
	// Edit, when set, re-applies the change to the committed (HEAD) version of
	// each file, so uncommitted working-tree edits never ride into the PR.
	// Files is then only the preview.
	Edit func(ReadFunc) (map[string][]byte, error)
}

type ReadFunc func(rel string) ([]byte, error)

type Remote struct {
	Scheme   string // http, https or ssh
	Host     string // host[:port] for http(s); bare host for ssh
	Hostname string
	Path     string // group/sub/repo, no .git
}

type Report struct {
	Verdict    Verdict `json:"verdict"`
	Reason     string  `json:"reason"`
	Control    string  `json:"control"`
	Treatment  string  `json:"treatment"`
	NControl   int     `json:"nControl"`
	NTreatment int     `json:"nTreatment"`
	// PValue and Effect (treatment - control) are for the primary metric.
	PValue     float64           `json:"pValue"`
	Effect     float64           `json:"effect"`
	Guardrails []GuardrailReport `json:"guardrails"`
	// Source is the evidence source of the metric that decided a promote or
	// rollback verdict (the failing guardrail, else the primary); "" otherwise.
	Source string `json:"source,omitempty"`
}

type RunFunc func(ctx context.Context, dir, name string, args ...string) ([]byte, error)

type Target struct {
	RepoDir        string
	RingFile       string // YAML containing the Ring document
	ExperimentFile string // YAML containing the Experiment document
}

type ToggleChange struct {
	Default *bool    `json:"default,omitempty"`
	Expires string   `json:"expires,omitempty"`
	Rule    string   `json:"rule,omitempty"` // rule name or index; required with the fields below
	Percent *float64 `json:"percent,omitempty"`
	// Add*/Remove* edit the rule's rings, groups and users.
	AddRings     []string `json:"addRings,omitempty"`
	RemoveRings  []string `json:"removeRings,omitempty"`
	AddGroups    []string `json:"addGroups,omitempty"`
	RemoveGroups []string `json:"removeGroups,omitempty"`
	AddUsers     []string `json:"addUsers,omitempty"`
	RemoveUsers  []string `json:"removeUsers,omitempty"`
}

type Verdict string

type Window struct {
	Start    time.Time // zero = no data yet
	SpendUSD float64
}