simulate

type BuildEnv struct {
	// CGO is the spec's CGO_ENABLED: "0" or "1", "" when unset or not
	// understood (the melange default then applies: enabled).
	CGO string
	// GOExperiment is the GOEXPERIMENT the build runs with ("" for none).
	GOExperiment string
}

type BuildTarget struct {
	Patterns []string
	Tags     []string
	Arches   []string
	Env      BuildEnv
}

type Candidate struct {
	Module  string
	Version string
	FromCVE bool
	VulnIDs []string
	// Severity is the most severe advisory level the candidate addresses
	// (scan.SeverityRank vocabulary; empty when unknown).
	Severity string

	// Rungs is the candidate's fix ladder, highest first: one rung per
	// distinct advisory fix version (plus an existing YAML version), each
	// with the advisories it first fixes. The compile gate relaxes a
	// candidate whose version breaks the build one rung down. Empty means
	// the single rung {Version, VulnIDs, Severity}.
	Rungs []Rung

	// Replace marks a user-authored YAML replace (a replace seed), applied
	// as a go.mod replace directive rather than a `go get`; the loop never
	// creates replace directives of its own. ReplaceOld is the directive's
	// left-hand side; empty means a self-replace (ReplaceOld == Module).
	Replace    bool
	ReplaceOld string
}

type Cloner interface {
	CloneAtTag(ctx context.Context, repoURL, tag, destDir string) error
	HeadCommit(ctx context.Context, dir string) (string, error)
}

type CompileReport struct {
	// Failed maps each package that failed to compile to its first error
	// lines ("# pkg" header stripped).
	Failed map[string][]string
	// Modules maps every non-standard package in the graph to its module
	// path (replacement applied); "" for main-module packages.
	Modules map[string]string
	// Imports holds the direct imports of each failed package, for repair
	// and relaxation attribution.
	Imports map[string][]string
	// FileModules maps module-cache file paths named in error lines
	// (<GOMODCACHE>/<mod>@<ver>/...) back to "module@version".
	FileModules map[string]string
}

type Compiler interface {
	// Compile compiles (without linking) the transitive non-test import
	// graph of the target for GOOS=linux and GOARCH=arch, reporting
	// per-package failures. An error return means the go tool itself could
	// not run, not that packages failed to compile.
	Compile(ctx context.Context, dir string, target BuildTarget, arch string) (*CompileReport, error)
	// ModuleVersions lists module's released versions, ascending.
	ModuleVersions(ctx context.Context, dir, module string) ([]string, error)
	// ModuleRequires returns the require entries of module@version's own
	// go.mod.
	ModuleRequires(ctx context.Context, dir, module, version string) (map[string]string, error)
}

type DroppedCandidate struct {
	Module  string `json:"module" yaml:"module"`
	Version string `json:"version" yaml:"version"`
	Reason  string `json:"reason" yaml:"reason"`
	// Redundant marks an entry removed because it did no work: it matched or
	// regressed upstream, or the final tidied go.mod is identical without it.
	Redundant bool `json:"redundant,omitempty" yaml:"redundant,omitempty"`
	// Hygiene marks a scanner-hygiene bump that was not proposed because it
	// is not free (see HygieneModule); Reason says why.
	Hygiene bool `json:"hygiene,omitempty" yaml:"hygiene,omitempty"`
}

type Engine int

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

type HygieneModule struct {
	Module  string   `json:"module" yaml:"module"`
	Version string   `json:"version" yaml:"version"`
	VulnIDs []string `json:"vuln_ids" yaml:"vuln_ids"`
}

type Linkage struct {
	Modules, Packages map[string]struct{}
	// Embeds are the packages whose //go:embed patterns matched no files in
	// the checkout (typically files generated at build time - see
	// unmatchedEmbed), sorted and deduplicated across arches. They do not
	// affect the import graph, so the sets above are complete regardless.
	Embeds []UnmatchedEmbed
}

