upgrade

type AffectedResource struct {
	Group string   `yaml:"group"`
	Kinds []string `yaml:"kinds"`
}

type AtRiskFinding struct {
	Group string `json:"group,omitempty" yaml:"group,omitempty"`
	Kind  string `json:"kind" yaml:"kind"`

	// Components is whose crossed records put this object at risk, sorted. It
	// is the actionable half of the finding: the object's identity says what
	// might be lost, and this says which upgrade would do it.
	Components []string `json:"components,omitempty" yaml:"components,omitempty"`

	// Namespace is empty for a cluster-scoped object.
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
	Name      string `json:"name" yaml:"name"`
}

type AtRiskKind struct {
	Group string `json:"group,omitempty" yaml:"group,omitempty"`
	Kind  string `json:"kind" yaml:"kind"`

	// Components is whose crossed records named this kind, sorted. See
	// ResourceKind, which carries it into the scan.
	Components []string `json:"components,omitempty" yaml:"components,omitempty"`

	// Present reports the cluster serving this kind. False means discovery
	// enumerated the kind's API group and found no match, which is ordinary:
	// the CRD a record names may simply not be installed. Examined is then
	// zero because nothing was listed, not because nothing exists.
	Present bool `json:"present" yaml:"present"`

	// Examined is how many objects of this kind the scan read, at risk or not.
	// It is the denominator Findings is read against.
	Examined int `json:"examined" yaml:"examined"`
}

type AtRiskReport struct {
	// Scanned reports a cluster having been examined. False is the offline
	// case and the failed-scan case alike, which Reason separates.
	Scanned bool `json:"scanned" yaml:"scanned"`

	// Reason says why no scan ran, and is empty exactly when Scanned.
	Reason string `json:"reason,omitempty" yaml:"reason,omitempty"`

	// Kinds is what the scan resolved and read, one entry per kind whatever
	// came of it. It is what separates "checked and clean" from "the kind is
	// not installed here", which an empty Findings alone conflates.
	Kinds []AtRiskKind `json:"kinds,omitempty" yaml:"kinds,omitempty"`

	// Findings is every object carrying no recognized ownership marker.
	Findings []AtRiskFinding `json:"findings,omitempty" yaml:"findings,omitempty"`
}

type BundleNote struct {
	Component  string
	Pin        string
	Transition *Transition
}

type BundlePin struct {
	Component string
	Version   string
}

type ChangeKind string

type Component struct {
	// Name is the registry component name.
	Name string
	// File is ComponentConfig.Upgrades.File. Empty means no record.
	File string
	// PinnedVersion is defaultVersion (Helm) or defaultTag (Kustomize).
	PinnedVersion string
}

type ComponentResult struct {
	// Component is the name the result is keyed and sorted by. On a
	// ChangeReplaced row it is the arriving component, which owns the verdict.
	Component string

	Change ChangeKind

	// ReplacedComponent is the departing component a ChangeReplaced row joins
	// in, and is that row's FROM column: two different pieces of software
	// share no version line, so From stays empty and a renderer reads the
	// kind instead of sniffing the string.
	ReplacedComponent string

	// From and To are the version strings as the tables gave them, not
	// normalized, so a report quotes what the artifacts actually said. From is
	// empty for ChangeAdded and ChangeReplaced, To for ChangeRemoved.
	From string
	To   string

	// IdentityChanges are moves no version comparison can see. Non-empty on a
	// row whose Change is ChangeIdentity, and on a ChangeVersion row when both
	// axes moved in the same hop.
	IdentityChanges []IdentityChange

	// Verdict is empty for ChangeAdded and ChangeRemoved.
	Verdict Verdict

	// Transition is the record that describes this exact move: one crossed
	// record whose `from` covers the source. It is nil wherever no single
	// record does, including the blocked results computed from several records
	// or from none that names this starting point, so a renderer cannot print
	// one record's steps for a jump that record does not describe.
	Transition *Transition

	// Crossed is every record this jump passes a boundary of, ordered by that
	// boundary. Unlike Transition it is set whatever the verdict turned out to
	// be, including where no single record describes the whole jump, so it is
	// what the at-risk scan reads: an intermediate record names resources the
	// jump disturbs whether or not its guidance was written for this starting
	// point. Empty on every result but a version transition, ChangeIdentity
	// included: a component that held its version passed no boundary, so the
	// scan draws nothing from a relocation however far it moves the release.
	Crossed []*Transition

	// Replaces is the arriving component's declaration, set only on a
	// ChangeReplaced row.
	Replaces *Replaces

	// StoppedAt is the `to` range a blocked jump stops at: the interval it must
	// not enter in one step. Set on every blocked version transition, and empty
	// on every other result including a blocked ChangeReplaced row, where two
	// pieces of software share no version line for a boundary to sit on.
	StoppedAt string

	// Span is how far the matched record's claim reaches, from the source
	// version to the ceiling its `to` names. This is the width ADR-021
	// requires the report to state. It is zero when no single record matched
	// or the record names no ceiling. An exclusive ceiling counts as reached:
	// the highest version actually covered is not knowable from the range
	// alone.
	//
	// Span is never narrower than Jump where it is set at all: a target past
	// the record's ceiling no longer takes that record's verdict, so a claim
	// cannot end up narrower than the move it is covering.
	Span Span

	// Jump is the distance between the two versions actually compared. Zero
	// when either side is unversioned.
	Jump Span

	// Breaking reports a boundary semver makes no stability promise across: a
	// major bump, a minor bump while the major version is 0, or a changed
	// prerelease identifier over an otherwise equal release triple. False when
	// either side is unversioned, where there is no boundary to classify.
	//
	// Descriptive only. It used to decide whether an unknown result stopped a
	// strict run; ADR-021 Decision 6 dropped that calibration, because an
	// unassessed transition is unassessed at any distance.
	Breaking bool

	// Downgrade reports that the target orders below the source.
	Downgrade bool

	// Reason and Explanation say why Verdict is what it is: a stable code and
	// the sentence an operator reads, naming the versions involved. Both are
	// empty exactly when Verdict is.
	Reason      Reason
	Explanation string
}

