Package: univers
univers: mostly universal version and version ranges comparison and conversionuniverswas born out of the need for a mostly universal way to store version
ranges and to compare two software package versions in VulnerableCode.Package version ranges and version constraints are useful and essential:When relating a known vulnerability or bug to a range of affected package
versions. For instance a statement such as “vulnerability 123 affects
package bar, version 3.1 and version 4.2 but not version 5” defines a
range of bar versions affected by a vulnerability.When resolving the dependencies of a package to express which subset of the
versions are supported. For instance a dependency requirement statement such
as “I require package foo, version 2.0 and later versions” defines a range of
acceptable foo versions.Version syntaxes and range notations are quite different across ecosystems,
making it is difficult to process versions and version ranges across ecosystems
in a consistent way.Existing tools and libraries typically support a single algorithms to parse and
compare versions with a single version range notation for a single package
ecosystem.universis different:It tracks each ecosystem versioning scheme and how two versions are compared.It support a growing number of package ecosystems versioning in a single
library.It can parse version range strings using their native notation (such as an npm
range) into the common “vers” notation and internal object model and can
return back a native version range string rebuilt from a “vers” range.It is designed to work withPackage URLs (purl).How doesuniverswork ?universwraps, embeds and implements multiple version comparison libraries,
each focused on a specific ecosystem versioning scheme.For each scheme,universprovides an implementation for:the version comparison procedure e.g, how to compare two versions,parsing and converting from a native version range notation to theuniversnormalized and unified internal model,converting a range back to its scheme-native range syntax and to theverssyntax.universimplementsvers, an experimental unified and mostly universal
version range syntax. It can parse and convert an existing native version range
strings to this unified syntax. For example, this means:converting “>=1.2.3” as used in a Python package intovers:pypi/>=1.2.3,or converting “^1.0.2” as used in an npm package dependency declaration intovers:npm/>=1.0.2|<2.0.0The supported package ecosystems versioning schemes and underlying libraries
include:npm that use the “node-semver” ranges notation and the semver versions syntax
This is supported in part by thesemantic_versionlibrary.pypi: handled by Python’s packaging library and the standardpackaging.versionmodule.Rubygems which use a semver-like but not-quite-semver scheme and there can be
commonly more than three version segments.
Gems also use a slightly different range notation from node-semver with
different operators and slightly different semantics: for instance it uses “~>”
as a pessimistic operator and supports exclusion with != and does not support
“OR” between constraints (that it call requirements).
Gem are handled by Python port of the Rubygems requirements and version
handling code from thepuppeteer tooldebian: handled by thedebian-inspector library.maven: handled by the embeddedpymaven library.rpm: handled by the embeddedrpm_vercmp library.golang (using semver)PHP composerebuild/gentoo: handled by the embeddedgentoo_vercmp module.arch linux: handled by the embeddedarch utility module borrowed from msys2.Alpine linux: handled using the base Gentoo version support and extras
specific to Alpine.The level of support for each ecosystem may not be even for now and new schemes
and support for more package types are implemented on a continuous basis.AlternativeRather than using ecosystem-specific version schemes and code, another approach
is to use a single procedure for all the versions as implemented inlibversion.libversionworks in the most
common case but may not work correctly when a task that demand precise version
comparisons such as for dependency resolution and vulnerability lookup where
a “good enough” comparison accuracy is not acceptable.libversiondoes not
handle version range notations.Installation$ pip install universExamplesCompare two native Python versions:fromunivers.versionsimportPypiVersionassertPypiVersion("1.2.3")<PypiVersion("1.2.4")Normalize a version range from an npm:fromunivers.version_rangeimportNpmVersionRangerange=NpmVersionRange.from_native("^1.0.2")assertstr(range)=="vers:npm/>=1.0.2|<2.0.0"Test if a version is within or outside a version range:fromunivers.versionsimportPypiVersionfromunivers.version_rangeimportVersionRangerange=VersionRange.from_string("vers:pypi/>=1.2.4")assertPypiVersion("1.2.4")inrangeassertPypiVersion("1.2.3")notinrangeDevelopmentRun these commands, starting from a git clone ofhttps://github.com/nexB/univers$ ./configure --dev
$ source venv/bin/active
$ pytest -vvsWe use the same development process as other AboutCode projects.Visithttps://github.com/nexB/universandhttps://gitter.im/aboutcode-org/vulnerablecodeandhttps://gitter.im/aboutcode-org/aboutcodefor support and chat.Primary license: Apache-2.0
SPDX-License-Identifier: Apache-2.0 AND BSD-3-Clause AND MIT