plan

type ApplyOptions struct {
	// Delay paces the writes. GitHub's documented ceiling for mutating
	// requests is 500 an hour, and its own advice is at least a second
	// between them; going faster earns escalating secondary rate limits
	// rather than a refusal.
	Delay time.Duration
	// Limit stops after this many repository writes; 0 means no limit. It
	// counts removals as well as additions, and reconciling is refused
	// alongside it — otherwise a "cautious first run" could delete every list
	// the plan has dropped before the limit was ever consulted.
	Limit int
	// Only restricts the apply to the named categories.
	Only []string
	// ContinueOnError keeps going past a failed repository instead of aborting.
	ContinueOnError bool
	// DryRun reports what would change without changing anything.
	DryRun bool
	// Reconcile makes the account match the plan instead of only adding to it:
	// repositories leave categories they no longer belong to, and categories
	// the plan has dropped are deleted.
	//
	// Only lists this tool wrote are touched, recognized by the marker their
	// descriptions carry. A list made by hand is left exactly alone.
	Reconcile bool
	// Private creates and keeps the lists private. Visibility is enforced on
	// every run, not only at creation.
	Private bool
	// Adopt lets apply take over an existing list whose name matches a planned
	// category but which this tool did not create.
	//
	// Taking one over replaces its description with the plan's, and that
	// description carries the marker identifying a list as this tool's — so an
	// adopted list becomes subject to --reconcile and to reset. It is
	// announced when it happens, because neither consequence is recoverable
	// from the flag's name.
	Adopt bool
	// Batch sends this many membership changes in one GraphQL request. One is
	// the conservative default: GraphQL executes batched mutations serially so
	// the effect is identical, but whether GitHub meters a batch as one
	// mutating request or as many is not documented, and that is what decides
	// how long a large apply takes.
	Batch int
	// Force makes room when the plan does not fit inside GitHub's cap by
	// deleting lists this tool created that the plan no longer contains. Lists
	// made by hand are never deleted, and neither is a list the plan still
	// has — so this only removes what a --reconcile run would have removed
	// anyway, and only as many as are needed to fit.
	Force bool
	Out   io.Writer
}

type ApplyResult struct {
	ListsDeleted []string
	ReposRemoved int
	ListsCreated []string
	ReposFiled   int
	ReposSkipped int
	Errors       []error
	StoppedAtCap bool
	// Conflicts are existing lists left untouched because their name matches a
	// planned category but they were not created here.
	Conflicts []string
	// Adopted are lists that were taken over with --adopt: their descriptions
	// were replaced and they are now managed here.
	Adopted []string
	// Placed maps a category to the repositories this run put in it or found
	// already there: the placements the run asserts are on the account, and
	// so the ones a verification can hold it to. A run that stopped at
	// --limit, or skipped a category over a name conflict, asserts nothing
	// about the rest. A dry run records only what was already in place.
	Placed map[string][]string
}

type Category struct {
	Name        string   `json:"name"`
	Description string   `json:"description"`
	Terms       []string `json:"terms"`
	// Exists is true when a list of this name is already on the account, in
	// which case applying only adds repositories to it.
	Exists   bool    `json:"exists"`
	Cohesion float64 `json:"cohesion"`
	Repos    []Repo  `json:"repos"`
}

type Plan struct {
	Version     int       `json:"version"`
	GeneratedAt time.Time `json:"generated_at"`
	User        string    `json:"user"`
	Backend     string    `json:"backend"`
	// Settings records the tuning the plan was produced with, so a plan is
	// self-describing: the categories depend on a dozen weights and
	// thresholds, and without them a plan cannot be reproduced or explained
	// months later except by remembering the command line.
	//
	// Keys are the flag names of the run that built the categories. An
	// incremental run does not rebuild them, so it carries these forward
	// unchanged from the plan it extended — whatever clustering flags were on
	// its own command line — and records itself separately:
	// "incremental" is "true", "incremental-from" is the GeneratedAt of the
	// plan extended, in RFC 3339, and the "place-" keys
	// (place-min-similarity, place-outlier-sigmas, place-multi-list,
	// place-multi-list-ratio) are the placement knobs the newcomers were
	// filed with. Only the latest pass is recorded: each one overwrites them.
	Settings   map[string]string `json:"settings,omitempty"`
	TotalStars int               `json:"total_stars"`
	Categories []Category        `json:"categories"`
	Unassigned []Repo            `json:"unassigned"`
}

type Repo struct {
	FullName    string    `json:"full_name"`
	Description string    `json:"description,omitempty"`
	Similarity  float64   `json:"similarity"`
	Stars       int       `json:"stars,omitempty"`
	PushedAt    time.Time `json:"pushed_at,omitzero"`
	StarredAt   time.Time `json:"starred_at,omitzero"`
}

type ResetOptions struct {
	DryRun          bool
	ContinueOnError bool
	Delay           time.Duration
	Out             io.Writer
}

type ResetResult struct {
	Deleted []string
	// Kept are lists left alone because they were not created here.
	Kept   []string
	Errors []error
}

type VerifyResult struct {
	// Missing maps a category to the repositories the plan places there that
	// the account does not have.
	Missing map[string][]string
	// MissingLists are planned categories with no list at all.
	MissingLists []string
	Checked      int
}