type ComponentUpgrades struct {
	APIVersion  string       `yaml:"apiVersion"`
	Kind        string       `yaml:"kind"`
	Component   string       `yaml:"component"`
	Transitions []Transition `yaml:"transitions,omitempty"`
	Replaces    *Replaces    `yaml:"replaces,omitempty"`
}

type Hook struct {
	File  string `yaml:"file"`
	Phase string `yaml:"phase"`
}

type Identity struct {
	Version          string
	Namespace        string
	Chart            string
	Source           string
	Path             string
	Type             string
	ManifestFiles    []string
	PreManifestFiles []string

	// ObjectNames are the merged values naming the objects the chart owns,
	// keyed by dotted value path ("fullnameOverride",
	// "grafana.fullnameOverride").
	//
	// Empty is not the same as a component pinning none: it is also what a
	// caller that could not read the values hands over, because a resolved
	// recipe records them by reference rather than by value. The caller
	// reports that gap once for the whole run rather than per component, so
	// nothing here distinguishes the two.
	ObjectNames map[string]string
}

type IdentityChange struct {
	Field   string
	From    string
	To      string
	Added   []string
	Removed []string
}

type Reason string

type Replaces struct {
	Component       string      `yaml:"component"`
	Verdict         Verdict     `yaml:"verdict"`
	VerifiedBy      string      `yaml:"verifiedBy,omitempty"`
	Summary         string      `yaml:"summary"`
	StepsByDeployer []StepGroup `yaml:"stepsByDeployer,omitempty"`
}

type Report struct {
	From     string `json:"from,omitempty" yaml:"from,omitempty"`
	To       string `json:"to,omitempty" yaml:"to,omitempty"`
	Deployer string `json:"deployer,omitempty" yaml:"deployer,omitempty"`

	// Source names where the `from` table was read when it came from a
	// cluster. Nil for an artifact comparison, which needs no such statement.
	Source *ReportSource `json:"source,omitempty" yaml:"source,omitempty"`

	// ObjectNamesCompared reports whether the object-name axis was assessed at
	// all. False means no row can be read as evidence that object names held:
	// they were never looked at. ObjectNamesSkipped says why.
	ObjectNamesCompared bool   `json:"objectNamesCompared" yaml:"objectNamesCompared"`
	ObjectNamesSkipped  string `json:"objectNamesSkipped,omitempty" yaml:"objectNamesSkipped,omitempty"`

	Components []ReportComponent `json:"components" yaml:"components"`
	Summary    ReportSummary     `json:"summary" yaml:"summary"`

	// AtRisk is always present, never omitted. A run that did not scan says
	// so: an absent warning reads as an all-clear, and the resources this
	// section covers are exactly the ones AICR cannot fix if it is wrong.
	//
	// It is not part of Summary and never reaches FailsRun, per ADR-021
	// Decision 3: AICR blocking an upgrade over resources it does not own is a
	// claim it has not earned.
	AtRisk AtRiskReport `json:"atRisk" yaml:"atRisk"`
}

