simulate

type Candidate struct {
	Module  string
	Version string
	FromCVE bool
	VulnIDs []string

	// Replace marks a candidate applied as a go.mod replace directive
	// (survives `go mod tidy`, unlike a plain require pin) rather than a
	// `go get`. ReplaceOld is the directive's left-hand side; empty means a
	// self-replace (ReplaceOld == Module). User-authored YAML replaces enter
	// as replace seeds; the loop also promotes tidy-unsustainable CVE pins.
	Replace    bool
	ReplaceOld string
}

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

type DroppedCandidate struct {
	Module  string `json:"module" yaml:"module"`
	Version string `json:"version" yaml:"version"`
	Reason  string `json:"reason" yaml:"reason"`
}

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

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
	// VulnImports maps each seed advisory ID to the import paths its
	// vulnerable code lives in (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.
	VulnImports map[string][]string
	// 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{}
}

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 replace directives ("old=new@version", gobump
	// grammar) proven to apply cleanly: user-authored seeds plus pins the
	// loop promoted because go mod tidy would not sustain them as plain
	// requires. 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:"-"`

	// 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 parity tidy rewrites it with -go=<host>.
	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"`

	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
}

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 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 given build patterns (empty
	// means ./...) - 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).
	Linked(ctx context.Context, dir string, patterns []string) (modules, packages map[string]struct{}, err error)
	// LinkedStd returns the set of standard-library import paths in the
	// transitive non-test import graph of the given build patterns (empty
	// means ./...), evaluated for GOOS=linux (same walk semantics as
	// Linked, inverted filter).
	LinkedStd(ctx context.Context, dir string, patterns []string) (map[string]struct{}, error)
}