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"`

	// 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 mirrors [FindingKind.Advisory] in the artifact, so a reader
	// knows the weight of the finding without knowing the kinds.
	Advisory bool `json:"advisory,omitempty"`
}

type FindingKind string

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
	// 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
}

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"`
	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
	// CircleCI is the client for follow, settings, keys and pipelines.
	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) and the switch to rulesets: with it
	// the protection step writes the default branch's ruleset with the App
	// and the owning team (the team file's team) as bypass actors in
	// pull_request mode (none on agentMerge: false) and removes classic
	// protection; 0 keeps classic branch protection as before and reports
	// the missing id.
	DevctlAppID 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:"-"`
}