reconcile

type Baseline struct {
	// DefaultBranch is the protected default branch.
	DefaultBranch string `json:"defaultBranch"`

	// Features.
	HasWiki     bool `json:"hasWiki"`
	HasIssues   bool `json:"hasIssues"`
	HasProjects bool `json:"hasProjects"`

	// Merge settings.
	AllowMergeCommit bool `json:"allowMergeCommit"`
	AllowSquashMerge bool `json:"allowSquashMerge"`
	AllowRebaseMerge bool `json:"allowRebaseMerge"`
	// SquashMergeCommitTitle names the squash commit: PR_TITLE is the pull
	// request's title; COMMIT_OR_PR_TITLE, GitHub's default, is the title
	// for a pull request of several commits and the commit's own subject
	// for one of a single commit. The title check validates the title
	// alone and auto-release reads the subject that lands on the branch:
	// under COMMIT_OR_PR_TITLE a one-commit pull request whose title was
	// made conventional after the commit was written merges under its
	// unconventional subject, which git-cliff neither releases nor lists.
	// PR_TITLE in [DefaultBaseline], the subject the merge tool sets too.
	SquashMergeCommitTitle string `json:"squashMergeCommitTitle"`

	// Pull requests.
	AllowUpdateBranch   bool `json:"allowUpdateBranch"`
	AllowAutoMerge      bool `json:"allowAutoMerge"`
	DeleteBranchOnMerge bool `json:"deleteBranchOnMerge"`

	// WorkflowPermissions is the default GITHUB_TOKEN permission of the
	// repository's workflows: read or write.
	WorkflowPermissions string `json:"workflowPermissions"`

	// TeamPermissions maps a team slug to the permission it holds on every
	// repository: pull, triage, push, maintain or admin.
	TeamPermissions map[string]string `json:"teamPermissions"`

	// Branch protection: classic without a devctl App id, the default
	// branch's ruleset ([RulesetName]) with one.
	RequiredReviews int `json:"requiredReviews"`
	// EnforceAdmins binds administrators to classic protection too. True in
	// [DefaultBaseline], the company baseline: what `devctl repo setup`
	// applies and what the merge tool lifts and restores around a merge.
	// The ruleset has no such switch: everyone but its bypass actors is
	// bound.
	EnforceAdmins bool `json:"enforceAdmins"`
	// StrictChecks requires a branch to be up to date before it merges.
	// False in [DefaultBaseline]: on a repository with Renovate and sweep
	// traffic every merge would invalidate every other open pull request
	// and re-run its CI.
	StrictChecks bool `json:"strictChecks"`
	// RequiredChecks are required whatever reported.
	RequiredChecks []string `json:"requiredChecks,omitempty"`
	// RequiredChecksIfReported are required once they have reported on the
	// default branch or a recently merged pull request — the generated
	// GitHub Actions gates. The generated CircleCI pipeline's jobs are
	// candidates the same way, read from the repository.
	RequiredChecksIfReported []string `json:"requiredChecksIfReported,omitempty"`
	// IgnoredChecks are regular expressions of contexts never required and
	// removed when found required: release workflows, path-filtered
	// workflows, the dependency-graph submission — contexts that report
	// on the default branch but cannot report on every pull request.
	IgnoredChecks []string `json:"ignoredChecks,omitempty"`
	// KeepRequiredChecks keeps every currently required context the run was
	// not told to remove: only an IgnoredChecks match, or a CircleCI job
	// missing from the pipeline the request hands in, stops being required.
	// Contexts that have not reported, and the CircleCI contexts of a
	// pipeline read from the repository, stay. On a repository the engine's
	// ruleset protects, only its required_status_checks rule is written:
	// the other rules and the bypass actors stay as they are. Set by
	// `devctl repo checks`, which edits a team's protection on its caller's
	// word.
	KeepRequiredChecks bool `json:"keepRequiredChecks,omitempty"`

	// Webhooks every repository carries; none by default (CircleCI installs
	// its own on follow).
	Webhooks []Webhook `json:"webhooks,omitempty"`

	// RenovateInstallationID is the Renovate GitHub App installation whose
	// repository list the renovate step reads as detail when the token can
	// (an organization owner's; a GitHub App token cannot); 0 reads none.
	// The step's verdict comes from the repository's own evidence.
	RenovateInstallationID int64 `json:"renovateInstallationID"`

	// CatalogRepository holds the catalog and the two workflows, as
	// owner/name.
	CatalogRepository string `json:"catalogRepository"`
	// CatalogPath is the catalog file listing the components.
	CatalogPath string `json:"catalogPath"`
	// CatalogWorkflow regenerates the catalog (input force).
	CatalogWorkflow string `json:"catalogWorkflow"`
	// MappingRepository holds the apps-to-teams mapping, as owner/name.
	MappingRepository string `json:"mappingRepository"`
	// MappingPath is the mapping ConfigMap file.
	MappingPath string `json:"mappingPath"`
	// MappingWorkflow regenerates the mapping (input repository), in
	// CatalogRepository.
	MappingWorkflow string `json:"mappingWorkflow"`
}

