supplychain

type Dependency struct {
	Name    string // e.g. "golang", "github.com/spf13/cobra", "react"
	Current string // currently pinned/resolved concrete version string

	// Constraint is the RAW manifest version requirement, operator included, for
	// ecosystems whose manifests express a range (cargo "^1.8" / "~1.2" / "=1.8.0" /
	// ">=1, <2"). It is the native intent honored during eligibility selection —
	// distinct from Current (the concrete resolved version). Empty for ecosystems
	// that pin an exact version (go.mod, toolchain), where Current is the pin.
	Constraint string

	// Latest is the newest version the registry publishes — "latest AVAILABLE".
	// It is NOT necessarily a safe autonomous-update target: a major / out-of-range
	// bump can break the build (feature renames, API migrations). See LatestEligible.
	Latest string

	// LatestEligible is the newest version that is semver-COMPATIBLE with the current
	// constraint — the safe autonomous-remediation target. Empty for ecosystems with
	// no compatibility model (exact go.mod pins), where Latest is the target. When
	// Latest > LatestEligible a major upgrade exists OUT of range: review-domain,
	// constraint-expanding, never auto-applied.
	LatestEligible string

	// AvailableVersions is the set of published versions the registry lists — a pure
	// registry fact retained so the deps layer can re-target within a max_update
	// ceiling (e.g. patch-lock selecting the newest patch of the current minor rather
	// than holding on a minor bump). Populated only where cheaply available: cargo (the
	// list is already fetched to compute LatestEligible) and Go (via an @v/list fetch
	// enabled only under patch-lock). Empty otherwise. Never a policy input — the deps
	// layer selects a target from it; discovery just records what exists.
	AvailableVersions []string

	// Pinned records that a NATIVE dependency-selection directive already governs
	// this dependency, so StageFreight neither reports it outdated nor proposes an
	// update — it respects the toolchain's own decision. The value names the
	// mechanism (e.g. "replace directive"). Empty = freely resolvable. This is the
	// discovery-side counterpart to what apply already honors, so both agree.
	Pinned string

	// LockPending marks a dependency whose resolvable target exists but whose lockfile
	// entry has not been written yet — a wildcard toolchain constraint with no
	// .stagefreight/toolchains.lock entry. Current already equals the target (nothing to
	// bump), yet the update pass must still MATERIALIZE the lock, so the filter treats it
	// as a candidate rather than "up to date". This is how a first lock is born.
	LockPending bool

	Ecosystem string // one of the Ecosystem* constants below
	File      string // relative path from repo root
	Line      int    // line number of the pinned version
	Indirect  bool   // e.g. go.mod // indirect
	SourceURL string // registry/API URL that was queried
	Binding   string // editable anchor used by source-specific updaters (e.g. ENV var name)

	// Vulnerability info populated by the OSV correlation pass.
	Vulnerabilities []VulnInfo // known CVEs affecting the current version

	// Advisory is an optional informational message set by the resolver
	// when a non-versioned or pre-release tag has stable releases available.
	Advisory string

	// ResolutionError records why Latest could NOT be determined — a registry
	// lookup failure, an empty response, a parse error. When set, the dependency
	// is UNRESOLVED: an indeterminate state that must never be rendered as
	// up-to-date. StageFreight never claims freshness it failed to verify.
	ResolutionError string

	// CooldownHeld is a newer release that exists but is withheld by the MinReleaseAge
	// supply-chain cooldown (younger than the configured window). Latest then points at the
	// newest version old enough to adopt; this records what was held back, for disclosure.
	CooldownHeld string

	// Fields populated by the config/rule engine after resolution.
	// Used by future update commands for MR grouping and automerge.
	Group     string // assigned group name from package rules
	Automerge bool   // whether this dep's MR should automerge

	// ResolvedTarget, when set by the deps layer, is a ceiling-constrained update
	// target that OVERRIDES the natural UpdateTarget(). It lets a max_update ceiling
	// re-target to a lower in-range version — e.g. patch-lock choosing the newest
	// patch of the current minor instead of holding — rather than skipping the dep
	// entirely. Empty means "use the natural target". Never set by discovery.
	ResolvedTarget string
}

type DigestEntry struct {
	Digest  string `yaml:"digest"`
	Checked string `yaml:"checked"`
}

type DigestLock struct {
	Digests map[string]DigestEntry `yaml:"digests"`
}

type DockerFreshnessInfo struct {
	Stages      []StageInfo
	EnvVars     map[string]EnvVar
	PinnedTools []PinnedTool
	ApkPackages []PackageRef
	AptPackages []PackageRef
	PipPackages []PackageRef
}

type EnvVar struct {
	Name  string
	Value string
	Line  int
}

type PackageRef struct {
	Name    string
	Version string // empty if unpinned
	Line    int
}

type PinnedTool struct {
	EnvName string // e.g. "BUILDX_VERSION"
	Version string // e.g. "v0.31.1"
	Owner   string // GitHub owner
	Repo    string // GitHub repo
	Line    int    // line of the ENV declaration
}

type Snapshot struct {
	Dependencies []Dependency
}

type StageInfo struct {
	Image string // full image reference (e.g. "golang:1.25-alpine")
	Name  string // AS alias
	Line  int
}

type VulnInfo struct {
	ID       string   // e.g. "GHSA-xxxx-yyyy-zzzz", "CVE-2024-12345"
	Aliases  []string // other identifiers for the SAME advisory (CVE/GHSA/GO-… cross-refs)
	Summary  string   // short description
	Severity string   // "LOW", "MODERATE", "HIGH", "CRITICAL" (from OSV/CVSS)
	FixedIn  string   // version that fixes the vulnerability (if known)
	Source   string   // provenance: "osv" (default), "trivy", "grype", "trivy+grype"
}