gitops

type ArgoApp struct {
	Name       string
	SourcePath string // spec.source.path
	Namespace  string // spec.destination.namespace
	// File is the wrapper file that declared it, relative to the repo root — so a report can
	// point at the wrapper rather than guessing from the family name.
	File string
}

type Edit struct {
	Occurrence
	New image.Ref
}

type Env struct {
	Name string
	// Dir is the directory holding this env's family directories when every family shares
	// one parent, else "". It is informational; families carry their own Dir.
	Dir      string
	Families map[string]*Family // keyed by Family.Name
}

type Family struct {
	Name        string // base name of Dir
	Dir         string // spec.source.path, relative to the repo root
	App         string // the Application's metadata.name
	Occurrences []Occurrence
}

type Occurrence struct {
	// File is the manifest path relative to the repo root, slash-separated.
	File string
	// Doc is the 0-based index of the document within File.
	Doc int
	// Line is 1-based and file-absolute: yaml.v3 does not reset it per document.
	Line int
	// Col is yaml.v3's Column for the scalar node: 1-based, counted in characters, and
	// pointing at the first character of the scalar *token*. For a quoted scalar that is the
	// opening quote, so the value itself starts one column later (verified against yaml.v3
	// v3.0.1 — the docs are silent on it).
	//
	// This deviates knowingly from the M1 brief, which describes the column as "after any
	// quote": Col records what yaml.v3 emits, unchanged, rather than a derived value that
	// would have to be kept in step with the parser. Apply and Verify compensate — both step
	// past the opening quote for DoubleQuotedStyle/SingleQuotedStyle before matching Raw — so
	// the brief's intent (the edit replaces exactly the value, never the quotes) holds.
	// Callers should treat Col as opaque.
	Col int
	// Style is the scalar's yaml.v3 style: 0 plain, DoubleQuotedStyle, SingleQuotedStyle, or a
	// block style (LiteralStyle/FoldedStyle), which is recorded but refused by Apply.
	Style yaml.Style
	// Kind and Name identify the enclosing document (kind, metadata.name).
	Kind, Name string
	// Container is the item's name field, "" when absent.
	Container string
	// Path is the dotted YAML path of the scalar, e.g. spec.template.spec.containers[0].image.
	Path string
	// Raw is the scalar text exactly as decoded (node.Value). Apply searches for this text at
	// Line/Col; it exists as a separate field because Ref.String() normalises (drops a
	// docker-pullable:// prefix, for one) and so cannot serve as the search key.
	Raw string
	// Ref is the parsed reference.
	Ref image.Ref
}

type Plan struct {
	// Variant says which operation produced this plan and therefore how it should describe
	// itself — VariantPromote (an env pair, BuildPlan) or VariantDeploy (one image into one
	// env, BuildDeployPlan). The empty string means VariantPromote, so a Plan built before
	// this field existed, or by a test that does not care, keeps its original meaning.
	//
	// It exists only for rendering. Nothing that drives a promotion reads it, or SourceEnv:
	// engine.DeriveID hashes the target env and the resulting refs, BranchName and the PR
	// marker are id-only, and ClaimInFlight/findInFlight key on the target env — so a deploy
	// and a promotion into the same env already contend correctly, and a deploy that would
	// land the same refs as a promotion is deliberately the same promotion (see DeriveID).
	Variant string
	// SourceEnv is the env a promotion reads its refs from. Empty for VariantDeploy, which
	// has no source: the caller names the reference outright.
	SourceEnv string
	TargetEnv string
	Edits     []Edit
	// Untouched lists the distinct target-env references no Edit touches: third-party images
	// (repo outside the promotable prefixes), repos absent from the source env, and — for a
	// deploy — every repo other than the one being deployed.
	Untouched   []image.Ref
	Warnings    []Warning
	GeneratedAt time.Time
}

type Repo struct {
	Root     string
	AppsRoot string // relative to Root
	Envs     map[string]*Env
	Apps     []ArgoApp
	// Unmanaged lists directories (relative to Root) under the apps root, beside a managed
	// family, or nested inside one, that hold YAML manifests but are the source path of no
	// Application. They are never scanned for promotion: a family is read one level deep, so
	// a nested subdirectory's manifests are reported here rather than silently ignored.
	Unmanaged []string
}

type Warning struct {
	Code        string
	Message     string
	Occurrences []Occurrence
}