type Counter struct {
	// Base sends the requests; nil means http.DefaultTransport.
	Base http.RoundTripper
	// contains filtered or unexported fields
}

type CreateRequest struct {
	// Owner is the GitHub organization; empty means reposetup.DefaultOwner.
	Owner string
	// Team is the slug of the team file the entry is declared in.
	Team string
	// Entry is an accepted entry of the dry run; its Rendered declaration
	// gives the name, the description and the visibility.
	Entry reposetup.Entry
	// Mode is check or repair; empty means check. [ModeCheck] is the dry
	// run: the caller's organization role is read and the two steps plan
	// what they would do, nothing is written.
	Mode Mode
	// RenderOptions selects among the template's options for the scaffold.
	RenderOptions map[string]string
}

type CreateResult struct {
	// Repository is owner/name.
	Repository string `json:"repository"`
	// URL is the repository on GitHub; empty in a dry run of a repository
	// that does not exist yet.
	URL string `json:"url,omitempty"`
	// Created says this run created the repository; false when it existed
	// (a resumed creation) or in a dry run.
	Created bool `json:"created"`
	// ScaffoldCommit is the commit holding the scaffold at the head of the
	// default branch — the one this run pushed, or the one it found.
	ScaffoldCommit string    `json:"scaffoldCommit,omitempty"`
	Mode           Mode      `json:"mode"`
	StartedAt      time.Time `json:"startedAt"`
	FinishedAt     time.Time `json:"finishedAt"`
	// Steps are the create and the scaffold step, in that order.
	Steps []StepResult `json:"steps"`
}

type Finding struct {
	Kind    FindingKind `json:"kind"`
	Message string      `json:"message"`
	Fix     string      `json:"fix"`
	// Advisory says this finding does not prevent convergence. It defaults
	// to [FindingKind.Advisory]; a skipped classic protection read in check
	// mode is advisory too. The artifact carries the weight for its readers.
	Advisory bool `json:"advisory,omitempty"`
}

type FindingKind string

type Label struct {
	// Name is the label's name; GitHub compares it case-insensitively.
	Name string `json:"name"`
	// Color is the six hex digits GitHub takes, without '#'; empty means
	// [DefaultLabelColor].
	Color string `json:"color,omitempty"`
	// Description is the label's description; empty leaves it without one.
	Description string `json:"description,omitempty"`
}

type Mode string

type ReportedChecker interface {
	ReportedChecks(ctx context.Context, repository *github.Repository, branch string) ([]string, error)
}