type ModrootRequest struct {
	Modroot string
	Seeds   []Candidate
	// Baseline maps module path -> effective version in the original
	// manifest (replace directives applied). FinalDeps entries that don't
	// move a module beyond its baseline are dropped as no-ops.
	Baseline map[string]string
	// Packages are the build package patterns (relative to Modroot,
	// go/build's space-separated with.packages grammar) whose non-test
	// import graphs define artifact reachability; empty falls back to ./...
	// (over-approximate, never narrower than the artifact).
	Packages []string
	// Tags are the go/build steps' build tags (toolchaintags plus tags),
	// applied by reachability and the compile gate so they judge the files
	// the build will compile.
	Tags []string
	// Arches are the GOARCHes the package is built for (see BuildTarget):
	// reachability is their union; the compile gate runs on the first and
	// the final set is compiled once more on each of the others.
	Arches []string
	// Env is the build environment the spec sets (see BuildEnv).
	Env BuildEnv
	// VulnImports maps each seed advisory ID to its vulnerable imports (from
	// the analysis scan's OSV metadata; see
	// scan.Vulnerability.VulnerableImports). Seed candidates whose
	// advisories all live in unlinked packages are dropped before the
	// first apply. Absent/empty entries fail open (see scan.ImportsLinked).
	VulnImports map[string][]scan.VulnerableImport
	// BaselineVulnIDs are the advisory IDs the analysis scan found in the
	// pristine graph. Residual advisories with no ID in this set were
	// INTRODUCED by the bump (they apply only to a bumped-to version) and
	// are reported and counted separately. Nil disables introduced-vuln
	// classification (fail open).
	BaselineVulnIDs map[string]struct{}
	// Engine is the bump step's apply semantics (see Engine).
	Engine Engine
	// NoTidy mirrors a `tidy: false` bump step: the engine runs no go mod
	// tidy at all.
	NoTidy bool
	// GoVersion is the build's Go version (bare, e.g. "1.25.9"); omnibump
	// lowers the go directive to it, never raises it. "" means the host go
	// (EngineOmnibump only).
	GoVersion string
	// ProbeTidy asks, for a NoTidy EngineOmnibump request, whether the
	// pristine module would tidy under omnibump anyway (DoUpdate with tidy
	// on and no entries); the answer is ModrootResult.BaselineTidies. It is
	// informational only - the simulation itself still honours NoTidy.
	ProbeTidy bool
}

