osv

type Advisory struct {
	// ID is the canonical OSV identifier (e.g. GO-2024-1234, DSA-5678-1).
	ID string
	// Aliases are all other identifiers this advisory is known by.
	Aliases []string
	// Upstream is the vulnerabilities this record addresses, which for a distro
	// advisory is the CVEs its patch fixes.
	//
	// It is deliberately not merged into Aliases, because an alias is a claim
	// of identity and this is not one. Every distro database uses this field
	// and none uses aliases: SUSE-SU-2026:0312-1 addresses eight unrelated
	// CVEs, RHSA-2024:2447 seven. Treating those as eight names for one thing
	// would let buildMap file the record under eight keys and borrowSeverity
	// copy one CVE's vector onto the other seven.
	//
	// Consumers that join on CVE read it anyway, because a bundle still has to
	// be findable by what it fixes -- see advisoryResolver.cveSets.
	Upstream []string
	// Summary and Details are the advisory prose. They are the input to
	// advisory-text mining for ecosystems that publish no package-level data.
	Summary string
	Details string
	// Pkgs is the set of vulnerable import paths declared for a Go module.
	// Empty when OSV publishes no import paths (e.g. GitHub-only GHSA
	// records), in which case callers should fall back to module granularity,
	// and always empty for non-Go ecosystems.
	Pkgs []string

	// Fixed maps an affected package name to every version the record says its
	// patch landed in, read from the affected ranges in the order OSV published
	// them. It is the single most actionable field a report can show -- "this is
	// what to upgrade to" -- and unlike Pkgs it is populated for every
	// ecosystem.
	//
	// A package is absent when the record publishes no fixed version for it,
	// which is a real and common state: the flaw is acknowledged and no patch
	// has shipped. Callers must show that as "no fix" rather than as blank,
	// because the two mean opposite things.
	//
	// The list is a list because one affected entry routinely carries several
	// fixed events, one per branch the vendor still maintains: 22 of the 110
	// records for github.com/hashicorp/vault do, and GO-2022-0623 names 1.5.9,
	// 1.6.5 and 1.7.2 together. Those are alternatives, not a progression, so
	// there is no "latest" to collapse to without knowing what is installed --
	// telling a 1.5.x user to jump to 1.7.2 is a major upgrade they did not need
	// and did not ask for. Picking among them is the caller's job, because only
	// the caller knows the installed version. Distro records are single-branch,
	// so on Debian and Ubuntu the list is almost always one element.
	Fixed map[string][]string

	// Ecosystem is the OSV ecosystem this advisory was resolved for, copied from
	// the query ref. It is what tells a caller which comparator orders the Fixed
	// versions -- dpkg rules for "Debian:12", semver for "Go" -- and picking the
	// wrong one is worse than declining to order them at all.
	Ecosystem string

	// CVSSVector is the CVSS:3.0 or CVSS:3.1 base vector the record publishes,
	// empty when it publishes none or publishes only a version this tool does
	// not score. It is kept as the string rather than only as a number so a
	// report can show the metrics behind a rating someone disputes.
	CVSSVector string
	// PublisherSeverity is the qualitative rating the database itself assigned,
	// verbatim. Empty when the record carries no label.
	//
	// It is kept separate from CVSSVector because the two are independent
	// claims that disagree more often than one would expect. See Severity.
	PublisherSeverity string
}

type Client struct {
	HTTP *http.Client
	// BaseURL is the API root; DefaultBaseURL when empty.
	BaseURL string
	// Concurrency bounds the parallel per-id fetches QueryBatch makes;
	// defaultConcurrency when zero.
	Concurrency int
	// OnCorrection is called once for every advisory a query set aside because
	// the record's own precise ranges exclude the version asked about; see
	// customranges.go.
	//
	// It is a callback rather than a return value because the corrections are
	// not the answer to any one caller's question -- they are something the
	// report has to say about the scan as a whole, and threading them back
	// through every resolver signature to reach it would be noise. Calls are
	// sequential: matching happens after hydration, on one goroutine.
	OnCorrection func(Correction)
}

type Correction struct {
	// Advisory is the OSV id that was set aside.
	Advisory string
	// Package and Version are what was queried.
	Package string
	Version string
	// Ranges renders the record's own precise affected ranges, so a reader can
	// check the arithmetic that excluded them.
	Ranges string
}

type Ref struct {
	// Ecosystem is an OSV ecosystem string, e.g. "Go", "Debian:12",
	// "Alpine:v3.19". See Release.Ecosystem for how these are derived for OS
	// distributions.
	Ecosystem string
	Name      string
	Version   string

	// Release narrows a bare-family ecosystem to a single product release. It
	// is empty for every ecosystem whose query already names its release, and
	// when set an advisory survives only if one of its affected entries names
	// a product of that release. See Release.ProductRelease for why SUSE
	// cannot be handled in the query itself.
	Release string
}

type Release struct {
	ID              string   // ID=
	IDLike          []string // ID_LIKE=
	Version         string   // VERSION=
	VersionID       string   // VERSION_ID=
	VersionCodename string   // VERSION_CODENAME=
	PrettyName      string   // PRETTY_NAME=
	CPEName         string   // CPE_NAME=
}

type StatusError struct {
	Status int
	URL    string
	Body   string
}