type Request struct {
	// Owner is the GitHub organization; empty means reposetup.DefaultOwner.
	Owner string
	// Team is the slug of the team file the entry lives in (team-bumblebee).
	Team string
	// Entry is an accepted entry of the front half's dry run; its Rendered
	// declaration is the desired state.
	Entry reposetup.Entry
	// Added says the triggering change added the entry: the one condition
	// under which a missing repository is created.
	Added bool
	// Unarchived says the triggering change took lifecycle: archived from the
	// entry: the one condition under which the lifecycle step unarchives a
	// repository archived on GitHub. An archive no declaration change undoes
	// stays the finding archived-undeclared.
	Unarchived bool
	// Mode is check or repair; empty means check.
	Mode Mode
	// Steps restricts the run to the named steps; nil runs every step. The
	// repository is looked up in any case.
	Steps []Step
	// RenderOptions selects among the template's options for the scaffold.
	RenderOptions map[string]string
	// Pipeline holds the documents of the generated CircleCI pipeline
	// (workflows.yml, custom.yml) the protection step reads the branch-side
	// jobs from instead of the repository's .circleci — the files a caller
	// has just generated and not pushed yet. Nil reads the repository.
	Pipeline [][]byte
	// CodeownersOverride is the repository's CODEOWNERS override, the file
	// align-files writes in place of the generated one
	// ([reposetup.CodeownersOverridePath] in giantswarm/github), resolved by
	// the caller with the entry: [reposetup.ReadCodeownersOverride] from a
	// checkout, [reposetup.Overrides] from the remote. The codeowners step
	// wants it verbatim; nil means the repository has none and the step
	// wants the generated file naming Team.
	CodeownersOverride []byte
}

type Requests struct {
	GitHub   int `json:"github"`
	CircleCI int `json:"circleci"`
}

type Result struct {
	// Repository is owner/name as the run addressed it — the renamed name
	// when the declared one redirected.
	Repository string `json:"repository"`
	// Declared is owner/name as the team file declares it.
	Declared string `json:"declared"`
	Team     string `json:"team"`
	Mode     Mode   `json:"mode"`
	// Added says whether the entry was passed as added by the triggering
	// change, which alone allows the create step to create.
	Added bool `json:"added"`
	// Unarchived says whether the entry was passed as one the triggering
	// change took lifecycle: archived from, which alone allows the
	// lifecycle step to unarchive.
	Unarchived bool         `json:"unarchived,omitempty"`
	StartedAt  time.Time    `json:"startedAt"`
	FinishedAt time.Time    `json:"finishedAt"`
	Steps      []StepResult `json:"steps"`
	// Converged says the repository is set up as declared: no step ended in
	// drift or failure and every finding is advisory ([StepResult.Converges]
	// for each step). A finding a person must fix clears it, and a refused
	// entry ([Refused]) never converges: nothing was checked.
	Converged bool `json:"converged"`
	// Requests is what the run cost in requests to GitHub and CircleCI,
	// when the Runner's clients count them ([Runner.GitHubRequests]);
	// omitted when nothing was counted.
	Requests Requests `json:"requests,omitzero"`
}