type ModrootResult struct {
	Modroot string `json:"modroot" yaml:"modroot"`

	// FinalDeps are the module@version entries proven to apply cleanly, in
	// stable (indirect -> direct -> new, alphabetical within group) order,
	// filtered to entries that actually move the module graph forward
	// relative to the original manifest.
	FinalDeps []string `json:"final_deps" yaml:"final_deps"`

	// FinalReplaces are the user-authored replace directives ("old=new@version",
	// gobump grammar) proven to apply cleanly, raised where an advisory
	// demanded it. Note a replace pins its module exactly - future graph
	// demands for a higher version are overridden until a later choam run
	// re-raises the directive.
	FinalReplaces []string `json:"final_replaces,omitempty" yaml:"final_replaces,omitempty"`

	// Resolved is the full module graph (module -> version) after the final
	// clean apply.
	Resolved map[string]string `json:"-" yaml:"-"`

	// Linked is the artifact-linked module set of the final clean state
	// (see Toolchain.Linked); nil when reachability was unavailable and
	// the loop failed open (everything treated as linked). Callers use it
	// to tell which analysis-time findings never affected the artifact.
	Linked map[string]struct{} `json:"-" yaml:"-"`

	// LinkedPackages is the package-level companion of Linked: the import
	// paths in the artifact's non-test import graph, for checking an
	// advisory's vulnerable import paths (nil when unavailable - fail open).
	LinkedPackages map[string]struct{} `json:"-" yaml:"-"`

	// LinkageError says why Linked is nil (the last Toolchain.Linked query
	// failed and reachability failed open); empty when it is known.
	LinkageError string `json:"-" yaml:"-"`

	// UnmatchedEmbeds are the go:embed gaps tolerated computing Linked (see
	// Linkage.Embeds).
	UnmatchedEmbeds []UnmatchedEmbed `json:"-" yaml:"-"`

	// GateUnchecked counts the packages the compile gate excluded because
	// they already fail to compile in the pristine checkout (primary arch) -
	// its blind spot; GateUncheckedFirst is the first one's "pkg: error".
	GateUnchecked      int    `json:"-" yaml:"-"`
	GateUncheckedFirst string `json:"-" yaml:"-"`

	// Requires are the final tidied go.mod require entries (module ->
	// version) - the sustainability contract melange's gobump verifies
	// deps entries against. A pin at (or below) its module's Requires
	// version is proven; anything above is not.
	Requires map[string]string `json:"-" yaml:"-"`

	// UnrequiredModules is the degraded module-level reachability signal,
	// populated ONLY when Linked is nil (the go list -deps walk failed open)
	// and the tidied go.mod's go directive is >= 1.17: modules present in
	// Resolved but absent from the tidied require block under any replace
	// identity. Such modules provide no package in the main module's import
	// closure and cannot be linked into any artifact. nil when unavailable or
	// when Linked is authoritative. Module-granular: unlike Linked, membership
	// of the COMPLEMENT does not imply linked (test-only deps are required but
	// never ship).
	UnrequiredModules map[string]struct{} `json:"-" yaml:"-"`

	// MaxDepGoVersion is the highest go directive across the final resolved
	// build list's non-main modules (bare form, e.g. "1.25"); empty when
	// unavailable. The scratch main module's own directive is deliberately
	// not consulted: the engine rewrites it (gobump: -go=<host>; omnibump:
	// lowered to the build's Go).
	MaxDepGoVersion string `json:"max_dep_go_version,omitempty" yaml:"max_dep_go_version,omitempty"`

	// StdPackages is the stdlib slice of the final artifact import graph
	// (LinkedStd over the converged checkout); nil when unknown.
	StdPackages map[string]struct{} `json:"-" yaml:"-"`

	// CVEBackedModules lists the modules in FinalDeps whose entries address
	// at least one advisory (vs coherence-only pins) - the simulation-time
	// equivalent of the checker's SecurityBumpModules.
	CVEBackedModules []string `json:"cve_backed_modules,omitempty" yaml:"cve_backed_modules,omitempty"`

	// HygieneModules are the FinalDeps entries proposed only for scanner
	// hygiene (see HygieneModule), by module path. A module can be in both
	// lists: a security fix raised further to clear an unlinked advisory.
	HygieneModules []HygieneModule `json:"hygiene_modules,omitempty" yaml:"hygiene_modules,omitempty"`

	// HygieneSkipped says why scanner-hygiene bumps were not evaluated
	// although candidates existed (compile gate off, package reachability
	// unknown, or no convergence); empty otherwise.
	HygieneSkipped string `json:"hygiene_skipped,omitempty" yaml:"hygiene_skipped,omitempty"`

	// BaselineTidies answers ModrootRequest.ProbeTidy: the pristine module
	// tidies under omnibump (so a `tidy: false` may no longer be needed).
	// Always false when no probe was requested.
	BaselineTidies bool `json:"baseline_tidies,omitempty" yaml:"baseline_tidies,omitempty"`

	Residuals []Residual         `json:"residuals,omitempty" yaml:"residuals,omitempty"`
	Dropped   []DroppedCandidate `json:"dropped,omitempty" yaml:"dropped,omitempty"`

	// RemainingVulnIDs are the advisory IDs still present in the final
	// resolved graph (the union of all residuals' VulnIDs).
	RemainingVulnIDs []string `json:"remaining_vuln_ids,omitempty" yaml:"remaining_vuln_ids,omitempty"`

	Iterations int  `json:"iterations" yaml:"iterations"`
	Converged  bool `json:"converged" yaml:"converged"`
}

