vers 1.0.0

data/lib/vers/version.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+module Vers
+  VERSION = "1.0.0"
+
+  ##
+  # Handles version comparison and normalization across different package ecosystems.
+  #
+  # This class provides version comparison functionality that can handle different
+  # versioning schemes used by various package managers (npm, gem, pypi, etc.).
+  #
+  # == Examples
+  #
+  #   Vers::Version.compare("1.2.3", "1.2.4")     # => -1
+  #   Vers::Version.compare("2.0.0", "1.9.9")     # => 1
+  #   Vers::Version.compare("1.0.0", "1.0.0")     # => 0
+  #
+  class Version
+    # Regex for parsing semantic version components including build metadata
+    SEMANTIC_VERSION_REGEX = /\A(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([^+]+))?(?:\+(.+))?\z/
+
+    attr_reader :major, :minor, :patch, :prerelease, :build
+
+    ##
+    # Creates a new Version object
+    #
+    # @param version_string [String] The version string to parse
+    #
+    def initialize(version_string)
+      @original = version_string.to_s
+      parse_version
+    end
+
+    ##
+    # Compares two version strings
+    #
+    # @param a [String] First version string
+    # @param b [String] Second version string
+    # @return [Integer] -1 if a < b, 0 if a == b, 1 if a > b
+    #
+    def self.compare(a, b)
+      return 0 if a == b
+      return -1 if a.nil?
+      return 1 if b.nil?
+
+      version_a = new(a)
+      version_b = new(b)
+      
+      version_a <=> version_b
+    end
+
+    ##
+    # Normalizes a version string to a consistent format
+    #
+    # @param version_string [String] The version string to normalize
+    # @return [String] The normalized version string
+    #
+    def self.normalize(version_string)
+      new(version_string).to_s
+    end
+
+    ##
+    # Checks if a version string is valid
+    #
+    # @param version_string [String] The version string to validate
+    # @return [Boolean] true if the version is valid
+    #
+    def self.valid?(version_string)
+      new(version_string)
+      true
+    rescue ArgumentError
+      false
+    end
+
+    ##
+    # Version comparison operator
+    #
+    # @param other [Version] The other version to compare to
+    # @return [Integer] -1, 0, or 1
+    #
+    def <=>(other)
+      return 0 if @original == other.to_s
+
+      # Compare major.minor.patch numerically
+      major_cmp = (major || 0) <=> (other.major || 0)
+      return major_cmp unless major_cmp == 0
+
+      minor_cmp = (minor || 0) <=> (other.minor || 0)
+      return minor_cmp unless minor_cmp == 0
+
+      patch_cmp = (patch || 0) <=> (other.patch || 0)
+      return patch_cmp unless patch_cmp == 0
+
+      # Handle prerelease comparison
+      return 1 if prerelease.nil? && !other.prerelease.nil?
+      return -1 if !prerelease.nil? && other.prerelease.nil?
+      return 0 if prerelease.nil? && other.prerelease.nil?
+
+      compare_prerelease(prerelease, other.prerelease)
+    end
+
+    ##
+    # String representation of the version
+    #
+    # @return [String] The normalized version string
+    #
+    def to_s
+      version = "#{major || 0}"
+      version += ".#{minor || 0}"
+      version += ".#{patch || 0}"
+      version += "-#{prerelease}" if prerelease
+      version
+    end
+
+    def ==(other)
+      other.is_a?(Version) && self <=> other == 0
+    end
+
+    def <(other)
+      (self <=> other) < 0
+    end
+
+    def <=(other)
+      (self <=> other) <= 0
+    end
+
+    def >(other)
+      (self <=> other) > 0
+    end
+
+    def >=(other)
+      (self <=> other) >= 0
+    end
+
+    def hash
+      [@original].hash
+    end
+
+    ##
+    # Increments the specified component of the version
+    #
+    # @param component [Symbol] The component to increment (:major, :minor, :patch)
+    # @return [Version] A new Version object with the incremented component
+    #
+    # == Examples
+    #
+    #   version = Vers::Version.new("1.2.3")
+    #   version.increment(:major)  # => #<Vers::Version "2.0.0">
+    #   version.increment(:minor)  # => #<Vers::Version "1.3.0">
+    #   version.increment(:patch)  # => #<Vers::Version "1.2.4">
+    #
+    def increment(component)
+      case component
+      when :major
+        self.class.new("#{major + 1}.0.0")
+      when :minor
+        self.class.new("#{major}.#{(minor || 0) + 1}.0")
+      when :patch
+        self.class.new("#{major}.#{minor || 0}.#{(patch || 0) + 1}")
+      else
+        raise ArgumentError, "Invalid component: #{component}. Must be :major, :minor, or :patch"
+      end
+    end
+
+    ##
+    # Increments the major version component
+    #
+    # @return [Version] A new Version object with incremented major version
+    #
+    def increment_major
+      increment(:major)
+    end
+
+    ##
+    # Increments the minor version component
+    #
+    # @return [Version] A new Version object with incremented minor version
+    #
+    def increment_minor
+      increment(:minor)
+    end
+
+    ##
+    # Increments the patch version component
+    #
+    # @return [Version] A new Version object with incremented patch version
+    #
+    def increment_patch
+      increment(:patch)
+    end
+
+    ##
+    # Checks if this version satisfies a constraint using pessimistic operator logic
+    #
+    # @param constraint [String] The constraint string (e.g., "~> 1.2")
+    # @return [Boolean] true if this version satisfies the constraint
+    #
+    # == Examples
+    #
+    #   version = Vers::Version.new("1.2.5")
+    #   version.satisfies?("~> 1.2")    # => true (>= 1.2.0, < 1.3.0)
+    #   version.satisfies?("~> 1.2.3")  # => true (>= 1.2.3, < 1.3.0)
+    #   version.satisfies?("~> 1.3")    # => false
+    #
+    def satisfies?(constraint)
+      if constraint.start_with?("~>")
+        # Pessimistic constraint
+        base_version = constraint.sub(/^~>\s*/, "").strip
+        base = self.class.new(base_version)
+        
+        # Must be >= base version
+        return false if self < base
+        
+        # Must be < next significant version
+        if base.patch && base.patch > 0
+          # ~> 1.2.3 means >= 1.2.3, < 1.3.0
+          upper_bound = self.class.new("#{base.major}.#{(base.minor || 0) + 1}.0")
+        elsif base.minor
+          # ~> 1.2 means >= 1.2.0, < 1.3.0  
+          upper_bound = self.class.new("#{base.major}.#{(base.minor || 0) + 1}.0")
+        else
+          # ~> 1 means >= 1.0.0, < 2.0.0
+          upper_bound = self.class.new("#{base.major + 1}.0.0")
+        end
+        
+        self < upper_bound
+      else
+        # For other constraints, delegate to constraint parsing
+        # This would require the Constraint class, so for now return true
+        true
+      end
+    end
+
+    ##
+    # Checks if this is a stable release (no prerelease components)
+    #
+    # @return [Boolean] true if this is a stable release
+    #
+    def stable?
+      prerelease.nil?
+    end
+
+    ##
+    # Checks if this is a prerelease version
+    #
+    # @return [Boolean] true if this is a prerelease version
+    #
+    def prerelease?
+      !prerelease.nil?
+    end
+
+    ##
+    # Gets the semantic version components as a hash
+    #
+    # @return [Hash] Hash with :major, :minor, :patch, :prerelease, :build keys
+    #
+    def to_h
+      {
+        major: major,
+        minor: minor,
+        patch: patch,
+        prerelease: prerelease,
+        build: build
+      }
+    end
+
+    ##
+    # Creates a new Version with the same major.minor but patch set to 0
+    #
+    # @return [Version] A new Version object with patch reset to 0
+    #
+    def base
+      self.class.new("#{major}.#{minor || 0}.0")
+    end
+
+    private
+
+    def parse_version
+      # Handle simple numeric versions
+      if @original.match(/^\d+$/)
+        @major = @original.to_i
+        return
+      end
+
+      # Try semantic version parsing first
+      if match = @original.match(SEMANTIC_VERSION_REGEX)
+        @major = match[1]&.to_i
+        @minor = match[2]&.to_i
+        @patch = match[3]&.to_i
+        @prerelease = match[4]
+        @build = match[5]
+        return
+      end
+
+      # Fall back to splitting on dots/dashes
+      parts = @original.split(/[.-]/)
+      
+      if parts.empty?
+        raise ArgumentError, "Invalid version format: #{@original}"
+      end
+
+      @major = parts[0]&.to_i
+      @minor = parts[1]&.to_i if parts[1]
+      @patch = parts[2]&.to_i if parts[2]
+      
+      # Everything after patch is considered prerelease
+      if parts.length > 3
+        @prerelease = parts[3..-1].join('.')
+      end
+    end
+
+    def compare_prerelease(pre_a, pre_b)
+      parts_a = pre_a.split('.')
+      parts_b = pre_b.split('.')
+      
+      max_length = [parts_a.length, parts_b.length].max
+      
+      0.upto(max_length - 1) do |i|
+        part_a = parts_a[i]
+        part_b = parts_b[i]
+        
+        return -1 if part_a.nil?
+        return 1 if part_b.nil?
+        
+        # Try numeric comparison first
+        if part_a.match(/^\d+$/) && part_b.match(/^\d+$/)
+          numeric_cmp = part_a.to_i <=> part_b.to_i
+          return numeric_cmp unless numeric_cmp == 0
+        else
+          string_cmp = part_a <=> part_b
+          return string_cmp unless string_cmp == 0
+        end
+      end
+      
+      0
+    end
+  end
+end

