version_boss 0.1.0

data/lib/version_boss/semver/incrementable_version.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+
+module VersionBoss
+  module Semver
+    # A Semver Version with additional constraints on the pre-release part of the version
+    #
+    # An IncrementableVersion is valid if one of the two following conditions is met:
+    #   1. The pre-release part is empty
+    #   2. The pre-release part is composed of two dot-separated identifiers:
+    #     * the first being a String representing the pre-release type (e.g. 'alpha',
+    #       'beta', etc.). The default pre-release type is 'pre'
+    #     * the second being an Integer representing the pre-release sequence number
+    #       (starting at 1)
+    #
+    # Valid versions with pre-release parts: `1.2.3-alpha.1`, `1.2.3-beta.2`, `1.2.3-pre.3`
+    #
+    # @api public
+    #
+    class IncrementableVersion < Version
+      # Create a new IncrementableVersion object
+      #
+      # @example
+      #   IncrementableVersion.new('1.2.3').valid? # => true
+      #   IncrementableVersion.new('1.2.3-alpha.1+build.001').valid? # => true
+      #   IncrementableVersion.new('1.2.3-alpha').valid? # => raise VersionBoss::Error
+      #   IncrementableVersion.new('1.2.3-alpha.1.2').valid? # => raise VersionBoss::Error
+      #   IncrementableVersion.new('1.2.3-alpha.one').valid? # => raise VersionBoss::Error
+      #
+      # @return [Boolean] true if the version string is a valid semver and meets the conditions above
+      #
+      def valid?
+        super && (
+          pre_release.empty? ||
+          (
+            pre_release_identifiers.size == 2 &&
+            pre_type.is_a?(String) &&
+            pre_number.is_a?(Integer)
+          )
+        )
+      end
+
+      # The default pre-release identifier
+      DEFAULT_PRE_TYPE = 'pre'
+
+      # Increment the major version
+      #
+      # @example
+      #   IncrementableVersionify::Semver.new('1.2.3').next_major # => IncrementableVersionify::Semver.new('2.0.0')
+      #
+      # @return [IncrementableVersion] a new IncrementableVersion object with the major version incremented
+      #
+      def next_major(pre: false, pre_type: DEFAULT_PRE_TYPE, build_metadata: nil)
+        version_string = "#{major.to_i + 1}.0.0"
+        version_string += "-#{pre_type}.1" if pre
+        build_metadata = self.build_metadata if build_metadata.nil?
+        version_string += "+#{build_metadata}" unless build_metadata.empty?
+        IncrementableVersion.new(version_string)
+      end
+
+      # Increment the minor version
+      #
+      # @example
+      #   IncrementableVersionify::Semver.new('1.2.3').next_minor # => IncrementableVersionify::Semver.new('1.3.0')
+      #
+      # @return [IncrementableVersion] a new IncrementableVersion object with the major version incremented
+      #
+      def next_minor(pre: false, pre_type: DEFAULT_PRE_TYPE, build_metadata: nil)
+        version_string = "#{major}.#{minor.to_i + 1}.0"
+        version_string += "-#{pre_type}.1" if pre
+        build_metadata = self.build_metadata if build_metadata.nil?
+        version_string += "+#{build_metadata}" unless build_metadata.empty?
+        IncrementableVersion.new(version_string)
+      end
+
+      # Increment the patch version
+      #
+      # @example
+      #   IncrementableVersionify::Semver.new('1.2.3').next_patch # => IncrementableVersionify::Semver.new('1.2.1')
+      #
+      # @return [IncrementableVersion] a new IncrementableVersion object with the patch part incremented
+      #
+      def next_patch(pre: false, pre_type: DEFAULT_PRE_TYPE, build_metadata: nil)
+        version_string = "#{major}.#{minor}.#{patch.to_i + 1}"
+        version_string += "-#{pre_type}.1" if pre
+        build_metadata = self.build_metadata if build_metadata.nil?
+        version_string += "+#{build_metadata}" unless build_metadata.empty?
+        IncrementableVersion.new(version_string)
+      end
+
+      # Increment the pre_release part of the version
+      #
+      # @example
+      #   IncrementableVersionify::Semver.new('1.2.3-pre.1').next_patch.to_s # => '1.2.3-pre.2'
+      #
+      # @return [IncrementableVersion] a new IncrementableVersion object with the pre_release part incremented
+      #
+      def next_pre(pre_type: nil, build_metadata: nil)
+        assert_is_a_pre_release_version
+        version_string = "#{major}.#{minor}.#{patch}"
+        version_string += next_pre_part(pre_type)
+        build_metadata ||= self.build_metadata
+        version_string += "+#{build_metadata}" unless build_metadata.empty?
+        IncrementableVersion.new(version_string)
+      end
+
+      # Drop the pre-release part of the version
+      #
+      # @example
+      #   IncrementableVersionify::Semver.new('1.2.3-pre.1').next_release.to_s # => '1.2.3'
+      #
+      # @return [IncrementableVersion] a new IncrementableVersion object with the pre_release part dropped
+      # @raise [VersionBoss::Error] if the version is not a pre-release version
+      #
+      def next_release(build_metadata: nil)
+        assert_is_a_pre_release_version
+        version_string = "#{major}.#{minor}.#{patch}"
+        build_metadata ||= self.build_metadata
+        version_string += "+#{build_metadata}" unless build_metadata.empty?
+        IncrementableVersion.new(version_string)
+      end
+
+      # The pre-release type (for example, 'alpha', 'beta', 'pre', etc.)
+      #
+      # @example
+      #   IncrementableVersionify::Semver.new('1.2.3-pre.1').pre_type # => 'pre'
+      #
+      # @return [String]
+      #
+      def pre_type
+        pre_release_identifiers[0]
+      end
+
+      # The pre-release sequence number
+      #
+      # The pre-release sequence number starts at 1 for each pre-release type.
+      #
+      # @example
+      #   IncrementableVersionify::Semver.new('1.2.3-pre.1').pre_number # => 1
+      #
+      # @return [Integer]
+      #
+      def pre_number
+        pre_release_identifiers[1]
+      end
+
+      private
+
+      # Raise an error if the version is not a pre-release version
+      #
+      # @return [void]
+      # @raise [VersionBoss::Error] if the version is not a pre-release version
+      # @api private
+      def assert_is_a_pre_release_version
+        return unless pre_release.empty?
+
+        raise VersionBoss::Error, 'Cannot increment the pre-release part of a release version'
+      end
+
+      # Raise an error if new pre-release type is less than the old pre-release type
+      #
+      # If the new pre-release type is lexically less than the old pre-release type,
+      # then raise an error because the resulting error would sort before the existing
+      # version.
+      #
+      # @return [void]
+      # @raise [VersionBoss::Error] if the pre-release type is not valid
+      # @api private
+      def assert_pre_type_is_valid(pre_type)
+        return if self.pre_type <= pre_type
+
+        message = 'Cannot increment the pre-release identifier ' \
+                  "from '#{self.pre_type}' to '#{pre_type}' " \
+                  "because '#{self.pre_type}' is lexically less than '#{pre_type}'"
+
+        raise VersionBoss::Error, message
+      end
+
+      # Return the next pre-release part
+      # @param pre_type [String, nil] the given pre-release type or nil to use the existing pre-release type
+      # @return [String]
+      # @api private
+      def next_pre_part(pre_type)
+        pre_type ||= self.pre_type
+        assert_pre_type_is_valid(pre_type)
+        next_pre_number = self.pre_type == pre_type ? (pre_number + 1) : 1
+        "-#{pre_type}.#{next_pre_number}"
+      end
+    end
+  end
+end

