state

type Flags struct {
	Registry   string
	Repository string
	Username   string
}

type Package struct {
	RepoOwner string `json:"repo_owner,omitempty"`
	RepoName  string `json:"repo_name,omitempty"`
	// Stars orders the work: packages with more stars are processed first.
	// It is not omitempty: a repository with 0 stars must stay distinguishable from
	// one whose star count could not be read, so that the latter can be retried.
	Stars int `json:"stars"`

	// Versions fingerprints the newest versions the last sweep saw upstream.
	//
	// It is what an ETag would have been, over the one thing a sweep cares about.
	// GitHub's own ETag for the release listing changes whenever an asset is
	// downloaded, because the listing carries the count, so it says "something
	// changed" for packages where nothing did — and does it most for the popular
	// ones, which is exactly backwards.
	Versions string `json:"versions,omitempty"`
	// CaughtUp says the registry held every version of that sweep.
	//
	// It is recorded from asking the registry, never from having opened a pull
	// request. A pull request that fails CI is never merged, and a package marked
	// done for work that didn't land would never be looked at again. Versions are
	// not removed from the registry, so what was true when it was written stays
	// true.
	CaughtUp bool `json:"caught_up,omitempty"`
	// Round counts the runs that have reached this package.
	//
	// A run works through the packages in order and stops when its budget is spent,
	// so the ones it never reached keep the lower count and come first next time.
	// Without it the order is the same every run, and a package that takes a share
	// and gets nowhere -- one whose asset can't be downloaded, say -- takes the same
	// share of every run and holds up everything behind it for as long as it is
	// broken.
	//
	// It counts turns rather than naming a round the whole registry is in, so that
	// nothing has to decide when a round ended: a package that has had fewer turns
	// than another is behind, and that is the whole rule. A package the registry has
	// just gained starts from the largest count there is, which is the back of the
	// order; starting from none would put it ahead of everything until it caught up.
	Round int `json:"round,omitempty"`
	// LastDeepCheck is when the package's whole history was last walked. Zero means
	// never, which is what a package that hasn't been backfilled looks like.
	//
	// A sweep sees the newest versions, and anything published after the history is
	// complete appears among them. A release dated in the past doesn't, so the
	// history is walked again from time to time to find what the sweep structurally
	// cannot.
	LastDeepCheck time.Time `json:"last_deep_check,omitzero"`
}

type Progress struct {
	// Packages is how many packages are in the order.
	Packages int
	// CaughtUp is how many hold every version their last sweep saw upstream.
	CaughtUp int
	// Untouched is how many no run has reached yet.
	Untouched int
	// Lap is the fewest turns any package has had, which is the lap the order is on.
	Lap int
	// Waiting is how many are still on that lap, so a run reaches them before anything
	// gets another turn.
	Waiting int
	// Unwalked is how many have never had their whole history walked. A sweep sees the
	// newest versions, so a release dated in the past is only found by walking.
	Unwalked int
	// Renamed is how many names the registry has stopped holding, each pointing at the
	// one it holds now.
	Renamed int
}

type Registry struct {
	// Registry is the container registry host, e.g. "ghcr.io".
	Registry string
	// Repository is the OCI repository, e.g. "aquaproj/ar2".
	Repository string
	// Username is the user the token belongs to.
	Username string
}

type State struct {
	// SchemaVersion allows the format to change without breaking an older ar2 that
	// reads the state.
	SchemaVersion string    `json:"schema_version"`
	UpdatedAt     time.Time `json:"updated_at"`
	// Packages is keyed by package name.
	Packages map[string]*Package `json:"packages"`
	// Renamed maps a name the registry has stopped holding to the one it holds now.
	//
	// A repository that is renamed makes the registry's name for the package the wrong
	// one, and the package is moved: its branch is carried over and the catalogue is
	// brought to the new name. What is left is aqua-registry, which still lists the old
	// name until its own updater notices, and a run reading that would add the package
	// back under the name it was just moved off.
	//
	// It is also what stops the same rename being done twice: the sweep asks about the
	// repository a package records, so once that is the new one GitHub says nothing has
	// changed.
	Renamed map[string]string `json:"renamed,omitempty"`
}