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

	// VulnScanError records why OSV vulnerability correlation could NOT complete for
	// this dependency — a batch-query or advisory-detail fetch that failed after
	// retries. When set, the dependency is VULN-UNVERIFIED: its CVE status is unknown
	// and must never be rendered as clean. This mirrors ResolutionError for freshness —
	// StageFreight never claims a security verdict it failed to reach. The audition and
	// lint layers surface a loud coverage-gap warning from it rather than swallowing it.
	VulnScanError string

	// 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

	// ResolvedDigest is the registry manifest digest ("sha256:…") of the update
	// target, resolved for a digest-pinned base image (FROM image:tag@sha256:…). The
	// apply layer writes it alongside the bumped tag so the pin stays immutable AND
	// current — Renovate pinDigests parity. Empty for non-digest-pinned deps.
	ResolvedDigest string

	// PinnedDigest is the digest currently written in the FROM line ("sha256:…"),
	// captured by discovery. Compared against ResolvedDigest to detect a same-tag
	// digest refresh (a CVE rebuild republished under the same version tag). Empty for
	// non-digest-pinned deps.
	PinnedDigest 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
	// Args holds every ARG declaration with a default value (name → value+line),
	// the resolution source for FROM references that interpolate a build arg
	// (FROM alpine:${ALPINE_VERSION}). Unlike EnvVars — which retains only *_VERSION
	// entries for tool cross-referencing — Args records all ARGs so any ${VAR} base
	// image can be resolved to its concrete tag.
	Args        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; resolved when it came from ${VAR}
	Line    int

	// Binding is the ARG/ENV name a ${VAR}-interpolated version resolved from, and
	// BindingLine that declaration's line — the same editable-anchor contract
	// PinnedTool and FROM interpolation use. An update to a bound package rewrites
	// the ARG default rather than the install line, which is where the version
	// actually lives. Empty when the version was written literally.
	Binding     string
	BindingLine 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 VulnIgnore struct {
	ID     string // e.g. "GHSA-xxxx-yyyy-zzzz", "CVE-2026-1234", "GO-2026-1234"
	Reason string // why this risk is carried
	Until  string // YYYY-MM-DD; empty = no expiry
}

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"
}