data/lib/version_boss/semver/regexp.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module VersionBoss
+  module Semver
+    # Match a semver within a string
+    REGEXP = /
+      (?<semver>
+        (?<major>0|[1-9]\d*)
+        \.
+        (?<minor>0|[1-9]\d*)
+        \.
+        (?<patch>0|[1-9]\d*)
+        (?:-
+          (?<pre_release>
+            (?:
+              0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*
+            )
+            (?:
+              \.
+              (?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)
+            )*
+          )
+        )?
+        (?:
+          \+
+          (?<build_metadata>
+            [0-9a-zA-Z-]+
+            (?:
+              \.
+              [0-9a-zA-Z-]+
+            )*
+          )
+        )?
+      )
+    /x
+
+    # Match a semver to the full string
+    REGEXP_FULL = /\A#{REGEXP.source}\z/x
+  end
+end

data/lib/version_boss/semver/version.rb

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+
+require_relative 'regexp'
+
+module VersionBoss
+  module Semver
+    # Parse and compare semver version strings
+    #
+    # This class will parse a semver version string that complies to Semantic
+    # Versioning 2.0.0.
+    #
+    # Two Semver objects can be compared using the spaceship operator (<=>)
+    # according to the rules of Semantic Versioning 2.0.0.
+    #
+    # @example Basic version parsing
+    #   semver = VersionBoss::Semver.new('1.2.3')
+    #   semver.major # => '1'
+    #   semver.minor # => '2'
+    #   semver.patch # => '3'
+    #
+    # @example Parsing a version with a pre-release identifier
+    #   semver = VersionBoss::Semver.new('1.2.3-alpha.1')
+    #   semver.pre_release # => 'alpha.1'
+    #   semver.pre_release_identifiers # => ['alpha', '1']
+    #
+    # @example A version with build metadata
+    #   semver = VersionBoss::Semver.new('1.2.3+build.1')
+    #   semver.build_metadata # => 'build.1'
+    #
+    # @example Comparing versions
+    #   semver1 = VersionBoss::Semver.new('1.2.3')
+    #   semver2 = VersionBoss::Semver.new('1.2.4')
+    #   semver1 <=> semver2 # => true
+    #
+    # See the Semantic Versioning 2.0.0 specification for more details.
+    #
+    # @see https://semver.org/spec/v2.0.0.html Semantic Versioning 2.0.0
+    #
+    # @api public
+    #
+    class Version
+      include Comparable
+
+      # Create a new Semver object
+      #
+      # @example
+      #   version = VersionBoss::Semver.new('1.2.3-alpha.1')
+      #
+      # @param version [String] The version string to parse
+      #
+      # @raise [VersionBoss::Error] version is not a string or not a valid semver version
+      #
+      def initialize(version)
+        assert_version_must_be_a_string(version)
+        @version = version
+        parse
+        assert_valid_version
+      end
+
+      # @!attribute version [r]
+      #
+      # The complete version string
+      #
+      # @example
+      #   semver = VersionBoss::Semver.new('1.2.3-alpha.1+build.001')
+      #   semver.version #=> '1.2.3-alpha.1+build.001'
+      #
+      # @return [String]
+      #
+      # @api public
+      #
+      attr_reader :version
+
+      # @attribute major [r]
+      #
+      # The major part of the version
+      #
+      # @example
+      #   semver = VersionBoss::Semver.new('1.2.3-alpha.1+build.001')
+      #   semver.major #=> '1'
+      #
+      # @return [String]
+      #
+      # @api public
+      #
+      attr_reader :major
+
+      # @attribute minor [r]
+      #
+      # The minor part of the version
+      #
+      # @example
+      #   semver = VersionBoss::Semver.new('1.2.3-alpha.1+build.001')
+      #   semver.minor #=> '2'
+      #
+      # @return [String]
+      #
+      # @api public
+      #
+      attr_reader :minor
+
+      # @attribute patch [r]
+      #
+      # The patch part of the version
+      #
+      # @example
+      #   semver = VersionBoss::Semver.new('1.2.3-alpha.1+build.001')
+      #   semver.patch #=> '3'
+      #
+      # @return [String]
+      #
+      # @api public
+      #
+      attr_reader :patch
+
+      # @attribute pre_release [r]
+      #
+      # The pre_release part of the version
+      #
+      # Will be an empty string if the version has no pre_release part.
+      #
+      # @example
+      #   semver = VersionBoss::Semver.new('1.2.3-alpha.1+build.001')
+      #   semver.pre_release #=> 'alpha.1'
+      #
+      # @example When the version has no pre_release part
+      #   semver = VersionBoss::Semver.new('1.2.3')
+      #   semver.pre_release #=> ''
+      #
+      # @return [String]
+      #
+      # @api public
+      #
+      attr_reader :pre_release
+
+      # @attribute pre_release_identifiers [r]
+      #
+      # The pre_release identifiers of the version
+      #
+      # @example
+      #   semver = VersionBoss::Semver.new('1.2.3-alpha.1+build.001')
+      #   semver.pre_release_identifiers #=> ['alpha', '1']
+      #
+      # @example When the version has no pre_release part
+      #   semver = VersionBoss::Semver.new('1.2.3')
+      #   semver.pre_release_identifiers #=> []
+      #
+      # @return [Array<String>]
+      #
+      # @api public
+      #
+      attr_reader :pre_release_identifiers
+
+      # @attribute build_metadata [r]
+      #
+      # The build_metadata part of the version
+      #
+      # Will be an empty string if the version has no build_metadata part.
+      #
+      # @example
+      #   semver = VersionBoss::Semver.new('1.2.3-alpha.1+build.001')
+      #   semver.build_metadata #=> 'build.001'
+      #
+      # @example When the version has no build_metadata part
+      #   semver = VersionBoss::Semver.new('1.2.3')
+      #   semver.build_metadata #=> ''
+      #
+      # @return [String]
+      #
+      # @api public
+      #
+      attr_reader :build_metadata
+
+      # Compare two Semver objects
+      #
+      # See the [Precedence Rules](https://semver.org/spec/v2.0.0.html#spec-item-11)
+      # in the Semantic Versioning 2.0.0 Specification for more details.
+      #
+      # @example
+      #   semver1 = VersionBoss::Semver.new('1.2.3')
+      #   semver2 = VersionBoss::Semver.new('1.2.4')
+      #   semver1 <=> semver2 # => -1
+      #   semver2 <=> semver1 # => 1
+      #
+      # @example A Semver is equal to itself
+      #   semver1 = VersionBoss::Semver.new('1.2.3')
+      #   semver1 <=> semver1 # => 0
+      #
+      # @example A pre-release version is always older than a normal version
+      #   semver1 = VersionBoss::Semver.new('1.2.3-alpha.1')
+      #   semver2 = VersionBoss::Semver.new('1.2.3')
+      #   semver1 <=> semver2 # => -1
+      #
+      # @example Pre-releases are compared by the parts of the pre-release version
+      #   semver1 = VersionBoss::Semver.new('1.2.3-alpha.1')
+      #   semver2 = VersionBoss::Semver.new('1.2.3-alpha.2')
+      #   semver1 <=> semver2 # => -1
+      #
+      # @example Build metadata is ignored when comparing versions
+      #   semver1 = VersionBoss::Semver.new('1.2.3+build.100')
+      #   semver2 = VersionBoss::Semver.new('1.2.3+build.101')
+      #   semver1 <=> semver2 # => 0
+      #
+      # @param other [Semver] the other Semver to compare to
+      #
+      # @return [Integer] -1 if self < other, 0 if self == other, or 1 if self > other
+      #
+      # @raise [VersionBoss::Error] other is not a semver
+      #
+      def <=>(other)
+        assert_other_is_a_semver(other)
+
+        result = compare_core_parts(other)
+
+        return result unless result.zero? && pre_release != other.pre_release
+        return 1 if pre_release.empty?
+        return -1 if other.pre_release.empty?
+
+        compare_pre_release_part(other)
+      end
+
+      # Determine if the version string is a valid semver
+      #
+      # Override this method in a subclass to provide extra or custom validation.
+      #
+      # @example
+      #   VersionBoss::Semver.new('1.2.3').valid? # => true
+      #   VersionBoss::Semver.new('1.2.3-alpha.1+build.001').valid? # => true
+      #   VersionBoss::Semver.new('bogus').valid? # => raises VersionBoss::Error
+      #
+      # @return [Boolean] true if the version string is a valid semver
+      #
+      def valid?
+        # If major is set, then so is everything else
+        !major.nil?
+      end
+
+      # Two versions are equal if their version strings are equal
+      #
+      # @example
+      #   VersionBoss::Semver.new('1.2.3') == '1.2.3' # => true
+      #
+      # @param other [Semver] the other Semver to compare to
+      #
+      # @return [Boolean] true if the version strings are equal
+      #
+      def ==(other)
+        version == other.to_s
+      end
+
+      # The string representation of a Semver is its version string
+      #
+      # @example
+      #   VersionBoss::Semver.new('1.2.3').to_s # => '1.2.3'
+      #
+      # @return [String] the version string
+      #
+      def to_s
+        version
+      end
+
+      private
+
+      # Parse @version into its parts
+      # @return [void]
+      # @api private
+      def parse
+        return unless (match_data = version.match(REGEXP_FULL))
+
+        core_parts(match_data)
+        pre_release_part(match_data)
+        build_metadata_part(match_data)
+      end
+
+      # Compare the major, minor, and patch parts of this Semver to other
+      # @param other [Semver] the other Semver to compare to
+      # @return [Integer] -1 if self < other, 0 if self == other, or 1 if self > other
+      # @api private
+      def compare_core_parts(other)
+        identifiers = [major.to_i, minor.to_i, patch.to_i]
+        other_identifiers = [other.major.to_i, other.minor.to_i, other.patch.to_i]
+
+        identifiers <=> other_identifiers
+      end
+
+      # Compare two pre-release identifiers
+      #
+      # Implements the rules for precedence for comparing two pre-release identifiers
+      # from the Semantic Versioning 2.0.0 Specification.
+      #
+      # @param identifier [String, Integer] the identifier to compare
+      # @param other_identifier [String, Integer] the other identifier to compare
+      # @return [Integer] -1, 0, or 1
+      # @api private
+      def compare_identifiers(identifier, other_identifier)
+        return 1 if other_identifier.nil?
+        return -1 if identifier.is_a?(Integer) && other_identifier.is_a?(String)
+        return 1 if other_identifier.is_a?(Integer) && identifier.is_a?(String)
+
+        identifier <=> other_identifier
+      end
+
+      # Compare two pre-release version parts
+      #
+      # Implements the rules for precedence for comparing the pre-release part of
+      # one version with the pre-release part of another version from the Semantic
+      # Versioning 2.0.0 Specification.
+      #
+      # @param other [Semver] the other Semver to compare to
+      # @return [Integer] -1, 0, or 1
+      # @api private
+      def compare_pre_release_part(other)
+        pre_release_identifiers.zip(other.pre_release_identifiers).each do |field, other_field|
+          result = compare_identifiers(field, other_field)
+          return result unless result.zero?
+        end
+        pre_release_identifiers.size < other.pre_release_identifiers.size ? -1 : 0
+      end
+
+      # Raise a error if other is not a valid Semver
+      # @param other [Semver] the other to check
+      # @return [void]
+      # @raise [VersionBoss::Error] if other is not a valid Semver
+      # @api private
+      def assert_other_is_a_semver(other)
+        raise VersionBoss::Error, 'other must be a Semver' unless other.is_a?(VersionBoss::Semver::Version)
+      end
+
+      # Raise a error if the given version is not a string
+      # @param version [Semver] the version to check
+      # @return [void]
+      # @raise [VersionBoss::Error] if the given version is not a string
+      # @api private
+      def assert_version_must_be_a_string(version)
+        raise VersionBoss::Error, 'Version must be a string' unless version.is_a?(String)
+      end
+
+      # Raise a error if this version object is not a valid Semver
+      # @return [void]
+      # @raise [VersionBoss::Error] if other is not a valid Semver
+      # @api private
+      def assert_valid_version
+        raise VersionBoss::Error, "Not a valid version string: #{version}" unless valid?
+      end
+
+      # Set the major, minor, and patch parts of this Semver
+      # @param match_data [MatchData] the match data from the version string
+      # @return [void]
+      # @api private
+      def core_parts(match_data)
+        @major = match_data[:major]
+        @minor = match_data[:minor]
+        @patch = match_data[:patch]
+      end
+
+      # Set the pre-release of this Semver
+      # @param match_data [MatchData] the match data from the version string
+      # @return [void]
+      # @api private
+      def pre_release_part(match_data)
+        @pre_release = match_data[:pre_release] || ''
+        @pre_release_identifiers = @pre_release.split('.').map { |f| f =~ /\A\d+\z/ ? f.to_i : f }
+      end
+
+      # Set the build_metadata of this Semver
+      # @param match_data [MatchData] the match data from the version string
+      # @return [void]
+      # @api private
+      def build_metadata_part(match_data)
+        @build_metadata = match_data[:build_metadata] || ''
+      end
+    end
+  end
+end