type Runner struct {
	// GitHub is the client the steps read and write GitHub with, under the
	// App installation token or the person's.
	GitHub *github.Client
	// Dispatch is the client the catalog step lists and dispatches the
	// catalog and mapping workflow runs with; nil means GitHub. A caller
	// whose GitHub identity holds no Actions permission on the catalog
	// repository gives the token that does (a workflow run's own, with
	// actions: write) here and keeps every read — the repository lookup,
	// the catalog and the mapping — with GitHub, which sees the private
	// repositories that token does not.
	Dispatch *github.Client
	// Checks answers which check contexts have reported.
	Checks ReportedChecker
	// PreserveCheckSources keeps existing required-check integration IDs and
	// leaves new checks unpinned. Callers accepting generic context names,
	// such as repo checks, cannot infer a GitHub Actions source from a name.
	// False pins the baseline's generated Actions gates as before.
	PreserveCheckSources bool
	// WriteClassicChecks replaces the full classic-protection write with a
	// checks-only writer. When set, only required-check differences are
	// compared; all other classic settings, including strictness, stay as
	// read. The writer receives the latest protection snapshot and must
	// refuse nil protection rather than creating it. Nil uses the baseline's
	// full protection policy. repo checks supplies its narrower writer here.
	WriteClassicChecks func(ctx context.Context, owner, repo, branch string, protection *github.Protection, want []string) error
	// CircleCI is a person's CircleCI client the circleci step reads the
	// project's pipeline definitions with; nil reads GitHub's statuses. The
	// engine writes nothing on CircleCI.
	CircleCI *circleciclient.Client
	// Renderer renders the scaffold the scaffold step pushes.
	Renderer ScaffoldRenderer
	// Baseline is the set-up applied on top of the declaration; nil means
	// [DefaultBaseline].
	Baseline *Baseline
	// DevctlAppID is the numeric id of the devctl GitHub App (the App's
	// settings page; not the client id): what the protection step's bypass
	// list takes to be compared and written. With it the step writes the
	// default branch's ruleset with the App and, for people, the owning
	// team (the team file's team) and the repository admins as bypass
	// actors in pull_request mode (none on agentMerge: false) and removes
	// classic protection; 0 reads a ruleset the repository has and compares
	// its rules alone, and writes classic branch protection as before where
	// there is none yet. An identity without write access to the ruleset
	// gets it without its bypass actors (GitHub returns the field to write
	// access alone): the list is then not compared either, and the summary
	// says so. The reconciler's wiring passes the id.
	DevctlAppID int64
	// AlignFilesAppID is the numeric id of the align-files GitHub App, whose
	// installation opens the generated-file pull requests and arms their
	// auto-merge. With it the protection step moves the review rule into the
	// ruleset [ReviewRulesetName], which the App and the Renovate App bypass
	// for pull requests beside the actors of [RulesetName]; the required
	// checks stay in [RulesetName], which they do not bypass. An entry with
	// agentMerge: false keeps the review in [RulesetName] without bypass. 0
	// keeps the review rule in [RulesetName] and deletes the review ruleset.
	AlignFilesAppID int64
	// ReleaseAppID is the numeric id of the giantswarm-release GitHub App,
	// which the generated release workflows authenticate as. It bypasses
	// [ReviewRulesetName] for pull requests beside the align-files and
	// Renovate Apps, so the version bump pull request the release workflow
	// opens and arms auto-merge on lands once the required checks of
	// [RulesetName], which it does not bypass, are green. 0 adds no release
	// App to the review ruleset.
	ReleaseAppID int64
	// GitHubRequests and CircleCIRequests count the requests the clients
	// send, when the caller built the clients' transports over them (one
	// [Counter] under GitHub, Checks and Dispatch, one under CircleCI). The
	// run's cost is what they counted over the run, in [Result.Requests]
	// and, per step, in the log. Nil counts nothing.
	GitHubRequests, CircleCIRequests *Counter
	// Log receives one line per step and change; nil discards.
	Log io.Writer
	// Now is the clock; nil means time.Now.
	Now func() time.Time
}

type ScaffoldRenderer interface {
	Render(ctx context.Context, req reposetup.RenderRequest) (*reposetup.Scaffold, error)
}

type Step string

type StepResult struct {
	Step    Step    `json:"step"`
	Verdict Verdict `json:"verdict"`
	// Summary is one line on the state found.
	Summary string `json:"summary,omitempty"`
	// Changes are the repairs made ([ModeRepair]) or the repairs a run
	// would make ([ModeCheck]).
	Changes []string `json:"changes,omitempty"`
	// Findings are reported, not repaired; each carries its fix.
	Findings []Finding `json:"findings,omitempty"`
}

type Verdict string

type Webhook struct {
	URL         string   `json:"url"`
	Events      []string `json:"events"`
	ContentType string   `json:"contentType"`
	// Secret is the shared secret; it is written, never read back.
	Secret string `json:"-"`
}