data/lib/vers/version_range.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require_relative 'interval'
+require_relative 'version'
+
+module Vers
+  class VersionRange
+    attr_reader :intervals
+
+    def initialize(intervals = [])
+      @intervals = intervals.compact.reject(&:empty?).sort_by { |i| [i.min || '', i.max || ''] }
+      merge_overlapping_intervals!
+    end
+
+    def self.empty
+      new([])
+    end
+
+    def self.unbounded
+      new([Interval.unbounded])
+    end
+
+    def self.exact(version)
+      new([Interval.exact(version)])
+    end
+
+    def self.greater_than(version, inclusive: false)
+      new([Interval.greater_than(version, inclusive: inclusive)])
+    end
+
+    def self.less_than(version, inclusive: false)
+      new([Interval.less_than(version, inclusive: inclusive)])
+    end
+
+    def empty?
+      intervals.empty?
+    end
+
+    def unbounded?
+      intervals.length == 1 && intervals.first.unbounded?
+    end
+
+    def contains?(version)
+      intervals.any? { |interval| interval.contains?(version) }
+    end
+
+    def intersect(other)
+      result_intervals = []
+      
+      intervals.each do |interval1|
+        other.intervals.each do |interval2|
+          intersection = interval1.intersect(interval2)
+          result_intervals << intersection unless intersection.empty?
+        end
+      end
+      
+      self.class.new(result_intervals)
+    end
+
+    def union(other)
+      self.class.new(intervals + other.intervals)
+    end
+
+    def complement
+      return self.class.unbounded if empty?
+      return self.class.empty if unbounded?
+
+      result_intervals = []
+      
+      sorted_intervals = intervals.sort_by { |i| i.min || '' }
+      
+      first_interval = sorted_intervals.first
+      if first_interval.min
+        result_intervals << Interval.new(
+          max: first_interval.min,
+          max_inclusive: !first_interval.min_inclusive
+        )
+      end
+      
+      sorted_intervals.each_cons(2) do |curr, next_interval|
+        if curr.max && next_interval.min
+          comparison = version_compare(curr.max, next_interval.min)
+          if comparison < 0 || (comparison == 0 && (!curr.max_inclusive || !next_interval.min_inclusive))
+            result_intervals << Interval.new(
+              min: curr.max,
+              max: next_interval.min,
+              min_inclusive: !curr.max_inclusive,
+              max_inclusive: !next_interval.min_inclusive
+            )
+          end
+        end
+      end
+      
+      last_interval = sorted_intervals.last
+      if last_interval.max
+        result_intervals << Interval.new(
+          min: last_interval.max,
+          min_inclusive: !last_interval.max_inclusive
+        )
+      end
+      
+      self.class.new(result_intervals)
+    end
+
+    def exclude(version)
+      return self if !contains?(version)
+      
+      result_intervals = []
+      
+      intervals.each do |interval|
+        if interval.contains?(version)
+          if interval.min && version_compare(interval.min, version) < 0
+            result_intervals << Interval.new(
+              min: interval.min,
+              max: version,
+              min_inclusive: interval.min_inclusive,
+              max_inclusive: false
+            )
+          end
+          
+          if interval.max && version_compare(version, interval.max) < 0
+            result_intervals << Interval.new(
+              min: version,
+              max: interval.max,
+              min_inclusive: false,
+              max_inclusive: interval.max_inclusive
+            )
+          end
+        else
+          result_intervals << interval
+        end
+      end
+      
+      self.class.new(result_intervals)
+    end
+
+    def to_s
+      return "∅" if empty?
+      return intervals.map(&:to_s).join(" ∪ ")
+    end
+
+    private
+
+    def merge_overlapping_intervals!
+      return if intervals.length <= 1
+
+      merged = []
+      current = intervals.first
+
+      intervals[1..-1].each do |interval|
+        union_result = current.union(interval)
+        if union_result
+          current = union_result
+        else
+          merged << current
+          current = interval
+        end
+      end
+
+      merged << current
+      @intervals = merged
+    end
+
+    def version_compare(a, b)
+      return 0 if a == b
+      return -1 if a.nil?
+      return 1 if b.nil?
+      
+      # Use the Version class for comparison
+      Version.compare(a, b)
+    end
+  end
+end