data/lib/version_boss/semver.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module VersionBoss
+  # Classes for working with Gem versions
+  module Semver; end
+end
+
+require_relative 'semver/incrementable_version'
+require_relative 'semver/version'

data/lib/version_boss/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module VersionBoss
+  # The current version of this gem
+  VERSION = '0.1.0'
+end

data/lib/version_boss.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'version_boss/gem'
+require_relative 'version_boss/semver'
+
+# Parse, compare, and increment versions according to the SemVer 2.0.0
+module VersionBoss
+  # Errors reported by the VersionBoss gem
+  class Error < StandardError; end
+end

data/version_boss.gemspec

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative 'lib/version_boss/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'version_boss'
+  spec.version = VersionBoss::VERSION
+  spec.authors = ['James Couball']
+  spec.email = ['jcouball@yahoo.com']
+
+  spec.summary = 'A Gem to parse and compare SemVer versions AND increment versions for Ruby Gems'
+  spec.description = <<~DESC
+    Parse, compare, and increment RubyGem versions with the 'gem-version' CLI
+    command or the 'VersionBoss::Gem::Version' class.
+  DESC
+
+  spec.homepage = 'http://github.com/main-branch/version_boss'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "https://rubydoc.info/gems/#{spec.name}/#{spec.version}/file/CHANGELOG.md"
+  spec.metadata['documentation_uri'] = "https://rubydoc.info/gems/#{spec.name}/#{spec.version}"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'thor', '~> 1.3'
+
+  spec.add_development_dependency 'bundler-audit', '~> 0.9'
+  spec.add_development_dependency 'create_github_release', '~> 1.3'
+  spec.add_development_dependency 'rake', '~> 13.1'
+  spec.add_development_dependency 'rspec', '~> 3.12'
+  spec.add_development_dependency 'rubocop', '~> 1.59'
+  spec.add_development_dependency 'simplecov', '~> 0.22'
+  spec.add_development_dependency 'simplecov-lcov', '~> 0.8'
+
+  unless RUBY_PLATFORM == 'java'
+    spec.add_development_dependency 'redcarpet', '~> 3.6'
+    spec.add_development_dependency 'yard', '~> 0.9', '>= 0.9.28'
+    spec.add_development_dependency 'yardstick', '~> 0.9'
+  end
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end