type ReportComponent struct {
	Component string     `json:"component" yaml:"component"`
	Change    ChangeKind `json:"change" yaml:"change"`

	// From is the source version, or on a replaced row the departing
	// component's name: two different pieces of software share no version
	// line to compare. Empty on an added row, as To is on a removed one.
	From string `json:"from,omitempty" yaml:"from,omitempty"`
	To   string `json:"to,omitempty" yaml:"to,omitempty"`

	// IdentityChanges are the moves the version columns cannot show: a
	// component that held its version and relocated anyway, or one that moved
	// on both axes in the same hop. Explanation names them in prose too, but a
	// machine consumer reads them here rather than parsing a sentence.
	IdentityChanges []ReportIdentityChange `json:"identityChanges,omitempty" yaml:"identityChanges,omitempty"`

	// Verdict is empty on an added or removed row, which made no transition.
	Verdict Verdict `json:"verdict,omitempty" yaml:"verdict,omitempty"`

	// Notes is the one-line justification the table's last column shows.
	Notes string `json:"notes,omitempty" yaml:"notes,omitempty"`

	// Reason is the stable code for why Verdict is what it is, and Explanation
	// the sentence an operator reads. Both are empty exactly when Verdict is.
	Reason      Reason `json:"reason,omitempty" yaml:"reason,omitempty"`
	Explanation string `json:"explanation,omitempty" yaml:"explanation,omitempty"`

	// Jump is the distance between the two versions compared, and Covers the
	// wider distance the matched record's claim reaches over, both as phrases
	// ("1 patch", "11 minors"). Covers is empty when no single record matched
	// or the record names no ceiling.
	Jump   string `json:"jump,omitempty" yaml:"jump,omitempty"`
	Covers string `json:"covers,omitempty" yaml:"covers,omitempty"`

	Breaking  bool `json:"breaking" yaml:"breaking"`
	Downgrade bool `json:"downgrade" yaml:"downgrade"`

	// StoppedAt is the interval a blocked row must not enter in one step. Set
	// on every blocked version row, and empty on a blocked replaced row, which
	// joins two pieces of software rather than two versions of one. Such a row
	// carries a Summary, Precondition and Steps only when one record describes
	// the whole jump: rendering one record's instructions for a jump it does
	// not describe is the thing the verdict exists to prevent.
	StoppedAt string `json:"stoppedAt,omitempty" yaml:"stoppedAt,omitempty"`

	Summary      string `json:"summary,omitempty" yaml:"summary,omitempty"`
	Precondition string `json:"precondition,omitempty" yaml:"precondition,omitempty"`

	// Steps are the selected deployer's steps only. Empty when no deployer was
	// named, when the verdict needs none, when no single record describes the
	// jump, or when the record's groups do not cover the named deployer.
	Steps []ReportStep `json:"steps,omitempty" yaml:"steps,omitempty"`

	// FailsRun mirrors ComponentResult.FailsRun so a consumer reading only the
	// report reaches the same conclusion the exit code did.
	FailsRun bool `json:"failsRun" yaml:"failsRun"`
}

type ReportIdentityChange struct {
	Field string `json:"field" yaml:"field"`
	From  string `json:"from" yaml:"from"`
	To    string `json:"to" yaml:"to"`
}

type ReportOptions struct {
	From     string
	To       string
	Deployer string

	// Source is where the `from` table was read when it came from a cluster,
	// and nil for an artifact comparison. NewReport copies it rather than
	// retaining the pointer, so the report keeps the ownership contract the
	// rest of its fields hold.
	Source *ReportSource

	// AtRisk is the advisory scan's answer, and nil for a run that did not
	// scan. NewReport then fills the report's own section with NotScannedOffline
	// rather than leaving it zero, so silence is never publishable as an
	// all-clear. Copied for the reason Source is.
	AtRisk *AtRiskReport

	// ObjectNamesCompared says the object-name axis was assessed, and
	// ObjectNamesSkipped says why it was not.
	//
	// Stated rather than derived from the other being empty, because the zero
	// value has to mean "not compared": Match and every other versions-only
	// caller sets neither, and defaulting those to compared would claim an
	// axis was checked that nothing looked at.
	//
	// They are report-level rather than per-row because an unread axis is one
	// fact about the run, not one fact per component; a row each would bury
	// the rows that did find something. Saying nothing at all is not an
	// option: a source artifact that cannot state its object names is
	// indistinguishable from one whose names held, and reporting the second
	// when the first is true is the failure this axis exists to prevent.
	ObjectNamesCompared bool
	ObjectNamesSkipped  string
}

