imagepin

type Family struct {
	// contains filtered or unexported fields
}

type Literal struct {
	// Path is repo-relative.
	Path string
	// Re must capture the tag in group 1.
	Re *regexp.Regexp
	// Why records what the site is, so a reader of the declaration does
	// not have to open the file to find out.
	Why string
}

type Pin struct {
	// Source is the file that carries the pin, relative to the artifact
	// being judged. It can differ from the overlay when the overlay
	// composes another one (example-otel composes example) or inherits
	// the image straight off a base's Deployment (gke-deploy does).
	Source string
	// Image is the matched family name.
	Image string
	// Tag is the tag, empty for a digest pin.
	Tag string
	// Digest is the digest, empty for a tag pin.
	Digest string
	// DigestVersion is the release a digest pin declared itself resolved
	// from, via the family's provenance comment. Empty otherwise.
	DigestVersion string
}

type PinBearingFile struct {
	Path    string
	Extract func([]byte, *Family) []Pin
}

type RewritePlan struct {
	// contains filtered or unexported fields
}

type Site struct {
	// Path is repo-relative and slash-separated.
	Path string
	// Line is 1-based, for messages.
	Line int
	// Tag is the tag as written.
	Tag string
	// Kind is the shape it was written in.
	Kind SiteKind
	// Text is the surrounding match, trimmed, for the report.
	Text string
	// Group is the unit freezing applies to: the recipe directory this
	// site belongs to, or the file's own path when it sits outside any
	// scanned root.
	Group string
	// Frozen is set on every site in a group where a pin declared
	// itself frozen. See [Tracked.FrozenMarker].
	Frozen bool
	// FrozenReason is the text the marker carried, review clause and all.
	FrozenReason string
	// FrozenReview is the date the marker says the freeze should be
	// looked at again, at UTC midnight. Never the zero time on a site
	// that survived [Tracked.Sites] with Frozen set: a marker with no
	// parseable review date does not freeze anything, it errors.
	FrozenReview time.Time
	// contains filtered or unexported fields
}

type SiteKind string

type Tracked struct {
	// Family is the image-name predicate every scan path is scoped by.
	Family *Family
	// UpstreamRepo is the "owner/name" the resolver asks for releases.
	UpstreamRepo string
	// Roots are repo-relative paths walked for declarations. A directory
	// is walked whole and a site's freeze group is its immediate
	// subdirectory of that root — the recipe directory; a single file is
	// scanned as itself and is its own freeze group.
	//
	// Naming one file is not a special case bolted on: a deploy artifact
	// can live outside the tree it deploys, and the e2e harness that
	// pins the watcher image sits in dev/tools precisely because it is
	// CI's, not the recipe's.
	Roots []string
	// Docs are repo-relative documents that state the pin to a reader.
	// They are read for image references AND for [Tracked.ProseRe].
	//
	// This list is DECLARED rather than discovered because the prose
	// matchers are deliberately narrow, and a discovered list would
	// have to be "every markdown file", which sweeps in the changelog
	// and every historical version mention in it.
	//
	// Non-vacuity — "each of these still states the pin at least once"
	// — is NOT enforced here. That is an offline, in-tree property, and
	// it is already gated in test-unit by the recipe's own
	// TestWatcherTagInDocsIsCurrent, which reads this same list.
	Docs []string
	// Literals are the declared bare-tag sites.
	Literals []Literal
	// ImageRefRe matches a full image reference with the tag captured
	// in group 1. It is the narrow, assertion-facing sibling of the
	// family's internal discovery regexp: discovery deliberately also
	// matches `:latest` and `:${VAR}` refs so it can SEE them and skip
	// them on purpose, while this one only ever matches a real tag.
	// Exported so the recipe's own offline test asserts against the
	// same matcher the rewriter uses.
	ImageRefRe *regexp.Regexp
	// ProseRe matches an English statement of the pin, capturing the
	// tag in group 1. Applied ONLY to Docs.
	ProseRe *regexp.Regexp
	// TagRe is the shape a rewritable tag has. A reference whose tag
	// fails it — `:latest`, `:${WATCHER_IMAGE##*:}`, a digest — is not
	// a site: there is nothing there to bump.
	TagRe *regexp.Regexp
	// Frozen names the freeze groups — recipe directories, exactly as
	// [freezeGroup] renders them — that deliberately do not track
	// upstream.
	//
	// This list is the SAFETY and [Tracked.FrozenMarker] is the
	// EXPLANATION, and both are required. A marker alone used to be
	// enough, and that was a hole of the same class this whole package
	// exists to close: the natural place to document how freezing works
	// is next to a pin, an adjacent comment is indistinguishable from an
	// attached one, and a tree that exempts itself by accident reports
	// drift=false forever while going stale. So the two disagreeing is
	// an ERROR in both directions — a marker outside a declared group,
	// and a declared group with no marker — never a silent exemption.
	Frozen []string
	// FrozenMarker matches the opt-out comment, capturing the reason in
	// group 1. It must match a whole comment line. A marker with no
	// reason, or one whose reason is an angle-bracketed placeholder,
	// does not count: an unexplained freeze is how a gate rots, and a
	// `<why>` placeholder is a worked example rather than a decision.
	//
	// The reason must also carry a review date — see [reviewClause].
	FrozenMarker *regexp.Regexp
}