data/lib/vers.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require_relative "vers/version"
+require_relative "vers/interval"
+require_relative "vers/version_range"
+require_relative "vers/constraint"
+require_relative "vers/parser"
+
+##
+# Vers - A Ruby gem for parsing, comparing and sorting versions according to the VERS spec
+#
+# This gem provides tools for working with version ranges across different package managers,
+# using a mathematical interval model internally and supporting the vers specification from
+# the Package URL (PURL) project.
+#
+# == Features
+#
+# * Parse version ranges from multiple package ecosystems (npm, gem, pypi, maven, etc.)
+# * Convert between native version range syntax and universal vers URI format
+# * Mathematical interval-based operations (union, intersection, complement)
+# * Version comparison and containment checking
+# * Extensible architecture for adding new package manager support
+#
+# == Quick Start
+#
+#   require 'vers'
+#
+#   # Parse a vers URI
+#   range = Vers.parse("vers:npm/>=1.2.3|<2.0.0")
+#   range.contains?("1.5.0")  # => true
+#   range.contains?("2.1.0")  # => false
+#
+#   # Parse native package manager syntax
+#   npm_range = Vers.parse_native("^1.2.3", "npm")
+#   gem_range = Vers.parse_native("~> 1.0", "gem")
+#
+#   # Check version containment
+#   Vers.satisfies?("1.5.0", ">=1.0.0,<2.0.0")  # => true
+#
+#   # Compare versions
+#   Vers.compare("1.2.3", "1.2.4")  # => -1
+#
+# == Mathematical Model
+#
+# Internally, all version ranges are represented as mathematical intervals,
+# similar to those used in mathematics (e.g., [1.0.0, 2.0.0) represents
+# versions from 1.0.0 inclusive to 2.0.0 exclusive).
+#
+# This allows for precise set operations like union, intersection, and
+# complement, regardless of the original package manager syntax.
+#
+# @see https://github.com/package-url/purl-spec/blob/main/VERSION-RANGE-SPEC.rst
+# @author Andrew Nesbitt
+#
+module Vers
+  class Error < StandardError; end
+
+  # Default parser instance for convenience methods
+  @@parser = Parser.new
+
+  ##
+  # Parses a vers URI string into a VersionRange
+  #
+  # @param vers_string [String] The vers URI string (e.g., "vers:npm/>=1.2.3|<2.0.0")
+  # @return [VersionRange] The parsed version range
+  # @raise [ArgumentError] if the vers string is invalid
+  #
+  # == Examples
+  #
+  #   Vers.parse("vers:npm/>=1.2.3|<2.0.0")
+  #   Vers.parse("vers:gem/~>1.0")
+  #   Vers.parse("*")  # unbounded range
+  #
+  def self.parse(vers_string)
+    @@parser.parse(vers_string)
+  end
+
+  ##
+  # Parses a native package manager version range into a VersionRange
+  #
+  # @param range_string [String] The native version range string
+  # @param scheme [String] The package manager scheme (npm, gem, pypi, etc.)
+  # @return [VersionRange] The parsed version range
+  #
+  # == Examples
+  #
+  #   Vers.parse_native("^1.2.3", "npm")      # npm caret range
+  #   Vers.parse_native("~> 1.0", "gem")      # gem pessimistic operator
+  #   Vers.parse_native(">=1.0,<2.0", "pypi") # python constraints
+  #
+  def self.parse_native(range_string, scheme)
+    @@parser.parse_native(range_string, scheme)
+  end
+
+  ##
+  # Converts a VersionRange to a vers URI string
+  #
+  # @param version_range [VersionRange] The version range to convert
+  # @param scheme [String] The package manager scheme
+  # @return [String] The vers URI string
+  #
+  def self.to_vers_string(version_range, scheme)
+    @@parser.to_vers_string(version_range, scheme)
+  end
+
+  ##
+  # Checks if a version satisfies a version range constraint
+  #
+  # @param version [String] The version to check
+  # @param constraint [String] The version constraint (vers URI or native format)
+  # @param scheme [String, nil] The package manager scheme (if not using vers URI)
+  # @return [Boolean] true if the version satisfies the constraint
+  #
+  # == Examples
+  #
+  #   Vers.satisfies?("1.5.0", "vers:npm/>=1.0.0|<2.0.0")  # => true
+  #   Vers.satisfies?("1.5.0", "^1.2.3", "npm")            # => true
+  #
+  def self.satisfies?(version, constraint, scheme = nil)
+    range = if scheme
+              parse_native(constraint, scheme)
+            else
+              parse(constraint)
+            end
+    
+    range.contains?(version)
+  end
+
+  ##
+  # Compares two version strings
+  #
+  # @param a [String] First version string
+  # @param b [String] Second version string
+  # @return [Integer] -1 if a < b, 0 if a == b, 1 if a > b
+  #
+  # == Examples
+  #
+  #   Vers.compare("1.2.3", "1.2.4")  # => -1
+  #   Vers.compare("2.0.0", "1.9.9")  # => 1
+  #   Vers.compare("1.0.0", "1.0.0")  # => 0
+  #
+  def self.compare(a, b)
+    Version.compare(a, b)
+  end
+
+  ##
+  # Normalizes a version string to a consistent format
+  #
+  # @param version_string [String] The version string to normalize
+  # @return [String] The normalized version string
+  #
+  def self.normalize(version_string)
+    Version.normalize(version_string)
+  end
+
+  ##
+  # Checks if a version string is valid
+  #
+  # @param version_string [String] The version string to validate
+  # @return [Boolean] true if the version is valid
+  #
+  def self.valid?(version_string)
+    Version.valid?(version_string)
+  end
+
+  ##
+  # Creates an exact version range
+  #
+  # @param version [String] The exact version
+  # @return [VersionRange] A range containing only the specified version
+  #
+  def self.exact(version)
+    VersionRange.exact(version)
+  end
+
+  ##
+  # Creates a greater-than version range
+  #
+  # @param version [String] The minimum version
+  # @param inclusive [Boolean] Whether to include the minimum version
+  # @return [VersionRange] A range for versions greater than (or equal to) the specified version
+  #
+  def self.greater_than(version, inclusive: false)
+    VersionRange.greater_than(version, inclusive: inclusive)
+  end
+
+  ##
+  # Creates a less-than version range
+  #
+  # @param version [String] The maximum version
+  # @param inclusive [Boolean] Whether to include the maximum version
+  # @return [VersionRange] A range for versions less than (or equal to) the specified version
+  #
+  def self.less_than(version, inclusive: false)
+    VersionRange.less_than(version, inclusive: inclusive)
+  end
+
+  ##
+  # Creates an unbounded version range (matches all versions)
+  #
+  # @return [VersionRange] An unbounded range
+  #
+  def self.unbounded
+    VersionRange.unbounded
+  end
+
+  ##
+  # Creates an empty version range (matches no versions)
+  #
+  # @return [VersionRange] An empty range
+  #
+  def self.empty
+    VersionRange.empty
+  end
+end