# `VulnCheck.Semver`
[🔗](https://github.com/Voskan/vulncheck/blob/v1.0.1/lib/vulncheck/semver.ex#L1)

Version comparison and range matching for Hex, Erlang and OTP versions.

`Version.parse/1` rejects many legitimate versions published by Erlang
packages (`"2.8"`, `"1.0.2.1"`, `"25"`). This module accepts any number of
numeric segments, compares them numerically (missing segments count as
`0`), and follows SemVer 2.0 for pre-release identifiers
(`1.19.0-rc.0 < 1.19.0-rc.1 < 1.19.0`) while ignoring `+build` metadata.

It also evaluates OSV `ranges`/`versions`, CVE 5.1 `versions` and OTP
runtime constraints such as `"<= 25"` or `">= 24 and <= 25"`.

# `parsed`

```elixir
@type parsed() :: {[non_neg_integer()], [String.t() | non_neg_integer()]}
```

# `affected?`

```elixir
@spec affected?(String.t(), VulnCheck.Types.Advisory.t()) :: boolean()
```

Returns `true` when the installed version is affected by the advisory.

An advisory with neither ranges nor explicit versions is considered to
affect every version (fail-safe). Unparseable installed versions are also
considered affected.

# `affected?`

```elixir
@spec affected?(String.t(), [VulnCheck.Types.VersionRange.t()], [String.t()]) ::
  boolean()
```

Checks a single source's numbered intervals and explicit versions.

# `compare`

```elixir
@spec compare(String.t(), String.t()) :: :lt | :eq | :gt
```

Compares two versions.

    iex> VulnCheck.Semver.compare("2.8", "2.8.0")
    :eq
    iex> VulnCheck.Semver.compare("27.2", "25.3.2.12")
    :gt
    iex> VulnCheck.Semver.compare("1.19.0-rc.1", "1.19.0")
    :lt

Unparseable versions are compared as plain strings.

# `fixed_versions`

```elixir
@spec fixed_versions([VulnCheck.Types.VersionRange.t()]) :: [String.t()]
```

Collects the `fixed` versions declared by a list of ranges.

# `from_cve_affected`

```elixir
@spec from_cve_affected(map()) :: [VulnCheck.Types.VersionRange.t()]
```

Numbered range hints for a CVE affected product. An affected or unknown default keeps the set open.

# `from_cve_git_versions`

```elixir
@spec from_cve_git_versions(map()) :: [VulnCheck.Types.VersionRange.t()]
```

Converts the `versionType: "git"` entries of a CVE 5.1 affected product into
commit intervals (`type: :git`). Unaffected entries are dropped.

# `from_cve_versions`

```elixir
@spec from_cve_versions([map()] | nil) :: [VulnCheck.Types.VersionRange.t()]
```

Converts numbered CVE 5.1 `versions` entries into ranges. Affected and
unknown segments are retained.

# `from_osv_git_ranges`

```elixir
@spec from_osv_git_ranges([map()] | nil) :: [VulnCheck.Types.VersionRange.t()]
```

Converts the `GIT` ranges of an OSV `ranges` array into commit intervals
(`type: :git`). They are kept apart from numbered ranges and never take part
in version matching.

# `from_osv_ranges`

```elixir
@spec from_osv_ranges([map()] | nil) :: [VulnCheck.Types.VersionRange.t()]
```

Converts an OSV `ranges` array (decoded JSON) into version ranges.

Each range's `events` are processed in version order: an `introduced` event
opens an interval that the next `fixed` or `last_affected` event closes.
A `limit` restricts the range without declaring a fixed release.
`GIT` ranges are ignored because they cannot be compared with package
versions.

# `git_affected?`

```elixir
@spec git_affected?(VulnCheck.Types.Package.t(), VulnCheck.Types.Advisory.t()) ::
  :confirmed | :uncertain | :unaffected
```

Evaluates whether a git dependency is confirmed, unaffected, or uncertainly
affected by an advisory. Without git commit history, a git dependency is
only marked `:unaffected` when the upstream repository identity is confirmed
and a non-commit SemVer tag lies outside the advisory's numbered ranges.

# `in_range?`

```elixir
@spec in_range?(String.t(), VulnCheck.Types.VersionRange.t()) :: boolean()
```

Returns `true` when `version` lies inside the range.

# `otp_affected?`

```elixir
@spec otp_affected?(String.t(), String.t() | nil) :: boolean()
```

Evaluates an OTP runtime constraint against an OTP release.

Supported expressions: `"< 26"`, `"<= 25"`, `">= 24 and <= 25"`,
`"24 || 25"`, `"== 25"`, `"25"`. Comparison happens at the precision of the
constraint, so `"<= 25"` matches OTP `25.3.2`. When the known release
prefix matches a more precise boundary, the comparison remains open.
A `nil` or unparseable constraint is treated as affecting every runtime.

    iex> VulnCheck.Semver.otp_affected?("27", "<= 25")
    false
    iex> VulnCheck.Semver.otp_affected?("25.3", "<= 25")
    true

# `parse`

```elixir
@spec parse(String.t()) :: {:ok, parsed()} | :error
```

Parses a version string into `{numeric_segments, pre_release_identifiers}`.

    iex> VulnCheck.Semver.parse("1.19.0-rc.1+build.5")
    {:ok, {[1, 19, 0], ["rc", 1]}}

    iex> VulnCheck.Semver.parse("2.8")
    {:ok, {[2, 8], []}}

    iex> VulnCheck.Semver.parse("not a version")
    :error

# `recommended_fix`

```elixir
@spec recommended_fix(String.t(), VulnCheck.Types.Advisory.t()) :: String.t() | nil
```

Returns the closest upgrade that fixes the advisory for the installed
version, preferring the fix of the release branch the version belongs to.

For `plug 1.16.2` affected by `1.16.0..<1.16.4` and `1.19.0..<1.19.3` this
returns `"1.16.4"`, not `"1.19.3"`.

# `same_commit?`

```elixir
@spec same_commit?(term(), term()) :: boolean()
```

`true` when two strings designate the same commit: both are hexadecimal
object ids of at least 12 characters and one is a prefix of the other.
Placeholders such as `"0"` never match.

# `sort`

```elixir
@spec sort([String.t()]) :: [String.t()]
```

Sorts versions in ascending order.

# `valid?`

```elixir
@spec valid?(String.t()) :: boolean()
```

Returns `true` when the string is a version this module understands.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
