versions

package
v3.25.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 11, 2026 License: AGPL-3.0 Imports: 4 Imported by: 0

Documentation

Overview

Package versions provides SemVer-aware version parsing, comparison, range evaluation, and CVE 5.1 affected/unaffected status determination.

MIRRORED — this package is kept byte-identical between vdb-api/internal/versions and cli/internal/versions. The shared test corpus lives in corpus_test.go. Update both copies together.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildRangeList 

func BuildRangeList(entries []VersionEntry, defaultStatus string) []string

BuildRangeList renders entries into per-OR-group canonical strings (one element per affected range) for consumers that cannot split "||".

func BuildRangeStrings 

func BuildRangeStrings(entries []VersionEntry, defaultStatus string) (versionRange, unaffectedVersions string)

BuildRangeStrings renders entries into canonical range expressions for the affected set and the unaffected set, each OR-joined with " || ". Range entries include their introduced lower bound: {version: "1.0.0", lessThan: "2.0.0"} renders ">= 1.0.0 < 2.0.0". Junk entries are skipped. When defaultStatus is affected and no affected entries rendered, the affected expression is "*".

func Compare 

func Compare(a, b Version) int

Compare returns -1, 0, or 1 ordering a against b per SemVer 2.0 precedence (extended with Extra segments for 4-part schemes). Build metadata is ignored. A Wildcard version compares equal to anything.

func DeriveFixedVersions 

func DeriveFixedVersions(entries []VersionEntry) []string

DeriveFixedVersions extracts fix-version candidates from version entries, unifying the per-handler interpretations: an unaffected entry's version, or a range's lessThan / lessThanOrEqual boundary. Order-preserving, deduplicated. Values are passed through verbatim — git shas, letter versions ("1.0.2k"), and epoch versions ("1:2.4.5-1") are legitimate fix identifiers in some ecosystems, so no SemVer parse gate is applied.

func EqualExact 

func EqualExact(a, b Version, p PseudoPolicy) bool

EqualExact reports whether a and b match for "="/"!=" purposes. Under PseudoBaseEqual a pseudo/build-suffixed version additionally equals its bare base release (in either direction). Wildcards equal anything; a segment wildcard ("8.x") prefix-matches any version sharing the segments before it ("8.x" equals 8.2.0 but not 9.0.0).

func EvaluateStatus 

func EvaluateStatus(installed string, entries []VersionEntry, defaultStatus string, opt Options) (Status, Evidence)

EvaluateStatus determines whether installed is affected, unaffected, or unknown given CVE 5.1 version entries and a default status.

Precedence (first hit wins):

  1. exact entry, status unaffected, exact match → unaffected
  2. exact entry, status affected, exact match → affected
  3. range entry, status unaffected, contains → unaffected
  4. range entry, status affected, contains → affected
  5. defaultStatus affected/unaffected → that status
  6. → unknown

An entry's Changes array (in-range status steps) overrides the entry status with the status of the latest change at or below installed. Junk entries (unparseable versions/bounds) are skipped, never fatal.

func IsWildcardRange 

func IsWildcardRange(s string) bool

IsWildcardRange reports whether a range expression means "all versions". Mirrors (and supersedes) the historical CLI heuristics.

func Normalize 

func Normalize(s string) string

Normalize prepares a raw version (or range fragment) string for parsing: unicode operators become ASCII, whitespace is trimmed and collapsed, and the redundant "v"/"V" and "npm:" prefixes are stripped from version tokens.

Types

type Constraint 

type Constraint struct {
	Op      Op
	Version Version
}

Constraint is a single operator + version comparison.

type Evidence 

type Evidence struct {
	// MatchKind is one of: exact-unaffected, exact-affected,
	// range-unaffected, range-affected, default, unparseable-version, none.
	MatchKind string
	// RangeString is the canonical rendering of the deciding entry.
	RangeString string
}

Evidence explains why EvaluateStatus reached its verdict.

type Op 

type Op string

Op is a comparison operator in a version constraint. 

const (
	OpEq       Op = "="
	OpLt       Op = "<"
	OpLte      Op = "<="
	OpGt       Op = ">"
	OpGte      Op = ">="
	OpNeq      Op = "!="
	OpWildcard Op = "*"
)

type Options 

type Options struct {
	Ecosystem    string
	PseudoPolicy *PseudoPolicy
}

Options threads ecosystem context (and an optional explicit policy override) through evaluation call sites.

type PseudoPolicy 

type PseudoPolicy int