type Options struct {
	// MaxIterations caps the raise-and-rescan fixpoint loop (default 5).
	MaxIterations int
	// CommandTimeout bounds each go tool invocation (default 2m).
	CommandTimeout time.Duration
	// Budget bounds the whole per-package simulation (default 10m).
	Budget time.Duration
	// NoCompile disables the compile gate (see Compiler).
	NoCompile bool
}

type ReplaceTarget struct {
	Path    string
	Version string // empty for local filesystem replacements
}

type Residual struct {
	Module          string   `json:"module" yaml:"module"`
	ResolvedVersion string   `json:"resolved_version" yaml:"resolved_version"`
	FixedVersion    string   `json:"fixed_version,omitempty" yaml:"fixed_version,omitempty"` // empty: no released fix
	VulnIDs         []string `json:"vuln_ids,omitempty" yaml:"vuln_ids,omitempty"`
	Reason          string   `json:"reason" yaml:"reason"`

	// Introduced marks an advisory absent from the baseline analysis scan -
	// it applies only to a version the bump itself moved to, not to the
	// original graph. Accounting must not subtract introduced residuals from
	// the baseline "found" count.
	Introduced bool `json:"introduced,omitempty" yaml:"introduced,omitempty"`
}

type Rung struct {
	Version  string
	VulnIDs  []string
	Severity string
}

type Scanner interface {
	ScanPackages(ctx context.Context, pkgs []scan.Package) (*scan.ScanResult, error)
}

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

type Toolchain interface {
	// ModTidy runs `go mod tidy` in dir.
	ModTidy(ctx context.Context, dir string) error
	// Get runs `go get module@version` in dir.
	Get(ctx context.Context, dir, moduleAtVersion string) error
	// ListModules returns the resolved module graph (module path -> version)
	// from `go list -m all` in dir, with replace directives applied and the
	// main module and local-path replacements omitted.
	ListModules(ctx context.Context, dir string) (map[string]string, error)
	// Requirements returns the require entries (module path -> version) of
	// dir's go.mod as written - the set melange's gobump verifies deps
	// entries against after its final tidy.
	Requirements(ctx context.Context, dir string) (map[string]string, error)
	// DepGoVersions returns the go directive of every non-main module in the
	// build list (bare form, e.g. "1.24" or "1.24.5"), keyed by module path,
	// with replace directives applied (same skip-main semantics as
	// ListModules).
	DepGoVersions(ctx context.Context, dir string) (map[string]string, error)
	// Replace applies a replace directive (gobump parity:
	// `go mod edit -dropreplace=<old>` then `-replace=<old>=<new>@<version>`).
	Replace(ctx context.Context, dir, oldPath, newPath, version string) error
	// Replaces returns dir's go.mod replace directives keyed by Old.Path; a
	// local filesystem target is reported with Version == "".
	Replaces(ctx context.Context, dir string) (map[string]ReplaceTarget, error)
	// Linked returns the module paths AND package import paths in the
	// transitive non-test import graph of the target (see BuildTarget),
	// unioned over its arches - the modules the linker records in the
	// binary's buildinfo, i.e. what actually ships, plus the package-level
	// detail for checking advisories' vulnerable import paths. Errors make
	// reachability filtering fail OPEN (treat everything as linked).
	// Unmatched go:embed patterns are tolerated and reported (see Linkage).
	Linked(ctx context.Context, dir string, target BuildTarget) (Linkage, error)
	// LinkedStd returns the set of standard-library import paths in the
	// transitive non-test import graph of the target (same arch union and
	// walk semantics as Linked, inverted filter).
	LinkedStd(ctx context.Context, dir string, target BuildTarget) (map[string]struct{}, error)
}

type UnmatchedEmbed struct {
	Package string
	Pattern string
}