type ReportSource struct {
	// Kubeconfig is the file the read resolved to and Context the context
	// within it. Either can be empty: an in-cluster run has no file, a merged
	// multi-file KUBECONFIG has no single path, and the cluster read does not
	// yet report the context at all. WriteTable renders the gap rather than
	// dropping the line, so an unknown reads as unknown rather than as a line
	// the renderer skipped.
	Kubeconfig string `json:"kubeconfig,omitempty" yaml:"kubeconfig,omitempty"`
	Context    string `json:"context,omitempty" yaml:"context,omitempty"`

	// Matched is how many components the read resolved to an installed
	// version. It is carried rather than derived from Components, which cannot
	// answer it: a component installed at the target version produces no row
	// at all, so the rows do not distinguish "found, unchanged" from "never
	// found".
	Matched int `json:"matched" yaml:"matched"`

	Helm ReportSourceHelm `json:"helm" yaml:"helm"`
	Argo ReportSourceArgo `json:"argo" yaml:"argo"`
}

type ReportSourceArgo struct {
	// Read reports whether the deployer installs through Argo CD and the read
	// therefore listed its Applications. The counts are zero when it did not.
	Read bool `json:"read" yaml:"read"`

	// Applications is every Application examined, including the ones belonging
	// to no component.
	Applications int `json:"applications" yaml:"applications"`

	Unattributed int `json:"unattributed" yaml:"unattributed"`
	Unreadable   int `json:"unreadable" yaml:"unreadable"`

	// Remote is Applications matching a component that deploy to another
	// cluster, excluded so a remote install is never this cluster's baseline.
	Remote int `json:"remote" yaml:"remote"`
}

type ReportSourceHelm struct {
	// Read reports whether the deployer installs through Helm releases and
	// the read therefore listed them. The counts are zero when it did not.
	Read bool `json:"read" yaml:"read"`

	// Records is every storage object examined, including the ones belonging
	// to no component. It is the denominator the other counts read against.
	Records int `json:"records" yaml:"records"`

	// Unattributed is records carrying no release name.
	Unattributed int `json:"unattributed" yaml:"unattributed"`

	// Unreadable is releases whose records could not be read.
	Unreadable int `json:"unreadable" yaml:"unreadable"`

	// Uninstalled is releases excluded because `helm uninstall
	// --keep-history` left the record behind.
	Uninstalled int `json:"uninstalled" yaml:"uninstalled"`

	// StampedUnmatched is records carrying an AICR stamp that matched no
	// component. Anything above zero means the release-name mapping is broken
	// rather than that the cluster is bare: AICR wrote those records and no
	// longer recognizes them.
	StampedUnmatched int `json:"stampedUnmatched" yaml:"stampedUnmatched"`
}

type ReportStep struct {
	ID          string `json:"id" yaml:"id"`
	Description string `json:"description" yaml:"description"`
	Reason      string `json:"reason,omitempty" yaml:"reason,omitempty"`
}

type ReportSummary struct {
	// Components counts the rows, which is the number of components whose
	// deployment changes rather than the size of either table.
	Components int `json:"components" yaml:"components"`
	// Failing counts the rows whose verdict stops a strict run.
	Failing int `json:"failing" yaml:"failing"`
}

type ResourceKind struct {
	Group      string   `json:"group,omitempty" yaml:"group,omitempty"`
	Kind       string   `json:"kind" yaml:"kind"`
	Components []string `json:"components,omitempty" yaml:"components,omitempty"`
}

type Set map[string]*ComponentUpgrades

type Source interface {
	ReadFile(ctx context.Context, path string) ([]byte, error)
}

type Span struct {
	Majors  int
	Minors  int
	Patches int
}

type Step struct {
	ID          string `yaml:"id"`
	Description string `yaml:"description"`
	Reason      string `yaml:"reason,omitempty"`
}

type StepGroup struct {
	Deployers []string `yaml:"deployers,omitempty"`
	Steps     []Step   `yaml:"steps"`
}

type Transition struct {
	From              string             `yaml:"from"`
	To                string             `yaml:"to"`
	Verdict           Verdict            `yaml:"verdict"`
	VerifiedBy        string             `yaml:"verifiedBy,omitempty"`
	Summary           string             `yaml:"summary"`
	Precondition      string             `yaml:"precondition,omitempty"`
	Reversible        *bool              `yaml:"reversible,omitempty"`
	ReversibleNotes   string             `yaml:"reversibleNotes,omitempty"`
	StepsByDeployer   []StepGroup        `yaml:"stepsByDeployer,omitempty"`
	Hooks             []Hook             `yaml:"hooks,omitempty"`
	AffectedResources []AffectedResource `yaml:"affectedResources,omitempty"`
	References        []string           `yaml:"references,omitempty"`
}

type Verdict string