PseudoPolicy controls whether a pseudo/build-suffixed version (e.g. "5.3.2-0.20260526213025-e8e5b83ca9a5") is considered equal to its base release ("5.3.2") for exact-match (= / !=) purposes. Relational operators always use true SemVer ordering regardless of policy. 

const (
	// PseudoBaseEqual treats the suffix as a build artifact: the pseudo
	// version equals its base release for exact matches. Default for
	// ecosystems other than Go.
	PseudoBaseEqual PseudoPolicy = iota
	// PseudoStrict follows Go module semantics: a pseudo-version sorts
	// strictly before its base release and never equals it. Default for
	// the go/golang ecosystem.
	PseudoStrict
)

func ResolvePseudoPolicy 

func ResolvePseudoPolicy(opt Options) PseudoPolicy

ResolvePseudoPolicy returns the effective policy: an explicit override wins; otherwise the go/golang ecosystem gets PseudoStrict and everything else gets PseudoBaseEqual.

type Range 

type Range struct {
	Constraints []Constraint
}

Range is a set of constraints ANDed together.

type RangeSet 

type RangeSet struct {
	Ranges   []Range
	Original string
}

RangeSet is a set of ranges ORed together.

func ParseRange 

func ParseRange(s string) (RangeSet, error)

ParseRange parses a version range expression into a RangeSet.

Grammar (canonical, as emitted by the VDB API): 

RangeSet   := Range ( " || " Range )*          OR
Range      := Constraint ( " " Constraint )*   AND
Constraint := Op " "? Version | Version        bare Version ⇒ "="
Op         := "=" | "==" | "<" | "<=" | ">" | ">=" | "!="

Additionally tolerated (never emitted): unicode operators (≥ ≤ ≠), v/V/npm: version prefixes, interval notation "[a, b)" / "(a, b]", and comma lists with disambiguation — items carrying operators make commas AND separators (">= 2.0.0, < 2.3.1"); all-bare items make commas an OR exact list ("1.14.1, 0.30.4" ⇒ "= 1.14.1 || = 0.30.4"). "*" matches all versions.

func (RangeSet) Contains 

func (rs RangeSet) Contains(v Version, p PseudoPolicy) bool

Contains reports whether v satisfies the range set (any OR group whose constraints all hold). Exact-match constraints honor the pseudo policy; relational constraints always use true SemVer ordering.

type Status 

type Status string

Status is the canonical three-state outcome of a version evaluation. 

const (
	StatusAffected   Status = "affected"
	StatusUnaffected Status = "unaffected"
	StatusUnknown    Status = "unknown"
)

func NormalizeStatus 

func NormalizeStatus(s string) Status

NormalizeStatus maps the status vocabulary seen across CVE 5.1, MSRC, and relationship-type data onto the canonical three-state Status.

type Version 

type Version struct {
	Major, Minor, Patch uint64
	Extra               []uint64 // 4th+ numeric segments (maven/.NET style), compared after Patch
	Prerelease          string
	PrereleaseIDs       []string // dot-split identifiers for SemVer 2.0 precedence
	Build               string   // build metadata after "+", ignored in comparison
	IsPseudo            bool     // timestamp+hash suffix detected (Go pseudo-version or distro rebuild)
	PseudoBase          string   // e.g. "5.3.2"
	PseudoTimestamp     string   // e.g. "20260526213025"
	Wildcard            bool     // "*" or "x" — equals anything
	SegWildcard         bool     // a SEGMENT is a wildcard ("8.x", "1.2.*") — prefix-matches for =/!=
	SegWildcardAt       int      // index of the first wildcard segment (0=major)
	Original            string
}

Version is a parsed, comparison-ready version.

func Parse 

func Parse(s string) (Version, error)

Parse parses a version string tolerantly: optional v/V and npm: prefixes, unicode digits/operators normalized, 1–4+ numeric segments ("1.2" → 1.2.0), wildcard segments ("1.2.x" → 1.2.0), prerelease and build metadata, full-string wildcards ("*", "x"), and Go-style pseudo-versions.

type VersionChange 

type VersionChange struct {
	At     string
	Status Status
}

VersionChange is a CVE 5.1 in-range status step: at version At and above (within the entry's range) the status becomes Status.

type VersionEntry 

type VersionEntry struct {
	Version         string
	Status          Status
	VersionType     string
	LessThan        *string
	LessThanOrEqual *string
	Changes         []VersionChange
}

VersionEntry mirrors a CVE 5.1 affected.versions[] element (one row of CVEAffectedVersion): an exact version or a range with an "introduced" lower bound (Version) and an exclusive (LessThan) or inclusive (LessThanOrEqual) upper bound.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.